CLI reference

August 6, 2026 · View on GitHub

Live help: agenc help and agenc help <topic>. Sources: runtime/src/bin/*-cli.ts, runtime/src/app-server/{daemon,agent}-cli.ts, runtime/src/plugins/cli/pluginCliCommands.ts, runtime/src/permissions/permission-cli.ts, and top-level formatCliHelpText() in runtime/src/bin/agenc.ts.

Note: top-level formatCliHelpText() is incomplete relative to real dispatch (for example doctor, remote, and the full gateway surface are wired and have topic help but may not appear in the top-level usage block). This page documents the dispatched surface.

Version: 0.14.2. Default session provider grok, fresh-config session model grok-4.5 (see providers.md).

Default modes

agenc [options] [PROMPT]
agenc -p|--print [options] [PROMPT]
agenc --no-tui [options] [PROMPT]

With no subcommand, AgenC starts the interactive TUI (or continues/resumes a session when those flags are set). A positional prompt without --print / --no-tui still goes through the normal startup path.

Global / session options

From formatCliHelpText():

Flag	Meaning
`-h`, `--help`	Show top-level help
`--version`	Print `agenc <version>`
`-p`, `--print`	Headless one-shot print mode
`--output-format <format>`	Print mode output: `text`, `json`, or `stream-json`
`--input-format <format>`	Print mode input: `stream-json`
`--no-tui`	Force one-shot CLI mode (no interactive TUI)
`-c`, `--continue`	Continue the latest project session
`-r`, `--resume <session-id>`	Resume a prior project session in the TUI
`--profile <name>`	Named config profile
`--provider <name>`	Override provider for this session
`--model <id\|provider:id>`	Override model for this session
`--permission-mode <mode>`	Override startup permission mode: `default`, `acceptEdits`, `plan`, `bypassPermissions`, `dontAsk`, `auto` (internal-only `unattended` / `bubble` are not CLI addressable)
`--autonomous`, `--proactive`	Enable autonomous tick mode
`--dangerously-bypass-approvals-and-sandbox`	Bypass approvals and sandbox checks
`--yolo`	Alias for approval/sandbox bypass
`--allow-dangerously-skip-permissions`	Skip approval prompts
`--image <file\|url\|data-url>`	Attach a startup image

Print-mode notes

--print / -p and --no-tui select non-interactive runs suitable for scripts and CI.
--output-format stream-json with --input-format stream-json is the protocol used by the SDK subprocess transport (promptViaSubprocess in @tetsuo-ai/agenc-sdk).
--output-format json emits a single structured result; text is human stdout.

Examples

agenc
agenc "summarize this repository"
agenc --no-tui "run the tests and report failures"
agenc --print --output-format stream-json "summarize this repository"
agenc --resume <session-id>
agenc help permissions

Compaction operator commands

The interactive runtime and daemon-backed TUI expose explicit recovery commands for a previously committed compaction. These commands require the attempt ID reported by the compaction transaction and refuse to run during an active turn.

/compact-rollback <attempt-id>
/compact-rollback <attempt-id> --branch <target-session-id>
/compact-retain <attempt-id> --until <ISO-8601>

Same-session rollback is allowed only when no newer canonical work exists.
--branch preserves newer source-session work and materializes the restored history as the named reviewed session.
/compact-retain accepts an absolute future deadline and can only extend, never shorten, the durable rollback-retention window.

`help`

agenc help [command]

Topics include (among others): agent, init, login / logout / whoami, daemon, remote, mcp, doctor, onboard, security, update, gateway, budget, run, permissions, plugin / plugins, providers, config, state, trajectories. Unknown topics error with a pointer to agenc help.

`init`

agenc init [--force]

Creates project-level files in the current directory:

.agenc/config.json
AGENC.md

Option	Meaning
`--force`	Overwrite existing AgenC project files

agenc init
agenc init --force

`doctor`

agenc doctor
agenc doctor --json
agenc doctor --apparmor-profile

Diagnoses installation and environment: version, install type, packaged ripgrep, update permissions, transaction-guard, PATH/glob warnings, with suggested fixes. Grep, Glob, and Orient require AgenC's pinned packaged ripgrep and never use a PATH binary or JavaScript search fallback; remediation is to identify and reinstall the same AgenC version, not to install an unrelated rg. --json emits the raw diagnostic. --apparmor-profile prints, but does not install, a narrow Ubuntu AppArmor user-namespace profile bound to the verified standalone agenc wrapper.

MCP-specific diagnostics: agenc mcp doctor.

`onboard`

agenc onboard
agenc onboard identity
agenc onboard channel
agenc onboard autonomy
agenc onboard recap
agenc onboard --status
agenc onboard --status --json
agenc onboard --reset

Form	Meaning
(no args)	Interactive setup wizard (provider, key, theme, first chat); re-runs even after a completed first run
`identity`	Act 2a — name your agent (persona workspace + one-time naming ritual)
`channel`	Act 2b — connect Telegram / Discord / Slack / WebChat with live token checks + pairing walkthrough
`autonomy`	Act 3 — budget cap, heartbeat, cron, webhooks (guardrails first)
`recap`	Posture summary + starter prompts
`--status`	Non-interactive wizard completion + daemon status (scripts)
`--json`	With `--status`: JSON report
`--reset`	Clear wizard completed/seen flags so it shows again on next interactive start

Act subcommands do not accept extra arguments.

`update`

agenc update
agenc update --check
agenc update --pin <x.y.z>

Option	Meaning
`--check`	Report whether an update is available; no downloads or writes
`--json`	Machine-readable result on stdout
`--pin <x.y.z>`	Install a private-Node release (`0.11.2` or newer) instead of latest
`--repo <owner/name>`	Release repository override
`--manifest-url <url>`	Manifest override (`file://` allowed for testing)
`--wrapper <path>`	Explicit wrapper script to repoint

Installer-style installs extract the new runtime under <AGENC_HOME>/runtime/<version>/<platform>-<arch>-<libc-or-native>-node-abi-<abi>-sha256-<digest>/ after compatibility, byte-count, sha256, and archive-safety checks, then atomically repoint the agenc wrapper. A running daemon keeps the old version until agenc daemon restart.

npm-launcher installs update with:

npm install -g @tetsuo-ai/agenc@latest

`security`

agenc security audit
agenc security audit --fix
agenc security audit --json

Checks daemon exposure, AgenC-state file permissions, config integrity, and permission-mode blast radius. Exit 1 on critical findings.

Option	Meaning
`--fix`	Apply safe permission fixes (`chmod` 700/600 on AgenC state only; never edits config or environment)
`--json`	Emit report as JSON

Only subcommand: audit.

`gateway`

agenc gateway run [--stdio] [--webchat] [--heartbeat] [--hooks]
agenc gateway install-service
agenc gateway status [--json]
agenc gateway pairing list [--json]
agenc gateway pairing pending [--json]
agenc gateway pairing approve <channel> <peerId>
agenc gateway pairing revoke <channel> <peerId>

Subcommand	Meaning
`run`	Start the gateway (runs until Ctrl-C). `--stdio` local dev channel; `--webchat` loopback token-gated browser UI; `--heartbeat` proactive budget-bounded ticks (`HEARTBEAT.md`); `--hooks` webhook hooks. Telegram when `AGENC_TELEGRAM_BOT_TOKEN` is set (Discord/Slack via their bot tokens / gateway config).
`install-service`	Install + start the always-on gateway user service (systemd or launchd; reads gateway/env)
`status`	Channels, DM policies, bindings, paired-sender counts
`pairing list`	Paired senders per channel
`pairing pending`	Pending pairing requests (codes not yet approved)
`pairing approve`	Approve a pending peer (`<channel> <peerId>`)
`pairing revoke`	Remove a paired sender

Config: <AGENC_HOME>/gateway/config.json (fail-closed defaults when absent).

Narrative guide: ../gateway.md.

`budget`

agenc budget status [--json]
agenc budget reset <agent>

Cost-bounded execution admission policy; disabled by default. Durable usage is inspected by run id with agenc run status|replay|evidence.

Subcommand	Meaning
`status`	Configured admission policy and canonical run-inspection commands
`reset <agent>`	Rejected compatibility command; durable admission evidence cannot be reset

Configure via [budget] in config.toml or AGENC_BUDGET* env vars. The daemon execution-admission kernel is the sole production accounting authority; gateway heartbeat, cron, and hooks do not maintain separate ledgers.

Design: ../design/execution-admission-kernel.md.

`run`

agenc run start --goal <text> [--goal-file <path>] [--cwd <dir>]
                [--model <model>] [--reviewer-model <model>]
                [--max-cost <usd>] [--permission-mode <mode>]
                [--verify "label=script"]... [--json] [--follow]
agenc run status <run-id> [--json]
agenc run result <run-id>
agenc run replay <run-id> [--after <sequence>] [--limit <1-200>]
agenc run evidence <run-id> [--after <sequence>] [--limit <1-200>]
agenc run cancel <run-id> [--reason <text>]

run start launches the M5 verified-change workflow as a durable daemon run: intake freezes the spec (goal, base commit, pinned reviewer model, permission policy, required verification commands) and the fixed pipeline intake → worktree → plan → implement → verify → review → finalize continues in the daemon. At least one --verify "label=script" command is required — completed mechanically demands every required command exit 0, an adversarial-verification VERDICT: PASS, and an independent review with zero blockers. The frozen spec's --permission-mode and unattended allow/deny lists are applied to the run's daemon session, so pipeline children execute under the declared policy rather than the daemon default. The command returns after the durable intake commit (runId, specDigest, baseCommit); --follow then tails the run journal until the terminal result.

The other commands use the daemon's durable run/admission contract and print canonical JSON. status includes aggregate admission and budget/hold state; for workflow runs it also carries a workflow block — one entry per pipeline stage with attempts, machine verdicts, and content-addressed artifact pointers, plus a machine-readable stopReason on failure (and the CLI renders a step table unless --json). result succeeds only after the durable run is terminal; its lastSequence is the terminal snapshot coordinate. A later exclusively leased offline effect review can advance the replay tail without resuming execution or changing that result. replay pages the canonical append-only rollout journal with an exclusive per-run sequence cursor. evidence adds source/completeness metadata and SHA-256 hashes for mechanical review; for workflow runs it also includes a bundle block describing the sealed per-run evidence ledger (<agencHome>/run-evidence/<run-id>/): sealed, the verified-change recordDigest, the ledger path, and every artifact pointer (cas://sha256/...). The exported bundle is self-contained — hash chain, per-command records, patch/changed-file digests, review output, and terminal status are re-verifiable offline from the exported bytes alone. cancel durably locks the run tree, cancels queued descendants, and propagates to running descendants without deleting partial evidence.

Replay and evidence pages default to the daemon's bounded page size and never accept more than 200 events. Retention, compaction, corruption truncation, a missing source, and a cursor beyond the canonical tail are explicit gaps and do not advance the returned cursor past a missing range. Pre-M4 runs can fall back to the project-database-scoped execution-admission journal, which is labeled as a compatibility source. An admission-only record is not presented as a fabricated terminal result.

`remote`

agenc remote on
agenc remote status
agenc remote off

Pair this machine with the AgenC phone app via the signed relay.

Subcommand	Meaning
`on`	Pair (first run shows a code) then keep the host reachable
`status`	Whether this host is linked to a phone
`off`	Forget this host's pairing locally

Environment	Default
`AGENC_BACKEND_URL`	`https://id.agenc.ag`
`AGENC_DAEMON_URL`	`ws://127.0.0.1:7766`

Requires a signed-in remote auth session for pairing. Guide: ../remote-control.md.

agenc login
agenc logout
agenc whoami

Command	Meaning
`login`	Sign in using the configured AgenC auth backend
`logout`	Clear the current AgenC auth session
`whoami`	Show the current AgenC auth identity

AGENC_AUTH_BACKEND=remote agenc login

No extra arguments on these commands.

`providers`

agenc providers [--json] [--no-local-check]

Provider readiness: BYOK key status, local server health, AgenC subscription tier.

Option	Meaning
`--json`	Machine-readable JSON
`--no-local-check`	Skip localhost health probes

Built-in provider slugs: grok, openai, anthropic, ollama, lmstudio, openai-compatible, openrouter, groq, deepseek, gemini, mistral, nvidia-nim, minimax, github, amazon-bedrock, agenc.

`config`

agenc config show
agenc config get <dot.path>
agenc config set <dot.path> <value>
agenc config unset <dot.path>
agenc config validate
agenc config edit
agenc config path

Command	Meaning
`show`	Effective config snapshot
`get`	One effective config value
`set`	Write one value to `config.toml`
`unset`	Remove one value from `config.toml`
`validate`	Validate `config.toml` and schema blocks
`edit`	Open `config.toml` in the configured editor
`path`	Print the `config.toml` path

Values parse as TOML when possible (true, 123, ["a"], { enabled = true }); unquoted single-line text is stored as a string.

agenc config set permissions.default_mode never
agenc config set plugins.enabled true
agenc config validate

`plugin` / `plugins`

agenc plugin <command> [options]

(plugins is accepted as a help-topic alias.)

Command	Meaning
`list [--json]`	List installed plugins
`validate <path> [--marketplace] [--json]`	Validate plugin or marketplace manifest
`install <path> [--scope <user\|project\|local>]`	Install a local plugin directory
`uninstall <name> [--scope …]`	Remove an installed plugin
`update <name> [--source <path>]`	Refresh an installed plugin from its source
`enable <name> [--path <path>]`	Enable a plugin in user config
`disable <name>`	Disable a plugin in user config
`disable-all`	Disable every currently enabled plugin
`marketplace list [--json]`	List configured marketplaces
`marketplace add <path\|git\|url\|github> [--name <name>]`	Add marketplace
`marketplace remove <name>`	Remove a marketplace
`marketplace upgrade [name]`	Refresh git or local marketplaces

Install options: --name, --force, --keep-data. Marketplace options: --ref, --sparse.

`permissions`

agenc permissions list [--json] [--agent <id>|--session <id>]
agenc permissions approve [--persist <user|project|local>] <rule>
agenc permissions revoke [--persist <user|project|local>] <rule>
agenc permissions approve --session <id> [--scope <once|session|agent>] <request-id>
agenc permissions revoke --session <id> [--reason <text>] <request-id>

List, update permission rules, or resolve live permission requests.

agenc permissions list
agenc permissions approve --persist project 'Read(./src/**)'
agenc permissions approve --session session_123 call_456

`state`

agenc state export <agent-id>
agenc state import
agenc state resolve-tool-call <session-id> <tool-call-id> <disposition> <evidence-ref> <evidence-sha256>
agenc state recovery quarantine list [--limit N] [--cursor C] [--state active|repaired|abandoned|all] [--json]
agenc state recovery quarantine show <quarantine-id> [--json]
agenc state recovery quarantine rescan <quarantine-id> --confirm-source-sha256 <sha256>
agenc state recovery quarantine abandon <quarantine-id> --confirm-run-id <run-id> --confirm-source-sha256 <sha256> --reason <text>
agenc state recovery deferred list [--limit N] [--cursor C] [--state active|resolved|abandoned|all] [--json]
agenc state recovery deferred show <block-id> [--json]
agenc state recovery deferred retry <block-id>
agenc state recovery deferred abandon <block-id> --confirm-run-id <run-id> --confirm-source-sha256 <sha256> --reason <text>

Command	Meaning
`export <agent-id>`	Print a JSON state export for one agent
`import`	Read a JSON state export from stdin and import it
`resolve-tool-call <session-id> <tool-call-id> <disposition> <evidence-ref> <evidence-sha256>`	Record a typed, evidence-bound operator disposition for one unresolved `unknown_outcome` tool call
`recovery quarantine list/show`	Inspect bounded source-integrity evidence offline
`recovery deferred list/show`	Inspect bounded operational blocks and retry metadata offline
`recovery … rescan/retry/abandon`	Strict descriptor-pinned recovery actions; rescan and abandon require exact digest/run confirmations

agenc state export agent_123 > state.json
agenc state import < state.json
AGENC_REVIEWER_ID=operator_7 \
  agenc state resolve-tool-call session_abc call_42 \
    confirmed_no_effect operator-report:INC-42 <64-character-sha256>
agenc state recovery quarantine list --state active --json
agenc state recovery deferred show <block-id> --json

Run resolve-tool-call from the affected session's project directory after stopping the live session. For an M4 effect, it appends and fsyncs a canonical effect_review_resolved event before advancing the SQLite review projection; it never reruns the tool or rewrites unknown_outcome as success. Valid dispositions are confirmed_committed, confirmed_no_effect, and remains_unknown; the last explicitly abandons the blocked domain item while preserving the uncertain physical outcome. The evidence reference identifies an operator-controlled receipt/report and the digest binds its exact bytes. Reviewer identity comes from AGENC_REVIEWER_ID, then USER / USERNAME, with local_operator as the final fallback. If the requested call is not found, the error lists any unresolved calls known for that session.

Recovery list and show commands expose only bounded, secret-redacted metadata; they never print a malformed source record or journal payload. Pages contain at most 100 records and use an opaque, collection/state-bound keyset cursor. There is deliberately no clear or delete command. The descriptor-pinned adapter validates twice and resolves evidence in the same outer transaction as projection. The normal CLI installs it. Active quarantine, active operational blocks, and permanent abandonment remain non-executable across startup, on-demand inspection, stale-tool restoration, and admission recovery until a strict rescan/retry succeeds or an operator records permanent abandonment.

`trajectories`

agenc trajectories export [options]

Curates redacted trajectory exports written by the session sink (enable with AGENC_TRAJECTORY_EXPORT_DIR=<dir>, then run sessions) into training-data JSONL. If the dir env is unset, --dir can also fall back to the parent of AGENC_TRAJECTORY_EXPORT_PATH. Local file processing only — no network.

Only trajectories that completed at least one turn with no error event, no abort/interrupt, and no user tool-use rejection are kept.

Option	Meaning
`--format <sft\|dpo>`	Output format (default `sft`). `sft`: chat-schema conversations; `dpo`: prompt/chosen/rejected pairs from thread-rollback regenerations
`--dir <path>`	Export dir or single `.jsonl` to read (defaults from env)
`--out <file>`	Write JSONL here instead of stdout

--require-eval-passed is not available (exported records carry no evaluation outcome field).

Guide: ../trajectory-training-data.md.

`daemon`

agenc daemon start
agenc daemon start --foreground
agenc daemon stop
agenc daemon status
agenc daemon reload
agenc daemon restart

Command	Meaning
`start`	Start the local AgenC daemon
`start --foreground`	Run the daemon in the current process
`stop`	Stop the local AgenC daemon
`status`	Show local daemon status
`reload`	Reload daemon configuration in place
`restart`	Stop and start the local AgenC daemon

Service templates under packaging/ invoke agenc daemon start --foreground. Launcher autostart: AGENC_DAEMON_AUTOSTART=0 disables; ready timeout AGENC_DAEMON_READY_TIMEOUT_MS.

`agent`

agenc agent start [--unattended-allow <tools>] [--unattended-deny <tools>] <objective>
agenc agent list
agenc agent attach <id>
agenc agent stop <id>
agenc agent logs <id>

Background agents managed by the daemon.

Command	Meaning
`start`	Start a background agent with an objective string
`list`	Show active background agents
`attach <id>`	Attach to a running agent
`stop <id>`	Stop a running agent
`logs <id>`	Print an agent's full local log and transcript

agenc agent start "fix the failing parser test"
agenc agent start --unattended-allow read,grep "audit imports"

`mcp`

agenc mcp serve [--transport <stdio|sse>]
agenc mcp add …
agenc mcp list
agenc mcp get
agenc mcp remove
agenc mcp add-json
agenc mcp add-from-agenc-desktop
agenc mcp reset-project-choices
agenc mcp doctor
agenc mcp xaa

Command	Meaning
`serve`	Expose workspace-scoped AgenC prompts and resources as an MCP server
`add`	Add an MCP server
`list`	List configured MCP servers
`get`	Show one MCP server
`remove`	Remove an MCP server
`add-json`	Add an MCP server from JSON
`add-from-agenc-desktop`	Import servers from AgenC Desktop config
`reset-project-choices`	Reset project MCP approval choices
`doctor`	Diagnose MCP configuration
`xaa`	Manage XAA IdP authentication (SEP-990)

Option (selected)	Meaning
`serve --transport <stdio\|sse>`	Transport for serve
`add -t, --transport <stdio\|sse\|http>`	Transport for add
`-s, --scope <scope>`	Config scope for add/remove/import (default user for add/add-json)
`-e, --env <KEY=value>`	Environment variable for stdio add
`-H, --header <K: V>`	Header for HTTP/SSE add
`--client-secret`	Prompt for remote MCP OAuth client secret

agenc mcp serve --transport stdio
agenc mcp list

Inbound serve does not advertise or execute tools until a request can be bound to a daemon session-owned admission identity. Direct tools/call requests fail closed with ADMISSION_IDENTITY_REQUIRED; environment flags cannot authorize execution. Prompts and resources remain workspace-scoped. Daemon SSE autostart additionally requires an absolute mcp.server.workspace; foreground serve uses its working directory.