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.

macOS / Linux
curl -fsSL https://www.tofupilot.app/install | sh
Windows
$p = "$env:TEMP\tp-install.ps1"; irm https://www.tofupilot.app/install.ps1 -OutFile $p; powershell -ExecutionPolicy Bypass -File $p; ri $p -EA 0

After install, run tofupilot --help to see every subcommand, or jump straight into tofupilot login to authenticate.

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.

json output
tofupilot runs ls --limit 5 --json

Coding 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.

start a project for an agent
tofupilot init board-test && cd board-test && claude

Environment variables

VariableEffect
TOFUPILOT_NO_UPDATESet to 1 or true to disable automatic update checks.
TOFUPILOT_API_KEYAuthenticates the CLI without a stored login, for CI runners. Takes precedence over tofupilot login. Never written to disk.
TOFUPILOT_URLThe dashboard TOFUPILOT_API_KEY belongs to. Defaults to https://www.tofupilot.app; set it for a self-hosted instance.
TOFUPILOT_PROCEDURE_IDThe procedure a run --upload uploads to, in place of the tofupilot.json that tofupilot link writes.
TOFUPILOT_NO_CI_METADATASet to 1 or true to stop run from adding the CI context to run metadata.
TOFUPILOT_HOMEAbsolute 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_PORTOverrides the default loopback port of the operator UI server.
TOFUPILOT_AGENT_RULESSet 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 Python

When 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?

On this page