The CLI — Print Mode, JSON Output & CI/CD

# match the model to the task
claude --model opus "design a caching strategy"
claude --model haiku -p "format this JSON"

# reliability for unattended runs
claude -p --model opus \
       --fallback-model sonnet "analyze architecture"

Gateway model discovery (v2.1.129+, opt-in): when ANTHROPIC_BASE_URL points at a gateway, set CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 to populate /model from its /v1/models endpoint. Opt-in because discovery can surface models you're not entitled to — v2.1.126 made it implicit and that was reverted.

Replace when you want a clean persona with none of the defaults; append when you want the defaults plus house rules.

# complete custom persona
claude --system-prompt "You are a senior security
engineer. Focus on vulnerabilities."

# keep defaults, add house rules
claude --append-system-prompt "Always include
unit tests with code examples"

# long prompt from a file — print mode only
claude -p --system-prompt-file \
       ./prompts/code-reviewer.txt "review main.py"

# read-only review
claude --permission-mode plan "review this codebase"

# safe tools only, no prompts for git reads
claude --tools "Read,Grep,Glob" -p "find TODOs"
claude --allowedTools "Bash(git status:*)" "Bash(git log:*)"

• Glob/Grep footnote (v2.1.113+): native builds run them as embedded bfs/ugrep via Bash — but keep writing Glob/Grep in configs; the substitution is transparent on every platform
• PowerShell (v2.1.119): auto-approve with the same matcher syntax — PowerShell(Get-ChildItem:*)
• Resume fix (v2.1.132+): --permission-mode is now honored on --continue/--resume — older versions silently dropped it, downgrading plan-mode sessions

# JSON for programmatic use
claude -p --output-format json "list all
functions in main.py"

# streaming JSON for real-time processing
claude -p --output-format stream-json "generate
a long report"

# schema-validated structure
claude -p --json-schema '{"type":"object",
  "properties":{"bugs":{"type":"array"}}}' \
  "find bugs and return as JSON"

# extract a field · filter an array
claude -p --output-format json "analyze this code" | jq '.result'
… "list issues" | jq -r '.issues[] | select(.severity=="high")'

# pick several fields (object construction)
… "describe the project" | jq '{name, version, description}'

# reshape · CSV · count
… | jq 'map({title: .title, priority: .priority})'
… | jq -r '.functions[] | [.name, .lineCount] | @csv'
… | jq '.todos | length'

# gate a script on Claude's verdict
RESULT=$(claude -p --output-format json \
  "is this code secure? answer with
   {secure: boolean, issues: []}" < code.py)
if echo "$RESULT" | jq -e '.secure == false' > /dev/null; then
  echo "Security issues found!"
  echo "$RESULT" | jq '.issues[]'
fi

# conditional verdicts
… | jq 'if .vulnerabilities | length > 0
        then "UNSAFE" else "SAFE" end'

Heads-up: the source guide prints the multi-field example as .{name, …} — that's not valid jq. Object construction is written {…} with no leading dot, as shown here.

Logs & history in, analysis out

tail -1000 /var/log/app/error.log | \
  claude -p "summarize these errors, suggest fixes"

cat access.log | claude -p "identify suspicious
access patterns"

git log --oneline -50 | claude -p "summarize
recent development activity"

grep -r "TODO" src/ | claude -p "prioritize
these TODOs by importance"

Batch processing with loops

# summarize every file — haiku keeps it cheap
for file in src/*.ts; do
  claude -p --model haiku "summarize this file:
    $(cat $file)" >> summaries.md
done

# generate tests per module
for module in $(ls src/modules/); do
  claude -p "generate unit tests for
    src/modules/$module" > "tests/$module.test.ts"
done

Same idea with find … -exec for batch code review across a tree.

# parallel threads of work
claude -r "feature-auth" "add password reset"
claude -r "feature-payments" "continue Stripe work"

# fork to explore without risk
claude --resume feature-auth --fork-session \
       "try OAuth instead"

Why fork?

• Try alternative implementations without losing the original
• Experiment with different approaches in parallel
• Branch variations from successful work
• Test breaking changes without touching the main session

Cleanup: claude project purge

When a project ends, its local state lingers — transcripts, tasks, debug logs, edit history, prompt history. claude project purge ~/work/repo --dry-run previews the deletion; --yes executes it; --all --interactive walks every project on the machine (v2.1.126+).

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use
      proactively after code changes.",   ← required
    "prompt": "You are a senior code reviewer…",
                                          ← required
    "tools": ["Read","Grep","Glob","Bash"],
                       ← optional · inherits all if omitted
    "model": "sonnet"  ← optional · sonnet|opus|haiku
  }
}' "review the auth module"

Or load from a file: claude --agents "$(cat ~/.claude/agents.json)" — and combine with -p/--model for scripted runs.

Priority when names collide

The team-file pattern

Keep a shared agents.json defining your reviewer (opus), documenter (sonnet/haiku), and refactorer (with a restricted tools list) — everyone on the team gets the same specialists with one flag. The full priority table, including plugin-level agents, is in the Chapter 4 deck.

A Research Preview (v2.1.139+): one view of every Claude Code session on the machine — running, blocked on you, done. Built for background agents, scheduled tasks, and --bg-launched sessions.

• Dispatch from the view or via claude --bg ‹prompt› — with the same configuration flags as claude itself
• --json (v2.1.145) prints the list as machine-readable JSON — status bars, session pickers, tmux integrations
• Ctrl+T pins a session (v2.1.147): stays alive when idle, restarted in place for updates, shed under memory pressure last
• In an attached session, Shift+Tab cycles permission modes incl. auto (v2.1.143); finished sessions with an open shell move to Completed (v2.1.141 fix)

Dispatch flags

Scoping note: in the Agent View Ctrl+T pins; in the main session it toggles the task list.

Fast Mode: as of v2.1.154, /fast runs Opus 4.8 as a research preview — about 2× the standard rate for ~2.5× the output speed. The old Opus-4.6 override env var was deprecated and removed 2026-06-01; to get fast mode on 4.6, switch model first, then /fast on.

Effort: low ○ → medium ◐ → high ● → xhigh → max

• Default is high on Opus 4.8, Opus 4.6 and Sonnet 4.6 — xhigh on Opus 4.7
• xhigh needs Opus 4.8/4.7 · max works on Opus 4.8/4.7/4.6 and Sonnet 4.6 (session-only)
• Set it three ways: --effort high · /effort high · CLAUDE_CODE_EFFORT_LEVEL=high
• "ultrathink" in a prompt activates deep reasoning; the /effort menu's ultracode is not an effort level — it sends xhigh and has Claude orchestrate dynamic workflows

Combinations to memorize

When it breaks