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-id>" "query" | Resume session by ID | claude -r "abc123" "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 |
--agents | Define custom subagents dynamically via JSON (see below for format) | claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}' |
--allowedTools | A list of tools that should be allowed without prompting the user for permission, in addition to settings.json files | "Bash(git log:*)" "Bash(git diff:*)" "Read" |
--disallowedTools | A list of tools that should be disallowed without prompting the user for permission, in addition to settings.json files | "Bash(git log:*)" "Bash(git diff:*)" "Edit" |
--print, -p | Print response without interactive mode (see SDK documentation for programmatic usage details) | claude -p "query" |
--system-prompt | Replace the entire system prompt with custom text (works in both interactive and print modes; added in v2.0.14) | claude --system-prompt "You are a Python expert" |
--system-prompt-file | Load system prompt from a file, replacing the default prompt (print mode only; added in v1.0.54) | claude -p --system-prompt-file ./custom-prompt.txt "query" |
--append-system-prompt | Append custom text to the end of the default system prompt (works in both interactive and print modes; added in v1.0.55) | claude --append-system-prompt "Always use TypeScript" |
--output-format | Specify output format for print mode (options: text, json, stream-json) | claude -p "query" --output-format json |
--input-format | Specify input format for print mode (options: text, stream-json) | claude -p --output-format json --input-format stream-json |
--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" |
--verbose | Enable verbose logging, shows full turn-by-turn output (helpful for debugging in both print and interactive modes) | claude --verbose |
--max-turns | Limit the number of agentic turns in non-interactive mode | claude -p --max-turns 3 "query" |
--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 |
--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" |
--resume | Resume a specific session by ID, or by choosing in interactive mode | claude --resume abc123 "query" |
--continue | Load the most recent conversation in the current directory | claude --continue |
--dangerously-skip-permissions | Skip permission prompts (use with caution) | claude --dangerously-skip-permissions |
The --output-format json flag is particularly useful for scripting and
automation, allowing you to parse Claude’s responses programmatically.
--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 (e.g., ["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."
}
}'
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"
--system-prompt and --system-prompt-file are mutually exclusive. You cannot use both flags simultaneously.
For most use cases, --append-system-prompt is recommended as it preserves Claude Code’s built-in capabilities while adding your custom requirements. Use --system-prompt or --system-prompt-file only when you need complete control over the system prompt.
-p) including output formats,
streaming, verbose logging, and programmatic usage, see the
SDK documentation.
See also
