CLI Reference

This is the complete agent-runner command reference. For conceptual context, see concepts.md and runs.md.

All commands accept --help / -h.

Command index

Command	Purpose
`run`	Execute a fresh run, promote an initialized run to ready, start a ready run, or resume
`init`	Prepare a run workspace without invoking the backend
`serve`	Start the local daemon / control plane
`status`	Print system/environment status
`run status\|brief\|audit`	Print run state, the composed worker handoff, or persisted audit history
`run environment status\|validate\|cleanup`	Inspect, validate, or clean up a run execution environment
`task list\|show\|set\|append-notes\|add`	Run task-state inspection and mutation
`attachment add\|list\|download\|remove`	Attachment management
`list agents\|assignments\|launchers\|environments\|tasks\|runs`	Enumerate definitions and runs
`show agent\|assignment\|launcher\|environment\|task`	Render a single definition
`run reset\|archive\|unarchive\|delete`	Lifecycle mutations
`run schedule`, `run schedule enable\|disable\|clear`	Schedule mutations
`run set-name\|set-backend-session\|clear-backend-session`	Metadata mutations
`run set-group\|clear-group`	Run group mutations
`run add-dep\|remove-dep\|clear-deps`	Dependency graph mutations
`run queue-message\|queued-messages\|remove-queued-message`	Queue, inspect, or remove pending resume messages

Global flags

Flag	Applies to	Effect
`--help`, `-h`	any	Print command help
`--connect <ws-url>`	client commands	Route command through a daemon (also `AGENT_RUNNER_CONNECT`)
`--connect-host <host>`	connected client commands	Open an invocation-scoped SSH local forward before dialing `--connect` (also `AGENT_RUNNER_CONNECT_HOST`)
`--connect-local-port <port>`	connected client commands	Override the loopback port used by `--connect-host` (also `AGENT_RUNNER_CONNECT_LOCAL_PORT`)
`--output-format text\|json`	most commands	Output format (default `text`)

Commands reject flags they do not consume — unknown flag combinations error out rather than being silently ignored.

Reusable task definition inspection uses top-level list tasks and show task <name|path>. Run task state remains under agent-runner task ....

--connect-host requires connected mode via --connect or AGENT_RUNNER_CONNECT. When present, the CLI keeps the logical daemon URL for user-facing output, but tunnels the actual WebSocket/HTTP traffic through 127.0.0.1:<local-port> for the lifetime of the invocation.

`run`

Execute a run. With no subcommand it creates a fresh run, starts a ready run (run ready then run --resume-run), or resumes an existing run. See resume.md for the rules.

agent-runner run \
  [--agent <name|path>] \
  [--assignment <name|path>] \
  [--cwd <path>] \
  [--backend <id>] \
  [--launcher <name>] \
  [--environment <name|path>] \
  [--model <id>] \
  [--effort <level>] \
  [--timeout-sec <n>] \
  [--max-retries <n>] \
  [--unrestricted] \
  [--name <name>] \
  [--group-id <group-id>] \
  [--var <key>=<value> ...] \
  [--add-task <title> ...] \
  [--backend-session-id <id>] \
  [--parent-run <run-id>] \
  [--resume-run <id|path>] \
  [--detach] \
  [--message-file <path>] \
  [<message tokens...>]

Flags:

--agent <name|path> — bare name resolved under the config dir, or a direct path to agent.md. If omitted, --backend <id> is required and agent-runner synthesizes an ad-hoc agent from the backend/model/effort overrides.
--assignment <name|path> — same resolution as --agent. Optional; a run without an assignment is a "chat" run with no tasks.
--cwd <path> — override the run cwd. Fresh-run precedence is --cwd → assignment cwd → caller cwd.
--backend <id> — override the agent's backend. Built-ins are claude, codex, cursor, opencode, pi, and passive; custom backend names are accepted and resolved through the backend registry.
--launcher <name> — override the agent's launcher by named launcher id. Fresh-run/init only; forbidden on resume and ready-start. The built-in direct launcher is always available.
--environment <name|path> — override the agent's execution environment for a fresh run/init. The selected environment is frozen into the manifest and reset seed. Forbidden on resume.
--model <id> — override the agent's model.
--effort <level> — one of off, minimal, low, medium, high, xhigh, max.
--timeout-sec <n> — positive integer per-attempt wall-clock budget.
--max-retries <n> — non-negative integer; maxAttemptsPerSession = retries + 1.
--unrestricted — pass the backend's safety-bypass flag.
--name <name> — set the persisted display name.
--group-id <group-id> — set the explicit run group for a fresh run. Forbidden on resume and ready-start.
--var <key>=<value> — repeatable. Split on the first =. Forbidden on resume. Descendant runs usually should prefer assignment sources: [parent] over manually re-passing inherited vars.
--add-task <title> — repeatable. Append a task to the run's list. Allowed on resume (non-passive runs); forbidden on ready-start.
--backend-session-id <id> — bootstrap-import an existing backend session. Forbidden on resume.
--parent-run <run-id> — set the lineage parent for a fresh run/init. If omitted, AGENT_RUNNER_PARENT_RUN_ID is honored.
--resume-run <id|path> — continue an existing run. Many flags are forbidden in combination with this; see resume.md.
--detach — daemon mode only; dispatch the run and exit after the daemon accepts it.
--message-file <path> — read UTF-8 message text from a file instead of positional message text.

Positional args are joined with spaces into the message body. --message-file cannot be combined with positional message text.

A run is the durable lifecycle record. Each backend execution window is a session: the fresh execution creates session 0, and each resume creates the next session. Attempts are backend invocations within a session. maxAttemptsPerSession is the per-session retry budget. Attempt numbers are monotonic across the run, while attemptIndexInSession is zero-based within its session.

Assignment task refs follow the same explicit loader model:

bare strings are named task refs under ${AGENT_RUNNER_CONFIG_DIR}/tasks
only absolute paths and strings beginning with ./ or ../ are path refs
slashful ids such as review/reuse are named refs, not implicit paths
bundled assignments that need shared review tasks use named refs such as review/architecture

`init`

Same inputs as run except no --detach, but the backend is never invoked. Used for passive runs or to inspect a run before executing it.

agent-runner init \
  [--agent <name|path>] \
  [--assignment <name|path>] \
  [--cwd <path>] [--backend <id>] [--model <id>] [--effort <level>] \
  [--timeout-sec <n>] [--max-retries <n>] \
  [--unrestricted] [--name <name>] [--group-id <group-id>] [--var key=value ...] \
  [--add-task <title> ...] [--backend-session-id <id>] \
  [--run-id <id|path>] \
  [--schedule-at <iso> | --schedule-delay <duration> | --schedule-cron <expr>] \
  [--schedule-timezone <iana>] [--schedule-mode reuse|reset|clone] \
  [--schedule-continue-on-failure] \
  [--message-file <path>] \
  [<message tokens...>]

If --agent is omitted, --backend <id> is required so the run can use an ad-hoc agent. --assignment is optional; omitting it creates a chat run with no initial tasks.

init does not dump the worker brief to stdout — fetch it with agent-runner run brief <run-id>. When init reinitializes an existing initialized run via --run-id, the run keeps its frozen run group even if --group-id is present. Use agent-runner run set-group or clear-group to change group membership.

Launcher precedence on fresh run/init is:

--launcher <name>
agent-authored launcher
built-in direct

In connected mode the daemon resolves named launchers against its own config root, then freezes the result into the manifest and reset seed. Launchers apply to subprocess-backed execution only; passive runs and Codex websocket/UDS transports keep the built-in direct launcher.

Execution environment precedence on fresh run/init is:

--environment <name|path>
agent-authored executionEnvironment
host execution

Container environments are currently subprocess-only and require the built-in direct launcher. They do not apply to passive runs or Codex websocket/UDS transports.

Schedule flags are accepted on init and run ready. Exactly one of --schedule-at, --schedule-delay, or --schedule-cron is required when scheduling. --schedule-timezone, --schedule-mode, and --schedule-continue-on-failure are cron-only. Schedule flags are rejected on fresh run, run --resume-run, and ready-start execution.

`serve`

Start the daemon. Hosts WebSocket JSON-RPC, HTTP, and the bundled web UI.

agent-runner serve [--listen <ws-url>]

--listen <ws-url> — defaults to ws://127.0.0.1:4773/ (or AGENT_RUNNER_LISTEN).
Rejects --connect, --connect-host, and --connect-local-port.

Set AGENT_RUNNER_DAEMON_AUTH_ENABLED=true and AGENT_RUNNER_DAEMON_TOKEN=<token> in the daemon environment to require a shared bearer token for daemon /api/* and WebSocket access. This is daemon access protection only; anyone with the token has full daemon access.

See daemon.md.

`status`

Print the current agent-runner system/environment context for this invocation.

agent-runner status [--output-format text|json]

Takes no positional arguments.
Text output prints the resolved config dir, state dir, host mode, connect URL, and daemon connectivity state.
JSON output returns { configDir, stateDir, hostMode, connectUrl, daemon }.
--field is not supported.

`run status <run-id>`

Print the run's current state.

agent-runner run status <run-id> [--output-format json] [--field <name> ...]

Run-id-only. Paths are not accepted.
--output-format json returns the shared RunDetail DTO.
--field <name> — repeatable. Projects top-level JSON fields.
JSON detail includes parentRunId when the run belongs to a lineage and always includes runGroupId.
JSON detail includes note, pinned, persisted schedule, and derived scheduleState.
Text output may show Pinned: yes and Note: present, but it never prints the note markdown body. It prints Schedule: none or the formatted schedule plus derived state.

`run brief <run-id>`

Print the composed worker handoff for a run. Text-only — does not support --output-format or --field. Run-id-only.

agent-runner run brief <run-id>

`run audit <run-id>`

Print the persisted audit history for a run. Text is the default output; JSON returns the shared RunAuditHistory DTO.

agent-runner run audit <run-id> [--output-format text|json] [--limit <n>]

Run-id-only. Paths are not accepted.
--output-format text|json — defaults to text.
--limit <n> — optional positive integer; keeps only the newest n audit envelopes after history load.
Text output is deterministic chronological rendering from the raw audit envelopes. Unknown event types fall back to raw field rendering instead of failing.
JSON output returns { runId, events, lastCursor }.
Exit codes:
- 0 success
- 1 usage / validation error
- 2 run not found
- 3 daemon / transport / other runtime error

`task`

Canonical task state commands. All subcommands accept --connect and --output-format.

agent-runner task list <run-id>
agent-runner task show <run-id> <task-id>

agent-runner task set <run-id> <task-id> \
  [--status pending|in_progress|completed|blocked] \
  [--notes <text>]

agent-runner task append-notes <run-id> <task-id> --text <text>

agent-runner task add <run-id> --title <title> [--body <body>]

Mutation rules depend on run state and backend type; see tasks.md.

`attachment`

agent-runner attachment add <run-id|path> <source-file> \
  [--name <text>] [--mime-type <type>]

agent-runner attachment list <run-id|path> [--scope run|group]

agent-runner attachment download <run-id|path> <attachment-id> <output-path>

agent-runner attachment remove <run-id|path> <attachment-id>

All attachment subcommands accept connected mode through the global --connect <ws-url> flag. In connected mode, add and download transfer bytes over the existing daemon WebSocket stream notifications, while list and remove use WebSocket JSON-RPC. The daemon HTTP attachment endpoints remain available for browser/API callers.

See attachments.md.

`list`

agent-runner list agents
agent-runner list assignments
agent-runner list launchers
agent-runner list environments
agent-runner list tasks
agent-runner list runs \
  [--cwd <path> | --repo <name> | --global] \
  [--group-id <group-id>] \
  [--include-archived]

list agents, list assignments, list launchers, list environments, and list tasks enumerate reusable definitions from ${AGENT_RUNNER_CONFIG_DIR}.
list tasks lists markdown task definition files under ${AGENT_RUNNER_CONFIG_DIR}/tasks; invalid task definitions are warned to stderr in text mode and included in the JSON payload's warnings array in JSON mode.
list runs defaults to the caller's exact cwd.
--cwd <path> filters by exact persisted cwd.
--repo <name> filters by repo bucket.
--global disables cwd scoping.
--group-id <group-id> filters by exact run group and is mutually exclusive with --cwd, --repo, and --global.
--include-archived adds archived runs.

`show`

agent-runner show agent <name|path>
agent-runner show assignment <name|path>
agent-runner show launcher <name|path>
agent-runner show environment <name|path>
agent-runner show task <name|path>

Renders the parsed frontmatter, declared vars (for assignments), task lists, launcher definitions, environment definitions, or reusable task definition title/body/hooks. For show task, bare strings are named ids under ${AGENT_RUNNER_CONFIG_DIR}/tasks; absolute paths and strings beginning with ./ or ../ are direct markdown file paths.

`run` groupings

Lifecycle

agent-runner run reconfigure <id> [--var key=value ...] [--message-file <path> | <message...>]
agent-runner run ready    <id|path> [--schedule-at <iso> | --schedule-delay <duration> | --schedule-cron <expr>]
agent-runner run reset     <id|path>
agent-runner run archive   <id|path>
agent-runner run unarchive <id|path>
agent-runner run delete    <id|path>    # archived only

run ready can attach or replace the run's schedule during the initialized-to-ready transition. A scheduled run remains in ready until the daemon observes it as due, but a caller can still start it manually with run --resume-run <id|path>.

run reconfigure is only valid for unarchived initialized runs. It patches runtime vars and/or the initial message, then rerenders the brief and reset seed as one atomic mutation. If var validation, required inputs, locked fields, or prepare/rendering fail, the existing manifest is left unchanged. Reconfigure does not support identity/runtime changes: agent, assignment, backend, cwd, tasks, schedule, launcher, hooks, selected backendConfig, and selected backend args remain the frozen values from the initialized run.

Execution environment

agent-runner run environment status <id>
agent-runner run environment validate <id>
agent-runner run environment cleanup <id>

status prints the frozen execution environment state from the run manifest. validate checks an existing container or starts/validates a managed container and persists the updated state. cleanup removes a agent-runner-managed environment when the run is not running and no same-group initialized, ready, or running run still references the shared environment. Externally managed containers are never removed.

Exit codes are 0 for success, 2 when the run id is not found, 3 for invalid input/lifecycle/var/lock/prepare failures, and 4 for unexpected runtime errors.

Queued resume messages

agent-runner run queue-message <id|path> <message text>
agent-runner run queued-messages <id|path>
agent-runner run remove-queued-message <id|path> <message-id>

Queued resume messages are daemon-owned pending follow-ups for live runs. queue-message appends message text, queued-messages lists the current queue, and remove-queued-message deletes one queued message. When a managed run finishes with queued messages still present, the daemon starts the next resume session with those messages joined by a blank line.

All three commands accept --connect and --output-format text|json. The target may be a run id or workspace path.

Schedule

agent-runner run schedule <id|path> --at <iso>
agent-runner run schedule <id|path> --delay <duration>
agent-runner run schedule <id|path> --cron <expr> \
  [--timezone <iana>] [--mode reuse|reset|clone] [--continue-on-failure]
agent-runner run schedule enable <id|path>
agent-runner run schedule disable <id|path>
agent-runner run schedule clear <id|path>

run schedule <id|path> ... sets or replaces the schedule and requires exactly one of --at, --delay, or --cron. There is no explicit set subcommand. --timezone, --mode, and --continue-on-failure are valid only with --cron. clear removes one-time schedules only; recurring schedules must be disabled.

One-time schedules stay subject to AGENT_RUNNER_MIN_SCHEDULE_DELAY_SEC. Recurring schedules are validated with AGENT_RUNNER_MIN_RECURRENCE_INTERVAL_SEC and can run in reuse, reset, or clone mode.

Metadata

agent-runner run set-name <id|path> <name>
agent-runner run set-name <id|path> --clear
agent-runner run set-note <id|path> <markdown>
agent-runner run clear-note <id|path>
agent-runner run pin <id|path>
agent-runner run unpin <id|path>
agent-runner run set-group <id|path> <group-id>
agent-runner run clear-group <id|path>
agent-runner run set-backend-session   <id|path> <session-id>   # passive only
agent-runner run clear-backend-session <id|path>                # passive only

run set-note trims only for empty/whitespace detection; a whitespace-only value clears the note.
run clear-note clears the note without a second positional.
run pin / run unpin toggle persisted pin metadata without moving a run across status columns.
run set-group and run clear-group apply to non-running runs. A cleared group becomes the run's singleton group (runGroupId === runId).
Metadata mutations accept --output-format text|json and --connect.
Note text is never echoed back in text output; use JSON or the web UI to inspect the full stored note.

Dependencies

agent-runner run add-dep    <id> --run <dependency-run-id>
agent-runner run add-dep    <id> --group <group-id>
agent-runner run remove-dep <id> --run <dependency-run-id>
agent-runner run remove-dep <id> --group <group-id>
agent-runner run clear-deps <id>

Dependency mutations are only allowed on initialized runs and require a typed ref for add/remove: exactly one of --run or --group. See dependencies.md.

Exit codes

Code	Meaning
`0`	Success (all tasks completed, or initialized run)
`1`	Retries exhausted with incomplete tasks
`2`	One or more tasks reported blocked
`3`	Validation, config, or daemon connectivity error
`4`	Backend or runtime failure
`130`	User cancellation / confirmed interrupt

Environment variables

Recognized by the CLI:

AGENT_RUNNER_CONFIG_DIR, AGENT_RUNNER_STATE_DIR
AGENT_RUNNER_CMD
AGENT_RUNNER_LISTEN, AGENT_RUNNER_CONNECT, AGENT_RUNNER_CONNECT_HOST, AGENT_RUNNER_CONNECT_LOCAL_PORT
AGENT_RUNNER_PARENT_RUN_ID, AGENT_RUNNER_RUN_ID, AGENT_RUNNER_RUN_GROUP_ID, AGENT_RUNNER_CWD
AGENT_RUNNER_CLAUDE_BIN, AGENT_RUNNER_CODEX_BIN, AGENT_RUNNER_CODEX_UDS_PATH, AGENT_RUNNER_CODEX_WS_URL, AGENT_RUNNER_CURSOR_BIN, AGENT_RUNNER_OPENCODE_BIN, AGENT_RUNNER_OPENCODE_DATA_DIR, AGENT_RUNNER_PI_BIN, PI_HOME
AGENT_RUNNER_CAPTURE_BACKEND_STDOUT, AGENT_RUNNER_BACKEND_SESSION_SYNC
AGENT_RUNNER_MIN_SCHEDULE_DELAY_SEC, AGENT_RUNNER_MIN_RECURRENCE_INTERVAL_SEC
AGENT_RUNNER_MAX_CALL_DEPTH
AGENT_RUNNER_DAEMON_AUTH_ENABLED, AGENT_RUNNER_DAEMON_TOKEN, AGENT_RUNNER_DAEMON_FILESYSTEM_LOCKS

See configuration.md.

Daemon vs embedded

Every client command (except serve) can run embedded (no daemon) or route through a daemon with --connect <ws-url> or AGENT_RUNNER_CONNECT. Daemon-routed commands use the same WebSocket JSON-RPC surface that the web dashboard uses.

When connecting to an auth-enabled daemon, set AGENT_RUNNER_DAEMON_TOKEN in the client environment. Connected CLI requests trim that value and send Authorization: Bearer <token> on WebSocket handshakes and direct daemon HTTP helper requests. Empty or unset client tokens omit Authorization and will be rejected by auth-enabled daemons. A 401 WebSocket handshake failure prints a hint to set AGENT_RUNNER_DAEMON_TOKEN instead of the generic daemon-start hint.

The token is not a transport security layer. For remote daemons, use --connect-host SSH forwarding, HTTPS, WireGuard, Tailscale, a VPN, or an equivalent secure channel, and keep tokens and Authorization headers out of logs. The MVP does not provide per-user isolation.

run --detach is daemon-only: the CLI dispatches the run and exits after the daemon accepts it.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CLI Reference

Command index

Global flags

`run`

`init`

`serve`

`status`

`run status <run-id>`

`run brief <run-id>`

`run audit <run-id>`

`task`

`attachment`

`list`

`show`

`run` groupings

Lifecycle

Execution environment

Queued resume messages

Schedule

Metadata

Dependencies

Exit codes

Environment variables

Daemon vs embedded

FilesExpand file tree

cli.md

Latest commit

History

cli.md

File metadata and controls

CLI Reference

Command index

Global flags

run

init

serve

status

run status <run-id>

run brief <run-id>

run audit <run-id>

task

attachment

list

show

run groupings

Lifecycle

Execution environment

Queued resume messages

Schedule

Metadata

Dependencies

Exit codes

Environment variables

Daemon vs embedded

`run`

`init`

`serve`

`status`

`run status <run-id>`

`run brief <run-id>`

`run audit <run-id>`

`task`

`attachment`

`list`

`show`

`run` groupings