LABGRID-CLIENT(1)

🌈 LABGRID-CLIENT(1) 🌈

hi bestie 💖 this is labgrid-client(1), straight out of the labgrid manual. It's a big one — part 1 of 2, so don't go anywhere, we are not done.

👑 NAME 👑

labgrid-client — labgrid's client interface to control boards 💅

okay so Labgrid is a scalable infrastructure and test architecture for embedded (linux) systems. That's the whole concept, no cap.

And this thing right here? This is the client you use to control a board's status and interface with it on remote machines. It's giving remote-control queen 👑

💖 LABGRID-CLIENT 💖

Here's the shape of the whole thing:

usage: labgrid-client [-x ADDRESS] [-c CONFIG] [-p PLACE] [-s STATE]
                      [-i INITIAL_STATE] [-d] [-v] [-P PROXY]
                      COMMAND ...

These are your global flags — the ones that apply before the COMMAND even shows up ✨

-x <address>, --coordinator <address> — the coordinator, as HOST[:PORT]. Default comes from the env variable LG_COORDINATOR, and if that's not set, you get 127.0.0.1:20408.
-c <config>, --config <config> — env config file. Default comes from the env variable LG_ENV.
-p <place>, --place <place> — place name or alias. Default comes from the env variable LG_PLACE.
-s <state>, --state <state> — strategy state to switch into before the command runs. Default comes from the env variable LG_STATE.
-i <initial_state>, --initial-state <initial_state> — strategy state to force into before switching to the desired state.
-d, --debug — enable debug mode, aka show python tracebacks 🐍
-v, --verbose — verbose mode.
-P <proxy>, --proxy <proxy> — proxy connections via the given ssh host.

🔒 labgrid-client acquire|lock

acquire a place 🔐

usage: labgrid-client acquire|lock [--allow-unmatched]

--allow-unmatched — allow missing resources for matches when locking the place.

🏷️ labgrid-client add-alias

add an alias to a place.

usage: labgrid-client add-alias alias

<alias> — the alias.

➕ labgrid-client add-match

add one (or multiple) match pattern(s) to a place.

usage: labgrid-client add-match PATTERN [PATTERN ...]

<pattern> — the match pattern(s).

🎀 labgrid-client add-named-match

add one match pattern with a name to a place.

usage: labgrid-client add-named-match PATTERN NAME

<pattern> — the match pattern.
<name> — the name.

🫶 labgrid-client allow

allow another user to access a place. Sharing is caring fr.

usage: labgrid-client allow user

<user> — <host>/<username>.

🔊 labgrid-client audio

start an audio stream 🎧

usage: labgrid-client audio [--name NAME]

--name <name>, -n <name> — optional resource name.

🥾 labgrid-client bootstrap

start a bootloader.

usage: labgrid-client bootstrap [-w WAIT] [--name NAME] filename ...

<filename> — filename to boot on the target.
<arg> — extra bootstrap arguments.
-w <wait>, --wait <wait> — wait time.
--name <name>, -n <name> — optional resource name.

❌ labgrid-client cancel-reservation

cancel a reservation. bye reservation 💀

usage: labgrid-client cancel-reservation [token]

<token> — the reservation token.

🖥️ labgrid-client console|con

connect to the console ✨

usage: labgrid-client console|con [-l] [-o] [--logfile FILE] [name]

<name> — optional resource name.
-l, --loop — keep trying to connect if the console is unavailable. Stubborn on purpose, we love her.
-o, --listenonly — do not modify local terminal, do not send input from stdin. Just vibes, no typing.
--logfile <file> — log output to FILE.

🌱 labgrid-client create

add a new place, with the name specified via --place or the LG_PLACE environment variable.

usage: labgrid-client create

🗑️ labgrid-client del-alias

delete an alias from a place.

usage: labgrid-client del-alias alias

<alias> — the alias.

✂️ labgrid-client del-match

delete one (or multiple) match pattern(s) from a place.

usage: labgrid-client del-match PATTERN [PATTERN ...]

<pattern> — the match pattern(s).

💥 labgrid-client delete

delete an existing place. gone, reduced to atoms.

usage: labgrid-client delete

⚡ labgrid-client dfu

communicate with a device in DFU mode.

usage: labgrid-client dfu [--wait WAIT] [--name NAME]
                          {download,detach,list} [altsetting] [filename]

<action> — action.
<altsetting> — altsetting name or number (download, detach only).
<filename> — file to write into device (download only).
--wait <wait> — wait time.
--name <name>, -n <name> — optional resource name.

🌍 labgrid-client env

generate a labgrid environment file for a place 🦋

usage: labgrid-client env

📦 labgrid-client export

export driver information to a file (needs an environment with drivers).

usage: labgrid-client export [--format {shell,shell-export,json}] filename

<filename> — output filename.
--format {shell,shell-export,json} — output format (default: shell-export).

🏃 labgrid-client fastboot

run fastboot.

usage: labgrid-client fastboot [--wait WAIT] [--name NAME] ...

<arg> — fastboot arguments.
--wait <wait> — wait time.
--name <name>, -n <name> — optional resource name.

🔥 labgrid-client flashscript

Run an arbitrary script with arguments to flash the device.

usage: labgrid-client flashscript [--name NAME] script ...

<script> — flashing script.
<arg> — script arguments.
--name <name>, -n <name> — optional resource name.

🔀 labgrid-client forward

forward a local port to the remote target.

usage: labgrid-client forward [--name NAME] [--local [LOCAL:]REMOTE]
                              [--remote REMOTE:LOCAL]

--name <name>, -n <name> — optional resource name.
--local, -L — forward local port LOCAL to remote port REMOTE. If LOCAL is unspecified, an arbitrary port will be chosen.
--remote, -R — forward remote port REMOTE to local port LOCAL.

🔌 labgrid-client io

change (or get) a digital IO status.

usage: labgrid-client io {high,low,get} [name]

<action> — action.
<name> — optional resource name.

👀 labgrid-client monitor

monitor events from the coordinator. Live updates, main character energy 📡

usage: labgrid-client monitor

🕸️ labgrid-client netns

start a network namespace with access to NetworkInterface.

usage: labgrid-client netns [--name NAME] [--address ADDRESS]
                            [--mac-address MAC_ADDRESS] [--nsenter [NSENTER]]
                            ...

<cmd> — command to execute in the namespace. If unspecified, $SHELL is invoked.
--name <name>, -n <name> — optional resource name.
--address <address>, -a <address> — assign address to interface (CIDR notation).
--mac-address <mac_address> — assign MAC address to interface.
--nsenter <nsenter>, -e <nsenter> — create nsenter wrapper script.

📍 labgrid-client places|p

list available places.

usage: labgrid-client places|p [-a] [-r] [--sort-last-changed]

-a, --acquired — only acquired places.
-r, --released — only released places.
--sort-last-changed — sort by last changed date (oldest first).

⚡ labgrid-client power|pw

change (or get) a place's power status. cut the power, iconic.

usage: labgrid-client power|pw [-t DELAY] [--name NAME] {on,off,cycle,get}

<action> — action.
-t <delay>, --delay <delay> — wait time in seconds between off and on during cycle.
--name <name>, -n <name> — optional resource name.

🔓 labgrid-client release-from

atomically release a place, but only if it's locked by a specific user.

usage: labgrid-client release-from HOST/USER

<host/user> — user and host to match against when releasing.

ngl, important: this command returns success as long as the specified user no longer owns the place — meaning it may be acquired by another user, or not at all. So success here does not mean "you got it, bestie" 🙈

🔓 labgrid-client release|unlock

release a place.

usage: labgrid-client release|unlock [-k]

-k, --kick — release a place even if it is acquired by a different user. yes, we're kicking them out 💅

📋 labgrid-client reservations

list current reservations.

usage: labgrid-client reservations

🎟️ labgrid-client reserve

create a reservation.

usage: labgrid-client reserve [--wait] [--shell] [--prio PRIO]
                              KEY=VALUE [KEY=VALUE ...]

<key=value> — required tags.
--wait — wait until the reservation is allocated.
--shell — format output as shell variables.
--prio <prio> — priority relative to other reservations (default 0).

🧩 labgrid-client resources|r

list available resources.

usage: labgrid-client resources|r [-a] [-e EXPORTER]
                                  [--sort-by-matched-place-change]
                                  [match]

<match> — the match.
-a, --acquired — only acquired.
-e <exporter>, --exporter <exporter> — the exporter.
--sort-by-matched-place-change — sort by matched place's changed date (oldest first) and show place and date.

🔄 labgrid-client rsync

transfer files via rsync.

usage: labgrid-client rsync [--name NAME] src dst

<src> — source path (use :dir/file for remote side).
<dst> — destination path (use :dir/file for remote side).
--name <name>, -n <name> — optional resource name.

Additional arguments are passed to the rsync subprocess.

📤 labgrid-client scp

transfer a file via scp.

usage: labgrid-client scp [--name NAME] src dst

<src> — source path (use :dir/file for remote side).
<dst> — destination path (use :dir/file for remote side).
--name <name>, -n <name> — optional resource name.

🎛️ labgrid-client sd-mux

switch USB SD Muxer, or get the current mode.

usage: labgrid-client sd-mux [--name NAME] {dut,host,off,client,get}

<action> — action.
--name <name>, -n <name> — optional resource name.

💬 labgrid-client set-comment

update the place comment.

usage: labgrid-client set-comment comment [comment ...]

<comment> — the comment.

🏷️ labgrid-client set-tags

update the place tags.

usage: labgrid-client set-tags KEY=VALUE [KEY=VALUE ...]

<key=value> — use an empty value for deletion.

🔎 labgrid-client show

show a place and related resources.

usage: labgrid-client show

🖇️ labgrid-client ssh

connect via ssh (with optional arguments).

usage: labgrid-client ssh [--name NAME]

--name <name>, -n <name> — optional resource name.

Additional arguments are passed to the ssh subprocess.

🗂️ labgrid-client sshfs

mount via sshfs (blocking).

usage: labgrid-client sshfs [--name NAME] path mountpoint

<path> — remote path on the target.
<mountpoint> — local path.
--name <name>, -n <name> — optional resource name.

☎️ labgrid-client telnet

connect via telnet.

usage: labgrid-client telnet

🔬 labgrid-client tmc

control a USB TMC device.

usage: labgrid-client tmc [--name NAME] SUBCOMMAND ...

--name <name>, -n <name> — optional resource name.

📺 labgrid-client tmc channel

use a channel.

usage: labgrid-client tmc channel channel {info,values}

<channel> — the channel.
<action> — action.

⌨️ labgrid-client tmc cmd|c

execute a raw command.

usage: labgrid-client tmc cmd|c command [command ...]

<command> — the command.

❓ labgrid-client tmc query|q

execute a raw query.

usage: labgrid-client tmc query|q query [query ...]

<query> — the query.

📸 labgrid-client tmc screen

show or save a screenshot.

usage: labgrid-client tmc screen {show,save}

<action> — action.

🔗 labgrid-client usb-mux

switch USB Muxer.

labgrid-client usb-mux 🔀

okay so this one switches which side of the USB mux is connected, bestie ✨

usage: labgrid-client usb-mux [--name NAME]
                              {off,dut-device,host-dut,host-device,host-dut+host-device}

links 🔌

--name <name>, -n <name> — optional resource name 💖

labgrid-client version 🏷️

just tells you what version you're on, short and sweet fr fr

usage: labgrid-client version

labgrid-client video 🎥

starts a video stream, main character moment for your camera ngl 🌸

usage: labgrid-client video [-q QUALITY] [-c CONTROLS] [--name NAME]

-q <quality>, --quality <quality> — pick a video quality (pass 'list' to see all the options, iykyk) ✨
-c <controls>, --controls <controls> — configure v4l controls, like this: 'focus_auto=0,focus_absolute=40' 💅
--name <name>, -n <name> — optional resource name 🫶

labgrid-client wait ⏳

waits around (patiently, like a good bestie) for a reservation to be allocated 🎀

usage: labgrid-client wait [token]

token — the token you're waiting on

labgrid-client who 🕵️‍♀️

lists which places have been acquired, by user 👑

usage: labgrid-client who [-e]

-e, --show-exporters — also show the exporters each place is currently using ✨

labgrid-client write-files 📁

copies files onto a mass storage device, no cap 💾

usage: labgrid-client write-files [OPTION]... -T SOURCE DEST
       labgrid-client write-files [OPTION]... [-t DIRECTORY] SOURCE...

source — source file(s) to copy 💖
dest — destination file name for SOURCE
-w <wait>, --wait <wait> — storage poll timeout in seconds ⏰
-p <0-255>, --partition <0-255> — partition number to mount, or 0 to mount the whole disk (default: 1) 🗂️
-t <directory>, --target-directory <directory> — copy all SOURCE files into DIRECTORY (default: partition root) 🌸
-T — copy the SOURCE file and rename it to DEST ✨
--name <name>, -n <name> — optional resource name 💜

labgrid-client write-image 🖼️

writes an image onto mass storage, glow-up incoming 🔥

usage: labgrid-client write-image [-w WAIT] [-p PARTITION] [--skip SKIP]
                                  [--seek SEEK] [--mode {dd,bmaptool}]
                                  [--name NAME]
                                  filename

filename — filename to boot on the target 👑
-w <wait>, --wait <wait>
-p <partition>, --partition <partition> — partition number to write to 🗂️
--skip <skip> — skip n 512-sized blocks at start of input ⏭️
--seek <seek> — skip n 512-sized blocks at start of output ⏭️
--mode {dd,bmaptool} — choose the tool for writing images (default: dd) 🛠️
--name <name>, -n <name> — optional resource name 💖

🌈 CONFIGURATION FILE 🌈

The configuration file follows the description in labgrid-device-config(5). periodt 💅

✨ ENVIRONMENT VARIABLES ✨

Various labgrid-client commands use the following environment variable, bestie — lowkey important, don't skip these 🫶

LG_PLACE

This variable can be used to specify a place without using the -p option, the -p option overrides it. 💖

LG_TOKEN

This variable can be used to specify a reservation for the wait command and for the + place expansion. 🎟️

LG_STATE

This variable can be used to specify a state which the device transitions into before executing a command. Requires a configuration file and a Strategy specified for the device. 🌸

LG_INITIAL_STATE

This variable can be used to specify an initial state the device is known to be in. This is useful during development. The Strategy used must implement the force() method. A desired state must be set using LG_STATE or -s/--state. 🧚

LG_ENV

This variable can be used to specify the configuration file to use without using the --config option, the --config option overrides it. 📝

LG_COORDINATOR

This variable can be used to set the default coordinator in the format HOST[:PORT] (instead of using the -x option). 🛰️

LG_PROXY

This variable can be used to specify a SSH proxy hostname which should be used to connect to the coordinator and any resources which are normally accessed directly. 🔐

LG_HOSTNAME

Override the hostname used when accessing a resource. Typically only useful for CI pipelines where the hostname may not be consistent between pipeline stages. 🖥️

LG_USERNAME

Override the username used when accessing a resource. Typically only useful for CI pipelines where the username may not be consistent between pipeline stages. 🙋‍♀️

LG_SSH_CONNECT_TIMEOUT

Set the connection timeout when using SSH (The ConnectTimeout option). If unspecified, defaults to 30 seconds. ⏰

LG_AGENT_PREFIX

Add a prefix to .labgrid_agent_{agent_hash}.py allowing specification for where on the exporter it should be uploaded to. 📤

🦋 MATCHES 🦋

Match patterns are used to assign a resource to a specific place, fr fr. The format is: exporter/group/cls/name — exporter is the name of the exporting machine, group is a name defined within the exporter, cls is the class of the exported resource and name is its name. Wild cards in match patterns are explicitly allowed — * matches anything. ✨

💜 ADDING NAMED RESOURCES 💜

If a target contains multiple Resources of the same type, named matches need to be used to address the individual resources. In addition to the match taken by add-match, add-named-match also takes a name for the resource. The other client commands support the name as an optional parameter and will inform the user that a name is required if multiple resources are found, but no name is given. 👀

If one of the resources should be used by default when no resource name is explicitly specified, it can be named default. 💅

🌟 EXAMPLES 🌟

To retrieve a list of places run:

$ labgrid-client places

To access a place, it needs to be acquired first, this can be done by running the acquire command and passing the placename as a -p parameter:

$ labgrid-client -p <placename> acquire

Open a console to the acquired place:

$ labgrid-client -p <placename> console

Add all resources with the group "example-group" to the place example-place:

$ labgrid-client -p example-place add-match */example-group/*/*

👀 SEE ALSO 👀

labgrid-exporter(1)

🎀 AUTHOR 🎀

Jan Luebbe, Rouven Czerwinski

💖 COPYRIGHT 💖

2016-2025 Pengutronix, Jan Luebbe and Rouven Czerwinski

and that's a wrap bestie, you ate this whole page fr fr 🫶 this is the LABGRID-CLIENT(1) manual, dated 2025, and it's living its best life in the labgrid source tree ✨ go forth and slay your hardware 💅🌈

📦 where this page comes from

ubuntu stonking: labgrid-client 26.0-2 · LGPL-2.1-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-02: a language model's rewrite of the original, under its terms