Coordinator address, in order: -x, then LG_COORDINATOR, then the active named coordinator, then coordinator in config.toml, then 127.0.0.1:20408. A bare host gets the default port. All files live in ~/.config/labgrid-tui/ ($XDG_CONFIG_HOME honoured); none needs to exist.

config.toml (hand-edited; labgrid-tui config init writes a commented template, config show prints every resolved value and its source):

coordinator = "coordinator.example.org:20408"   # or a named coordinator
prefix = "labgrid-client -x coordinator.example.org:20408"   # optional

[capabilities]
MyCustomResource = "power"        # resource class -> resource chip

[[commands]]                      # extra labgrid-client entries
category = "Custom"
label = "Ping DUT"
suffix = "ssh -- ping -c1 10.0.0.1"
class = "NetworkService"          # omit for a place-level entry

Named coordinators live in coordinators.toml, written by the tool: shift+p in the TUI (enter switch, n new, e edit, x delete) or labgrid-tui coordinator list|add|use|remove|show|edit. -x and coordinator accept a name from it as well as an address.

LG_PROXY is not supported: if it is set, labgrid-tui refuses to start. UI state (panels, theme) persists to ~/.local/state/labgrid-tui/ui.toml.

The six benches in labgrid-tui tour are a plausible real lab, written out in examples/lab/: exporter.yaml declares the serial, power and SSH resources for labgrid-exporter, and places.sh runs the labgrid-client calls that create the matching places and tag them.

A place carries a free-form tags dict (labgrid-client -p NAME set-tags board=imx8 env=dev site=lab1) and labgrid-tui shows it in one Tags column of key=value pairs. Each key gets a fixed slot, sized over the whole fleet, so the same key sits at the same column on every row; a pair every place shares is dimmed and is the first to go when the terminal runs out of room. Tag with whatever your lab sorts by; there is no fixed schema.

A pack is a TOML file of copy-only recipes. Register it explicitly; nothing is discovered on its own:

labgrid-tui pack add PATH|URL     # also: list, show, update, remove

A path is re-read on every start; an HTTPS URL is cached and refreshed by pack update. Each pack is its own tab in the command overlay (c) and its own palette group; enter copies, the TUI never executes a pack entry.

[pack]
name = "robot"

[[commands]]
label = "Smoke tests on this bench"
command = "robot -v PLACE:{place} -v DUT_IP:{res.NetworkService.address} tests/smoke"
requires = ["res.NetworkService"]

Placeholders: {place}, {coordinator}, {prefix}, {token} (your reservation for this place), {tag.KEY}, {res.CLASS.PARAM} (first matched resource of that class; PARAM may be name). requires items: res.CLASS, tag.KEY, held. An unmet requirement or an unresolvable placeholder greys the entry with the reason instead of failing. A full example ships in examples/robot.toml.

Plugins are Python modules registered under the labgrid_tui.plugins entry-point group that may define capabilities: dict[str, str] (resource class to capability) and commands: dict[str, tuple[CommandTemplate, ...]] (resource class to extra entries). A plugin that raises while loading is skipped with a warning.

Building a larger shell on top (authentication, another execution backend, extra status): every widget and screen takes its data through constructor arguments, LabgridTuiApp is subclassable, and every action is dispatched through one two-method protocol:

class ActionRunner(Protocol):
    def run(self, entry: CommandEntry) -> None: ...
    def copy(self, entry: CommandEntry) -> None: ...

Hand the widgets your own runner and the validity engine (which commands are offered, and why not) stays shared. Extra status-bar segments are Callable[[], str | None] providers on extra_status_segments. Unknown keys in coordinators.toml entries survive edits, so a shell can store its own per-coordinator data there. This surface may change before 1.0.

See CONTRIBUTING.md for the gate to run before opening a PR.

uv sync
uv run pre-commit install      # ruff check and format on every commit
uv run ruff check src tests
uv run mypy src
uv run pytest                  # unit and UI tests against a fake coordinator

• tests/model and tests/coordinator: pure logic and the gRPC layer.
• tests/ui: widgets and screens, driven through Textual's pilot.
• tests/integration: a real coordinator, excluded by default. Start one with docker run -d -p 20408:20408 labgrid/coordinator and run uv run pytest -m integration (LABGRID_TUI_TEST_COORDINATOR points elsewhere).
• scripts/generate-stubs.sh regenerates the gRPC stubs from the vendored proto.

Release: tag vX.Y.Z and push the tag. The version is derived from the tag at build time, and the publish workflow uploads to PyPI through trusted publishing.