# Claude Code CLI flags and commands: the full reference

The claude command starts a session; flags change how it starts. The ones you will use most are -c to continue the last conversation, -r to pick an older one, -p to answer once and exit (for scripts), --model to choose the model, --permission-mode to start in plan or another mode, and -w to work in a separate Git worktree.

- Page: https://tecyfy.com/coding-agents/claude-code/cli
- Guide: Claude Code (https://tecyfy.com/coding-agents/claude-code), from Anthropic's documentation (https://code.claude.com/docs/en/overview)

Everything starts with `claude`. Typed alone in a folder it opens an interactive session there. Flags after it change how that session starts, and a few words after it, such as `claude update`, run a separate job and exit.

Flags apply to one session. To make a choice stick, such as a default model or a permission rule, put it in a [settings file](/coding-agents/claude-code/settings) instead. A flag overrides the settings for that session.

## The flags you will use every day

```bash
claude -c                         # carry on with the last conversation here
claude -r                         # pick an older conversation from a list
claude -r billing-bug             # reopen the one you named billing-bug
claude -n billing-bug             # start one and give it that name
claude --model opus               # start with a particular model
claude --permission-mode plan     # start in plan mode: read and propose, no edits
claude -w fix-header              # work in a separate Git worktree
```

`-w` is worth knowing early. It creates a Git worktree under `.claude/worktrees/`, a second checkout of the same repository on its own branch, and starts the session inside it. 2 sessions in 2 worktrees can edit at the same time without touching each other's files.

## One-off and scripted runs

`-p` (print) is the flag that turns Claude Code into a command-line tool. It runs the task, prints the answer and exits:

```bash
claude -p "summarize what changed in the last 5 commits"
git diff main | claude -p "write a pull request description for this diff"
claude -p "list every TODO in src/ as JSON" --output-format json
```

Several flags only work with `-p`, because they only make sense when no one is watching: `--max-turns` and `--max-budget-usd` stop a run that goes on too long, `--output-format json` returns the result with its cost and session id, and `--json-schema` makes the answer match a shape your script can read. [Scripts and CI](/coding-agents/claude-code/headless) covers these runs in full.

## Permissions from the command line

You can set what a session may do as you start it:

```bash
claude --allowedTools "Bash(npm test *)" "Bash(git diff *)" "Read"
claude --disallowedTools "Bash(git push *)" "WebFetch"
```

`--allowedTools` lets matching calls run without asking. `--disallowedTools` blocks them. `--tools` goes further and decides which built-in tools exist at all.

`--dangerously-skip-permissions` turns every permission prompt off. The name is the warning: use it only on a machine or container you can throw away, never on your own laptop with your keys and your production access. [Permissions](/coding-agents/claude-code/permissions) explains the safer options.

## Adding to Claude Code's instructions

`--append-system-prompt "..."` adds text to the end of the instructions Claude Code gives the model, and `--append-system-prompt-file` does the same from a file. Use them for rules that belong to one run, such as a reply language or an output format.

`--system-prompt` replaces those instructions entirely, including the guidance on using tools safely. Keep it for agents that are not coding assistants, such as a script that sorts support tickets. For rules your whole project follows, [CLAUDE.md](/coding-agents/claude-code/project-instructions) is the better place.

## Commands that do not start a session

`claude update` installs the latest version, `claude doctor` checks your install, and `claude auth status` tells a script whether it is signed in. `claude mcp add` connects [MCP servers](/coding-agents/claude-code/mcp) and `claude plugin install` adds [plugins](/coding-agents/claude-code/plugins). `claude setup-token` makes a long-lived token for CI.

Mistype one and Claude Code suggests the closest match instead of starting a session: `claude udpate` asks whether you meant `claude update`.

## Every flag and command

Search by name or by job, such as "resume", "budget" or "worktree". `claude --help` leaves some flags out, so this list is longer than what it prints.

| Flag or command | Group | What it does |
| --- | --- | --- |
| `claude` | Start | Starts an interactive session in the current folder. Put a task in quotes after it to start with that message. Example: `claude "explain how the build works"` |
| `--continue, -c` | Start | Reopens the most recent conversation in this folder. Example: `claude -c` |
| `--resume, -r` | Start | Reopens a conversation by its name or id, or shows a list to pick from. Add a message to send it straight away. Example: `claude -r auth-refactor "finish the tests"` |
| `--fork-session` | Start | With --resume or --continue, copies the conversation into a new session instead of adding to the old one. Example: `claude -r auth-refactor --fork-session` |
| `--name, -n` | Start | Names the session, so claude --resume can find it by that name. Example: `claude -n "billing-bug"` |
| `--session-id` | Start | Uses a session id you choose, which must be a UUID. Example: `claude --session-id "550e8400-e29b-41d4-a716-446655440000"` |
| `--from-pr` | Start | Lists only the sessions linked to a pull request, by number or link. Example: `claude --from-pr 123` |
| `--worktree, -w` | Start | Starts in a separate Git worktree under .claude/worktrees/, so this session's edits do not collide with another's. Pass a pull request number to branch from it. Example: `claude -w feature-auth` |
| `--tmux` | Start | With --worktree, opens the session in its own tmux session or iTerm2 pane. Example: `claude -w feature-auth --tmux` |
| `--add-dir` | Start | Lets Claude read and edit files in more folders than the one you started in. Example: `claude --add-dir ../shared ../docs` |
| `--bg, --background` | Start | Starts the session in the background and returns at once, printing its id. Watch it with claude agents. Example: `claude --bg "investigate the flaky test"` |
| `--exec` | Start | With --bg, runs a shell command as a background job instead of a Claude session. Example: `claude --bg --exec 'pytest -x'` |
| `--version, -v` | Start | Prints the version. Example: `claude -v` |
| `--model` | Model | Sets the model for this session, by alias (sonnet, opus, haiku, fable) or full name. Example: `claude --model opus` |
| `--effort` | Model | Sets how much the model reasons for this session, from low to max. Not saved. Example: `claude --effort high` |
| `--fallback-model` | Model | Names models to switch to, in order, if the main one is overloaded or gone. Example: `claude --fallback-model sonnet,haiku` |
| `--advisor` | Model | Gives the session a second model to ask for advice at hard moments. Example: `claude --advisor opus` |
| `--autocompact` | Model | Sets how full the context window gets before it compacts, for this session only. Example: `claude --autocompact 500k` |
| `--betas` | Model | Adds beta headers to API requests. API key users only. Example: `claude --betas interleaved-thinking` |
| `--permission-mode` | Permissions | Starts in a permission mode - default (Manual), acceptEdits, plan, auto, dontAsk or bypassPermissions. Example: `claude --permission-mode plan` |
| `--allowedTools` | Permissions | Tools, or patterns of them, that run without asking. Quote each rule. Example: `claude --allowedTools "Bash(npm test *)" "Read"` |
| `--disallowedTools` | Permissions | Deny rules. A bare tool name removes the tool; a pattern such as "Bash(rm *)" blocks only matching calls. Example: `claude --disallowedTools "Bash(git push *)"` |
| `--tools` | Permissions | Limits which built-in tools exist at all. "" for none, "default" for the usual set, or a list. Example: `claude --tools "Read,Edit,Bash"` |
| `--dangerously-skip-permissions` | Permissions | Skips permission prompts, the same as --permission-mode bypassPermissions. Only for isolated machines or containers. Example: `claude --dangerously-skip-permissions` |
| `--allow-dangerously-skip-permissions` | Permissions | Adds bypassPermissions to the Shift+Tab cycle without starting in it. Example: `claude --permission-mode plan --allow-dangerously-skip-permissions` |
| `--permission-prompt-tool` | Permissions | In a script, sends permission questions to an MCP tool of yours to answer. Example: `claude -p --permission-prompt-tool mcp_auth_tool "query"` |
| `--permission-prompts` | Permissions | In a script, none denies every permission question when nobody is there to answer. Example: `claude -p --permission-prompts none "query"` |
| `--restricted` | Permissions | Restricted mode for test harnesses on shared machines - no tools that run commands or code, file tools kept to the working folders, and no user or project settings. Example: `claude --restricted -p "query"` |
| `--print, -p` | Scripts | Answers once and exits, with no interactive session. The basis of every script and CI job. Pipe text in to give it input. Example: `cat error.log \| claude -p "explain this error"` |
| `--output-format` | Scripts | With -p, prints text, json (one object with the result, cost and session id) or stream-json (one event per line). Example: `claude -p "list the API routes" --output-format json` |
| `--input-format` | Scripts | With -p, reads input as text or as a stream of JSON messages. Example: `claude -p --input-format stream-json --output-format stream-json` |
| `--json-schema` | Scripts | With -p, returns JSON that matches the schema you give, checked when the task ends. Example: `claude -p --json-schema '{"type":"object"}' "summarize the diff"` |
| `--max-turns` | Scripts | With -p, stops after this many agent turns and exits with an error. Example: `claude -p --max-turns 5 "fix the lint errors"` |
| `--max-budget-usd` | Scripts | With -p, stops once the estimated spend reaches this many dollars. The estimate can differ from your bill, so leave room. Example: `claude -p --max-budget-usd 2 "review this PR"` |
| `--no-session-persistence` | Scripts | With -p, does not save the session, so it cannot be resumed. Example: `claude -p --no-session-persistence "query"` |
| `--bare` | Scripts | Skips loading hooks, skills, plugins, MCP servers, memory and CLAUDE.md, so scripted runs start faster and behave the same on every machine. Example: `claude --bare -p "query"` |
| `--verbose` | Scripts | Shows the full output of every turn. Needed with -p and stream-json. Example: `claude -p --output-format stream-json --verbose "query"` |
| `--include-partial-messages` | Scripts | With stream-json, also sends the answer as it is written, piece by piece. Example: `claude -p --output-format stream-json --verbose --include-partial-messages "query"` |
| `--include-hook-events` | Scripts | With stream-json, also reports when hooks start and finish. Example: `claude -p --output-format stream-json --verbose --include-hook-events "query"` |
| `--forward-subagent-text` | Scripts | With stream-json, includes what subagents write, so each one's transcript can be rebuilt. Example: `claude -p --output-format stream-json --verbose --forward-subagent-text "query"` |
| `--replay-user-messages` | Scripts | With stream-json in and out, echoes each message it receives back on its output. Example: `claude -p --input-format stream-json --output-format stream-json --verbose --replay-user-messages` |
| `--prompt-suggestions` | Scripts | With stream-json, adds a guess at your next prompt after each turn. Example: `claude -p --prompt-suggestions --output-format stream-json --verbose "query"` |
| `--exclude-dynamic-system-prompt-sections` | Scripts | Moves per-user details out of the system prompt so the same job run by many users shares the prompt cache. Example: `claude -p --exclude-dynamic-system-prompt-sections "query"` |
| `--init` | Scripts | With -p, runs your Setup hooks with the init matcher before the task. Example: `claude -p --init "query"` |
| `--init-only` | Scripts | Runs the Setup and SessionStart hooks, then exits. Example: `claude --init-only` |
| `--maintenance` | Scripts | With -p, runs your Setup hooks with the maintenance matcher before the task. Example: `claude -p --maintenance "query"` |
| `--append-system-prompt` | Prompt | Adds your text to the end of Claude Code's own instructions, keeping them. Example: `claude --append-system-prompt "Answer in British English"` |
| `--append-system-prompt-file` | Prompt | Adds the contents of a file to the end of Claude Code's own instructions. Example: `claude --append-system-prompt-file ./style.md` |
| `--system-prompt` | Prompt | Replaces Claude Code's instructions entirely, including its guidance on tools and safety. For agents that are not coding assistants. Example: `claude -p --system-prompt "You sort support tickets" "query"` |
| `--system-prompt-file` | Prompt | Replaces Claude Code's instructions with the contents of a file. Example: `claude --system-prompt-file ./prompts/triage.txt` |
| `--system-prompt-snapshot` | Prompt | off rebuilds the system prompt on every request instead of keeping the one the conversation started with, useful while you tune it. Example: `claude --system-prompt-snapshot off` |
| `--append-subagent-system-prompt` | Prompt | With -p, adds your text to every subagent's instructions. Example: `claude -p --append-subagent-system-prompt "Cite file paths" "query"` |
| `--append-subagent-system-prompt-file` | Prompt | With -p, adds a file's contents to every subagent's instructions. Example: `claude -p --append-subagent-system-prompt-file ./subagent-rules.txt "query"` |
| `--settings` | Extend | Loads settings from a file or a JSON string for this session, on top of your settings files. Example: `claude --settings ./ci-settings.json` |
| `--setting-sources` | Extend | Chooses which settings files load - user, project, local. Example: `claude --setting-sources user,project` |
| `--mcp-config` | Extend | Loads MCP servers from JSON files or strings. Example: `claude --mcp-config ./mcp.json` |
| `--strict-mcp-config` | Extend | Uses only the MCP servers from --mcp-config and ignores all others. Example: `claude --strict-mcp-config --mcp-config ./mcp.json` |
| `--agent` | Extend | Runs the session as one of your subagents, with its instructions and tools. Example: `claude --agent code-reviewer` |
| `--agents` | Extend | Defines subagents for this session as JSON. Example: `claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You review code for bugs"}}'` |
| `--plugin-dir` | Extend | Loads a plugin from a folder or .zip for this session only. Repeat it for more. Example: `claude --plugin-dir ./my-plugin` |
| `--plugin-url` | Extend | Downloads a plugin .zip from a link for this session only. Example: `claude --plugin-url https://example.com/plugin.zip` |
| `--disable-slash-commands` | Extend | Turns off all skills and commands for this session. Example: `claude --disable-slash-commands` |
| `--safe-mode` | Extend | Starts with every customization off - CLAUDE.md, skills, plugins, hooks, MCP servers, memory - to find out whether one of them is causing a problem. Example: `claude --safe-mode` |
| `--chrome` | Extend | Turns on Claude in Chrome for browser tasks. Example: `claude --chrome` |
| `--no-chrome` | Extend | Turns off Claude in Chrome for this session. Example: `claude --no-chrome` |
| `--ide` | Extend | Connects to your code editor at start, if exactly one is found. Example: `claude --ide` |
| `--channels` | Extend | Listens for messages pushed by channel plugins, such as a chat app or your own server. Research preview. Example: `claude --channels plugin:my-notifier@my-marketplace` |
| `--dangerously-load-development-channels` | Extend | Allows channels that are not on the approved list, for testing your own. Example: `claude --dangerously-load-development-channels server:webhook` |
| `--teammate-mode` | Extend | Sets how agent team members are shown - in-process, auto, tmux or iterm2. Example: `claude --teammate-mode tmux` |
| `--cloud` | Cloud | Starts a new session in the cloud with the task you give, or sends a message to an existing cloud session. Example: `claude --cloud "fix the login bug"` |
| `--teleport` | Cloud | Brings a cloud session into your terminal. Example: `claude --teleport` |
| `--remote-control, --rc` | Cloud | Starts a session you can also drive from claude.ai or the Claude app. Example: `claude --rc "my project"` |
| `--remote-control-session-name-prefix` | Cloud | Sets the start of automatic Remote Control session names, which is otherwise your computer's name. Example: `claude remote-control --remote-control-session-name-prefix dev-box` |
| `--environment` | Cloud | Starts a cloud session on your organization's own self-hosted environment. Example: `claude -p "run the smoke test" --environment ccpool_abc123` |
| `--ref` | Cloud | With --environment, starts the cloud session from a named branch instead of your current commit. Example: `claude -p "run the smoke test" --environment ccpool_abc123 --ref main` |
| `--desktop` | Cloud | Opens the Claude desktop app on this folder, or on a session with --continue or --resume. Example: `claude --desktop --continue` |
| `--debug` | Debug | Turns on debug logging, optionally for some areas only. Example: `claude --debug='mcp,startup'` |
| `--debug-file` | Debug | Writes the debug log to a file you name. Example: `claude --debug-file /tmp/claude-debug.log` |
| `--ax-screen-reader` | Debug | Plain output for screen readers, with no borders or animation. Example: `claude --ax-screen-reader` |
| `claude update` | Subcommands | Installs the newest version now. Example: `claude update` |
| `claude install` | Subcommands | Installs or reinstalls the program, at a version, stable or latest. Example: `claude install stable` |
| `claude doctor` | Subcommands | Checks the install and your settings files without starting a session. Example: `claude doctor` |
| `claude auth login` | Subcommands | Signs in. --console bills a Console account instead of a Claude plan; --sso forces single sign-on. Example: `claude auth login --console` |
| `claude auth logout` | Subcommands | Signs out. Example: `claude auth logout` |
| `claude auth status` | Subcommands | Shows how you are signed in, as JSON, and exits with 0 if you are and 1 if not. --text for plain words. Example: `claude auth status --text` |
| `claude setup-token` | Subcommands | Makes a long-lived sign-in token for CI and scripts, printed once and not saved. Needs a Claude plan. Example: `claude setup-token` |
| `claude mcp` | Subcommands | Adds, lists and removes MCP servers. Example: `claude mcp add --transport http notion https://mcp.notion.com/mcp` |
| `claude mcp login` | Subcommands | Signs in to an MCP server that needs it, without opening /mcp. --no-browser prints the link instead, for SSH. Example: `claude mcp login sentry` |
| `claude mcp logout` | Subcommands | Removes an MCP server's saved sign-in. Example: `claude mcp logout sentry` |
| `claude plugin` | Subcommands | Installs, lists and manages plugins. Also claude plugins. Example: `claude plugin install code-review@claude-plugins-official` |
| `claude agents` | Subcommands | Opens agent view, to start and watch sessions running in the background. --json lists them for scripts. Example: `claude agents` |
| `claude attach` | Subcommands | Joins a background session in this terminal. Example: `claude attach 7c5dcf5d` |
| `claude logs` | Subcommands | Prints the latest output of a background session. Example: `claude logs 7c5dcf5d` |
| `claude stop` | Subcommands | Stops a background session. Also claude kill. Example: `claude stop 7c5dcf5d` |
| `claude respawn` | Subcommands | Restarts a background session with its conversation, for example to pick up a new version. --all for every one. Example: `claude respawn --all` |
| `claude rm` | Subcommands | Removes a background session from the list. Its transcript stays on your machine. Example: `claude rm 7c5dcf5d` |
| `claude daemon` | Subcommands | Looks after the process that hosts background sessions - logs, run, status and stop. Example: `claude daemon status` |
| `claude remote-control` | Subcommands | Runs a server so you can start and drive sessions on this machine from claude.ai or the Claude app. Example: `claude remote-control --name "work laptop"` |
| `claude import` | Subcommands | Brings settings, instructions, MCP servers and skills over from OpenAI Codex, Gemini CLI or Cursor. Example: `claude import codex --dry-run` |
| `claude purge` | Subcommands | Deletes everything Claude Code stored locally for a project - transcripts, edit history, prompt history. --dry-run previews. Example: `claude purge ~/work/repo --dry-run` |
| `claude auto-mode defaults` | Subcommands | Prints the rules auto mode's safety check uses, as JSON. claude auto-mode config shows yours with your settings applied. Example: `claude auto-mode defaults` |
| `claude auto-mode reset` | Subcommands | Removes your own auto mode rules from your user settings, back to the defaults. Example: `claude auto-mode reset` |
| `claude ultrareview` | Subcommands | Runs the deep cloud code review from a script and prints the findings. --post adds them to a GitHub pull request. Example: `claude ultrareview 1234 --json` |
| `claude gateway` | Subcommands | Runs a self-hosted gateway that signs a company's developers in and sends their requests to Bedrock, Google Cloud or Foundry. For administrators. Example: `claude gateway --config gateway.yaml` |
| `claude self-hosted-runner` | Subcommands | Registers this machine to run your organization's cloud sessions on its own infrastructure. Example: `claude self-hosted-runner setup` |

## Questions

### What does claude -p do?

It runs Claude Code once without the interactive screen. It takes your prompt, works through the task, prints the result and exits. It is how you use Claude Code in scripts, Git hooks and CI. Pipe text into it to give it input, as in cat error.log | claude -p "explain this".

### What is the difference between claude -c and claude -r?

claude -c reopens the most recent conversation in the current folder with no questions. claude -r reopens a particular one, by name or id, or shows a list to choose from when you give neither.

### Should I use --system-prompt or --append-system-prompt?

Almost always --append-system-prompt. It adds your rules and keeps Claude Code's own instructions, including how to use its tools safely. --system-prompt replaces all of them, which only makes sense for an agent that is not meant to be a coding assistant.

### Why does claude --help not show every flag?

The help text leaves some flags out. A flag missing from claude --help can still work; the reference on this page lists them all.

## Sources

- [CLI reference](https://code.claude.com/docs/en/cli-reference)
- [Choose a permission mode](https://code.claude.com/docs/en/permission-modes)