CLI
Last updated on November 20, 2026
Learn how the TofuPilot CLI runs every subcommand for procedures, runs, units, stations, and the REST API from a single binary on macOS, Linux, and Windows.
The tofupilot CLI is a single binary that runs procedures locally, manages every resource through the REST API, and powers a factory Station when installed as a system service. You get one binary, one credential file, and a consistent flag layout across every subcommand.
The CLI is free to download and install on any machine, and tofupilot run ./procedure.yaml executes a procedure locally without an account. Running a pulled deployment instead needs one. Commands that read or write data on TofuPilot need tofupilot login, or a TOFUPILOT_API_KEY in the environment on a CI runner.
Install
The CLI runs on macOS, Linux, and Windows, and you install it with a one-line script.
curl -fsSL https://www.tofupilot.app/install | sh$p = "$env:TEMP\tp-install.ps1"; irm https://www.tofupilot.app/install.ps1 -OutFile $p; powershell -ExecutionPolicy Bypass -File $p; ri $p -EA 0After install, run tofupilot --help to see every subcommand, or jump straight into tofupilot login to authenticate.
tofupilot login
Authenticate the CLI and start using every subcommand.
tofupilot run
Execute a procedure locally with the same operator UI as a station.
Station
Install the CLI as a system service on a factory bench.
JSON output
The commands that return data accept --json, which switches output to machine-readable JSON on stdout: run, validate, plug, init, agents-md, docs, doctor, the API commands (runs, units, …), queue, whoami, deploy, build, pull, link, unlink, config, env, and service status. Put it after the subcommand. Errors become a single {"type":"error","code":"...","message":"..."} object on stdout (with action when there is a next step, and a problems list when several problems are refused together), and tofupilot run --json emits an NDJSON event stream on stdout, one event per line.
tofupilot runs ls --limit 5 --jsonCoding agents
A coding agent (Claude Code, Codex, Cursor) needs nothing but the CLI to write and test a procedure. tofupilot init creates a project that runs offline, with an AGENTS.md that tells the agent the loop and where the docs are (tofupilot agents-md adds it to an existing project). The agent reads the framework docs at the CLI's version with tofupilot docs and the procedure schema with tofupilot schema, checks its work with tofupilot validate --json, runs it with tofupilot run --json and simulated plugs, calls an instrument with tofupilot plug, and inspects the Python environment with tofupilot doctor. For commands that reach the dashboard, the user runs tofupilot login (--org <slug> with several organizations): it opens the browser with a code to approve, then logs in.
tofupilot init board-test && cd board-test && claudeEnvironment variables
| Variable | Effect |
|---|---|
TOFUPILOT_NO_UPDATE | Set to 1 or true to disable automatic update checks. |
TOFUPILOT_API_KEY | Authenticates the CLI without a stored login, for CI runners. Takes precedence over tofupilot login. Never written to disk. |
TOFUPILOT_URL | The dashboard TOFUPILOT_API_KEY belongs to. Defaults to https://www.tofupilot.app; set it for a self-hosted instance. |
TOFUPILOT_PROCEDURE_ID | The procedure a run --upload uploads to, in place of the tofupilot.json that tofupilot link writes. |
TOFUPILOT_NO_CI_METADATA | Set to 1 or true to stop run from adding the CI context to run metadata. |
TOFUPILOT_HOME | Absolute path used as the home directory for every CLI file (.tofupilot/ with the credentials, state database, pinned CA bundles, logs and attachments) instead of the user profile. Same behaviour on every OS. |
TOFUPILOT_LOCAL_UI_PORT | Overrides the default loopback port of the operator UI server. |
TOFUPILOT_AGENT_RULES | Set to 0 to stop validate and run from refreshing the AGENTS.md block under a coding agent. |
Framework detection
tofupilot run scans the procedure directory, picks the framework that fits, and runs the suite under a framework-specific connector that maps outcomes, Measurements, Logs, and Attachments to the dashboard.
The CLI walks the directory in a fixed order, and the first framework it recognizes wins.
procedure.yaml → TofuPilot Framework
openhtf in deps → OpenHTF
pytest config → Pytest
.robot files → Robot Framework
main.py only → Plain PythonWhen a repo carries both an OpenHTF suite and pytest tests, OpenHTF wins because pytest is assumed to be unit-test tooling for the OpenHTF code. When a repo carries pytest tests next to .robot files, pytest wins for the same reason.
How is this guide?
Phase Pareto
Rank test phases by failures, retries, and duration with TofuPilot Phase Pareto, then drill into the measurements behind each failure.
tofupilot agents-md
Learn how to give coding agents like Claude Code, Codex and Cursor the TofuPilot docs, schema and commands for your procedure project with AGENTS.md.