circuit run
Execute a flow against a goal.
circuit run <flow-id> --goal '<task>' [options]Runs a flow against a goal and writes the run folder.
Pass the flow id as the first argument: build, fix, explore, review,
or prototype. When you invoke Circuit through an agent with
/circuit:run, the agent picks the flow and calls this command for you.
--goal is required unless you are resuming a checkpoint with
circuit resume.
Flags
| Flag | Description | Default |
|---|---|---|
--goal <goal> | The task to run. Required. | |
--why <why> | Why the task matters. Threaded into worker prompts. | |
--power <auto|low|medium|high> | Model tier for each worker. Also derives the run's process thoroughness. | medium |
--tournament [2|3|4] | Run candidates in parallel and pick a winner. Optional candidate count. | off (3 when set) |
--process <low|medium|high> | Advanced. Explicitly overrides the process power derives. | derived from --power |
--autonomous | Drive the continuation loop instead of a single pass. | off |
--run-folder <path> | Where to write the run. | .circuit/runs/<run-id> |
--fixture <path> | Use a specific compiled flow file instead of the resolved one. | |
--flow-root <path> | Directory of compiled flows. | generated/flows |
--progress <jsonl> | Stream progress events as JSONL on stderr. | off |
--include-untracked-content | Include untracked file content in evidence. | off |
--reuse-children-from <path> | Reuse finished sub-runs from a prior crashed run folder instead of re-running them. Fresh runs only; rejected on resume. |
Not every flow supports every control. --tournament and --autonomous are
rejected when the flow does not declare them. --power works on every flow,
and the process it derives clamps silently to what the flow supports. An
explicit --process outside the flow's set is rejected before the run
starts. See Power, process, and modes.
--power auto lets the run pick the tier: the researcher recommends one and
the engine clamps it to the power_auto bounds in
config. It also derives a medium process
while letting the run pick its own model tier. Checkpoint resume re-reads
power from config, so omit --power when resuming.
Examples
Run a named flow:
circuit run fix --goal 'fix the off-by-one in pagination'Set the power dial:
circuit run build --goal 'add a rate limiter to the API' --power lowOverride the derived process without changing model power:
circuit run build --goal 'add a rate limiter to the API' --power low --process highRun a tournament with three candidates:
circuit run explore --goal 'compare caching strategies' --tournament 3