displayName
amux run
kind
cli-subcommand
surface
cli
parentBin
amux
subcommandVerb
run
flags
- --stream:0:enable streaming output
- --no-stream:0:disable streaming
- --thinking-effort:1:low|medium|high|max
- --thinking-budget:1:thinking budget tokens
- --thinking-override:1:JSON object override for thinking config
- --temperature:1:sampling temperature 0.0-2.0
- --top-p:1:nucleus sampling
- --top-k:1:top-k sampling
- --max-tokens:1:max output tokens
- --max-output-tokens:1:max output tokens (alias)
- --max-turns:1:maximum agentic turns
- --session:1:resume session id
- --fork:1:fork session id
- --no-session:0:ephemeral run
- --system:1:system prompt
- --system-mode:1:prepend|append|replace
- --cwd:1:working directory
- --env:N:KEY=VALUE pair (repeatable)
- --yolo:0:auto-approve all tool calls
- --deny:0:auto-deny all approval requests
- --timeout:1:overall timeout ms
- --inactivity-timeout:1:inactivity timeout ms
- --output-format:1:event/JSONL output format
- --tag:N:tag (repeatable)
- --run-id:1:explicit run id
- --attach:N:attachment ref (repeatable)
- --skill:N:skill name (repeatable)
- --agents-doc:1:path to AGENTS.md
- --mcp-server:N:MCP server spec (repeatable)
- --project-id:1:project id
- --profile:1:named profile to apply
- -p / --prompt:1:prompt text
- --non-interactive:0:force headless one-shot
- -i / --interactive:0:enter interactive REPL
- -q / --quiet:0:suppress non-essential output
- --use-mock-harness:0:swap in mock harness adapter
- --mock-scenario:1:mock scenario name
subcommandExitCodes
- 0:success:run completed
- 1:general-error:internal/INTERNAL or unhandled adapter error
- 2:usage-error:VALIDATION_ERROR (missing prompt/agent, mutual exclusion)
- 3:agent-not-found:AGENT_NOT_FOUND/UNKNOWN_AGENT
- 4:agent-not-installed:AGENT_NOT_INSTALLED
- 5:auth-error:AUTH_ERROR
- 6:capability-error:CAPABILITY_ERROR (e.g. interactive unsupported)
- 7:config-error:CONFIG_ERROR / CONFIG_LOCK_ERROR
- 8:session-not-found:SESSION_NOT_FOUND
- 9:profile-not-found:PROFILE_NOT_FOUND
- 11:timeout:TIMEOUT / INACTIVITY_TIMEOUT / runResult.exitReason=timeout|inactivity
- 12:agent-crashed:AGENT_CRASH / runResult.exitReason=crashed|killed
- 13:aborted:ABORTED / runResult.exitReason=aborted|interrupted
- 14:rate-limited:RATE_LIMITED
- 15:context-exceeded:CONTEXT_EXCEEDED
description
Run an agent with a prompt. Resolves agent + prompt from positionals/flags/stdin,
optionally swaps in a mock harness, calls client.run() and streams events
(text deltas in plain mode, JSONL in --json mode). Source:
packages/agent-mux/cli/src/commands/run.ts:188-313.