Claude code cli

Claude Code CLI

Updated as of June 25, 2026. Verified against Claude Code CLI 2.1.191 and the official Claude Code docs available that day.

Workflow

1. Confirm the local CLI and auth path before spending tokens:

   claude --version
   claude auth status --text
   

   If the machine relies on saved Claude subscription auth, avoid --bare unless ANTHROPIC_API_KEY or an apiKeyHelper is configured. --safe-mode keeps auth while disabling customizations for troubleshooting.

2. Prefer print mode for agent-to-agent calls:

   claude -p --output-format json --model haiku --effort low --max-turns 1 --max-budget-usd 0.05 --tools "" --disallowedTools "mcp__*" --strict-mcp-config "Reply with exactly: ok"
   

   Use --tools "" for no built-in tools. MCP tools are separate; add --disallowedTools "mcp__*" or --strict-mcp-config when the call should not reach MCP servers.

3. Parse the JSON result instead of scraping text. Inspect:

   • result for the response text
   • session_id for follow-up calls
   • subtype, is_error, errors, and exit code for failure handling
   • total_cost_usd and modelUsage for cost/model auditing

4. Keep a session alive by preserving session_id and the working directory:

   claude -p --output-format json --model sonnet --effort high --max-turns 5 --max-budget-usd 0.30 "Start the analysis."
   claude -p --resume <session_id> --output-format json --max-turns 5 --max-budget-usd 0.30 "Continue from the prior answer."
   

   Run resume commands from the same project directory where the print-mode session started. Do not pass --no-session-persistence if a future turn may need the session.

Mode Selection

Use the smallest mode that can answer the question:

• Cheap consult: --model haiku --effort low --max-turns 1 --tools "" for short classification, wording, or sanity checks.
• Coding opinion: --model sonnet --effort medium|high --max-turns 3-8 when Claude should inspect or reason about code.
• Hard reasoning: --model opus --effort xhigh|max only when the task justifies higher spend.
• One-turn deeper reasoning: include ultrathink in the prompt. It adds an in-context instruction and does not change the API effort level.
• Workflow orchestration: include ultracode in the prompt for one task, or set --settings '{"ultracode":true}' for a print-mode session that should let Claude plan dynamic workflows. ultracode is not accepted by --effort; it runs with xhigh effort plus workflow orchestration.
• Interactive or long task: use --bg, claude agents --json, claude logs <id>, claude attach <id>, and claude stop <id> when a background Claude session is more appropriate than blocking Codex.

Budget Defaults

--max-budget-usd is a guardrail, not a cost planner. Too-low caps can fail after Claude Code startup/cache overhead, even for tiny prompts. Start with these ceilings and lower only after measuring this machine:

• haiku low, no tools, one turn: 0.05
• sonnet medium/high, small code consult: 0.15-0.30
• opus xhigh/max, hard consult: 0.50+
• ultracode, background agents, or workflows: set an explicit task budget that the user would consider acceptable

When a cap is hit, treat the result as failed even if tokens were spent. Retry only after adjusting scope, model, effort, or budget.

Recipes

Use the bundled wrapper when it helps avoid quoting mistakes:

python claude-code-cli/scripts/claude_call.py --prompt "Reply with exactly: ok" --budget 0.05 --result-only

Read references/cli-options.md before using less common features: --bare, --safe-mode, --continue, --fork-session, --bg, --json-schema, stream-json, ultracode, /deep-research, ultrareview, or MCP/tool allowlists.

Resumable Low-Cost Thread

$first = claude -p --output-format json --model haiku --effort low --max-turns 1 --max-budget-usd 0.05 --tools "" --disallowedTools "mcp__*" --strict-mcp-config "Remember the token alpha and reply with ready."
$sid = ($first | ConvertFrom-Json).session_id
claude -p --resume $sid --output-format json --model haiku --effort low --max-turns 1 --max-budget-usd 0.05 --tools "" --disallowedTools "mcp__*" --strict-mcp-config "What token did I ask you to remember?"

Hard One-Turn Review

claude -p --output-format json --model opus --effort xhigh --max-turns 3 --max-budget-usd 0.50 --append-system-prompt "Be concise. Return risks first." "ultrathink: Review this design decision: ..."

Print-Mode Ultracode

claude -p --output-format json --model opus --max-turns 10 --max-budget-usd 2.00 --settings '{"ultracode":true}' "ultracode: audit this repository for auth bypasses and return the top findings."

Print mode and the Agent SDK do not show interactive workflow approval prompts; permission behavior follows configured rules. Add an allowlist only for commands the task truly needs.

Accuracy Rules

• Prefer official docs and claude --help over community snippets when flags disagree.
• Read the actual modelUsage field because aliases such as haiku, sonnet, opus, fable, best, and [1m] can resolve differently by provider, plan, version, and settings.
• Do not pass secrets in prompts. Claude CLI auth may use saved account state even when ANTHROPIC_API_KEY is absent.
• Do not use --dangerously-skip-permissions from Codex unless the user explicitly asked for it and the workspace risk is understood.
• For pure advice calls, disable tools. For code-edit delegation, constrain tools and working directories deliberately.
• Re-check docs if the current date is after June 25, 2026 and the task depends on newly released Claude Code flags or model behavior.