Command-line options
Every switch the desktop waycoder command accepts. (On a phone you don't need them — you tap buttons.)
⚠ Don't copy this table by hand: it is generated from the argument registry by scripts/make-cli-help.py (--dump-help). Change an option without re-running it and this page goes stale (--check catches that).
Notation: [brackets] = optional value, <angle brackets> = placeholder to fill in; one option may have several aliases (e.g. -m / --model).
---< Model >----------------------
-m, --model [model ID/subcommand] Model management (keys support expiry: --model key <provider> <key> [forever|date])
list [provider] List the model catalog (OpenRouter shows short names)
name <id> Select the main model
small <id> Select the small model
key [set|remove] Manage API keys (keys are never auto-deleted; removal asks for confirmation)
check [connect] Check model capabilities (think/tools/vision/format/context/key)
report Test connectivity of every connect and report what works and what fails
free Test every free model (zen -free / openrouter :free) and list the reachable ones
restore Restore the model from before /free switched to a free one
import [alllocal|allonline|all|online <source>|source] Import models (alllocal = local / allonline = online / all = both / online <source> = one endpoint)
add model/provider/key Add a model / provider / key
remove <id> Remove a model or provider
clean Clean invalid providers/models + merge duplicates + drop invalid connects
test Test the connection
connect <base-url> Set the API base URL
<model ID> Quick-select a model
-b, --base-url <URL> API base URL
-k, --api-key <key> API key (saved automatically to the global ~/.waycoder/api_keys.json, under the current provider)
--tiny [window size] Tiny mode (trimmed prompt + small context window; pass e.g. --tiny 8k, otherwise auto-detected with a 4K fallback)
-tt, --test-tiny [window size] alias
-e, --economy [mode] Token-saving mode (--economy [on|auto|off], default on; auto adjusts the thresholds to task complexity)
---< Session >--------------------
-r, --resume [session name] Resume a session; leave the name out to resume the most recent one.
-c, --continue [session name] alias
-s, --session-list List every saved session
--sessions alias
--session <session ID> Resume by session id; same as --resume <id>
--resume-session-id <session ID> alias
--session-id <session ID> alias
---< Execution >------------------
-p, --prompt <text> One-shot prompt (plain CLI output, exits when done). -p1..-p0 queue into a slot (enters the TUI), -pa is a shared prefix, the same slot can be queued repeatedly
--print <text> alias
--output-format <format> Output format: json|stream-json behave like --json, text|default is normal output
--format <format> alias
-j, --json JSON output mode (use with -p one-shot mode; prints structured JSON to stdout for IDEs/scripts)
-pa, --prompt-all <prefix> Shared prefix for all slot tasks (prepended to every -pN)
---< Budget >---------------------
-B, --max-budget-usd <amount> Cost cap in USD; stops automatically once exceeded
--max-requeue <count> Auto-compact-and-continue attempts after the turn limit is hit (0 = off, default 3; raise it for very long tasks)
--max-turns <count> Maximum conversation turns
---< Permission >-----------------
-y, --yolo Skip every permission confirmation (turned on automatically in non-interactive mode)
--dangerously-skip-permissions alias
--permission-mode <mode> Permission mode: default|acceptEdits|plan|bypassPermissions (plan = read-only planning, acceptEdits = auto-edit, bypassPermissions = everything allowed)
--allowed-tools [tool name] Tool allowlist (space/comma separated); same as WAYCODER_ALLOWED_TOOLS
--allowedTools [tool name] alias
--disallowed-tools [tool name] Tool denylist (space/comma separated); same as WAYCODER_DISABLED_TOOLS
--disallowedTools [tool name] alias
--permit <tiny|chat|ack|auto|smart|yolo> Startup permission mode (tiny/chat = pure chat work mode)
tiny Chat: pure chat work mode (no tools, no prompt)
ack Ask: confirm every step
auto Auto: always ask on edits; reads pass, writes confirm
smart Smart: risk-graded confirmation
yolo Yolo: skip every confirmation
--mode <build|plan|chat> Startup work mode: build = full toolset, plan = read-only allowlist, chat = no tools and no prompt
---< Interface >------------------
--web [port] Browser chat UI (--web [port], default 9527, opens the browser automatically)
--tui Force the full-screen TUI (this is the default)
--cli Force the plain CLI text interface (line-by-line, not full screen)
--theme <name> Switch the color theme (ocean/forest/sunset/mono/cyberpunk)
-q, --quiet Quiet mode: suppress the banner and other non-essential output
--no-color Disable ANSI color output
-g, --gui [file] Launch the GUI (a separate Avalonia process; --gui [file] opens the editor directly)
--keypad <script file> Drive the TUI from a key script (KEY/TEXT/DELAY/SNAP/DIALOG) + frame captures
---< System >---------------------
-i, --init Initialize project configuration (the .waycoder/ directory)
--system-prompt <text> Text appended to the system prompt (--append-system-prompt is an alias)
--append-system-prompt <text> alias
-w, --watch Watch mode (listens for AI! comments in files)
--edit <file path> Open a file in the editor right away (--edit <file path>)
--update Check for and auto-upgrade to the latest version (GitHub first, Gitee as fallback)
-C, --config item [value] Command-line configuration
list List every setting
get <key> Read one setting
set <key> <value> Set it and write config.json
<key> [value] Shorthand: read or set
-d, --debug Enable debug logging (writes to the logs/ directory)
--auto-commit [on|off] Auto git-commit switch (on|off, default on)
--mcp-config <path> Path to the MCP server config file
--mcp [subcommand] MCP server management (no argument lists them, reload [name] reconnects)
(no args) List MCP server status
reload [name] Reconnect an MCP server
--reset Clear the current session history
--purge Purge cache files (file-tracker/todos/trajectory)
--provider [subcommand] Manage the provider database (providers.json)
list List every provider
add <id> <name> <base-url> Add a provider
rm <id> Remove a provider (and clear its key)
select <id> Switch the current provider (applies to the main model's connect)
key <id> <key> Save an API key for a provider
test Connectivity test
import [source] Import an external model catalog
clean Clean invalid providers (ones that failed the probe)
reconcile [apply] Merge models into the registered provider at the same address (preview by default; apply/run actually writes, after a backup)
---< Batch >----------------------
--batch <JSON> Batch engine: parallel multi-repo processing (--batch <JSON file|inline JSON>; each job runs isolated in its own clone)
--batch-repo <repo> Batch job: add a repository (repeatable; pair with --batch-task for a shared task)
--batch-task <text> Batch job: the task shared by every --batch-repo repository
--batch-keep Batch job: keep the cloned working copies (cleaned up after the run by default)
---< Test >-----------------------
-t, --test [module name] Run the self-test (optionally for a single module)
---< General >--------------------
-v, --version Show version information
-h, --help Show this help
---< Other >----------------------
--connect [connect name/subcommand] Connection layer management (connect registry / named connections / fallback chain)
list List connects + named connections + the fallback chain
add <name> <providerId> <modelId> Add a connect
rm <name> Remove a connect
select <id> Switch the main connect (connect name | providerId.modelId | providerId/modelId | baseUrl:model | modelId)
<id> Quick switch (same as select)
test Connectivity test
import Register the current main/small/fallback models as connects
conn add <name> <main> <small> Add a named connection (switches main and small together)
use <name> Switch to a named connection
chain <c1> <c2> ... Set the global fallback chain (connect names)
--debug-dump Enable automatic freeze capture (black box + periodic/freeze dumps to logs/freeze_*.txt, for diagnosing hangs)
--kb [subcommand] Programming knowledge base (mine extracts lessons / review does spaced-repetition self-tests / weak shows weakness stats)
mine [N] Extract lessons from git history (default 20)
diagnose <error> Diagnose an error (recalls the knowledge base + git fix history)
path Generate a learning path (gaps -> advanced, feeds /kb review)
profile [json] Skill profile (json export)
retro Retrospect this session and extract lessons
review Spaced-repetition self-test for one due lesson
weak Gap list + weakness stats
list List every lesson entry
--bench Run the performance benchmark
-tb, --test-benchmark alias
--perf alias
--limits Run the system-limits report (scans every hard-coded limit)
-tl, --test-limits alias