CLI Commands¶

Quick reference for every code-agent command. For copy-paste workflows see Recipes.

Global¶

code-agent --help          # or -h — quick starts + examples
code-agent --version       # or -V
code-agent --install-completion   # one-time: tab-complete in your shell

Mistyped commands get suggestions (e.g. code-agent docto → hints doctor).

Help & tab completion¶

The CLI is designed to stay fluid while you type:

1. Help — code-agent -h, code-agent run -h, code-agent experts run -h show grouped flags, verify tips, and copy-paste examples.
2. Tab completion — after install, complete subcommands, expert ids, and common --verify-cmd values (pytest -q, go test ./..., …).

Install completion (once)¶

code-agent --install-completion
# restart the shell, or open a new terminal

eval "$(code-agent --show-completion)"

alias code-agent='docker run --rm -it -e GEMINI_API_KEY -v "$PWD:/workspace" ghcr.io/kramlipi/code-agent:latest'
# then: code-agent --install-completion   # if the alias is a real local wrapper script

What Tab completes¶

List experts anytime:

code-agent experts list

code-agent run — one-shot task¶

Fix, add, or refactor code from a natural-language task.

code-agent run "TASK" [OPTIONS]

Examples:

code-agent run "Add type hints to src/utils.py" -w .
code-agent run "Fix failing login test" --verify-cmd "pytest -q tests/test_auth.py"
code-agent run "Refactor cache module" --dry-run

Success output (shape):

┌─ Result ─────────────────────────┐
│ Status: done                     │
│ Session: abc123def456            │
│ Run ID: a1b2c3d4e5f6            │
│ Files: src/utils.py              │
└──────────────────────────────────┘

code-agent chat — interactive REPL¶

code-agent chat [-w PATH] [--resume SESSION_ID]

Type tasks at you> prompt. Type exit to quit.

code-agent doctor — preflight¶

code-agent doctor
code-agent doctor --provider-test
code-agent doctor --verify-plan "fix failing unit tests" -w .

Checks Python, ripgrep, config, and optionally pings the LLM provider.

Verify gate: pass --verify-cmd so the agent only finishes when that command exits 0. See How to use verify commands below.

How to use verify commands¶

Tell code-agent what “done” means with --verify-cmd. It edits your repo with tools, then re-runs that command until it exits 0 (or it fails closed).

See which verify command would be used¶

No LLM call — discovery only:

code-agent doctor --verify-plan "fix failing unit tests" -w .
code-agent doctor --verify-plan "increase coverage to 80%" -w .
code-agent doctor --verify-plan "go test the package" -w /path/to/go-project

Fix failing tests (Python)¶

cd /path/to/your-python-repo

python3 -m pytest -q   # optional: show red first

code-agent run "Fix all failing unit tests. Minimal changes only — do not change tests unless required." \
  --verify-cmd "python3 -m pytest -q" \
  -w .

python3 -m pytest -q   # same command proves green

Narrow the gate:

code-agent run "Fix the auth tests." \
  --verify-cmd "python3 -m pytest -q tests/test_auth.py" \
  -w .

Fix failing tests (Go)¶

cd /path/to/your-go-package

go test ./...

code-agent run "Make unit tests pass. Minimal changes only." \
  --verify-cmd "go test ./..." \
  -w .

go test ./...

Omit --verify-cmd (auto-discovery)¶

If you omit --verify-cmd, it tries config → CI → project manifests (pytest, go test, npm, …). Prefer an explicit --verify-cmd when you know the right command.

Docker one-liner¶

cd /path/to/your-repo

docker run --rm -it \
  -e GEMINI_API_KEY \
  -e CODE_AGENT_MODEL \
  -v "$PWD:/workspace" \
  ghcr.io/kramlipi/code-agent:latest \
  run "Fix all failing unit tests. Minimal changes only." \
  --verify-cmd "python3 -m pytest -q" \
  -w /workspace

For Go, use --verify-cmd "go test ./..." (image must have Go, or run the binary locally).

code-agent config¶

code-agent config show

Prints resolved settings (secrets redacted).

code-agent env¶

code-agent env sync     # sync keys from host (e.g. Windows geminikey)
code-agent env show     # list discovered keys (redacted)

code-agent experts¶

List experts¶

code-agent experts list

Run an expert¶

code-agent experts run EXPERT_ID [OPTIONS]

Babysit a PR¶

code-agent experts watch --pr NUMBER --verify-cmd "pytest -q"

Polls CI on an open PR and runs bug-fix when checks fail.

HTTP serve (platform)¶

code-agent experts serve --host 0.0.0.0 --port 8080

Webhook router for deploy-guard, budget/throttle, approval gate.

Configuration files¶

Key settings:

model: gemini/gemini-2.0-flash
workspace: .
max_iterations: 10
temperature: 0.2

LiteLLM model strings: gemini/, openai/, anthropic/, ollama_chat/, etc.

Outputs¶

Related¶

• Experts — per-expert inputs and outputs
• Troubleshooting — exit codes and common failures