CLI reference

Every pipo command, generated from the CLI's own command table, so it matches pipo help <command>. From a checkout of the repository, run the CLI as bun pipo ….

Global behaviour#

--json: every command except pipo run (which streams the foreground runner's log) prints one JSON document for scripts and agents. A failure is {"ok": false, "error", "hint", "code"} with exit code 1.
Plain output: on a terminal, output has colour, ✔/▲/✖ symbols and spinners. --plain (any command), PIPO_PLAIN=1, NO_COLOR, CI, TERM=dumb, --json and output that isn't a terminal all give the stable plain format.
The engine starts on demand: commands that need the control plane start it when it isn't running. --no-engine talks to detached runners directly through their sockets instead (see The engine).
--home <dir>: the Pipo home, ~/.pipo by default, or PIPO_HOME.
Help: pipo help <command>, pipo <command> --help or -h.

Area	Commands
Create and validate	`check` · `fmt` · `test` · `schema` · `new` · `generate` · `templates` · `trust` · `compile`
Run	`run` · `start` · `stop` · `pause` · `resume` · `restart`
Observe	`status` · `logs` · `runners` · `attach` · `packets` · `inspect`
Recover	`dlq` · `rerun` · `push` · `ack` · `resolve`
Versions and proposals	`history` · `diff` · `rollback` · `proposals`
Engine and dashboard	`engine` · `ui` · `owner` · `help`
Other	`approvals` · `mcp`

Create and validate#

pipo check#

Validate .pipo files (default: every .pipo under the current directory).

pipo check [file|dir …] [--json]

Flag	Meaning
`--json`	Machine-readable output for scripts and agents

pipo fmt#

Rewrite .pipo files in the canonical format (default: every .pipo under the current directory).

pipo fmt [file|dir …] [--check] [--json]

Flag	Meaning
`--check`	Change nothing; exit 1 and list the files that would change
`--json`	Machine-readable output for scripts and agents

See also: Templates and generators.

pipo test#

Run a pipeline's fixtures in-process (outputs mocked, agents stubbed) and compare with snapshots.

pipo test <file|dir> [--fixtures dir] [--update-snapshots] [--json]

Flag	Meaning
`--fixtures <dir>`	Fixtures folder (default <pipeline folder>/fixtures; run-wide stubs in its stubs.json)
`--update-snapshots`	Rewrite snapshots that differ (a missing one is always written)
`--home <dir>`	Pipo home, for fn trust (default ~/.pipo, or PIPO_HOME)
`--json`	Machine-readable output for scripts and agents

pipo schema#

Print the .pipo JSON Schema.

pipo schema

pipo new#

Create a pipeline folder from a template (default: blank).

pipo new <name> [--template <t>] [--set key=value …] [--dir <path>] [--json]

Flag	Meaning
`--template <t>`	Template name (see 'pipo templates'); default blank
`--set key=value`	Template variable; repeatable. Without it the template's default is used
`--dir <path>`	Folder to create (default ./<name>); must be missing or empty
`--home <dir>`	Pipo home, where ~/.pipo/templates is looked up (default ~/.pipo, or PIPO_HOME)
`--json`	Machine-readable output for scripts and agents

See also: Templates and generators.

pipo generate#

Insert a node into a pipeline, before its output.

pipo generate node <pipeline> <id> --kind <kind> [--from <node>] [--json]

Flag	Meaning
`--kind <kind>`	tap, transform, filter, route or agent
`--from <node>`	Upstream: input, a node, or a route branch (default: whatever feeds the output)
`--use <value>`	Which tap/transform/agent, e.g. http, or fn.<name> (default log / map / claude_api)
`--json`	Machine-readable output for scripts and agents

See also: Templates and generators.

pipo templates#

List templates for 'pipo new' (project, home and built-in).

pipo templates [--json]

Flag	Meaning
`--home <dir>`	Pipo home (default ~/.pipo, or PIPO_HOME)
`--json`	Machine-readable output for scripts and agents

See also: Templates and generators.

pipo trust#

Trust a template's fn modules (by content hash), or re-accept a scaffolded project you edited.

pipo trust <template|project-folder> [--home <dir>] [--json]

Flag	Meaning
`--home <dir>`	Pipo home, where trust.json is kept (default ~/.pipo, or PIPO_HOME)
`--json`	Machine-readable output for scripts and agents

See also: Templates and generators.

pipo compile#

Advanced, used by the runner: check a pipeline and print its compiled form as JSON (diagnostics, definition, bundled fn module, schemas, file hashes).

pipo compile <file.pipo> [--home <dir>] [--stdin]

Flag	Meaning
`--home <dir>`	Pipo home: trust.json and config.yaml (default ~/.pipo, or PIPO_HOME)
`--stdin`	Read the source from stdin; <file.pipo> only names it and anchors relative paths

Run#

pipo run#

Run a pipeline in the foreground until Ctrl-C (drains; twice stops).

pipo run <file> [--listen <port>] [--home <dir>] [--env-allow A,B]

Flag	Meaning
`--listen <port>`	Serve the HTTP input on this port
`--home <dir>`	Pipo home (default ~/.pipo, or PIPO_HOME)
`--env-allow A,B`	Environment variables exposed to expressions as env (engine.env_allow)

pipo start#

Start a pipeline (starts the engine on demand).

pipo start <file|name> [--ttl 30m] [--detached] [--listen <port>]

Flag	Meaning
`--ttl <duration>`	Lifetime for this start, e.g. 30m: replaces lifetime.ttl and outlives crash restarts (a later start without it uses the file's)
`--detached`	Keep running if the engine dies
`--listen <port>`	HTTP input port, 1 to 65535 (saved in the runner registry)
`--home <dir>`	Pipo home (default ~/.pipo, or PIPO_HOME)
`--no-engine`	Do not use the engine: start and restart refuse (they need it), with a hint
`--json`	Machine-readable output for scripts and agents

pipo stop#

Stop a pipeline (drains unless --now).

pipo stop <name> [--now]

Flag	Meaning
`--now`	Stop at once
`--home <dir>`	Pipo home (default ~/.pipo, or PIPO_HOME)
`--no-engine`	Do not use the engine: talk to the runners' control sockets; output says engine: down
`--json`	Machine-readable output for scripts and agents

pipo pause#

Pause a pipeline (it keeps accepting packets into the journal).

pipo pause <name>

Flag	Meaning
`--home <dir>`	Pipo home (default ~/.pipo, or PIPO_HOME)
`--no-engine`	Do not use the engine: talk to the runners' control sockets; output says engine: down
`--json`	Machine-readable output for scripts and agents

pipo resume#

Resume a paused pipeline.

pipo resume <name>

Flag	Meaning
`--home <dir>`	Pipo home (default ~/.pipo, or PIPO_HOME)
`--no-engine`	Do not use the engine: talk to the runners' control sockets; output says engine: down
`--json`	Machine-readable output for scripts and agents

pipo restart#

Stop a pipeline, then start the same file again.

pipo restart <name> [--ttl 30m] [--detached] [--listen <port>]

Flag	Meaning
`--ttl <duration>`	Lifetime for the new start, e.g. 30m: replaces lifetime.ttl and counts from the restart (without it, the file's)
`--detached`	Keep running if the engine dies
`--listen <port>`	HTTP input port, 1 to 65535
`--home <dir>`	Pipo home (default ~/.pipo, or PIPO_HOME)
`--no-engine`	Do not use the engine: start and restart refuse (they need it), with a hint
`--json`	Machine-readable output for scripts and agents

Observe#

pipo status#

Show pipeline status (a dash means the runner does not report it); with a name, also the oldest pending packet's age and latency per node.

pipo status [name] [--watch]

Flag	Meaning
`--watch`	Keep updating every 2 s
`--home <dir>`	Pipo home (default ~/.pipo, or PIPO_HOME)
`--no-engine`	Do not use the engine: talk to the runners' control sockets; output says engine: down
`--json`	Machine-readable output for scripts and agents

pipo logs#

Show a pipeline's log from /logs/.log.

pipo logs <name> [-f] [--node id]

Flag	Meaning
`-f`	Follow: keep printing new lines
`--node <id>`	Only lines that mention this node id as a whole word
`--home <dir>`	Pipo home (default ~/.pipo, or PIPO_HOME)
`--no-engine`	Do not use the engine: talk to the runners' control sockets; output says engine: down
`--json`	Machine-readable output for scripts and agents

pipo runners#

List every runner found in /run: pid, port, version and whether it is attached (works without the engine).

pipo runners

Flag	Meaning
`--home <dir>`	Pipo home (default ~/.pipo, or PIPO_HOME)
`--no-engine`	Do not ask the engine which runners it supervises; output says engine: down
`--json`	Machine-readable output for scripts and agents

pipo attach#

Scan again and reattach: adopt live runners, restart dead ones, clean stale entries (starts the engine).

pipo attach [name]

Flag	Meaning
`--home <dir>`	Pipo home (default ~/.pipo, or PIPO_HOME)
`--json`	Machine-readable output for scripts and agents

pipo packets#

List a pipeline's packets, newest first (from its journal when it isn't running).

pipo packets <name> [--state s] [--limit n] [--after id]

Flag	Meaning
`--state <s>`	Only packets in this state: accepted, processing, writing, verifying, delivered, filtered, dead_lettered, rejected, escalated, branched
`--limit <n>`	Packets per page, 1 to 1000 (default 50)
`--after <id>`	The next page: the id the previous page ended with
`--home <dir>`	Pipo home (default ~/.pipo, or PIPO_HOME)
`--no-engine`	Do not use the engine: ask the runner's control socket, or read the journal
`--json`	Machine-readable output for scripts and agents

pipo inspect#

Trace one packet through every node: data after each step, timings, attempts, errors.

pipo inspect <name> <packet_id>

Flag	Meaning
`--home <dir>`	Pipo home (default ~/.pipo, or PIPO_HOME)
`--no-engine`	Do not use the engine: ask the runner's control socket, or read the journal
`--json`	Machine-readable output for scripts and agents

Recover#

pipo dlq#

Show the dead-letter queue; replay packets at the step they failed on, or purge them.

pipo dlq [list] <name> | pipo dlq replay|purge <name> [ids…|--all]

Flag	Meaning
`--all`	Replay or purge every dead-lettered packet
`--limit <n>`	Dead letters per page, 1 to 1000 (default 50)
`--after <id>`	The next page: the id the previous page ended with
`--home <dir>`	Pipo home (default ~/.pipo, or PIPO_HOME)
`--no-engine`	Do not use the engine: talk to the runner's control socket (listing also reads the journal)
`--json`	Machine-readable output for scripts and agents

pipo rerun#

Run settled packets again from a node to the output, with the data they had there.

pipo rerun <name> --from <node> [ids…|--last n|--since 1h|--all] [--current] [--yes]

Flag	Meaning
`--from <node>`	The node to run again from, or output (required)
`--last <n>`	The newest n packets that passed the node
`--since <duration>`	Packets received in this window (30m, 1h, 7d); with --last, the newest n of them
`--all`	Every delivered or filtered packet that passed the node
`--current`	Run them on the version in force instead of their own (re-pins them)
`--yes, -y`	Run the plan; without it, only print what would run
`--home <dir>`	Pipo home (default ~/.pipo, or PIPO_HOME)
`--no-engine`	Do not use the engine: talk to the runner's control socket
`--json`	Machine-readable output for scripts and agents

pipo push#

Push one packet into a running pipeline; prints its packet id once it is journaled.

pipo push <name> --data '{…}'|--file f [--source s] [--input i]

Flag	Meaning
`--data <json>`	The packet's data, inline JSON
`--file <f>`	Read the packet's data (JSON) from a file
`--source <s>`	meta.source for the packet (default cli)
`--input <i>`	The input the packet is for, when the pipeline has several (spec §3.3.1)
`--home <dir>`	Pipo home (default ~/.pipo, or PIPO_HOME)
`--no-engine`	Do not use the engine: talk to the runner's control socket
`--json`	Machine-readable output for scripts and agents

pipo ack#

Acknowledge a packet waiting on delivered.check: external.

pipo ack <name> <packet_id>

Flag	Meaning
`--home <dir>`	Pipo home (default ~/.pipo, or PIPO_HOME)
`--no-engine`	Do not use the engine: talk to the runner's control socket
`--json`	Machine-readable output for scripts and agents

pipo resolve#

Settle packets handed to the agent (then: agent, on_stall: handle): retry, dead-letter or drop them.

pipo resolve <name> <id…> --action retry|dead_letter|drop [--reason "…"]

Flag	Meaning
`--action <a>`	retry, dead_letter or drop
`--reason <text>`	Why, kept in the journal
`--by <who>`	Who is acting (default the OS user)
`--home <dir>`	Pipo home (default ~/.pipo, or PIPO_HOME)
`--no-engine`	Do not use the engine: talk to the runner's control socket
`--json`	Machine-readable output for scripts and agents

Versions and proposals#

pipo history#

List a pipeline's versions: who made each, why, and packets still pinned to it (journal when stopped).

pipo history <name>

Flag	Meaning
`--home <dir>`	Pipo home (default ~/.pipo, or PIPO_HOME)
`--no-engine`	Do not use the engine: ask the runner's control socket, or read the journal
`--json`	Machine-readable output for scripts and agents

pipo diff#

Unified diff of two versions of a pipeline.

pipo diff <name> <v1> <v2>

Flag	Meaning
`--home <dir>`	Pipo home (default ~/.pipo, or PIPO_HOME)
`--no-engine`	Do not use the engine: ask the runner's control socket, or read the journal
`--json`	Machine-readable output for scripts and agents

pipo rollback#

Run an earlier version again, as a new version for new packets (in-flight packets keep theirs).

pipo rollback <name> <v>

Flag	Meaning
`--home <dir>`	Pipo home (default ~/.pipo, or PIPO_HOME)
`--no-engine`	Do not use the engine: talk to the runner's control socket
`--json`	Machine-readable output for scripts and agents

pipo proposals#

List, show, make, apply or reject change proposals (validated, dry-run, applied at the safe point).

pipo proposals <name> [show <id> | propose <file> | apply <id> | reject <id>] [--reason "…"]

Flag	Meaning
`--state <s>`	List only proposals in this state: validated, verified, applied, rejected
`--limit <n>`	List at most this many proposals, newest first (default 50, at most 1000)
`--reason <text>`	Why (propose, reject)
`--base <n>`	propose: the version the file was written against (default the current one)
`--hold`	propose: validate and store it, but apply it later with `apply`
`--by <who>`	Who is acting (default the OS user)
`--home <dir>`	Pipo home (default ~/.pipo, or PIPO_HOME)
`--no-engine`	Do not use the engine: ask the runner's control socket, or read the journal
`--json`	Machine-readable output for scripts and agents

Engine and dashboard#

pipo engine#

Start, stop, restart or inspect the engine (detached runners keep running when it stops; restart runs updated code).

pipo engine start|stop|restart|status [--ttl 8h] [--listen <port>] [--host <addr>]

Flag	Meaning
`--ttl <duration>`	start: the engine drains its pipelines and stops after this long, e.g. 8h
`--listen <port>`	start: gateway port on 127.0.0.1 (0 picks a free one; default engine.listen, else 0)
`--host <addr>`	start: bind 127.0.0.1 (default), or 0.0.0.0 / :: for every interface (needs engine.public_url; default engine.host)
`--home <dir>`	Pipo home (default ~/.pipo, or PIPO_HOME)
`--json`	Machine-readable output for scripts and agents

pipo ui#

Open the dashboard, starting the engine if needed.

pipo ui [--no-open] [--workspace <dir>]

Flag	Meaning
`--no-open`	Print the URL without opening a browser
`--workspace <dir>`	Where the builder saves new pipelines when it starts the engine (default: here)
`--home <dir>`	Pipo home (default ~/.pipo, or PIPO_HOME)
`--json`	Machine-readable output for scripts and agents

pipo owner#

Show the owner of this Pipo home, or set a new password (no old one needed; every dashboard session ends).

pipo owner [reset [--username <name>] [--password-stdin] [--rotate-key]]

Flag	Meaning
`--username <name>`	reset: rename the owner (needed when there is no owner yet: it creates one)
`--password-stdin`	reset: read the new password from stdin instead of asking twice
`--rotate-key`	reset: also replace <home>/engine.key, the key the CLI sends to the engine
`--home <dir>`	Pipo home (default ~/.pipo, or PIPO_HOME)
`--json`	Machine-readable output for scripts and agents

pipo help#

Show help for pipo or one command.

pipo help [command]

Other#

pipo approvals#

List pipelines agents wrote, and approve or reject them (approval lets the agent start them).

pipo approvals [approve <name> [--start] | reject <name> [--reason "…"]]

Flag	Meaning
`--start`	approve: start the pipeline too
`--reason <text>`	reject: why, shown to the agent
`--by <who>`	Who is deciding (default the OS user)
`--home <dir>`	Pipo home (default ~/.pipo, or PIPO_HOME)
`--json`	Machine-readable output for scripts and agents

pipo mcp#

List the agents connected to the MCP endpoint (OAuth grants and config tokens), or revoke a grant.

pipo mcp grants [revoke <id>]

Flag	Meaning
`--home <dir>`	Pipo home (default ~/.pipo, or PIPO_HOME)
`--json`	Machine-readable output for scripts and agents