tofupilot run
Last updated on November 20, 2026
The run command executes a procedure. It takes an optional positional path to a procedure .yaml file, a directory, or a Python entry point, and runs that procedure locally without contacting the dashboard. Without a path, it runs the procedure in the current directory. To run a pulled deployment instead, pass --deployment. On a station, a bare tofupilot run from a directory without a procedure runs a pulled deployment, as it did before the current directory became the default.
tofupilot run ./procedures/pcb-fvt<PATH>
A positional argument that points to a procedure .yaml file, a directory, or a Python entry point. It defaults to the current directory, so tofupilot run and tofupilot run . are the same, except on a station when the current directory has no procedure.yaml or main.py. This conflicts with --deployment.
tofupilot run ./procedures/pcb-fvtWhen the path is a directory, the entry point is the procedure.yaml inside it, or main.py when there is none. A procedure file with another name is run by naming it: tofupilot run ./line3.yaml. When the path is a Python file, that file is the entry point, so a project with several procedures sharing one codebase can run any of them directly:
tofupilot run ./procedure1.pyThis is the local equivalent of the procedure's --entry-point setting, which deployed runs read from the deployment manifest.
--deployment [PROCEDURE_ID]
The --deployment flag runs a pulled deployment instead of a local path. Without a value, it picks from the pulled procedures: the only one when there is one, an interactive picker otherwise. To skip the picker and run one pulled procedure directly, pass the procedure ID. You cannot combine it with a path argument. Without a terminal, or with --json, there is no picker: with several pulled procedures and no procedure ID, the run lists them and exits with code 2.
The procedure ID stays the same when you push a new version, so a station script that pins it keeps working across deployments. You can read it from the procedure page in the dashboard, or from the ID column of tofupilot procedures ls.
tofupilot run --deploymenttofupilot run --deployment 550e8400-e29b-41d4-a716-446655440000--ui-values <FILE>
When you want to drive runs without an operator, pass a JSON file with pre-baked Operator UI values keyed by { phase_key: { component_key: value } }.
Pre-baked values are checked when the prompt opens, against the components declared in the procedure. A choice list the phase fills at run time with ui.set is empty at that moment, so its value cannot be pre-baked: answer that prompt with a ui_response after its ui_update arrives (see JSON events).
The file answers prompts whatever the operator surface: a plain headless run, the terminal UI, the kiosk, or --json. A prompt it answers is not shown. The unit identification form is the identify_unit key; a locked unit field needs no value. pytest, Robot Framework and OpenHTF procedures read the identify_unit entry too, and OpenHTF prompts are answered by the entry of their phase.
On a multi-slot run, one identify_unit entry answers every slot, so its serial number must contain {run.slot.key} or {run.slot.name} (formerly {slot} and {slot_name}), which expand to the slot key and its display name ("SN-{run.slot.key}"). An entry whose serial is the same for every slot is refused, unless the procedure locks the serial.
{
"identify_unit": { "serial_number": "SN-0001" },
"confirm": { "note": "ok" }
}On a run with no operator UI, a prompt the file does not answer fails its phase at once, and the phase error names the --ui-values entry to add. The file can live anywhere, a fixtures folder shared by several procedures for example. A file that is missing or not valid JSON is refused before the run as a usage error (exit 2, the error object with --json). On a YAML procedure, so is an entry for a phase or a field the procedure does not have, with the nearest key: a typo would leave its prompt unanswered.
A phase that calls ui.wait() gets the file values for its first prompt only. Its later prompts are asked like any prompt the file does not answer: on the operator UI (the kiosk, a browser tab or the printed URL), on the terminal UI, or as a ui_request on stdout with --json.
tofupilot run --ui-values phases.jsonOn a run with no operator surface (no --json, no TUI, and no UI: --no-ui, or a local path run without a terminal), a required prompt the file does not answer fails its phase right away instead of waiting.
--ui-timeout <SECONDS>
With --json, to time out phases waiting on required UI input, pass a number of seconds. The default is to wait forever, except under a coding agent with no other surface to answer (no kiosk or browser), where prompts expire after 120 s. The stderr line printed with each prompt names the deadline.
tofupilot run --ui-timeout 600--tui
The --tui flag shows the in-terminal operator UI. It is off by default for a local path, and always off with --json or without a terminal. A --deployment run follows the terminal_ui station config instead; a local-path run never reads station config. It conflicts with --no-tui.
tofupilot run ./procedure.yaml --tui--no-tui
The --no-tui flag hides the in-terminal operator UI.
tofupilot run ./procedure.yaml --no-tui--ui <MODE>
The --ui flag serves the Operator UI on http://127.0.0.1:7321 (or the port in TOFUPILOT_LOCAL_UI_PORT) for this run and shows it in one of three ways.
| Mode | Shows the UI | Use |
|---|---|---|
kiosk | Full screen, with no toolbars, as on a station (see Kiosk UI) | Operators at the bench |
browser | As a tab in the default browser | Developing a procedure |
headless | Nowhere: the CLI prints the URL | Default for a local path in a terminal; agents, CI, an SSH port-forward |
A local path in a terminal without --tui defaults to headless: the server starts and prints its URL, and nothing opens. If the port is taken (another run), or the station service owns it (kiosk_ui on), the default picks a free port instead and prints that URL; an explicit --ui fails on a taken port. Each prompt and unit identification form waiting for input prints its URL again (Waiting for operator input in <phase>: <url>). A run as root gets no default UI. Without a terminal there is no UI by default, so an unanswered prompt fails fast instead of waiting. With --json the prompt goes to the agent as a ui_request and waits for its ui_response on stdin; it fails once stdin is closed. A --deployment run follows the kiosk_ui station config, which means kiosk when on. The server stops when the run ends. It conflicts with --no-ui.
tofupilot run ./procedure.yaml --ui browser--no-ui
The --no-ui flag serves no operator UI, including on a --deployment run whose station has kiosk_ui on.
tofupilot run --deployment 550e8400-e29b-41d4-a716-446655440000 --no-ui--no-bootstrap
The --no-bootstrap flag skips the auto-bootstrap prompt for missing Python virtualenvs on local-path runs, so the run fails with the original Python resolution error instead of offering to provision a venv with uv venv and install dependencies.
tofupilot run ./procedure.yaml --no-bootstrap--upload
The --upload flag syncs a local-path run to the dashboard under the procedure it is linked to. It requires a tofupilot.json in the procedure directory (written by tofupilot link) or the TOFUPILOT_PROCEDURE_ID environment variable, which takes precedence. Without --upload, the run's results stay local. The flag does not change what the procedure can read: a phase or plug that takes dashboard acts as your CLI login either way. The flag is ignored for --deployment runs, which always upload.
tofupilot run ./procedures/pcb-fvt --upload--phase <KEY>
The --phase flag runs one main phase of a YAML procedure instead of the whole procedure. Setup and teardown still run, and so does every phase the target lists in depends_on, so the phase gets the plugs and the results it needs. Repeat the flag, or separate the keys with commas (--phase measure,flash, spaces allowed), to run several phases. tofupilot validate --json lists the phase keys, and the --ui-values entries each phase's prompts need.
tofupilot run . --phase measure_vout --ui-values answers.json --jsonA partial run never uploads: --phase cannot be combined with --upload or --deployment. The other troubleshooting flags below follow the same rule, and all of them need a TofuPilot Framework (YAML) procedure. A key the procedure does not have, a key given twice, a replacement plug class that does not exist or does not take the plug's with:, or flags that contradict each other, are refused before the run starts, as a usage error: exit code 2 and, with --json, one {"type": "error", "code": "usage"} object instead of a run stream.
--skip <KEY>
The --skip flag leaves a phase out of the run, as enabled: false would, without editing the YAML. Repeat it or separate keys with commas. A sequence call's key (--skip calibration) leaves out every phase of the call. A phase that only waits on it (depends_on) runs as it would after a failure. A phase that takes its result, a parameter named after it with no default (def measure(calibrate):), would start without it, so the run is refused and names that phase.
tofupilot run . --skip flash_firmware--force <KEY=pass|fail>
The --force flag records a phase as passed or failed without running its code. Repeat it or separate entries with commas (--force a=pass,b=fail); a sequence call's key forces every phase of the call. Use it to test what the procedure does after a pass or a failure (then: actions, on_first_failure, teardown) without making the hardware fail. A forced phase is never retried: its result would be the same on every attempt, so a then: … retry falls back to on_first_failure. The forced phase records no measurement and opens none of its plugs. With --json, its phase_finished carries forced, a skipped phase gets a phase_skipped with its reason, and a warning about a phase reading a forced result comes as an internal_warning. A phase that takes its result receives it without measurements, and the run says so before it starts.
tofupilot run . --force calibrate=fail--plug <KEY=REF>
The --plug flag replaces a plug's class for one run, typically with a simulator when the instrument is not on the bench. REF is written like the plug's python: in the YAML (plugs.mock_psu:MockPsu or plugs/mock_psu.py:MockPsu), and the plug's with: values are passed to the replacement unchanged.
tofupilot run . --plug psu=plugs/mock_psu.py:MockPsu--repeat <N|forever>
The --repeat flag runs the procedure N times (forever runs until you stop it), then prints the pass rate, the first run that did not pass, and for each measurement its minimum, maximum, mean and standard deviation across the runs. Each run is a complete run with setup and teardown. A plug declared scope: station stays connected from one run to the next. With --json, each run streams its events and a final repeat_summary line follows the last run_finished.
tofupilot run . --phase measure_vout --repeat 50 --until fail--until fail, --until pass or --until error stops after the first run with that outcome. --repeat cannot be combined with --ui kiosk or --ui browser, which would open the operator UI again for every run. Stopping a run (Ctrl-C or a signal) ends the loop, also between two runs or while the next one sets up its venv; so does a run that could not start (the procedure does not load, for example). A procedure that stops itself (phase.stop()) only ends that run. A run that could not start ends ERROR, with exit code 5 (see the exit code table). A refused flag stops the command before the first run. The exit code is the first run that did not pass, so a loop with one failure exits non-zero even if its last run passed; a loop that was stopped exits as the stop (130 for Ctrl-C, 143 for SIGTERM, 129 for SIGHUP), and a stop that lands before a run has recorded anything does not count that run. Answer prompts with --ui-values: with --json, stdin commands (abort_run, get_state, ui_response) go to the run under way, and one written between two runs reaches the next run, where a ui_response for an earlier prompt is refused (unknown_request).
--locals
When a phase raises an exception, --locals prints the variables of the innermost function of the procedure's own code where it raised (the phase, or a helper module of the procedure it called), and phase_finished carries them as locals with --json. Values are shortened. A variable whose name looks like a secret (password, auth_token, api_key…) is masked when it holds text, a number or a collection (a None, a bool or an object shows, with its own secret fields masked), and so are a password in a URL, a bearer token, a JSON Web Token, a value under a secret-looking key (a dict entry, an object's field, Password= in a connection string), and any declared secret value. These variables are never uploaded to the dashboard.
The flag is off by default: formatting a variable calls its __repr__, which on some instrument drivers talks to the device. It applies to TofuPilot Framework (YAML) procedures; other frameworks ignore it, with a warning.
tofupilot run . --phase measure_vout --localsStudio, the local editor tofupilot studio serves, invokes the same engine as tofupilot run, so a run behaves the same from either. Studio uploads a run only when you choose to; tofupilot run --upload does it from the terminal.
How is this guide?