commandagent [OPTIONS] [GOAL]... starts the interactive TUI when no action is
selected. A trailing goal can contain multiple words without quoting because it
is collected as the final argument list. The installed binary remains the
authority: use commandagent --help when its version differs from this checkout.
Use one of the action-selector flags for a direct command, or omit all of them
for the TUI. The action selectors are --prompt, --plan-steps, --plan-run,
--run-plan, --ultra-plan, --ultra-plan-run, --run-ultra-plan,
--validate-plan, --setup-interaction-probe, --runs, --ux-demo, --model-probe,
--doctor, and --extensions. The offline pack actions --packs, --pack-verify, and
--pack-pin, generated-artifact actions --completions and --generate-man,
config action --init-config, and delegated manifest actions
--validate-manifest and --init-profile are displayed in the same
Actions (use one) help group. CommandAgent rejects combinations whose action
contracts are mutually exclusive.
Clap also generates -h/--help and -V/--version. They are not part of the
66 application flags below. The hidden --completion-contract-json <PATH> is an
internal integration surface and is intentionally not a public user flag.
| Flag | Argument | Default when omitted | Description | Related |
|---|---|---|---|---|
--yes |
none | off | Allow every tool and skip resume confirmation; recognized Bash writes remain workspace-confined. It never auto-kills a busy-port owner. Use only in a trusted workspace. | Busy ports |
--allow |
<read|write|bash:verify> |
legacy read access and per-mutation approval | Allow only the selected tool classes; repeat or comma-separate read, write, and bash:verify. Selected mutations are auto-approved, while omitted classes are blocked. | Security model |
--preset |
<PRESET> |
none | Select a named [preset.<name>] assembled from configuration files. |
Presets |
--pack |
<ID@VERSION> |
preset pack, then none |
Activate an exact-version pack. A conflicting preset pack is rejected before the run. | Pack selection |
--pack-hash |
<SHA256> |
verified pack.sha256 |
Require the selected pack's exact-byte hash. Requires --pack. |
Pack selection |
--extension-root |
<DIR> |
top-level extension_root, then none |
Load local packs and profiles/<id>/manifest.toml draft profiles. External profiles are forced to draft and pinned by exact-byte hash. |
Pack selection |
--extensions |
none | off | Inspect profiles, overlays, packs, usability reasons, and the latest journal record under the extension root. | Conflicts |
--packs |
none | off | List compatible admitted packs and conformant packs found under --extension-root, including each source. Requires --profile and --intent. |
Conflicts |
--pack-verify |
<DIR> |
none | Run strict conformance for one pack directory and print the same JSON report as pack_conformance. |
Conflicts |
--pack-pin |
<DIR> |
none | Create pack.sha256 after green conformance, keep an identical pin unchanged, and reject a stale pin. |
Conflicts |
--context-budget |
<CONTEXT_BUDGET> integer |
65536 |
Set the approximate conversation compaction budget. | Resolved defaults |
--model |
<MODEL> |
qwen3.6:27b-coding-nvfp4 |
Set the executor model ID. | Providers |
--provider |
<PROVIDER>: ollama, lm-studio, openai, gemini, or openai-compatible |
ollama |
Select the executor provider. | Providers |
--base-url |
<URL> |
none | Set the base URL for the generic OpenAI-compatible provider; an optional trailing /v1 is normalized. |
OpenAI-compatible servers |
--api-key-env |
<NAME> |
none | Read an optional OpenAI-compatible bearer token from this process-environment variable. | OpenAI-compatible servers |
--api |
<chat-completions|responses> |
chat-completions |
Explicitly select the OpenAI-compatible API surface; model names never select it implicitly. | Presets |
--tool-protocol |
<native|text> |
provider capability default | Explicitly select native function tools or the established text/XML tool protocol. | Presets |
--prompt-layout |
<stable|legacy> |
legacy |
Choose prompt section order for A/B measurement. | Precedence |
--plan-preset |
<profile|none> |
normally none; profile is selected for explicit data fix/investigate cases |
Override planner-tier UltraPlan preset selection. data/fix can synthesize F1–F3 steps; nextjs/fix remains none-equivalent. |
Precedence |
--intent |
<create|fix|investigate> |
inferred from the goal | Force intent instead of goal-based resolution. | Examples |
--workflow |
<PATH> |
none | Run a declarative workflow-circle definition. Mutually exclusive with --intent. |
Examples |
--origin |
<PATH> |
none | Supply the existing failed origin run workspace for --workflow. |
Examples |
--planner-model |
<PLANNER_MODEL> |
executor model when providers match | Set the planner model ID. Required when planner and executor providers differ. | Provider roles |
--planner-provider |
<PLANNER_PROVIDER>: ollama, lm-studio, openai, gemini, or openai-compatible |
executor provider | Select the planner provider. | Provider roles |
--prompt |
<PROMPT> |
none | Run one minimal-loop prompt instead of entering the TUI. | Examples |
--plan-steps |
none | off | Generate and save a step plan for the trailing goal. | Action exclusivity |
--plan-run |
none | off | Generate and run a step plan for the trailing goal. | Action exclusivity |
--run-plan |
<RUN_PLAN> path |
none | Run an existing step-plan YAML file. | Action exclusivity |
--ultra-plan |
none | off | Generate and save an UltraPlan for the trailing goal. | Action exclusivity |
--ultra-plan-run |
none | off | Generate and run an UltraPlan for the trailing goal. | Action exclusivity |
--run-ultra-plan |
<RUN_ULTRA_PLAN> path |
none | Run an existing UltraPlan YAML file. | Action exclusivity |
--validate-plan |
<PATH> |
none | Validate a step-plan or UltraPlan YAML file without executing it; errors include line and column numbers. | Plan YAML editing |
--setup-interaction-probe |
none | off | Install or validate the managed Playwright interaction probe. | Probe unavailable |
--runs |
optional <ID> |
off | List recent runs, or show one run by ID, without creating provider clients. | Slash /runs |
--events |
none | off | Show the selected run's events in chronological order. Requires --runs <ID>. |
Troubleshooting |
--filter |
<phase|tool|provider> |
none | Filter a selected run's events by phase, tool, or provider. | Troubleshooting |
--ux-demo |
none | off | Run the offline presentation UX demo. | Action exclusivity |
--model-probe |
none | off | Run the bounded model behavior probe battery. | Model probe |
--doctor |
none | off | Diagnose configuration files, provider readiness, interaction probes, and the local environment without making network requests. | Slash /doctor |
--json |
none | off | Render --doctor, --extensions, or --runs output as stable machine-readable JSON. | Slash /doctor |
--completions |
<SHELL>: bash, elvish, fish, powershell, zsh |
none | Generate a completion script from the current Clap definition and write it to stdout. | Shell completions and man page |
--generate-man |
none | off | Generate the commandagent(1) man page from the current Clap definition and write it to stdout. |
Shell completions and man page |
--init-config |
none | off | Create .commandagent/config.toml from a starter template without overwriting an existing file. |
Config template |
--validate-manifest |
<PATH> |
none | Validate an external profile manifest without running it. | Manifest v2 |
--init-profile |
<ID> |
none | Initialize a draft profile manifest under --extension-root. |
Manifest v2 |
--profile |
<PROFILE> |
inferred, then generic |
Set a compiled profile or an external draft ID. An external ID requires the extension root that declares profiles/<id>/manifest.toml. |
Profile inference |
--style |
<STYLE> |
default |
Pass the plan presentation/generation style. | Inline flags |
--resume |
<RESUME> |
none | Load the named saved minimal-loop session for a direct --prompt run. |
Session options |
--offline |
none | off | Block runtime dependency setup and Bash commands containing npm/pnpm/yarn/cargo install, curl, or wget. Provider/API requests and other network-capable commands are unaffected. | Providers |
--quiet |
none | off (narration = "normal") |
Suppress presentation narration. | Top-level keys |
--summary-json |
none | off | Append one machine-readable terminal run summary as the final stdout line. Omitting it preserves existing stdout bytes. | Headless execution |
--trace |
none | off | Opt in to scrubbed provider request and response traces under the active run directory. | Troubleshooting |
--ollama-host |
<OLLAMA_HOST> URL |
http://localhost:11434 |
Set the Ollama server base URL used by CommandAgent. | Ollama host |
--think |
[=<true|false|low|medium|high>] |
omitted | Enable Ollama thinking for every Ollama provider role. A bare flag means true; explicit values require =, for example --think=high. |
Ollama thinking |
--lm-studio-host |
<LM_STUDIO_HOST> URL |
http://localhost:1234 |
Set the LM Studio base URL; an optional trailing /v1 is normalized. |
LM Studio server |
--num-predict |
<NUM_PREDICT> integer |
8192 |
Set the maximum provider output-token request. | Resolved defaults |
--max-iterations |
<MAX_ITERATIONS> integer |
12 |
Set the minimal-loop iteration budget. | Resolved defaults |
--recovery-plan-auto-runs |
<0..20> integer |
0 |
Automatically execute at most this many validated Recovery Plans after a failed UltraPlan execution, including direct actions, matching REPL commands, and resume (0 disables; total plan executions are at most 1 + this value). | Plan YAML |
--chat-timeout-secs |
<CHAT_TIMEOUT_SECS> integer |
600 if either role uses Ollama or LM Studio; otherwise 180 |
Set connect and whole-request timeouts for provider calls. | Resolved defaults |
--chat-retries |
<CHAT_RETRIES> integer |
1 |
Set retries after the initial provider attempt. | Provider failures |
--stream |
<on|off> |
on for the TUI, off for direct actions | Control visible executor and repair streaming; planner machine output stays hidden. Streaming still requires an interactive stdin and stdout TTY. | Top-level keys |
--state-dir |
<STATE_DIR> path |
$XDG_STATE_HOME/commandagent, otherwise ~/.local/state/commandagent |
Override saved session and REPL history storage; the default loader retains the legacy anvilminimal fallback. |
Paths |
--cwd |
<CWD> path |
current directory | Set and canonicalize the active workspace before config discovery and execution. | Paths |
--fresh-session |
none | off | Ignore --resume and create a session for a direct --prompt run. |
Session options |
--footer |
<on|off> |
on |
Control the fixed TUI footer; off keeps scrollback breadcrumbs. | Footer problems |
--no-footer |
none | off | Disable the fixed TUI footer. Equivalent in effect to --footer off. |
Footer problems |
Within one TUI session, /model <id> and /provider <name> change the
executor selection, while /profile <name> changes the explicit profile.
These settings apply to new Gate 1 cards and are shown by /status; an already
rendered card keeps its frozen identity. Use grouped /help or
/help <command> for runtime usage and examples. /status shows current
execution before the remaining session configuration, /last repeats the most
recent result, and /clear clears the terminal screen.
/confirm always accepts the full hash printed on the latest pending Gate 1
card. By default it also accepts a matching canonical sha256: prefix with at
least eight hexadecimal digits, such as /confirm sha256:77cd5e23. Set
COMMANDAGENT_STRICT_CONFIRM=1 before starting CommandAgent to require the
full hash. Prefixes are expanded to the frozen full hash before confirmation is
persisted.
REPL history is isolated beneath --state-dir at
workspace-history/<sha256-of-canonical-workspace>.txt. Only the active
workspace file is loaded, and history hints require two entered characters and
fit on one terminal line. The former shared <state-dir>/history.txt is not
loaded, migrated, modified, or deleted, so existing history is preserved
without exposing it in another workspace.
Only values declared with a Clap default are fixed before configuration
resolution. Values such as model, provider, context budget, timeout, profile,
footer, and stream receive their effective defaults in Config::from_cli.
See Configuration for the exact per-field layers.
| Setting | Effective default |
|---|---|
num_predict |
8192 |
max_iterations |
12 |
chat_timeout_secs |
600 seconds when either provider role is Ollama or LM Studio; 180 seconds when both are remote |
chat_retries |
1 retry after the first attempt |
context_budget |
65536 |
--footerand--no-footerare a Clap-level conflict and cannot be used together.--allowacceptsread,write, andbash:verifyas repeated or comma-separated values. Once supplied, omitted tool classes are blocked;--yesis the backward-compatible all-tools alias.- Only one action selector may be used. This is checked after parsing and fails
with
only one action selector can be used at a time. --packs,--pack-verify, and--pack-pinare Clap-level direct actions. They conflict with one another, run action selectors,--pack, and--pack-hash. Listing allows--extension-root, while verify and pin take their target directory directly.--extensionsis read-only and accepts--extension-root; when omitted, it resolves the top-levelextension_rootsetting.--jsonis accepted with either--extensionsor--doctor.--plan-steps,--plan-run,--ultra-plan, and--ultra-plan-runrequire a trailing goal.--validate-planis an offline, read-only action and conflicts with every execution or generated-artifact action. It accepts step-plan, UltraPlan, and recovery UltraPlan YAML; see Plan YAML editing.- A different
--planner-providerrequires an explicit or presetplanner_model; otherwise startup fails. --thinkrequires at least one resolved provider role to use Ollama. When both roles use another provider, startup fails instead of ignoring the flag.- For direct minimal-loop prompts,
--fresh-sessiontakes precedence over--resume. These session switches are not used by slash-command plan resume. --init-profilerequires an existing--extension-root. It creates a compact draft v2 manifest and refuses to overwrite an existing file.--validate-manifestchecks a v1/v2 profile manifest or v1 overlay without registering or running it. Failures report one file, line, column, and reason.
--init-config creates .commandagent/config.toml in the active workspace
(the current directory, or --cwd). The starter contains a complete local
preset with explicit provider, model, planner, classifier, budget, profile, and
display settings. Review the values before selecting it with --preset local.
An existing config is never changed:
commandagent --init-config
commandagent --preset localBoth interfaces generate from the current Clap command definition, so newly
added flags are included automatically. The completion registration delegates
each completion request to the installed binary. For --model and
--planner-model, that binary briefly queries the default Ollama /api/tags
and LM Studio /v1/models endpoints, merges their model IDs, and produces no
warning when either endpoint is unavailable. Generated artifacts write only to
stdout; redirect the output to a user-owned installation path and regenerate
it after updating CommandAgent.
scripts/setup.sh offers to install a completion for the detected Bash, Zsh,
or Fish shell. For manual installation, use the appropriate command below.
For Bash with the standard per-user bash-completion directory:
completion_dir="${BASH_COMPLETION_USER_DIR:-${XDG_DATA_HOME:-$HOME/.local/share}/bash-completion}/completions"
mkdir -p "$completion_dir"
commandagent --completions bash > "$completion_dir/commandagent"For Zsh, place the _commandagent function in a directory on fpath, then
initialize completion:
completion_dir="${XDG_DATA_HOME:-$HOME/.local/share}/zsh/site-functions"
mkdir -p "$completion_dir"
commandagent --completions zsh > "$completion_dir/_commandagent"
fpath=("$completion_dir" $fpath)
autoload -Uz compinit && compinitPersist the last two lines in .zshrc. For Fish:
set completion_dir (string join / (set -q XDG_CONFIG_HOME; and echo $XDG_CONFIG_HOME; or echo $HOME/.config) fish completions)
mkdir -p $completion_dir
commandagent --completions fish > $completion_dir/commandagent.fishFish loads that path automatically. For PowerShell, save the generated script
and dot-source it from the current session or from $PROFILE:
commandagent --completions powershell > "$HOME/.commandagent-completion.ps1"
. "$HOME/.commandagent-completion.ps1"Elvish generation is also available through commandagent --completions elvish; load or store that output according to your Elvish configuration.
To install the generated man page in the common per-user location:
man_dir="${XDG_DATA_HOME:-$HOME/.local/share}/man/man1"
mkdir -p "$man_dir"
commandagent --generate-man > "$man_dir/commandagent.1"
man -l "$man_dir/commandagent.1"Add the parent man directory to MANPATH if you want man commandagent to
discover it without an explicit path.
# Start the interactive TUI with defaults.
commandagent
# Run one executor prompt against a cloud provider.
commandagent --provider gemini --model gemini-model-id \
--prompt "Explain the current workspace"
# Generate and run an UltraPlan with explicit roles and profile.
commandagent --provider ollama --model local-executor \
--planner-provider openai --planner-model openai-model-id \
--profile nextjs --ultra-plan-run Build a Next.js app on port 3011
# Disable the fixed footer when the terminal renders it badly.
commandagent --footer off