Commands

the-loop --help
the-loop --version
the-loop --config path/to/cli-config.yaml <command>   # must precede the subcommand

The control plane

Since issue-161 every command below that touches the-loop's state runs through the control-plane service, which is the single implementation of each capability. It is started for you on first use, so nothing here needs setting up first.

Command	What it does
start	Bring up every service the CLI config enables — the control-plane service (+ /mcp), the webhook receiver, the poller.
stop	Stop every running the-loop service, whatever the enabled flags say now.
status	Per-service liveness and the poller's progress; exit 0 iff everything enabled is running.
restart	stop then start, optionally upgrading the CLI in between (--with-upgrade). Also POST /api/v1/restart.

Daemon commands

Long-running or machine-scoped. Their own settings come from the CLI config and from nowhere else — no repository configures the daemon (decision-044). When they act on a work item they still read that item's own checkout, the same way the repo-scoped commands do.

Command	What it does
sessions	The work-item ↔ session registry, execution control (start/pause/resume/stop), and reset — forget a work item's state so it starts over.
standing	The sessions the-loop keeps for itself — no work item, addressed by name: list, start, stop, restart, and say to talk to one.
instances	The fleet a manager serves: list on any instance; register / unregister on a manager, writing the registry through the same splice as the Settings tab.
ask	Post an agent's question on its work item — marker stamped centrally, wait recorded as session.awaiting_input.
comment	Post the agent's comment on its work item — marked, enveloped, mirrored to subscribed channels.
ticket	show a ticket (body, comments, attachment links) as JSON, create one, or close a registered work item's.
pr	create a pull request and link it in one act; status, checks (each check, with failed jobs' log tails), threads, resolve-thread, ready (a draft → ready for review), and merge (gated by routing.mergeOnApproval); lifecycle acts need a registered work item.
add-collaborator	Give one GitHub login a voice on one work item: their comments become input for its session, and nothing else.
remove-collaborator	Take that voice back; it lapses on the next event.
channels	Operate the conversation channels (the Slack bot): status, threads, one poll cycle, the Socket Mode listener (replies, buttons, the /the-loop command), or the app manifest to import.
events	Query the structured event log — the answer to "why did nothing happen?".

Repo-scoped commands

Run once, inside a checkout. They read the project's files and the operator's CLI config — never the project's harness config, which is the agent's (decision-123) — and are no part of the daemon (decision-032). They run with no cli-config.yaml at all, on defaults, which is what lets check run as a CI gate in a bare checkout (--spec-dir when the specs are not under docs/specs).

Command	What it does
check	Evaluate a work item's nodes against its checked-in artifacts. Pure: no network, no subprocess, no mutation — so CI runs the same code the runtime does.
graph	Inspect and drive the process graph: show, status, advance, run, force.
hooks	The lifecycle hooks your CLI config declares, importing nothing — and points, the catalog they can attach to.
critic	Hand a review round to a different harness and read back what it said, as one JSON envelope.
scenarios	The table of Gherkin scenarios the integration tests cover.
instructions	Which of the project's registered custom instruction docs actually resolve — and onMissing as an exit code.

Maintenance

Command	What it does
install	Install the-loop itself — the CLI and the Claude Code / Cursor plugin — at user or project scope. Plans, previews, and reports every step.
upgrade	The same plan, moving an installed CLI/plugin to the current version with the installer that owns it.
migrate-config	Migrate a cli-config.yaml to the current schema version. Deterministic, idempotent, previewable.

Global flags

--config PATH / -c PATH

The CLI config to use. Must precede the subcommand — the-loop --config x.yaml start, not the-loop start --config x.yaml. Same priority as $THE_LOOP_CLI_CONFIG; see where the file is found.

--version

The installed package version, read from package metadata — so it always reports what you actually have rather than a string someone forgot to bump.

Exit codes

Consistent across commands:

Code	Meaning
0	Success
1	Ran, and the answer is negative — a failed round, an unmet gate, a stopped run
2	Could not run — bad arguments, missing work item, unreadable config, or no reachable service

Adding one

Commands come from a registry, so a new one is three steps — see extending the CLI. A registered command with no page here fails the repository's test suite, which is why this table cannot quietly fall behind the code.