CLI

Every piloop command and its options.

Run piloop --help for the list of commands, and piloop <command> --help for the options of one command.

Many commands take a REF: a project name, or a path inside the project’s repo. Without a REF, piloop status and piloop history use the project of the current directory, else the only active project, else every project. piloop inbox, piloop inbox wait and piloop watch cover every project.

Commands that write sign their writes with PILOOP_ACTOR (human by default). See Environment variables.

Set up

piloop init

piloop init [PATH] [--example enwik8|titanic-tracks]

Makes PATH (default .) a piloop project and registers it. It is safe to run again.

• Runs git init and makes a baseline commit when necessary.
• When there is no piloop.toml, writes piloop.toml, brief.md and evaluate.py from the template. It keeps files that exist already. While evaluate.py is the unchanged stub, it stops and says what to edit.
• Measures HEAD as the baseline candidate and registers the project. When the project is registered already, it reads piloop.toml again.

--example creates a bundled example instead of the blank template.

piloop install-skills

Copies the skills of this CLI into the skill directory of every harness on your PATH: ~/.claude/skills for Claude Code (or $CLAUDE_CONFIG_DIR/skills), and ~/.agents/skills for Codex, pi, Gemini CLI and Cursor. It replaces only piloop’s own skills. The installer and piloop upgrade run it.

piloop doctor

Checks the install, without changing anything. Each failure says how to fix it, often with the command to run. See Upgrading.

piloop upgrade

piloop upgrade [--timeout SECONDS]

Upgrades the CLI, the skills and the database, and restarts a running daemon in place. --timeout (default 30) is how long to wait for the daemon to come back. See Upgrading.

piloop migrate

Brings the database to the schema of this CLI and prints what changed. The daemon and every command that reads or writes projects do this silently when they start. piloop doctor and piloop sql do not.

The daemon

piloop serve

piloop serve [--detach]

Runs the daemon in the foreground. --detach starts it in the background, with its output in $PILOOP_HOME/serve.log. Only one daemon runs for each PILOOP_HOME.

piloop stop

piloop stop [--timeout SECONDS]

Sends SIGTERM to the daemon and waits up to --timeout seconds (default 30) for it to exit. The daemon stops the running agents, and their runs fail with daemon stopped. The projects stay active, and the next piloop serve continues them. A campaign ends only at its [stop] limits.

piloop restart

piloop restart [--timeout SECONDS]

Restarts the running daemon in place on the installed code. The process keeps its pid, its environment and its service manager. The running agents continue, and the new code connects to them again. --timeout (default 30) is how long to wait for the daemon to come back.

piloop service-unit

Prints a systemd user unit (Linux) or a launchd agent (macOS) that keeps piloop serve running. It installs nothing. See Running for days.

Ideas and candidates

piloop idea add

piloop idea add REF TITLE [options]

Adds a defined idea. A ready idea runs when a worker slot is free, in order of priority.

Option	Meaning
--hypothesis	Why the idea should help, and by how much.
--plan	Concrete steps for the worker.
--from	What prompted the idea, with ids or a URL.
--family	The mechanism family. Ideas that try the same mechanism share it.
--priority	0 (urgent) to 4 (someday). Default 2.
--harness	Pin a harness instead of the rotation.
--base	The candidate id to start from, instead of the head.
--proposed	Wait for a human to approve the idea.
--track	The track. Required when the project has several.
--after	An idea to wait for. Repeat it for several.
--supersedes	An idea that this one refines. Repeat it for several.

Research, the orchestrator and humans add ideas. A watchdog files a seed with piloop idea seed instead, and a worker files neither.

piloop idea seed

piloop idea seed REF HUNCH --from POINTERS [--base CANDIDATE] [--track TRACK]

Files a seed: a hunch in one line, with pointers to what prompted it. The research agent develops it into an idea, or rejects it. See Seeds.

piloop idea develop

piloop idea develop IDEA_ID --hypothesis … --evidence … --check … --metric … --effect … [options]

Develops a seed into a defined idea. Every one of these is required:

Option	Meaning
--hypothesis	The mechanism, and why it should move the metric.
--evidence	What supports it, with ids and paths.
--check	The cheapest measurement that could kill it, and the result that stops the run.
--metric	What decides success: the primary metric, or the part of it that the idea targets.
--effect	The expected size of the effect, in the metric’s units, and why.

Optional: --plan, --title, --family, --base, --priority (default: the seed’s) and --proposed.

piloop candidate import

piloop candidate import REF COMMIT [--summary TEXT]

Registers the tree of a commit, branch or tag of the repo as a reference candidate: a starting point that an idea can pin with --base. The daemon measures it. It is never kept, never the head and never a bar. To import a candidate of another project, fetch its commit into this repo first: git fetch <its repo> <sha>.

piloop candidate note

piloop candidate note CANDIDATE_ID REASON [--follow-up HUNCH]... [--track TRACK]

Keeps a measured discard or interesting candidate in view as a starting point. Its verdict becomes interesting, and its reason becomes note: <REASON>, followed by the earlier reason. Each --follow-up files a seed pinned to the candidate. See Notes.

Status and the inbox

piloop status

piloop status [REF]

Prints the daemon’s state, then for each project: the head, the tracks, the trajectory, the progress against [stop], the open runs, the queue, the running agents with their last line, the recent candidates, the anomalies, the inbox, the latest decisions and the recent events. The watchdog and research agents get the same overview in their brief.

piloop watch

piloop watch [REF]

Shows the campaign on one screen, with keys to act on it. See Watching a campaign.

piloop history

piloop history [REF]

Prints the research pack: the metrics, the ideas by source, the analysis files, what was tried for each mechanism, the latest 60 ideas with their outcomes, the kept lineage, the findings, the digests and the open escalations. A research sweep reads it before it proposes ideas.

piloop inbox

piloop inbox [REF] [--kind KIND]... [--all]

Lists the unacknowledged items addressed to you, most urgent first, then the seeds that wait for research. --kind keeps only items of the given kind: note, finding, decision or escalation. Repeat it to keep several kinds. --all includes acknowledged items. See The orchestrator and the inbox.

piloop inbox show

piloop inbox show COMMENT_ID

Prints one item, then the comments linked to it: the comments it cites, the comments that cite it, and its replies.

piloop inbox ack

piloop inbox ack IDS...
piloop inbox ack --up-to ID [--project REF] [--kind KIND]...

Marks items as seen. --up-to marks every unacknowledged item up to that id instead. With --up-to, --project keeps only the items of one project, and --kind keeps only the items of the given kinds. With IDS, --project and --kind are refused. Nothing waits on an acknowledgement. To revise a decision, write a decision comment on its target.

piloop inbox wait

piloop inbox wait [REF] [--after EVENT_ID] [--timeout SECONDS]

Blocks until something needs the orchestrator, then prints it, one line each, and the command for the next wait. It returns for a new inbox item that someone else wrote, a seed that someone else filed, a project that the daemon stopped, an anomaly that the daemon gave to a watchdog, and the daemon’s verdict on a measured candidate. --after is the cursor that the last wait printed (default: now). --timeout (default 1800) is how long to wait before it returns with nothing. Set the timeout of your shell tool above it.

Agents

piloop launch

piloop launch REF ROLE [--harness NAME] [--model MODEL] [--reason TEXT] [--scout]

Asks the daemon for one more agent of ROLE: watchdog, research or a role that you defined. The daemon starts it on its next tick, within the role’s max_concurrent. --scout asks for a research sweep in scout mode. Only the daemon starts workers, because a worker needs a run.

piloop attach

piloop attach WORKER_ID

Focuses the agent’s tab in the piloop Herdr session and attaches this terminal to it. This needs the Herdr runtime.

piloop prompt

piloop prompt WORKER_ID TEXT

Types TEXT into a running agent of any role. This needs the Herdr runtime. The worker ids are in piloop status.

The database

piloop sql

piloop sql STATEMENT

Runs one SQL statement against the piloop database. Schema changes, transactions, ATTACH and all but the read-only PRAGMAs are denied. So are writes to piloop’s internal tables and to the full-text indexes. Everything else, including DELETE, is allowed. The output stops at 500 rows. See the database schema.

piloop schema

Prints what piloop sql accepts, the conventions for writing to the database, and every table. Agents read it before they write.