> ## Documentation Index > Fetch the complete documentation index at: https://piloop.autoresearch.inc/llms.txt > Use this file to discover all available pages before exploring further. # CLI > Every piloop command and its options. Run `piloop --help` for the list of commands, and `piloop --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](/reference/environment). ## Set up ### piloop init ```text theme={null} 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. * Copies the documents that `[memory] documents` names into the database. See [research memory](/concepts/research-memory). `--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](/guides/upgrading#check-the-install). ### piloop upgrade ```text theme={null} 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](/guides/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 ```text theme={null} 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 ```text theme={null} 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 ```text theme={null} 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](/guides/running-for-days#under-a-service-manager). ## Ideas and candidates ### piloop idea add ```text theme={null} 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 ```text theme={null} 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](/concepts/ideas-and-runs#seeds). ### piloop idea develop ```text theme={null} 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 ```text theme={null} 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 `. ### piloop candidate note ```text theme={null} 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: `, followed by the earlier reason. Each `--follow-up` files a seed pinned to the candidate. See [Notes](/concepts/verdict#notes). ## Status and the inbox ### piloop status ```text theme={null} 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 ```text theme={null} piloop watch [REF] ``` Shows the campaign on one screen, with keys to act on it. See [Watching a campaign](/guides/watch). ### piloop history ```text theme={null} 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 ```text theme={null} 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](/concepts/orchestrator). ### piloop inbox show ```text theme={null} 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 ```text theme={null} 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 ```text theme={null} 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. ### piloop wake ```text theme={null} piloop wake [--budget TOKENS] ``` Prints what an orchestrator session needs first, in a fixed budget (default 2000 tokens, about 4 characters each; 0 prints nothing): the latest lines of the journal, the open inbox, the head of each active project, and the current lessons on their repos. Each section says how to read what did not fit. Run it at the start of every orchestrator session. ### piloop journal ```text theme={null} piloop journal LINE ``` Adds one line, at most 280 bytes, to the orchestrator's journal: a decision, a plan or a result, with its ids. The journal is append-only. `piloop wake` prints the latest lines, so that a new session picks up where the last one stopped. ## Agents ### piloop launch ```text theme={null} 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](/concepts/roles#define-a-role). The daemon starts it on its next tick, within the role's `max_concurrent`. `--scout` asks for a research sweep in [scout mode](/concepts/roles#scout-mode). Only the daemon starts workers, because a worker needs a run. ### piloop attach ```text theme={null} 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 ```text theme={null} 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 ```text theme={null} piloop sql STATEMENT ``` Runs one SQL statement against the piloop database. Schema changes, transactions, `ATTACH` and all but the read-only `PRAGMA`s 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](/reference/schema). ### piloop schema Prints what `piloop sql` accepts, the conventions for writing to the database, and every table. Agents read it before they write. ## The workspace archive ### piloop restore ```text theme={null} piloop restore REF [IDEA | PATH] ``` Writes archived workspace files back into the project's workspace. `IDEA` (`12` or `idea#12`) restores the files of that idea. `PATH` restores one workspace-relative file or everything under a directory. With neither, it restores every archived file. A file that is already there with other content is kept and listed, never overwritten. See [The artifact store](/concepts/artifact-store). ### piloop store status Prints what the store holds (blobs, their local size, how many are on the remote), how much of each project was archived, and how many done ideas and stopped projects are still due. ### piloop store evict Uploads the blobs that the remote does not have yet, then drops local copies as `[storage]` says. The daemon does this every hour. ### piloop store verify ```text theme={null} piloop store verify [REF] ``` Checks that the store holds every blob of every archive: local copies are hashed again, evicted ones are looked up on the remote. Exits non-zero when one is missing or corrupt. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.