Commands

pipelines [--repo <path>] <command> [options]

--repo, before the command, is the path to the data repo or to any of its subdirectories. If it's omitted, the engine uses PIPELINES_REPO; if that isn't set either, it looks for pipelines.yaml walking up from the current directory.

validate

pipelines validate [name] [--file <path>]

Validates the schema, the dependency graph (cycles), the {{...}} references in prompts, cwd, when (including when[].changed.path), run, additional_dirs and requires.env, that notify.channel exists, and five fixed rules on the shell text. Without name, it validates every pipeline in the repo. --file <path> validates a standalone YAML instead of an installed one. The rules and --file are explained in Surviving the night.

doctor

pipelines doctor <name> [--set key=value ...]

Checks that this machine can run the pipeline: agents, binaries, MCP servers (a real start-up plus live schema drift), environment variables, network resolution and, when the pipeline has agent steps, the Anthropic API key.

--set (repeatable) gives values to params, which the requires.env secrets whose name depends on params need. doctor also reads .params.local.json, so an installed pipeline resolves without --set; without either, each name it can't resolve shows as a red check.

On Linux it adds platform checks: the systemd user bus, linger, bash on the PATH and the time zone (on UTC it warns that schedules will be read in UTC). Platform checks are informational: they show in red when they fail but never make doctor or run fail.

install

pipelines install <name> [--set k=v] [--force] [--dry-run]

Installs the pipeline as a scheduled job from its triggers.cron: launchd on macOS, a systemd user timer on Linux. It writes the params to .params.local.json and the job files, derived and with no values inside. It computes the PATH from requires.bin and the mcp_servers commands, and checks that this PATH resolves everything needed (including the shell steps' interpreter: sh on macOS, bash on Linux) before writing anything. It warns about optional params without a value and the steps they affect.

It stops if doctor is red, if there's a suspicious foreign job and, on Linux, if linger is missing. --force skips those cut-offs, but still warns, never silently.

--dry-run goes through the same validations, prints the files it would write (on Linux, each one preceded by its path) and exits without touching anything: not the job files, not .params.local.json even if it gets --set, not the scheduler. A failing validation makes it fail all the same, so it's usable inside a script; the exception is linger, which the dry run shows but doesn't stop on.

The job freezes the absolute path of the engine's index.ts at install time: always install from the checkout that is going to persist. More in Scheduling.

uninstall

pipelines uninstall <name>

Unloads the job (always, even if its files no longer exist) and deletes its files if it finds them: the plist on macOS; the .service and the .timer on Linux. It never uses launchctl disable or systemctl mask, doesn't touch .params.local.json or the logs, and is idempotent.

run

pipelines run <name> [--set key=value ...] [--force]

Runs the pipeline now. --set is repeatable, to pass or override params. It evaluates requires (blocking) and the when: guards before starting; a skipped is a success, not an error. It holds an exclusive per-pipeline lock for the duration of the run.

--force skips the when: guards ("not today") but not requires, which measures whether this machine can run the pipeline. It warns on stderr and marks the run with forced: true. A forced run doesn't prove the guards would have let it through, and it anchors the throttle like any other run that executed.

resume

pipelines resume <name> <run-id>

Resumes a failed run from where it stopped, reusing its original params.

status

pipelines status [name] [-n, --limit <n>]

Lists the latest runs (5 by default) of one pipeline, or of all of them if the name is omitted: id, status, cost and skip reason if any.

show

pipelines show <name> <run-id> [step]

Dumps the full run record as JSON, or the record of one step if given, including denials if the step had any tool denied. The run record includes notify when the channel was invoked: channel, exit code, timestamp and the redacted tail of its output, also when the channel failed. The error of a failed shell step includes the last lines of its stderr. The fields are listed in What lives on disk.

web

pipelines web [-p, --port <n>]

Starts a local, read-only server over the repo and its runs: a health overview (with the next run of each pipeline and this month's spend), a costs page (/costs), a page per pipeline (with its spending caps), each run's detail (with the outputs of its agent steps) and the numbered log of each finished step. The overview and the run page update live while a run is in progress. It listens only on 127.0.0.1, with no flag to change that. Default port 7717. See The dashboard.

Exit codes

Designed so that a cron job or a script can act without parsing the output: