008 cli

CLI reference

Every command dispatched by the looply binary, every flag it accepts, and which of them start a coding agent.

This page is the command surface of the harness: what a coding agent is put to work on, and what happens to the result. The binary is looply, installed from the looply-cli package, and every command below is one case in the switch statement in packages/cli/src/bin.ts. Nothing else is dispatched.

Every command

Anything else exits 64 and prints the usage text to stderr. Two of the cases above are dispatched without appearing in that usage text: agent, deliberately, because it is a surface for tooling rather than a step in anyone's workflow, and help, which is the thing printing the text.

Which commands call an agent

Three commands start a coding agent, and those are the three that cost money. The rest read files, talk to the server, or run the commands you configured. If you are unsure whether a command will spend anything, this table is the answer.

scan --dry-run still runs every lens and still costs money. It only skips writing to the queue and the ledger. run --dry-run is the opposite: it prints the plan, creates no branch, and calls nothing.

Flags

--no-color is the only global. It is stripped from the argument list before dispatch, so it works on any command in any position. Everything else is per-command, matched positionally by indexOf, so a flag that takes a value must be followed by that value. doctor, daemon, scan, verify and run all default --config to .looply/config.yaml; passing --config as the last argument with nothing after it prints the command's own refusal — run: --config needs a path — and exits 1. queue and stop take no --config at all: they read and write .looply/state directly and never load the config.

looply run

The branch name is looply/run- plus a 14-character UTC timestamp, computed in run-cmd.ts; the round runner is what actually creates it, so exactly one thing owns git. The run then loops until one of five things happens: the minimum hours elapse, the round cap is reached, the queue empties, a signal arrives, or a pause or stop is picked up from control.json between rounds — written there by looply stop on this machine, or by the daemon on a phone's behalf. Defaults from the config are 4 hours and 400 rounds. Two refusals happen before round one: a working tree with any changed path outside .looply stops the run, and so does a queue with nothing pickable — though if nothing is ready and there are drafts, the run verifies those first rather than refusing outright. When the run ends it prints the stop reason and the tally of rounds kept, discarded and abandoned — and if ten or more rounds ran with proof enabled and nothing was ever discarded, it says that a prover which never rejects is usually misconfigured.

# See what would happen. Costs nothing.
$ looply run --dry-run
project : tabsy
branch  : looply/run-20260816120447 (would be created from a1b2c3d)
budget  : 4h, up to 400 rounds
queue   : 12 ready
proof   : on
gates   : typecheck, test

dry run: would start with "...".
dry run: no branch created, no agent called.

stopped : command
rounds  : 0 — 0 kept, 0 discarded, 0 abandoned

# Then the real thing. The runner creates the branch.
$ looply run --hours 8
branch  : looply/run-20260816121502
base    : a1b2c3d
budget  : 8h, up to 400 rounds

looply scan

Six lenses ship, each a narrow question asked of the whole codebase: silent-failures, dead-ends, missing-states, untested-logic, accessibility, boundaries. Every finding is written as a draft item, never as a ready one, because a finding an agent volunteered is a claim and not yet a task. Each lens writes its findings to a file in the system temp directory rather than inside the repo — the same prompt tells the agent not to modify the project, and a findings file inside it is a contradiction the agent resolves by writing nothing.

# All six lenses, up to 8 findings each, written to the queue.
looply scan

# Two lenses, three findings each. Cheaper, still real agent calls.
looply scan --lens silent-failures,boundaries --per-lens 3

# Runs the passes, prints the report, writes nothing.
looply scan --dry-run

looply verify

The cheapest agent work looply does. Each draft is shown to the agent along with the titles and ids of the other open items, so a duplicate can be named rather than merely suspected. A draft is moved to verifying before the call and back to draft if the agent dies, so a failed pass leaves nothing stranded. Confirmed and amended items become ready; their evidence is cached against the current HEAD so the next pick starts at the right file and line instead of paying to find it again. A run does this by itself when it has nothing pickable — the standalone command exists so you can see what survives contact with the code before spending a round on anything.

looply queue

Reads .looply/state/queue.json and prints it grouped by state, in triage order: what can be worked on, then what needs you, then what is finished. Under each item go the three things a count cannot tell you — the first piece of evidence as path:line, which is exactly where a round would start; how many attempts the item has already had; and why it is in the state it is in, which is the blocked reason, the item a duplicate was merged into, or the reason the last attempt was thrown away.

The settled states — duplicate, stale, done, closed — are left out by default and replaced with a count and a pointer to --all, because a queue worked through a night otherwise buries its own live items under its history. An empty queue says so and names looply scan. A queue holding drafts and nothing ready says nothing is pickable yet and names looply verify, which is the command that changes that.

$ looply queue

   2 ready to pick
     itm_9f2c0a11  ItemForm image edits fail with no explanation
                   admin/src/menu/ItemForm.tsx:178
     itm_4b70d3e2  the table charge is billed but never shown to the diner
                   web/src/menu/MenuTable.tsx:64  ·  1 attempt
                   last attempt: the gate failed on typecheck

   1 blocked — needs you
     itm_0c81aa53  move pricing behind a flag
                   needs a schema change

  6 more already dealt with — looply queue --all

looply stop

Writes a stop request to .looply/state/control.json — the same file the daemon writes when a phone sends one, and the only channel two separate processes share. The runner reads it between rounds, so the round in flight finishes and is kept or discarded on its own merits, and then the run ends with stop reason command. A run the phone started is detached and has no terminal to interrupt at all, which is the case this command exists for.

--now deliberately kills nothing. Nothing in this build can interrupt a round in flight, and a round cut off halfway leaves a working tree with changed paths in it — which is the first thing the next looply run refuses on. So the flag adds one line saying the round still has to finish, rather than accepting the word and then quietly waiting up to three quarters of an hour.

When no run is live, nothing is written at all and the command says so. A run clears any pending request immediately after it starts, so that last night's stop cannot wedge tonight's run before its first round; the same clearing is why a request written now would never be read by anything. A file left there would be an order nobody was going to obey, and a message is more honest than a write that changes nothing.

$ looply stop

  stopping — the round in flight finishes first, then the run ends.

$ looply stop --now

  stopping — the round in flight finishes first, then the run ends.
  --now still lets the round in flight finish: cutting it off would leave the tree dirty.

$ looply stop

  no run is going — nothing to stop.

looply agent

Written for another program. It exits 0 whenever it could answer at all, including "nothing is running"; a non-zero exit means the question could not be answered, never that the answer was dull. Every field is present or explicitly null, and schemaVersion changes when a field's meaning changes. suggests is a stable token — init, answer-question, wait, scan, run — so a caller branching on it keeps working when the wording elsewhere changes.

$ looply agent --text
schema=1
project=tabsy
configured=true
paired=true
run.live=true
run.stale=false
round=7
phase=gating
queue.ready=11
queue.draft=4
queue.blocked=0
questions=0
totals.committed=5
totals.discarded=1
suggests=wait

Exit codes

One command is still named in the usage text under "not built yet", and it is item. It is not in the switch, so running it exits 64. Everything else the usage text lists is dispatched, and the bare looply screen now agrees with it: verify, queue and stop are all on its own command list, so it no longer offers anything that is missing. There are three ways to end a run and all three let the round in flight finish — looply stop from anywhere in the repo, a stop sent from a paired phone, which the daemon writes to the same control.json, and a Ctrl-C in the run's own terminal, which travels as a signal rather than a file and ends the run with stop reason signal instead of command.