Documentation 2025-12-03 00:04 UTC to 2025-12-04 21:02 UTC

23| Flag | Description | Example |23| Flag | Description | Example |

24| :------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------- |24| :------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------- |

25| `--add-dir` | Add additional working directories for Claude to access (validates each path exists as a directory) | `claude --add-dir ../apps ../lib` |25| `--add-dir` | Add additional working directories for Claude to access (validates each path exists as a directory) | `claude --add-dir ../apps ../lib` |

26| `--agent` | Specify an agent for the current session (overrides the `agent` setting) | `claude --agent my-custom-agent` |

26| `--agents` | Define custom [subagents](/en/sub-agents) dynamically via JSON (see below for format) | `claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'` |27| `--agents` | Define custom [subagents](/en/sub-agents) dynamically via JSON (see below for format) | `claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'` |

27| `--allowedTools` | A list of tools that should be allowed without prompting the user for permission, in addition to [settings.json files](/en/settings) | `"Bash(git log:*)" "Bash(git diff:*)" "Read"` |28| `--allowedTools` | A list of tools that should be allowed without prompting the user for permission, in addition to [settings.json files](/en/settings) | `"Bash(git log:*)" "Bash(git diff:*)" "Read"` |

29| `--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"` |

30| `--betas` | Beta headers to include in API requests (API key users only) | `claude --betas interleaved-thinking` |

31| `--continue`, `-c` | Load the most recent conversation in the current directory | `claude --continue` |

32| `--dangerously-skip-permissions` | Skip permission prompts (use with caution) | `claude --dangerously-skip-permissions` |

33| `--debug` | Enable debug mode with optional category filtering (e.g., `"api,hooks"` or `"!statsig,!file"`) | `claude --debug "api,mcp"` |

28| `--disallowedTools` | A list of tools that should be disallowed without prompting the user for permission, in addition to [settings.json files](/en/settings) | `"Bash(git log:*)" "Bash(git diff:*)" "Edit"` |34| `--disallowedTools` | A list of tools that should be disallowed without prompting the user for permission, in addition to [settings.json files](/en/settings) | `"Bash(git log:*)" "Bash(git diff:*)" "Edit"` |

29| `--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"` |35| `--fallback-model` | Enable automatic fallback to specified model when default model is overloaded (print mode only) | `claude -p --fallback-model sonnet "query"` |

30| `--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"` |36| `--fork-session` | When resuming, create a new session ID instead of reusing the original (use with `--resume` or `--continue`) | `claude --resume abc123 --fork-session` |

31| `--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"` |37| `--ide` | Automatically connect to IDE on startup if exactly one valid IDE is available | `claude --ide` |

32| `--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"` |38| `--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"` |

33| `--output-format` | Specify output format for print mode (options: `text`, `json`, `stream-json`) | `claude -p "query" --output-format json` |

34| `--input-format` | Specify input format for print mode (options: `text`, `stream-json`) | `claude -p --output-format json --input-format stream-json` |39| `--input-format` | Specify input format for print mode (options: `text`, `stream-json`) | `claude -p --output-format json --input-format stream-json` |

35| `--json-schema` | Get validated JSON output matching a JSON Schema after agent completes its workflow (print mode only, see [Agent SDK Structured Outputs](https://docs.claude.com/en/docs/agent-sdk/structured-outputs)) | `claude -p --json-schema '{"type":"object","properties":{...}}' "query"` |40| `--json-schema` | Get validated JSON output matching a JSON Schema after agent completes its workflow (print mode only, see [Agent SDK Structured Outputs](https://docs.claude.com/en/docs/agent-sdk/structured-outputs)) | `claude -p --json-schema '{"type":"object","properties":{...}}' "query"` |

36| `--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"` |

37| `--verbose` | Enable verbose logging, shows full turn-by-turn output (helpful for debugging in both print and interactive modes) | `claude --verbose` |

38| `--max-turns` | Limit the number of agentic turns in non-interactive mode | `claude -p --max-turns 3 "query"` |41| `--max-turns` | Limit the number of agentic turns in non-interactive mode | `claude -p --max-turns 3 "query"` |

42| `--mcp-config` | Load MCP servers from JSON files or strings (space-separated) | `claude --mcp-config ./mcp.json` |

39| `--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` |43| `--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` |

44| `--output-format` | Specify output format for print mode (options: `text`, `json`, `stream-json`) | `claude -p "query" --output-format json` |

40| `--permission-mode` | Begin in a specified [permission mode](/en/iam#permission-modes) | `claude --permission-mode plan` |45| `--permission-mode` | Begin in a specified [permission mode](/en/iam#permission-modes) | `claude --permission-mode plan` |

41| `--permission-prompt-tool` | Specify an MCP tool to handle permission prompts in non-interactive mode | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |46| `--permission-prompt-tool` | Specify an MCP tool to handle permission prompts in non-interactive mode | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |

42| `--resume` | Resume a specific session by ID, or by choosing in interactive mode | `claude --resume abc123 "query"` |47| `--plugin-dir` | Load plugins from directories for this session only (repeatable) | `claude --plugin-dir ./my-plugins` |

43| `--continue` | Load the most recent conversation in the current directory | `claude --continue` |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"` |

44| `--dangerously-skip-permissions` | Skip permission prompts (use with caution) | `claude --dangerously-skip-permissions` |49| `--resume`, `-r` | Resume a specific session by ID, or by choosing in interactive mode | `claude --resume abc123 "query"` |

50| `--session-id` | Use a specific session ID for the conversation (must be a valid UUID) | `claude --session-id "550e8400-e29b-41d4-a716-446655440000"` |

51| `--setting-sources` | Comma-separated list of setting sources to load (`user`, `project`, `local`) | `claude --setting-sources user,project` |

52| `--settings` | Path to a settings JSON file or a JSON string to load additional settings from | `claude --settings ./settings.json` |

53| `--strict-mcp-config` | Only use MCP servers from `--mcp-config`, ignoring all other MCP configurations | `claude --strict-mcp-config --mcp-config ./mcp.json` |

54| `--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"` |

55| `--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"` |

56| `--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"` |

57| `--verbose` | Enable verbose logging, shows full turn-by-turn output (helpful for debugging in both print and interactive modes) | `claude --verbose` |

58| `--version`, `-v` | Output the version number | `claude -v` |

45 59 

46<Tip>60<Tip>

47 The `--output-format json` flag is particularly useful for scripting and61 The `--output-format json` flag is particularly useful for scripting and

29 29 

30Find and install the [Claude Code plugin](https://plugins.jetbrains.com/plugin/27310-claude-code-beta-) from the JetBrains marketplace and restart your IDE.30Find and install the [Claude Code plugin](https://plugins.jetbrains.com/plugin/27310-claude-code-beta-) from the JetBrains marketplace and restart your IDE.

31 31 

32### Auto-Installation32If you haven't installed Claude Code yet, see [our quickstart guide](/en/quickstart) for installation instructions.

33 

34The plugin may also be auto-installed when you run `claude` in the integrated terminal. The IDE must be restarted completely to take effect.

35 33 

36<Note>34<Note>

37 After installing the plugin, you must restart your IDE completely for it to take effect. You may need to restart multiple times.35 After installing the plugin, you may need to restart your IDE completely for it to take effect.

38</Note>36</Note>

39 37 

40## Usage38## Usage

208 208 

209### Local scope209### Local scope

210 210 

211Local-scoped servers represent the default configuration level and are stored in your project-specific user settings. These servers remain private to you and are only accessible when working within the current project directory. This scope is ideal for personal development servers, experimental configurations, or servers containing sensitive credentials that shouldn't be shared.211Local-scoped servers represent the default configuration level and are stored in `~/.claude.json` under your project's path. These servers remain private to you and are only accessible when working within the current project directory. This scope is ideal for personal development servers, experimental configurations, or servers containing sensitive credentials that shouldn't be shared.

212 212 

213```bash theme={null}213```bash theme={null}

214# Add a local-scoped server (default)214# Add a local-scoped server (default)

245 245 

246### User scope246### User scope

247 247 

248User-scoped servers provide cross-project accessibility, making them available across all projects on your machine while remaining private to your user account. This scope works well for personal utility servers, development tools, or services you frequently use across different projects.248User-scoped servers are stored in `~/.claude.json` and provide cross-project accessibility, making them available across all projects on your machine while remaining private to your user account. This scope works well for personal utility servers, development tools, or services you frequently use across different projects.

249 249 

250```bash theme={null}250```bash theme={null}

251# Add a user server251# Add a user server

260* **Project scope**: Team-shared servers, project-specific tools, or services required for collaboration260* **Project scope**: Team-shared servers, project-specific tools, or services required for collaboration

261* **User scope**: Personal utilities needed across multiple projects, development tools, or frequently-used services261* **User scope**: Personal utilities needed across multiple projects, development tools, or frequently-used services

262 262 

263<Note>

264 **Where are MCP servers stored?**

265 

266 * **User and local scope**: `~/.claude.json` (in the `mcpServers` field or under project paths)

267 * **Project scope**: `.mcp.json` in your project root (checked into source control)

268 * **Enterprise managed**: `managed-mcp.json` in system directories (see [Enterprise MCP configuration](#enterprise-mcp-configuration))

269</Note>

270 

263### Scope hierarchy and precedence271### Scope hierarchy and precedence

264 272 

265MCP server configurations follow a clear precedence hierarchy. When servers with the same name exist at multiple scopes, the system resolves conflicts by prioritizing local-scoped servers first, followed by project-scoped servers, and finally user-scoped servers. This design ensures that personal configurations can override shared ones when needed.273MCP server configurations follow a clear precedence hierarchy. When servers with the same name exist at multiple scopes, the system resolves conflicts by prioritizing local-scoped servers first, followed by project-scoped servers, and finally user-scoped servers. This design ensures that personal configurations can override shared ones when needed.

226| `commands` | string\|array | Additional command files/directories | `"./custom/cmd.md"` or `["./cmd1.md"]` |226| `commands` | string\|array | Additional command files/directories | `"./custom/cmd.md"` or `["./cmd1.md"]` |

227| `agents` | string\|array | Additional agent files | `"./custom/agents/"` |227| `agents` | string\|array | Additional agent files | `"./custom/agents/"` |

228| `hooks` | string\|object | Hook config path or inline config | `"./hooks.json"` |228| `hooks` | string\|object | Hook config path or inline config | `"./hooks.json"` |

229| `mcpServers` | string\|object | MCP config path or inline config | `"./mcp.json"` |229| `mcpServers` | string\|object | MCP config path or inline config | `"./custom-mcp-config.json"` |

230 230 

231### Path behavior rules231### Path behavior rules

232 232 

25 * macOS: `/Library/Application Support/ClaudeCode/managed-mcp.json`25 * macOS: `/Library/Application Support/ClaudeCode/managed-mcp.json`

26 * Linux and WSL: `/etc/claude-code/managed-mcp.json`26 * Linux and WSL: `/etc/claude-code/managed-mcp.json`

27 * Windows: `C:\ProgramData\ClaudeCode\managed-mcp.json`27 * Windows: `C:\ProgramData\ClaudeCode\managed-mcp.json`

28* **Other configuration** is stored in `~/.claude.json`. This file contains your preferences (theme, notification settings, editor mode), OAuth session, [MCP server](/en/mcp) configurations for user and local scopes, per-project state (allowed tools, trust settings), and various caches. Project-scoped MCP servers are stored separately in `.mcp.json`.

28 29 

29```JSON Example settings.json theme={null}30```JSON Example settings.json theme={null}

30{31{

23 <Tab title="Native Install (Recommended)">23 <Tab title="Native Install (Recommended)">

24 **Homebrew (macOS, Linux):**24 **Homebrew (macOS, Linux):**

25 25 

26 ```sh theme={null}26 ```sh theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

27 brew install --cask claude-code27 brew install --cask claude-code

28 ```28 ```

29 29 

30 **macOS, Linux, WSL:**30 **macOS, Linux, WSL:**

31 31 

32 ```bash theme={null}32 ```bash theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

33 curl -fsSL https://claude.ai/install.sh | bash33 curl -fsSL https://claude.ai/install.sh | bash

34 ```34 ```

35 35 

36 **Windows PowerShell:**36 **Windows PowerShell:**

37 37 

38 ```powershell theme={null}38 ```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

39 irm https://claude.ai/install.ps1 | iex39 irm https://claude.ai/install.ps1 | iex

40 ```40 ```

41 41 

42 **Windows CMD:**42 **Windows CMD:**

43 43 

44 ```batch theme={null}44 ```batch theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

45 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd45 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

46 ```46 ```

47 </Tab>47 </Tab>

49 <Tab title="NPM">49 <Tab title="NPM">

50 If you have [Node.js 18 or newer installed](https://nodejs.org/en/download/):50 If you have [Node.js 18 or newer installed](https://nodejs.org/en/download/):

51 51 

52 ```sh theme={null}52 ```sh theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

53 npm install -g @anthropic-ai/claude-code53 npm install -g @anthropic-ai/claude-code

54 ```54 ```

55 </Tab>55 </Tab>

183 If you encounter permission errors, see [configure Claude Code](/en/troubleshooting#linux-permission-issues) for recommended solutions.183 If you encounter permission errors, see [configure Claude Code](/en/troubleshooting#linux-permission-issues) for recommended solutions.

184</Warning>184</Warning>

185 185 

186### Local installation

187 

188* After global install via npm, use `claude migrate-installer` to move to local

189* Avoids autoupdater npm permission issues

190* Some users may be automatically migrated to this method

191 

192## Running on AWS or GCP186## Running on AWS or GCP

193 187 

194By default, Claude Code uses the Claude API.188By default, Claude Code uses the Claude API.

101 Make sure that you have the installation directory in your system PATH.101 Make sure that you have the installation directory in your system PATH.

102</Tip>102</Tip>

103 103 

104#### Alternative solution: Migrate to local installation

105 

106Alternatively, if Claude Code will run, you can migrate to a local installation:

107 

108```bash theme={null}

109claude migrate-installer

110```

111 

112This moves Claude Code to `~/.claude/local/` and sets up an alias in your shell configuration. No `sudo` is required for future updates.

113 

114After migration, restart your shell, and then verify your installation:

115 

116On macOS/Linux/WSL:

117 

118```bash theme={null}

119which claude # Should show an alias to ~/.claude/local/claude

120```

121 

122On Windows:

123 

124```powershell theme={null}

125where claude # Should show path to claude executable

126```

127 

128Verify installation:104Verify installation:

129 105 

130```bash theme={null}106```bash theme={null}

155 131 

156This removes your stored authentication information and forces a clean login.132This removes your stored authentication information and forces a clean login.

157 133 

134## Configuration file locations

135 

136Claude Code stores configuration in several locations:

137 

138| File | Purpose |

139| :---------------------------- | :--------------------------------------------------------------------- |

140| `~/.claude/settings.json` | User settings (permissions, hooks, model overrides) |

141| `.claude/settings.json` | Project settings (checked into source control) |

142| `.claude/settings.local.json` | Local project settings (gitignored) |

143| `~/.claude.json` | Global state (theme, OAuth, MCP servers, allowed tools) |

144| `.mcp.json` | Project MCP servers (checked into source control) |

145| `managed-settings.json` | [Enterprise managed settings](/en/settings#settings-files) |

146| `managed-mcp.json` | [Enterprise managed MCP servers](/en/mcp#enterprise-mcp-configuration) |

147 

148On Windows, `~` refers to your user home directory (e.g., `C:\Users\YourName`).

149 

150**Enterprise managed file locations:**

151 

152* macOS: `/Library/Application Support/ClaudeCode/`

153* Linux/WSL: `/etc/claude-code/`

154* Windows: `C:\ProgramData\ClaudeCode\`

155 

156For details on configuring these files, see [Settings](/en/settings) and [MCP](/en/mcp).

157 

158### Resetting configuration

159 

160To reset Claude Code to default settings, you can remove the configuration files:

161 

162```bash theme={null}

163# Reset all user settings and state

164rm ~/.claude.json

165rm -rf ~/.claude/

166 

167# Reset project-specific settings

168rm -rf .claude/

169rm .mcp.json

170```

171 

172<Warning>

173 This will remove all your settings, allowed tools, MCP server configurations, and session history.

174</Warning>

175 

158## Performance and stability176## Performance and stability

159 177 

160### High CPU or memory usage178### High CPU or memory usage

252 These networking issues only affect WSL2. WSL1 uses the host's network directly and doesn't require these configurations.270 These networking issues only affect WSL2. WSL1 uses the host's network directly and doesn't require these configurations.

253</Note>271</Note>

254 272 

255For additional JetBrains configuration tips, see our [IDE integration guide](/en/vs-code#jetbrains-plugin-settings).273For additional JetBrains configuration tips, see our [JetBrains IDE guide](/en/jetbrains#plugin-settings).

256 274 

257### Reporting Windows IDE integration issues (both native and WSL)275### Reporting Windows IDE integration issues (both native and WSL)

258 276