CLI reference

The executable name is iteron.

iteron [OPTIONS] [TASK] [COMMAND]

This page is generated from the argument parser, so every shipped flag and subcommand appears here. iteron --help is the same contract for the exact build you have installed, and iteron --version identifies it by commit and build date.

Arguments

Argument	Meaning
[TASK]	The task for the agent to perform. Optional in --tui mode (type it in the UI).

Options

Option	Meaning
--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 v8 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>	Maximum provider turns, or unlimited (the 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 50).
--max-wall-secs <MAX_WALL_SECS>	Wall-clock ceiling for ONE submission, in seconds (bounded invariant; overrides config / default). The default is 86400s (24h).
--allow-code	Enable code execution (bash/build/test). ON by default; a trusted or project allow_code: false, or --mode plan, can tighten it back off.
--confine	Tighten execution to the workspace sandbox even with the default dangerous bypass. The sandbox denies network and out-of-workspace shell writes, and fails closed if the platform cannot enforce it. Built-in file writers also reapply their workspace-write boundary when this flag is combined with dangerous bypass.
--dangerously-bypass-permissions	Explicitly request dangerous bypass (already the default for fresh ordinary sessions). Without --confine, code has host authority. Plan mode and explicit denies still apply.
--ask-permissions	Disable the fresh-session bypass and use default mode unless --mode was supplied. Execution is confined; one-shot (-p) refuses decisions requiring an interactive answer. On resume, this must agree with the recorded bypass authority.
--mode <MODE>	Permission mode: default | acceptEdits | plan | yolo (ADR-007 §3). Reads always auto; the fresh default is acceptEdits with dangerous bypass. Explicit default/acceptEdits restores approval gates unless the dangerous flag is also given; plan is always confined 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.
--implementation-candidate <PATH>	Operator/eval-harness pinned external implementation activation document.
--implementation-candidate-digest <SHA256>	Exact lowercase SHA-256 of --implementation-candidate bytes.
--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).
--verify-preconfined	Trust an already-attested outer sandbox for --verify and skip Iteron's nested sandbox. DANGEROUS without that outer boundary: this flag does not itself confine filesystem or network access. Timeout, output limits, and credential-environment scrubbing still apply.
--effort <EFFORT>	Effort level: low | medium | high | xhigh | max | ultracode. Higher = more model reasoning budget; ultracode additionally exposes model-directed bounded workflows.
--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.

Standard options

Option	Meaning
-h, --help	Print help.
-V, --version	Print the bare iteron <version>.
--version	Print the version with the commit and build date this binary was built from.

Subcommands

Command	Meaning
iteron reindex	Rebuild session metadata and the sessions index from hash-chained rollout truth.
iteron prune [--older-than-days <DAYS>] [--keep-last <N>] [--dry-run]	Delete old run journals under the runs dir according to an explicit retention policy. Journals are append-only and nothing else ever removes them.
iteron serve [--listen <LISTEN>] [--plantcore] [--recording-provider-ca-file <ABSOLUTE_CA_PEM>] [--recording-inject-harness-error] [--recording-app-server-fault <RECORDING_APP_SERVER_FAULT>]	Run a local-only versioned App Server for headless clients.
iteron workflow <SUBCOMMAND>	Run a bounded JavaScript workflow end-to-end, streaming progress to stdout.
iteron workflow run <SCRIPT> [--args <ARGS>]	Execute a workflow script now (agent()/parallel()/pipeline()/phase()/log()).
iteron workflow list	List persisted workflow runs (id, status, agents, model) under the workflows dir.
iteron workflow resume <RUN_ID> [--script <SCRIPT>] [--args <ARGS>]	Resume a prior run by id, replaying its journaled agent outcomes and continuing (blocking).
iteron workflow watch <RUN_ID> [--args <ARGS>]	Re-launch a prior run in the BACKGROUND (RunHandle) and attach the live tree to it.
iteron setup [--plan] [--byok <PROVIDER>] [--provider <PROVIDER>] [--stdin] [--expires-at <UNIX>]	First-run setup: choose a hosted plan or your own provider key, and validate it.
iteron auth <SUBCOMMAND>	Inspect or drop the credential in use.
iteron auth status [PROVIDER]	Print provider, api_root, credential source, validation state, and expiry.
iteron auth logout [PROVIDER]	Remove the stored credential, leaving the provider entry intact.
iteron config <SUBCOMMAND>	Read or write one operator setting in the user config.
iteron config get [KEY]	Print one persisted setting, or every settable key.
iteron config set <KEY> <VALUE>	Persist one setting atomically at mode 0600.
iteron config explain [--effective] [--family <FAMILY>] [--format <FORMAT>]	Explain the exact immutable settings that would govern this run.
iteron record <SUBCOMMAND>	Execute, inspect, or resume receipt-backed record erasure operations.
iteron record delete <RUN_ID> [--operation-id <ID>]	Delete one inactive session and all private-content references owned only by it.
iteron record revoke <DIGEST> [--operation-id <ID>]	Crypto-shred one content digest and invalidate every derivative handle.
iteron record prune [--older-than-days <DAYS>] [--keep-last <N>] [--operation-id <ID>]	Apply a durable, resumable retention operation.
iteron record receipt <OPERATION_ID>	Print one content-free erasure receipt.
iteron record receipts [--limit <LIMIT>]	List the bounded receipt inventory, including incomplete operations.
iteron record resume <OPERATION_ID>	Resume an incomplete operation from its durable receipt request.
iteron pricing <SUBCOMMAND>	Produce the operator pricing material a USD ceiling and a cost display require.
iteron pricing print-digests	Print the exact route a rate card must pin for the selected provider and model.
iteron pricing sign <CARD> [--key-env <KEY_ENV>] [--signer-id <SIGNER_ID>]	Sign an operator-authored rate card and print the rate_cards[] entry that installs it.
iteron tunables <SUBCOMMAND>	Resolve or explain one explicit tunables request without binding it to a live run.
iteron tunables resolve <REQUEST>	Resolve a frozen request and print one machine-readable simulation report.
iteron tunables explain <REQUEST> [--family <FAMILY>] [--format <FORMAT>]	Explain a frozen request. Text covers all 160 families; JSON selects one family.
iteron doctor	Run local configuration, recovery, and terminal diagnostics without contacting a provider.
iteron support [--output <PATH>]	Build a deterministic redacted support bundle; it is never transmitted by this command.
iteron plugin <SUBCOMMAND>	Manage signed, cached plugins without contacting a provider.
iteron plugin list	List installed versions, enablement, rollback availability, and publisher identity.
iteron plugin trust <KEY_ID> <PUBLIC_KEY_FILE>	Add an immutable trusted Ed25519 publisher key from a raw-32-byte or base64 file.
iteron plugin install <PACKAGE_DIR> [--precedence <PRECEDENCE>]	Verify and install a local signed package directory.
iteron plugin update <PACKAGE_DIR> [--precedence <PRECEDENCE>]	Verify and update from a newer local signed package directory.
iteron plugin enable <NAME>	Enable an installed plugin for future runtime composition.
iteron plugin disable <NAME>	Disable an installed plugin while retaining its offline cache.
iteron plugin rank <NAME> <PRECEDENCE>	Change the operator-owned conflict rank without reinstalling.
iteron plugin uninstall <NAME>	Remove a plugin from runtime composition while retaining cached artifacts.
iteron plugin rollback <NAME>	Atomically return to the one retained, re-verified prior artifact.
iteron plugin doctor	Re-verify every enabled cache entry and explain composition refusals/conflicts.
iteron mcp <SUBCOMMAND>	Configure, authenticate, test, and diagnose MCP servers.
iteron mcp add <NAME> [--url <URL>] [--stdio <COMMAND>] [--env <NAME>] [--oauth-resource <OAUTH_RESOURCE>] [--oauth-scopes <OAUTH_SCOPES>] [--oauth-client-registration <OAUTH_CLIENT_REGISTRATION>] [--oauth-client-id <OAUTH_CLIENT_ID>] [--oauth-client-secret-env <OAUTH_CLIENT_SECRET_ENV>] [--oauth-issuer <OAUTH_ISSUER>] [ARGS]	Add one operator-owned MCP server.
iteron mcp list [--format <FORMAT>]	List configured MCP servers.
iteron mcp get <NAME> [--format <FORMAT>]	Inspect one configured MCP server.
iteron mcp remove <NAME>	Remove one configured MCP server.
iteron mcp auth <SUBCOMMAND>	Inspect locally stored MCP authentication.
iteron mcp auth login <NAME> [--oauth-resource <RESOURCE>] [--scopes <SCOPES>] [--oauth-client-registration <REGISTRATION>] [--client-id <CLIENT_ID>] [--client-secret-env <CLIENT_SECRET_ENV>] [--oauth-issuer <ISSUER>]	Start an OAuth login for one configured HTTP server.
iteron mcp auth logout <NAME>	Remove locally stored credentials for one server.
iteron mcp auth status <NAME> [--format <FORMAT>]	Show local credential status without revealing credentials.
iteron mcp test <NAME> [--format <FORMAT>]	Connect, negotiate, and discover tools without calling a business tool.
iteron mcp status [NAME] [--connect] [--format <FORMAT>]	Show configured state, optionally with a bounded live connection probe.
iteron mcp doctor [--connect] [--format <FORMAT>]	Validate all MCP configuration, optionally opening bounded discovery connections.

Local validation runs before a new rollout is opened, so malformed mode, effort, verification, or TUI/one-shot combinations should fail without creating a phantom session.