capa gui¶

Audience: operators. Scope: launch the PySide6 GUI. The headless runtime sits underneath unchanged; the GUI is the visualization and command surface on top of it.

$ capa gui --help
Usage: capa gui [OPTIONS] [CONFIG]

  Launch the GUI. Loads the optional config if provided; otherwise opens
  empty and the operator picks a config via File > Open.

Arguments:
  CONFIG  Optional experiment config to preload.

Options:
  --runs-root    PATH  Where to write bundles. Default: $CAPA_RUNS_ROOT or ./runs.
  --plugins-lock PATH  plugins.lock for procedure trust; mirrored into the manifest.
  --help               Show this message and exit.

What it does¶

Starts the qasync bootstrap (Qt event loop merged with asyncio), loads PySide6, and opens the main window. If CONFIG is provided, the Setup tab opens with that experiment already loaded; otherwise the welcome screen lets the operator pick one from File → Open or Try a simulator.

The conductor / worker-pool stack underneath is the same one capa run uses. The GUI does not replace the runtime — it talks to the same conductor through the ManualClient surface described in the runtime architecture doc.

Lazy-imported PySide6: if you run anything other than capa gui (or capa run --gui), the GUI dependency is not loaded. This is why headless CI can run on a machine without a working Qt platform plugin.

Synopsis¶

# Empty welcome screen — pick a config from File > Open
uv run capa gui

# Launch with a config preloaded
uv run capa gui configs/experiments/sim_freerun.yaml

# Custom runs root
uv run capa gui --runs-root /data/runs

# Equivalent — `capa run --gui` dispatches to the same path
uv run capa run configs/experiments/sim_freerun.yaml --gui

Flags¶

Flag	Default	Meaning
`CONFIG` (positional, optional)	none	Preload this experiment YAML on launch. Omit to open empty.
`--runs-root PATH`	`$CAPA_RUNS_ROOT` → `./runs`	Where the GUI writes bundles.
`--plugins-lock PATH`	auto-discovery	`plugins.lock` to enforce. See plugins-lock resolution.

Exit codes¶

The GUI returns the underlying Qt exit code:

Code	Meaning
0	Clean shutdown via the window close button or File → Quit.
2	Initial config refused at launch.
other non-zero	An uncaught Qt or runtime error. Check the log.

The headless exit-code table from capa run does not apply here — the GUI does not collapse a run outcome into a process exit code, because the operator can run many sessions in one launch. Use capa catalog list to inspect outcomes after the fact.

What the GUI shows¶

A quick orientation; the dedicated pages have screenshots and the deep tour:

Setup tab — experiment/hardware editor, validation problems panel, connection strip. See the Setup tab.
Method tab — method-step editor for ramped/multi-step runs. See the Method tab.
Run tab — live plots, state badge, start/stop, manual cards. See the Run tab.
Status bar — saturation, loop, queue depth, current bundle path. See status bar guide.
Diagnostics dock — internal metrics; hidden by default. See diagnostics dock.