--tui |
Force the interactive TUI (it is the default when a terminal is attached). |
-p, --print |
One-shot / non-interactive: run the task, stream text, exit (like claude -p). Requires a task. Without -p, iteron opens the interactive TUI (the default). |
--image <PATH> |
Attach a local PNG, JPEG, GIF, or WebP to a one-shot task. On macOS, HEIC/HEIF is locally normalized to bounded JPEG. Repeat up to the attachment limit; bytes are sniffed before SQ. Repeatable. |
--output-format <OUTPUT_FORMAT> |
One-shot stdout contract: text | json | stream-json. Machine formats keep stdout as valid JSON/JSONL; diagnostics continue on stderr. Only valid in one-shot mode. Default text. |
--output-schema-version <VERSION> |
Pin a published machine stdout schema. Supported versions are reported by --machine-contract; omission keeps the current v5 default. |
--machine-contract |
Print the bounded, provider-free CLI capability report as JSON and exit. |
-C, --repo <REPO> |
The repository to work in (defaults to the current directory). Default .. |
--model <MODEL> |
Model id (overrides config / default). |
--max-turns <MAX_TURNS> |
Max turns (bounded invariant; overrides config / default). |
--max-usd <MAX_USD> |
Max spend in USD (bounded invariant; overrides config / default). |
--max-tokens <MAX_TOKENS> |
Aggregate provider-token ceiling across this run and all descendants. |
--max-consecutive-tool-errors <MAX_CONSECUTIVE_TOOL_ERRORS> |
Consecutive failing tool calls before the run stops as stuck (stability floor; overrides the default of 25). Raised from 3 on 2026-08-05: three was reachable by a model correcting its own mistake, so the floor fired on runs that were making progress. |
--max-wall-secs <MAX_WALL_SECS> |
Wall-clock ceiling for ONE submission, in seconds (bounded invariant; overrides config / default). The default is 14400s (4h), raised from 1800s on 2026-08-05 because one long refactor turn reached the old ceiling and ended reporting a budget instead of a result. |
--allow-code |
Enable code execution (bash/build/test). ON by default; a trusted ~/.iteron/config.json "allow_code": false, a project .iteron/config.json "allow_code": false, or --mode plan tightens it back off. The command runs with your own user authority unless --confine. |
--confine |
Put code execution back inside the platform sandbox: network denied, writes confined to the workspace, ambient HOME credential paths denied (ADR-007). Off by default — bash otherwise runs with your own user authority, which is what makes git push, gh, curl and package installs work. Filesystem tools address the host either way; this flag governs executed code only. |
--dangerously-bypass-permissions |
Auto-approve EVERY tool so the agent never prompts. ON by default since 2026-08-05, so this flag is now an explicit statement of the default rather than a change to it; pass --ask-permissions for the opposite. Plan mode still hard-denies and an explicit /permissions deny is still honored either way. |
--ask-permissions |
Restore the capability gate: edits, code execution, trust changes and external actions ask for approval according to the permission mode. This is the opt-out from the default bypass. In one-shot (-p) there is no approval channel, so an "ask" there is a refusal — pair it with --mode acceptEdits or an explicit /permissions allow rule. |
--mode <MODE> |
Permission mode: default | acceptEdits | plan | yolo (ADR-007 §3). Reads always auto; the mode governs edits/code/etc. Defaults to default (edits ask) in the interactive TUI and to acceptEdits in one-shot, which has no approval channel; pass --mode plan for read-only. |
--runs-dir <RUNS_DIR> |
Directory for the append-only rollout (the audit record). Default .iteron/runs. |
--benchmark-attempt-scope <ATTEMPT> |
Internal eval-harness attempt identity. Activates strict parent-memory isolation and content-free contamination evidence; hidden because ordinary sessions must inherit memory. |
--harness-profile <HARNESS_PROFILE> |
Immutable runtime-tunables profile. Benchmark attempts select benchmark automatically; ordinary runs select interactive unless this operator-owned flag says otherwise. |
--tunables-export |
Print the whole machine-readable optimization surface as JSON and exit: every family, every exposed parameter, the module axis and the addressable prompt artifacts. This is what an external optimizer reads to construct a legal profile. |
--tunables-profile <PATH> |
Apply a tunables profile document to this run. Requires --tunables-profile-digest; a candidate that can be swapped between digesting and applying is not pinned to anything. |
--tunables-profile-json <JSON> |
A tunables profile as inline JSON, for a one-off experiment. Mutually exclusive with --tunables-profile; neither can be digest-pinned, because bytes produced in the same breath as the claim about them have nothing prior to pin to. |
--set <KEY=VALUE> |
Set one tunable for this run: --set compaction_trigger=120000. Repeatable. Accepts a family id, semantic key, alias, or exposed parameter id; the source kind is inferred from the family's own declared bindings. Repeatable. |
--tunables-explain |
Print the exact assembled profile and whether each tier-2 parameter has a production use site, then exit without running anything. |
--tunables-module <MODULE> |
Restrict --tunables-export to one optimization module. |
--tunables-filter <SUBSTRING> |
Restrict --tunables-export to entries whose id or summary contains this substring. |
--tunables-format <TUNABLES_FORMAT> |
--tunables-export output shape: json for machines, table for a human scanning the surface. |
--tunables-profile-digest <SHA256> |
The SHA-256 the profile file must have. Any mismatch refuses the run. |
--emit-tunables-profile <PATH> |
Write the profile that reproduces this run's effective tunables, then continue. |
--resume <RESUME> |
Resume a prior run by id: reconstruct its transcript from the rollout and continue (invariant #2, recoverable). When set, the task argument may be a follow-up instruction. |
-c, --continue |
Continue the most recent session in this repo (like claude --continue). |
--sessions |
List sessions in this repo (id, turns, model, cost, title) and exit. |
--limit <N> |
How many sessions --sessions lists. Defaults to one page (200); the machine document keeps its published page ceiling and reports truncated instead. |
--session-cursor <TOKEN> |
Opaque continuation token returned by a prior session_list_page. |
--session-limit <SESSION_LIMIT> |
Maximum session rows in one machine page. |
--agent-definition-tag <TAG> |
Bounded immutable grouping metadata for a fresh run, or an exact filter for --sessions. |
--transcript <RUN_ID> |
Read one session's transcript and exit. Pair with --output-format json for the machine document; a client should never open a file under .iteron/runs itself. |
--otel-export <RUN_ID> |
Project one session into its OTel export payload and print it, without sending anything anywhere (#105). The offline half of the exporter: same projection the live sink ships, so an operator can see exactly what would leave the machine before enabling it. |
--transcript-cursor <TOKEN> |
Opaque continuation token returned by a prior session_transcript_page. |
--timeline <RUN_ID> |
Read one session's latency timeline and exit: the per-class effect breakdown, the distribution behind it, and what could not be accounted for. Pair with --output-format json for the machine document. Purely offline -- it reads the hash-verified record and measures nothing itself. |
--fork <FORK> |
Fork a prior run at its tail into a new branch (shared past, divergent future) and print the new run id. The fork is tamper-evident: its genesis pins the parent chain's hash at the fork point (ADR-008 §4), so a later edit to the parent prefix is detected on resume. |
--verify <VERIFY> |
Verification gate: a test command the harness runs itself when the agent claims done. If it fails, "done" is refused and the failure is fed back (don't trust the self-report). e.g. --verify "python3 -m pytest -q". Code execution must remain enabled (the default). |
--effort <EFFORT> |
Effort level: low | medium | high | xhigh | max | ultracode. Higher = more model reasoning budget; ultracode additionally enables internal workflow/subagent orchestration. |
--provider <PROVIDER> |
Provider instance id. Built-ins: anthropic, openai, deepseek, glm, minimax, fireworks. |
--base-url <BASE_URL> |
Trusted one-run OpenAI-compatible API root, including its full path/version prefix. Prefer a named provider in ~/.iteron/config.json for persistent configuration. Requires --key-env. |
--key-env <NAME> |
Environment variable holding the credential for --base-url. Required alongside it: without it a gateway would silently receive the default provider's key. |