CLI reference

Complete reference for Claude Code command-line interface, including commands and flags.

CLI commands

Command	Description	Example
`claude`	Start interactive REPL	`claude`
`claude "query"`	Start REPL with initial prompt	`claude "explain this project"`
`claude -p "query"`	Query via SDK, then exit	`claude -p "explain this function"`
`cat file \| claude -p "query"`	Process piped content	`cat logs.txt \| claude -p "explain"`
`claude -c`	Continue most recent conversation	`claude -c`
`claude -c -p "query"`	Continue via SDK	`claude -c -p "Check for type errors"`
`claude -r "<session>" "query"`	Resume session by ID or name	`claude -r "auth-refactor" "Finish this PR"`
`claude update`	Update to latest version	`claude update`
`claude mcp`	Configure Model Context Protocol (MCP) servers	See the Claude Code MCP documentation.

CLI flags

Customize Claude Code's behavior with these command-line flags:

Flag	Description	Example
`--add-dir`	Add additional working directories for Claude to access (validates each path exists as a directory)	`claude --add-dir ../apps ../lib`
`--agent`	Specify an agent for the current session (overrides the `agent` setting)	`claude --agent my-custom-agent`
`--agents`	Define custom subagents dynamically via JSON (see below for format)	`claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'`
`--allowedTools`	Tools that execute without prompting for permission. To restrict which tools are available, use `--tools` instead	`"Bash(git log:)" "Bash(git diff:)" "Read"`
`--append-system-prompt`	Append custom text to the end of the default system prompt (works in both interactive and print modes)	`claude --append-system-prompt "Always use TypeScript"`
`--betas`	Beta headers to include in API requests (API key users only)	`claude --betas interleaved-thinking`
`--continue`, `-c`	Load the most recent conversation in the current directory	`claude --continue`
`--dangerously-skip-permissions`	Skip permission prompts (use with caution)	`claude --dangerously-skip-permissions`
`--debug`	Enable debug mode with optional category filtering (for example, `"api,hooks"` or `"!statsig,!file"`)	`claude --debug "api,mcp"`
`--disallowedTools`	Tools that are removed from the model's context and cannot be used	`"Bash(git log:)" "Bash(git diff:)" "Edit"`
`--fallback-model`	Enable automatic fallback to specified model when default model is overloaded (print mode only)	`claude -p --fallback-model sonnet "query"`
`--fork-session`	When resuming, create a new session ID instead of reusing the original (use with `--resume` or `--continue`)	`claude --resume abc123 --fork-session`
`--ide`	Automatically connect to IDE on startup if exactly one valid IDE is available	`claude --ide`
`--include-partial-messages`	Include partial streaming events in output (requires `--print` and `--output-format=stream-json`)	`claude -p --output-format stream-json --include-partial-messages "query"`
`--input-format`	Specify input format for print mode (options: `text`, `stream-json`)	`claude -p --output-format json --input-format stream-json`
`--json-schema`	Get validated JSON output matching a JSON Schema after agent completes its workflow (print mode only, see Agent SDK Structured Outputs)	`claude -p --json-schema '{"type":"object","properties":{...}}' "query"`
`--max-turns`	Limit the number of agentic turns in non-interactive mode	`claude -p --max-turns 3 "query"`
`--mcp-config`	Load MCP servers from JSON files or strings (space-separated)	`claude --mcp-config ./mcp.json`
`--model`	Sets the model for the current session with an alias for the latest model (`sonnet` or `opus`) or a model's full name	`claude --model claude-sonnet-4-5-20250929`
`--output-format`	Specify output format for print mode (options: `text`, `json`, `stream-json`)	`claude -p "query" --output-format json`
`--permission-mode`	Begin in a specified permission mode	`claude --permission-mode plan`
`--permission-prompt-tool`	Specify an MCP tool to handle permission prompts in non-interactive mode	`claude -p --permission-prompt-tool mcp_auth_tool "query"`
`--plugin-dir`	Load plugins from directories for this session only (repeatable)	`claude --plugin-dir ./my-plugins`
`--print`, `-p`	Print response without interactive mode (see SDK documentation for programmatic usage details)	`claude -p "query"`
`--resume`, `-r`	Resume a specific session by ID or name, or show an interactive picker to choose a session	`claude --resume auth-refactor`
`--session-id`	Use a specific session ID for the conversation (must be a valid UUID)	`claude --session-id "550e8400-e29b-41d4-a716-446655440000"`
`--setting-sources`	Comma-separated list of setting sources to load (`user`, `project`, `local`)	`claude --setting-sources user,project`
`--settings`	Path to a settings JSON file or a JSON string to load additional settings from	`claude --settings ./settings.json`
`--strict-mcp-config`	Only use MCP servers from `--mcp-config`, ignoring all other MCP configurations	`claude --strict-mcp-config --mcp-config ./mcp.json`
`--system-prompt`	Replace the entire system prompt with custom text (works in both interactive and print modes)	`claude --system-prompt "You are a Python expert"`
`--system-prompt-file`	Load system prompt from a file, replacing the default prompt (print mode only)	`claude -p --system-prompt-file ./custom-prompt.txt "query"`
`--tools`	Specify the list of available tools from the built-in set (use `""` to disable all, `"default"` for all, or tool names like `"Bash,Edit,Read"`)	`claude -p --tools "Bash,Edit,Read" "query"`
`--verbose`	Enable verbose logging, shows full turn-by-turn output (helpful for debugging in both print and interactive modes)	`claude --verbose`
`--version`, `-v`	Output the version number	`claude -v`

Agents flag format

The --agents flag accepts a JSON object that defines one or more custom subagents. Each subagent requires a unique name (as the key) and a definition object with the following fields:

Field	Required	Description
`description`	Yes	Natural language description of when the subagent should be invoked
`prompt`	Yes	The system prompt that guides the subagent's behavior
`tools`	No	Array of specific tools the subagent can use (for example, `["Read", "Edit", "Bash"]`). If omitted, inherits all tools
`model`	No	Model alias to use: `sonnet`, `opus`, or `haiku`. If omitted, uses the default subagent model

Example:

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}'

For more details on creating and using subagents, see the subagents documentation.

System prompt flags

Claude Code provides three flags for customizing the system prompt, each serving a different purpose:

Flag	Behavior	Modes	Use Case
`--system-prompt`	Replaces entire default prompt	Interactive + Print	Complete control over Claude's behavior and instructions
`--system-prompt-file`	Replaces with file contents	Print only	Load prompts from files for reproducibility and version control
`--append-system-prompt`	Appends to default prompt	Interactive + Print	Add specific instructions while keeping default Claude Code behavior

When to use each:

--system-prompt: Use when you need complete control over Claude's system prompt. This removes all default Claude Code instructions, giving you a blank slate.
```
claude --system-prompt "You are a Python expert who only writes type-annotated code"
```
--system-prompt-file: Use when you want to load a custom prompt from a file, useful for team consistency or version-controlled prompt templates.
```
claude -p --system-prompt-file ./prompts/code-review.txt "Review this PR"
```
--append-system-prompt: Use when you want to add specific instructions while keeping Claude Code's default capabilities intact. This is the safest option for most use cases.
```
claude --append-system-prompt "Always use TypeScript and include JSDoc comments"
```

For detailed information about print mode (-p) including output formats, streaming, verbose logging, and programmatic usage, see the SDK documentation.

cli-reference.md +3 −3

5## CLI commands5## CLI commands

6 6

~~8| :--------------------------------- | :--------------------------------------------- | :------------------------------------------------ |~~8| :------------------------------ | :--------------------------------------------- | :------------------------------------------------ |

18 18

48| `--print`, `-p` | Print response without interactive mode (see [SDK documentation](https://docs.claude.com/en/docs/agent-sdk) for programmatic usage details) | `claude -p "query"` |48| `--print`, `-p` | Print response without interactive mode (see [SDK documentation](https://docs.claude.com/en/docs/agent-sdk) for programmatic usage details) | `claude -p "query"` |

cli-reference.md 2025-12-16 21:01 UTC to 2025-12-17 15:02 UTC