CLI reference

CLI commands

You can start sessions, pipe content, resume conversations, and manage updates with these commands:

Command	Description	Example
`claude`	Start interactive session	`claude`
`claude "query"`	Start interactive session 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 in current directory	`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 auth login`	Sign in to your Anthropic account. Use `--email` to pre-fill your email address and `--sso` to force SSO authentication	`claude auth login --email [email protected] --sso`
`claude auth logout`	Log out from your Anthropic account	`claude auth logout`
`claude auth status`	Show authentication status as JSON. Use `--text` for human-readable output. Exits with code 0 if logged in, 1 if not	`claude auth status`
`claude agents`	List all configured subagents, grouped by source	`claude agents`
`claude mcp`	Configure Model Context Protocol (MCP) servers	See the Claude Code MCP documentation.
`claude remote-control`	Start a Remote Control session to control Claude Code from Claude.ai or the Claude app while running locally. See Remote Control for flags	`claude remote-control`

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"}}'`
`--allow-dangerously-skip-permissions`	Enable permission bypassing as an option without immediately activating it. Allows composing with `--permission-mode` (use with caution)	`claude --permission-mode plan --allow-dangerously-skip-permissions`
`--allowedTools`	Tools that execute without prompting for permission. See permission rule syntax for pattern matching. 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	`claude --append-system-prompt "Always use TypeScript"`
`--append-system-prompt-file`	Load additional system prompt text from a file and append to the default prompt	`claude --append-system-prompt-file ./extra-rules.txt`
`--betas`	Beta headers to include in API requests (API key users only)	`claude --betas interleaved-thinking`
`--chrome`	Enable Chrome browser integration for web automation and testing	`claude --chrome`
`--continue`, `-c`	Load the most recent conversation in the current directory	`claude --continue`
`--dangerously-skip-permissions`	Skip all 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"`
`--disable-slash-commands`	Disable all skills and commands for this session	`claude --disable-slash-commands`
`--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`
`--from-pr`	Resume sessions linked to a specific GitHub PR. Accepts a PR number or URL. Sessions are automatically linked when created via `gh pr create`	`claude --from-pr 123`
`--ide`	Automatically connect to IDE on startup if exactly one valid IDE is available	`claude --ide`
`--init`	Run initialization hooks and start interactive mode	`claude --init`
`--init-only`	Run initialization hooks and exit (no interactive session)	`claude --init-only`
`--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 structured outputs)	`claude -p --json-schema '{"type":"object","properties":{...}}' "query"`
`--maintenance`	Run maintenance hooks and exit	`claude --maintenance`
`--max-budget-usd`	Maximum dollar amount to spend on API calls before stopping (print mode only)	`claude -p --max-budget-usd 5.00 "query"`
`--max-turns`	Limit the number of agentic turns (print mode only). Exits with an error when the limit is reached. No limit by default	`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-6`
`--no-chrome`	Disable Chrome browser integration for this session	`claude --no-chrome`
`--no-session-persistence`	Disable session persistence so sessions are not saved to disk and cannot be resumed (print mode only)	`claude -p --no-session-persistence "query"`
`--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 Agent SDK documentation for programmatic usage details)	`claude -p "query"`
`--remote`	Create a new web session on claude.ai with the provided task description	`claude --remote "Fix the login bug"`
`--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	`claude --system-prompt "You are a Python expert"`
`--system-prompt-file`	Load system prompt from a file, replacing the default prompt	`claude --system-prompt-file ./custom-prompt.txt`
`--teleport`	Resume a web session in your local terminal	`claude --teleport`
`--teammate-mode`	Set how agent team teammates display: `auto` (default), `in-process`, or `tmux`. See set up agent teams	`claude --teammate-mode in-process`
`--tools`	Restrict which built-in tools Claude can use. Use `""` to disable all, `"default"` for all, or tool names like `"Bash,Edit,Read"`	`claude --tools "Bash,Edit,Read"`
`--verbose`	Enable verbose logging, shows full turn-by-turn output	`claude --verbose`
`--version`, `-v`	Output the version number	`claude -v`
`--worktree`, `-w`	Start Claude in an isolated git worktree at `<repo>/.claude/worktrees/<name>`. If no name is given, one is auto-generated	`claude -w feature-auth`

The --output-format json flag is particularly useful for scripting and automation, allowing you to parse Claude’s responses programmatically.

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. Supports `Agent(agent_type)` syntax
`disallowedTools`	No	Array of tool names to explicitly deny for this subagent
`model`	No	Model alias to use: `sonnet`, `opus`, `haiku`, or `inherit`. If omitted, defaults to `inherit`
`skills`	No	Array of skill names to preload into the subagent’s context
`mcpServers`	No	Array of MCP servers for this subagent. Each entry is a server name string or a `{name: config}` object
`maxTurns`	No	Maximum number of agentic turns before the subagent stops

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 four flags for customizing the system prompt. All four work in both interactive and non-interactive modes.

Flag	Behavior	Use case
`--system-prompt`	Replaces entire default prompt	Complete control over Claude’s behavior and instructions
`--system-prompt-file`	Replaces with file contents	Load prompts from files for reproducibility and version control
`--append-system-prompt`	Appends to default prompt	Add specific instructions while keeping default Claude Code behavior
`--append-system-prompt-file`	Appends file contents to default prompt	Load additional instructions from files while keeping defaults

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 --system-prompt-file ./prompts/code-review.txt
```
--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"
```
--append-system-prompt-file: use when you want to append instructions from a file while keeping Claude Code’s defaults. Useful for version-controlled additions.
```
claude --append-system-prompt-file ./prompts/style-rules.txt
```

--system-prompt and --system-prompt-file are mutually exclusive. The append flags can be used together with either replacement flag. For most use cases, --append-system-prompt or --append-system-prompt-file is recommended as they preserve 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.

Reference

CLI commands

CLI flags

Agents flag format

System prompt flags

See also

Reference

​CLI commands

​CLI flags

​Agents flag format

​System prompt flags

​See also

CLI commands

CLI flags

Agents flag format

System prompt flags

See also