CLI overview

pikopod [command] [flags]

Every command accepts --config <path>, which defaults to ./pikopod.yaml. pikopod --version prints the version, commit and date. pikopod --help lists the commands in the six sections below; nothing is hidden, and every section is one --help away.

Exit codes

0 clean, 1 the check ran and failed, 2 pikopod or configuration error. See Exit codes.

Errors

Every error is one line on stderr: what failed, why, the next action, and a docs link.

error: no configuration found: pikopod.yaml does not exist → run `pikopod init` to scaffold one, or pass --config → https://github.com/pikopod/pikopod/blob/main/docs/config-reference.md

Sandbox

Command	What it does
`import`	Import a spec or a docs URL into a sandbox.
`up`	Serve the sandbox on `:4600` and the agent on `:4700`.
`mode set`, `show`, `clear`, `verify`	Put a running sandbox into a scenario’s standing state, and check what your tests sent against it.
`chaos`	Arm a fault on a running sandbox.
`rule list`, `add`, `drop`, `check`	Answer a declared operation by rule when the request or stored state looks a certain way.
`webhook emit`, `list`	Fire a declared event; inspect deliveries.
`requests`	What a running sandbox received; `--explain` replays one request with decision tracing.
`reproduce`	Turn a recorded production failure into a scenario and run it.

Scenarios

Command	What it does
`scenario list`, `check`, `create`, `from-drift`, `from-recordings`	Bind, check and generate scenarios.

CI

Command	What it does
`spec-diff`	Diff two spec versions. Exit 1 on breaking changes.

Observe

Everything the observing agent learns lives under pikopod agent.

Command	What it does
`agent incidents`, `agent incidents export`	Read the event log; export a bundle.
`agent status`, `report`, `inspect`	Health, inventory, and stored records.
`agent ack`, `accept`, `baseline reset`	Manage alerts and baselines.
`agent conformance`	Does the provider obey its own spec?
`agent contract`	The effective contract and the observed state machine.
`agent spec-update`	Write a traffic-evidenced spec update.
`agent truthfulness`	Score the sandbox against what the provider really sent.
`agent volatile suggest`	Suggest and lint `volatile_fields`.
`agent replay --ci`	Gate builds offline on recorded traffic.

Setup

Command	What it does
`init`	Scaffold `pikopod.yaml`.
`doctor`	Verify config, data dir, ports and upstreams.
`demo`	One lap of the loop in a second, zero config.
`mcp`	Serve the checks to a coding agent.

Command	What it does
`fix`	Drift to code change.
`pr comment`, `pr open`	Post findings on a pull request, or open one.
`sandbox add`, `list`, `reset`, `webhooks`	Manage sandboxes.

Old spellings

This release still accepts the previous spellings, each printing one line on stderr naming the new one: the twelve observe commands at the top level (pikopod incidents, pikopod status, and so on), pikopod sandbox requests, pikopod why, pikopod scenario reproduce, and pikopod scenario run. The new command’s --help names its old spelling.

What needs what

Needs	Commands
`pikopod up` running	`agent status`, `agent accept`, `chaos`, `mode`, `webhook`, `requests`, and the MCP control tools. `agent ack` works offline too.
A model key	`scenario create`, `fix`, and `import` from a docs URL that has no spec any other way.
A git repository	`pr open`, `pr comment`, `fix --pr`, and `spec-diff` with a `git:` source.
No config file at all	`demo`, `spec-diff`, `pr comment`, `pr open`.

CLI

Interfaces

Schemas

Exit codes

Errors

Sandbox

Scenarios

CI

Observe

Setup

More

Old spellings

What needs what

​Exit codes

​Errors

​Sandbox

​Scenarios

​CI

​Observe

​Setup

​More

​Old spellings

​What needs what

Exit codes

Errors

Sandbox

Scenarios

CI

Observe

Setup

More

Old spellings

What needs what