Menu
Drive the Claude Code CLI from Bash — headless sessions, structured output, model/permission control, and code reviews. Use when an agent needs to run Claude programmatically.
Design, build, and evaluate MCP servers end-to-end. Use when user says 'design an MCP server', 'decompose MCP tools', 'write a tool schema', 'implement an MCP server in Rust', 'call an MCP server from an agent', or 'evaluate MCP quality'. Five modes: DESIGN (decomposition, contracts), SCHEMA (JSON Schema), IMPLEMENT (Rust + rmcp), CLIENT (agent as consumer), QUALITY (8-dimension rubric, forked orchestrator spawns 8 parallel judge subagents).
Run a Plan-Do-Check-Act (PDCA) cycle to test a hypothesis with measurable success criteria. Use when user says 'run a PDCA cycle', 'test this hypothesis', 'A/B test this change', 'validate the improvement worked', or 'standardize this change'.
Archive completed plans, deduplicate stale memory, and clean auto-memory at the end of a project. Use when the user wants to wrap up a plan, clean up files, or run a memory cleanup pass.
Review a PR, simplify complex code, polish prose, or capture a project learning. Use when the user wants to improve the quality of an artifact (code, doc, PR) or consolidate insights into memory. Do NOT use for bug diagnosis or for creating new features.
Analyze Claude Code session transcripts to extract metrics, diagnose behavioral anti-patterns, and file GitHub issues from findings. Use when user says 'parse session log', 'session metrics', 'review session for anti-patterns', 'capture a session', 'cross-analyze artifacts', or 'create a meta-issue'. Modes: CAPTURE, INSPECT, REVIEW, ISSUE, CROSS-ANALYZE, ADJUDICATE.
Create, optimize, and test Claude Code skills, including metadata refinement and trigger benchmarking.
| name | claude-cli |
| description | Drive the Claude Code CLI from Bash — headless sessions, structured output, model/permission control, and code reviews. Use when an agent needs to run Claude programmatically. |
| when_to_use | - "Spawn a headless Claude session to run a task" - "Continue or resume a previous Claude Code session" - "Get structured JSON output from Claude" - "Run a cloud-hosted code review" - "Change the model, effort, or permission mode for a Claude invocation" - "Drive Claude Code programmatically from a Bash command" |
The claude CLI is the same binary that powers interactive Claude Code. With -p (print) it runs headlessly, accepts a prompt, and writes the response to stdout. This skill teaches the flags and patterns for driving it from the Bash tool — covering the six conceptual operations the marketplace has used historically (execute, session, context, review, agent, config), now expressed as native CLI flags rather than as wrapper-tool calls.
For MCP design/implementation/schema patterns (i.e., building MCP servers, not using the claude CLI), see the marketplace's MCP expertise skill (modes: DESIGN, SCHEMA, IMPLEMENT, CLIENT, QUALITY).
Use this skill when the request is to drive the claude CLI from a Bash invocation:
DO NOT use this skill for:
mcp-expertise DESIGN modeclaude plugin list / claude mcp list directly in BashThe marketplace historically exposed the claude CLI as six MCP tools. The wrapper is gone, but the conceptual decomposition is still useful as a mental model. Here's the mapping to native CLI flags:
| Operation | Old MCP tool | Native CLI pattern |
|---|---|---|
| execute | claude_execute | claude -p "..." --output-format json |
| session | claude_session | claude --resume <uuid> or claude --continue or claude --session-id <uuid> |
| context | claude_context | claude --add-dir <path> or claude --worktree [name] or claude doctor |
| review | claude_review | claude ultrareview [target] --json |
| agent | claude_agent | claude --agent <name> -p "..." and claude agents --json |
| config | claude_config | per-invocation flags: --model, --effort, --permission-mode, --settings |
The rest of this skill teaches the flags themselves.
execute — the workhorseThe primary tool. Run a prompt, get output. The claude -p form is non-interactive: it reads the prompt, processes it, writes the result to stdout, and exits.
claude -p "What is 2+2?"
This works but writes plain text. For an agent caller, you almost always want JSON.
claude -p "Refactor src/auth.rs to use the newtype pattern" \
--output-format json \
--model sonnet \
--effort high \
--permission-mode acceptEdits
Flags by category:
Execution mode:
-p, --print — non-interactive, write response to stdout, exit. This is the universal invocation prefix for headless use.--bare — minimal mode. Skips hooks, LSP, plugin sync, attribution, auto-memory, background prefetches, keychain reads, and CLAUDE.md auto-discovery. Sets CLAUDE_CODE_SIMPLE=1. Use only when you need to bypass plugin/hook machinery for a clean test or sandbox.Output:
--output-format text|json|stream-json — serialization. Default text. Use json when an agent will parse the response. Use stream-json for realtime token-by-token output.--json-schema <schema> — JSON Schema for structured output validation. Inline string, not a file path. The CLI validates the response against the schema; if it doesn't match, the call fails. This is the right way to get typed output from Claude — much better than asking Claude to "please respond in JSON" in the prompt.--input-format text|stream-json — input format (default text). Use stream-json for realtime streaming input.--include-partial-messages — include partial message chunks as they arrive (only with --print and --output-format=stream-json).--replay-user-messages — re-emit user messages from stdin back on stdout for acknowledgment (only with stream-json input + output).Model / effort / budget:
--model <model> — sonnet, opus, haiku, or a full name like claude-opus-4-8. Aliases resolve to the latest version of that family.--fallback-model <model> — automatic fallback when the default model is overloaded or unavailable. Only works with --print.--effort <level> — low, medium, high, xhigh, max. Default is whatever's configured in the project. Higher effort = more reasoning, more cost, more time.--max-budget-usd <amount> — spend cap for this invocation. Only works with --print. The CLI exits cleanly when the budget is reached.Permissions:
--permission-mode <mode> — acceptEdits, auto, bypassPermissions, default, dontAsk, plan. For agent-driven invocations, use acceptEdits so Claude can edit files without prompting the user.--allow-dangerously-skip-permissions — make bypassPermissions available without defaulting to it.--dangerously-skip-permissions — bypass all permission checks. Recommended only for sandboxes with no internet access. Do not use this in shared environments.Tool access:
--allowedTools, --allowed-tools <tools...> — comma- or space-separated allowlist. Example: Bash(git *),Edit. Repeatable; multiple values accumulate.--disallowedTools, --disallowed-tools <tools...> — denylist. Same syntax.--tools <tools...> — specify the available built-in tools. "" disables all tools, "default" uses the full set, or list names like Bash,Edit,Read.System prompt:
--system-prompt <prompt> — override the entire system prompt. Use for forcing a specific persona.--append-system-prompt <prompt> — extend the default system prompt. Use for adding context (project conventions, role).--exclude-dynamic-system-prompt-sections — move per-machine sections (cwd, env, memory paths, git status) out of the system prompt into the first user message. Improves cross-user prompt-cache reuse. Only applies with the default system prompt (ignored with --system-prompt).MCP / extensions:
--mcp-config <configs...> — load MCP servers from JSON files or inline JSON strings. Space-separated. Each config is independent.--strict-mcp-config — only use MCP servers from --mcp-config, ignoring all other MCP configurations.--plugin-dir <path> — load a plugin from a directory or .zip for this session only. Repeatable.--plugin-url <url> — fetch a plugin .zip from a URL for this session only. Repeatable.Metadata:
-n, --name <name> — display name for the session (shown in /resume picker and terminal title).--setting-sources <sources> — comma-separated list of setting sources to load: user, project, local. Default loads all three.File preloading:
--file <specs...> — file resources to download at startup. Format: file_id:relative_path. Used for hosted files.claude -p "Classify this support ticket: '$TICKET_TEXT'" \
--output-format json \
--json-schema '{"type":"object","properties":{"category":{"type":"string","enum":["bug","feature","question"]},"priority":{"type":"string","enum":["low","medium","high"]}},"required":["category","priority"]}'
Claude's response is validated against the schema. If it doesn't match, the call fails with a validation error.
session — lifecycleSessions are how you keep context across multiple invocations. The CLI manages session IDs as UUIDs; you pass them between invocations to resume continuity.
claude --resume <session-uuid> -p "Continue the refactor: also add tests"
The UUID must be valid (8-4-4-4-12 hex). If invalid, the CLI rejects it.
claude --resume
With no value, --resume opens an interactive session picker. Filter with a search term:
claude --resume "auth refactor"
(The interactive picker is unavailable in non-TTY contexts — for scripted use, pass an explicit UUID.)
claude --continue -p "Continue the refactor"
This is shorthand for "find the most recent session whose CWD matches the current directory and resume it". Use this when you've been iterating and just want to pick up where you left off.
claude --session-id <uuid> -p "Start a new session with this specific ID"
The UUID must be valid. Use this when you want to pre-allocate a session ID (e.g., for logging or external tracking) before the first invocation.
claude --resume <existing-uuid> --fork-session -p "Try a different approach"
--fork-session creates a new session ID branched from the existing one. The original session is unchanged. Use this for A/B exploration without polluting the original.
The CLI does not have a dedicated list-sessions flag. The two ways to enumerate sessions:
claude --resume with no value opens the picker, which lists all known sessions.~/.claude/sessions/ (or $CLAUDE_CONFIG_DIR/sessions/) directly. The CLI stores session metadata as JSONL files.For a Bash script, the second approach is the only one that works in non-TTY contexts.
The CLI does not have a dedicated session-info flag. To get metadata:
claude -p --output-format json includes the session ID.~/.claude/sessions/.The CLI does not have a dedicated close-session flag. Sessions are closed by:
--setting-sources and project settings).--no-session-persistence to opt out of persistence entirely (sessions are not saved to disk and cannot be resumed).claude --from-pr # interactive picker
claude --from-pr <pr-number> # session linked to the given PR
claude --from-pr https://github.com/<owner>/<repo>/pull/<pr-number>
Resumes a session that was started in the context of a specific PR. The session picker accepts an optional search term.
context — workspaceTell Claude about the working directory and any additional context it should have access to.
claude -p "Refactor this" --add-dir /path/to/lib --add-dir /path/to/tests
--add-dir is repeatable. The CLI grants tool access to each additional directory. Without it, Claude is sandboxed to the current working directory.
For the common case of "let Claude read the current directory", claude -p in the target dir is enough — --add-dir is for adding extras.
claude -p "Refactor in a clean worktree" --worktree
# or with a name:
claude -p "Refactor in a clean worktree" --worktree auth-refactor
--worktree creates a new git worktree for the session. The session runs in the worktree; changes are isolated until you merge. Optional [name] for the worktree branch.
Combine with --tmux to run the work in a tmux session (or iTerm2 native panes):
claude -p "Refactor in a worktree" --worktree --tmux
claude doctor
Runs health checks on the Claude Code auto-updater. Reports whether updates are available, and whether the installation is healthy. The workspace trust dialog is skipped; stdio servers from .mcp.json are spawned for health checks. Use only in directories you trust.
For deeper diagnostics (session analytics, hook events), use the marketplace's session-analytics skill.
review — code reviewThe CLI has a dedicated ultrareview subcommand for cloud-hosted multi-agent code reviews. This is the right way to do code review from the CLI — it's not a prompt pattern, it's a real subcommand with structured output.
claude ultrareview
Reviews the current branch's diff against the default branch. Prints findings to stdout.
claude ultrareview <pr-number> # PR number
claude ultrareview https://github.com/<owner>/<repo>/pull/<pr-number> # PR URL
claude ultrareview feature-branch # branch name (compared to default branch)
claude ultrareview --json
Prints the raw bugs.json payload instead of the formatted findings. Use this when an agent will parse the findings.
claude ultrareview --timeout 60 # wait up to 60 minutes
Default timeout is 30 minutes. The review aborts and prints partial findings on timeout.
If you need a quick, local review (not cloud-hosted, no multi-agent), use the prompt pattern:
claude -p "Review the changes in this branch for bugs, security issues, and code quality. Be specific: cite file:line for each finding. Do not propose architectural rewrites — focus on what's actually wrong in the diff." \
--output-format json \
--add-dir .
The structured-output skill (--json-schema) can enforce a finding-shape contract:
claude -p "Review the changes in this branch" \
--output-format json \
--json-schema '{"type":"object","properties":{"findings":{"type":"array","items":{"type":"object","properties":{"file":{"type":"string"},"line":{"type":"integer"},"severity":{"type":"string","enum":["blocker","warning","suggestion"]},"description":{"type":"string"}},"required":["file","line","severity","description"]}}}}'
Prefer claude ultrareview for serious reviews. The prompt pattern is a fallback for "I just want a quick sanity check" cases.
agent — background managementThe claude CLI has two ways to spawn agents:
--agent <name>) — pick an agent for the current sessionclaude agents) — manage agents that are running in the backgroundclaude -p "Run a security review of this codebase" --agent security-reviewer
The agent is selected for the current session only. If --agent is not specified, the default agent is used (or whatever the agent setting resolves to).
claude -p "Review this PR" \
--agents '{"reviewer": {"description": "Reviews code for security and quality issues", "prompt": "You are a code reviewer focused on security. For each finding, cite file:line and explain the exploit."}}'
--agents is a JSON object defining custom agents for this session. The keys are agent names; the values have description and prompt fields.
claude agents # open the interactive agent view
claude agents --json # list live background sessions as JSON, exit
claude agents --cwd /path/to/proj # filter by starting directory
claude agents --json is the right pattern for an agent caller that needs to enumerate running sessions. The output is a JSON array of session metadata.
When using the agent view, you can set defaults that apply to all sessions dispatched from it:
claude agents --model opus # default model
claude agents --effort high # default effort
claude agents --permission-mode acceptEdits # default permissions
claude agents --mcp-config /path/to/config.json # default MCP config
claude agents --add-dir /extra/dir # additional directories
The CLI does not have a --kill-agent flag. To terminate a background agent:
claude agents): use the keyboard shortcut to terminate the selected session.kill <pid> works but is unclean. Prefer the interactive view or letting the agent complete naturally.--max-budget-usd so the agent stops itself at the spend cap.For agent-runtime semantics (subagent orchestration, parallel dispatch, etc.), see the marketplace's subagent-orchestration skill. The CLI flags here are the surface; the orchestration pattern is the marketplace's separate concern.
config — runtime tuningThere is no "set config" command in the CLI. The model, effort, permission mode, and settings are all set as per-invocation flags, then re-invoked with different values as needed.
claude -p "Quick classification" --model haiku # cheap, fast
claude -p "Hard reasoning task" --model opus --effort max
claude -p "Default work" --model sonnet --effort high
claude -p "..." --effort low # fast, cheap, may be wrong
claude -p "..." --effort medium # default
claude -p "..." --effort high # more reasoning
claude -p "..." --effort xhigh # significantly more reasoning
claude -p "..." --effort max # the most reasoning the model will do
claude -p "..." --permission-mode acceptEdits # auto-accept file edits
claude -p "..." --permission-mode plan # enter plan mode first
claude -p "..." --permission-mode dontAsk # don't ask; reject by default
claude -p "..." --permission-mode bypassPermissions # bypass all checks
For agent-driven invocations, acceptEdits is almost always what you want — it lets Claude edit files without prompting the user (who isn't there to respond).
claude -p "..." --settings /path/to/settings.json
claude -p "..." --settings '{"permissions":{"allow":["Bash"]}}' # inline JSON
--settings accepts either a path to a JSON file or an inline JSON string. The settings merge with the user/project/local settings per --setting-sources.
claude -p "..." --setting-sources user,project
claude -p "..." --setting-sources project # only project settings
claude -p "..." --setting-sources "" # no settings
By default, all three sources (user, project, local) are loaded. Use this flag to scope which sources apply for a given invocation.
claude -p "..." --verbose
claude -p "..." --debug api,hooks # enable debug mode with category filter
claude -p "..." --debug-file /tmp/debug.log
--debug with no value enables all categories; with a value, filters to those categories. --debug-file writes debug logs to a file (implicitly enables debug mode).
The CLI's output contract is much simpler than the old wrapper's. Here's what an agent caller needs to know.
$ claude -p "What is 2+2?"
4
Plain text on stdout. Easy to capture; hard to parse programmatically.
$ claude -p "What is 2+2?" --output-format json | jq .
{
"type": "result",
"subtype": "success",
"is_error": false,
"duration_ms": 1234,
"duration_api_ms": 1100,
"num_turns": 1,
"result": "4",
"session_id": "abc-1234-...",
"total_cost_usd": 0.0023,
"usage": { ... }
}
The JSON envelope includes:
result (string) — Claude's responsesession_id (UUID) — the session that was used or createdis_error (boolean) — whether the call failedduration_ms / duration_api_ms (numbers) — wall-clock and API-only timenum_turns (number) — how many model turns the call usedtotal_cost_usd (number) — actual costusage (object) — token usage breakdownsession_id is inside the JSON output, not lifted to a top-level field. If you need to resume the session, parse the JSON, extract session_id, and pass it to --resume on the next call.
SESSION_ID=$(claude -p "..." --output-format json | jq -r '.session_id')
claude --resume "$SESSION_ID" -p "Continue: also add tests"
0 — successThe CLI uses raw Unix exit codes, not JSON-RPC codes. If you need a structured error, parse the JSON output and check is_error.
claude -p "..." --output-format stream-json
Writes newline-delimited JSON events as they happen. Each line is a typed event (assistant message, tool use, tool result, etc.). Use this for realtime UI or for piping into another agent's input stream.
Workflow 1: One-shot task
claude -p "Refactor user.rs to use the newtype pattern" --permission-mode acceptEdits
Workflow 2: Multi-turn session with continuity
# Turn 1
SESSION_ID=$(claude -p "Start a refactor of the auth module" --output-format json | jq -r '.session_id')
# Turn 2 (later)
claude --resume "$SESSION_ID" -p "Continue: also add tests"
Workflow 3: Background agent + polling
# Spawn (in a separate process / Bash background)
claude -p "Generate rustdoc for src/parser.rs" --output-format json > /tmp/doc-gen.json 2>&1 &
# Poll the result
while kill -0 $! 2>/dev/null; do sleep 5; done
cat /tmp/doc-gen.json | jq -r '.result'
Or use the agent view:
# List running agents
claude agents --json | jq '.[] | {name: .name, status: .status}'
Workflow 4: Code review of a PR
claude ultrareview <pr-number> --json | jq '.findings[]'
Workflow 5: Structured output for downstream parsing
claude -p "Classify this ticket: '$TICKET_TEXT'" \
--output-format json \
--json-schema '{"type":"object","properties":{"category":{"type":"string","enum":["bug","feature","question"]},"priority":{"type":"string","enum":["low","medium","high"]}},"required":["category","priority"]}' \
| jq '{category: .result | fromjson | .category, priority: .result | fromjson | .priority}'
Or use --json-schema together with a prompt that tells Claude to populate the result with the structured object directly:
claude -p "Classify this ticket. Respond with a JSON object that matches the schema." \
--output-format json \
--json-schema '...' \
| jq -r '.result' | jq .
The exact path depends on whether the model returns a JSON string (which it usually does) or a pre-parsed object.
Workflow 6: Headless capture into a session for later review
SESSION_ID=$(claude -p "Run a security audit" --output-format json | jq -r '.session_id')
# Later, resume and ask follow-ups:
claude --resume "$SESSION_ID" -p "Drill into the auth findings"
❌ Looping claude -p 50 times for 50 small tasks — use --continue to maintain context, or batch related tasks into a single prompt. Each -p invocation is a fresh model call; the session_id is the only state that persists.
❌ Forgetting --permission-mode acceptEdits — Claude will refuse to edit files (or ask the user, who isn't there). The call appears to hang. Always set the permission mode for agent-driven invocations.
❌ Using --dangerously-skip-permissions in shared environments — this bypasses all safety checks. Only use in sandboxes with no internet access.
❌ Using --output-format text when you need to parse the result — use json and parse with jq. Don't try to regex-match plain text.
❌ Putting a JSON Schema as a nested object — --json-schema takes a STRING. The CLI passes it to the model verbatim.
❌ Setting --disallowed-tools "Read,Edit" — these are core tools; you're effectively turning Claude into a chat-only instance.
❌ Using --bare in production — you lose hooks, LSP, plugin sync, attribution, auto-memory, keychain reads, and CLAUDE.md auto-discovery. Only use for clean test environments.
❌ Hardcoding a full model name like claude-opus-4-8 — prefer aliases (sonnet, opus, haiku) so the call tracks the latest model. Hardcoded names break when models are deprecated.
❌ Resuming a session without verifying the UUID format — invalid UUIDs cause the CLI to error. Validate with a regex check or use --continue (no UUID needed).
❌ Forgetting --add-dir when Claude needs to read files outside the cwd — without it, Claude is sandboxed to the current working directory and will fail to read external files.
--json-schema — official Claude Code docs on JSON Schema validation.claude-plugin/marketplace.json in this repo