Skip to content

commands.md

Latest commit

 

History

History
380 lines (270 loc) · 9.7 KB

commands.md

File metadata and controls

380 lines (270 loc) · 9.7 KB

Command Reference

Complete CLI reference for csa. All commands support --format json for machine-readable output.

csa run -- Execute a task

Run a prompt against an AI tool with session management and resource checks.

csa run --sa-mode false [OPTIONS] [PROMPT]
Flag Description
--sa-mode <BOOL> Root callers must pass true or false; internal recursive calls default to false
--tool <TOOL> Tool selection: auto (default), any-available, or specific name
--auto-route <INTENT> Resolve routing intent through [tier_mapping] or a tier selector while keeping tool choice automatic
--hint-difficulty <LABEL> Resolve a difficulty label through [tier_mapping] when no explicit --tier/--model-spec is set
--skill <NAME> Run a named skill as a sub-agent
--session <ID> Resume existing session (ULID or prefix)
--last Resume the most recent session
--description <TEXT> Description for a new session
--ephemeral Ephemeral session (no project files, auto-cleanup)
--model-spec <SPEC> Full model spec: tool/provider/model/thinking
--model <MODEL> Override tool default model
--thinking <LEVEL> Thinking budget: low, medium, high, xhigh
--force Bypass tier whitelist enforcement
--no-failover Disable automatic 429 failover
--wait Block-wait for a free slot instead of failing
--idle-timeout <SECS> Kill when no output for N seconds
--no-idle-timeout Disable idle-timeout killing
--stream-stdout Force stdout streaming to stderr
--no-stream-stdout Suppress real-time streaming
--cd <DIR> Working directory

If PROMPT is omitted, reads from stdin.

Examples:

csa run --sa-mode false "fix the login bug"
csa run --sa-mode false --tool codex --thinking high "refactor error handling"
csa run --sa-mode false --tool claude --hint-difficulty quick_question "answer briefly"
csa run --sa-mode false --auto-route analysis "trace the auth flow"
csa run --sa-mode false --model-spec "codex/openai/gpt-5.3-codex/xhigh" "complex task"
csa run --sa-mode false --last "continue where I left off"
echo "analyze this" | csa run --sa-mode false --tool gemini-cli

csa review -- Code review

Review code changes using a heterogeneous AI model.

csa review --sa-mode false [OPTIONS]
Flag Description
--sa-mode <BOOL> Root callers must pass true or false; internal recursive calls default to false
--diff Review uncommitted changes (git diff HEAD)
--range <RANGE> Review a commit range (e.g., main...HEAD)
--commit <SHA> Review a specific commit
--files <PATHSPEC> Review specific files
--branch <BRANCH> Compare against branch (default: main)
--tool <TOOL> Override tool selection
--hint-difficulty <LABEL> Resolve a difficulty label through [tier_mapping] when no explicit --tier/--model-spec is set
--model <MODEL> Override model
--fix Review-and-fix mode (apply fixes directly)
--security-mode <MODE> auto, on, or off
--reviewers <N> Number of parallel reviewers (default: 1)
--consensus <STRATEGY> majority, weighted, or unanimous
--context <FILE> Path to context file (e.g., TODO plan)
--timeout <SECS> Absolute wall-clock timeout
--idle-timeout <SECS> Kill on output silence
--allow-fallback Warn instead of error when pattern missing
--session <ID> Resume existing review session

Examples:

csa review --sa-mode false --diff
csa review --sa-mode false --tool claude-code --hint-difficulty code_review --diff
csa review --sa-mode false --range main...HEAD
csa review --sa-mode false --diff --reviewers 3 --consensus majority
csa review --sa-mode false --diff --fix --security-mode on

csa debate -- Adversarial debate

Run a multi-round debate between heterogeneous AI tools.

csa debate --sa-mode false [OPTIONS] [QUESTION]
Flag Description
--sa-mode <BOOL> Root callers must pass true or false; internal recursive calls default to false
--tool <TOOL> Override tool selection
--hint-difficulty <LABEL> Resolve a difficulty label through [tier_mapping] when no explicit --tier/--model-spec is set
--session <ID> Resume existing debate session
--model <MODEL> Override model
--thinking <LEVEL> Thinking budget
--rounds <N> Number of debate rounds (default: 3)
--timeout <SECS> Absolute wall-clock timeout
--idle-timeout <SECS> Kill on output silence

Examples:

csa debate --sa-mode false "Should we use anyhow or thiserror?"
csa debate --sa-mode false --tool claude-code --hint-difficulty architecture_design "Pick the storage boundary"
csa debate --sa-mode false --session 01JK "reconsider with performance data"
csa debate --sa-mode false --rounds 5 "Redis vs Memcached for session storage"

csa session -- Session management

csa session list

csa session list [--tree] [--tool <TOOLS>] [--branch <BRANCH>] [--cd <DIR>]

csa session compress

Send tool-specific compression command (/compress or /compact).

csa session compress --session <ID> [--cd <DIR>]

csa session delete

csa session delete --session <ID> [--cd <DIR>]

csa session clean

Remove sessions not accessed within N days.

csa session clean --days <N> [--dry-run] [--tool <TOOLS>] [--cd <DIR>]

csa session result

Show the last execution result.

csa session result --session <ID> [--json] [--cd <DIR>]

csa session logs

csa session logs --session <ID> [--tail <N>] [--cd <DIR>]

csa session is-alive

Check whether a session is still running via filesystem liveness signals.

csa session is-alive --session <ID> [--cd <DIR>]

csa session artifacts

List artifacts in a session's output directory.

csa session artifacts --session <ID> [--cd <DIR>]

csa session log

Show git history for a session.

csa session log --session <ID> [--cd <DIR>]

csa session checkpoint

Write a checkpoint note (git notes) for audit trail.

csa session checkpoint --session <ID> [--cd <DIR>]

csa session checkpoints

List all checkpoint notes.

csa session checkpoints [--cd <DIR>]

csa config -- Configuration management

csa config show

Display effective merged configuration.

csa config show [--cd <DIR>]

csa config edit

Open project config in $EDITOR.

csa config edit [--cd <DIR>]

csa config validate

Validate configuration file syntax and references.

csa config validate [--cd <DIR>]

csa config get

Query a single config value by dotted key path.

csa config get <KEY> [--default <VALUE>] [--project] [--global] [--cd <DIR>]

Examples:

csa config get review.tool
csa config get tools.codex.enabled --default true
csa config get review.tool --global

csa todo -- Plan management

csa todo create

csa todo create <NAME>

csa todo show

csa todo show -t <TIMESTAMP>

csa todo diff

csa todo diff -t <TIMESTAMP> --from <VER> --to <VER>

csa todo dag

csa todo dag --format mermaid

csa todo list

csa todo list [--status <STATUS>]

csa todo status

csa todo status <TIMESTAMP> <STATUS>

csa plan -- Workflow execution

Execute compiled weave workflow files.

csa plan run --sa-mode false <FILE> [--var KEY=VALUE...] [--tool <TOOL>] [--dry-run] [--cd <DIR>]

csa mcp-hub -- MCP Hub daemon

csa mcp-hub serve

csa mcp-hub serve [--background] [--foreground] [--socket <PATH>] [--systemd-activation]

csa mcp-hub status

csa mcp-hub status [--socket <PATH>]

csa mcp-hub stop

csa mcp-hub stop [--socket <PATH>]

csa mcp-hub gen-skill

Regenerate the mcp-hub routing-guide skill from live tools/list.

csa mcp-hub gen-skill [--socket <PATH>]

csa skill -- Skill management

csa skill install

csa skill install <SOURCE> [--target <TOOL>]

csa skill list

csa skill list

csa audit -- Codebase audit tracking

csa audit init

csa audit init [--root <PATH>] [--ignore <PATTERN>...] [--mirror-dir <DIR>]

csa audit status

csa audit status [--format text|json] [--filter <STATUS>] [--order topo|depth|alpha]

csa audit update

csa audit update <FILES...> [--status <STATUS>] [--auditor <NAME>]

csa audit approve

csa audit approve <FILES...> [--approved-by <NAME>]

csa audit reset / csa audit sync

csa audit reset <FILES...>
csa audit sync

Operations Commands

Command Description
csa init [--full] [--template] Initialize project configuration
csa doctor Check environment and tool availability
csa gc [--dry-run] [--max-age-days N] [--global] Garbage collect expired sessions and locks
csa tiers list List configured tiers with model specs
csa batch --sa-mode false <FILE> [--dry-run] Execute tasks from a batch TOML file
csa setup claude-code Setup MCP integration for Claude Code
csa setup codex Setup MCP integration for Codex
csa setup opencode Setup MCP integration for OpenCode
csa migrate [--dry-run] [--status] Run pending config/state migrations
csa self-update [--check] Update CSA to the latest release
csa mcp-server Run as MCP server (JSON-RPC over stdio)