Claude Code CLI flags: a cheat sheet by task

The Claude Code command-line flags you actually use, grouped by job instead of A to Z. Resuming a session, picking the model and effort, permissions, scripts with -p and JSON output, loading settings and MCP servers, worktrees and background sessions, and the flags for fixing a broken setup. Checked against Claude Code 2.1.308.

By Behnia Zarei5 min readClaude CodeCommands

Short answer: The ones worth remembering: claude -c continues the last conversation in this folder, claude -r picks an older one, --model and --effort choose the model and how hard it thinks, --permission-mode plan starts in plan mode, -p "prompt" runs once and prints the answer for scripts, and --safe-mode starts with every customisation off when something is broken. claude --help lists them all.

claude --help prints more than sixty flags in alphabetical order, which is the right order for a reference and the wrong one for remembering. Below are the ones that matter, grouped by what you are trying to do, with an example each. All of them are from the help of Claude Code 2.1.308.

How do you start, continue and resume sessions?

FlagExampleDoes
(a prompt)claude "explain this repo"Starts a session with a first message
-c, --continueclaude -cContinues the most recent conversation in this folder
-r, --resumeclaude -r or claude -r auth-fixOpens the session picker, or resumes by ID or name
--fork-sessionclaude -c --fork-sessionResumes under a new session ID, leaving the original as it was
-n, --nameclaude -n auth-fixNames the session for the picker and the terminal title
--from-prclaude --from-pr 128Resumes the session linked to a pull request

How do you pick the model and the effort?

FlagExampleDoes
--modelclaude --model opusModel for this session: an alias (fable, opus, sonnet) or a full model name
--effortclaude --effort highEffort level: low, medium, high, xhigh or max
--fallback-modelclaude -p --fallback-model sonnet "..."Falls back to these models, in order, when the default is overloaded

How do you control permissions from the command line?

FlagExampleDoes
--permission-modeclaude --permission-mode planStarts in manual, acceptEdits, plan, auto, dontAsk or bypassPermissions
--allowedToolsclaude --allowedTools "Bash(git *)" EditAllows these tools without asking
--disallowedToolsclaude --disallowedTools "Bash(rm *)"Denies these tools
--add-dirclaude --add-dir ../sharedGives Claude access to another folder too
--toolsclaude --tools "Read,Grep,Glob"Limits the built-in tools to this list
--dangerously-skip-permissionsSkips every permission check; only in a sandbox without internet

Claude Code permission modes explains what each mode allows.

Which flags are for scripts and CI?

FlagExampleDoes
-p, --printclaude -p "summarise CHANGELOG.md"Runs one prompt, prints the answer and exits
--output-formatclaude -p --output-format json "..."text, json (one result) or stream-json (as it happens)
--json-schemaclaude -p --json-schema '{...}' "..."Makes the answer match a JSON Schema
--max-budget-usdclaude -p --max-budget-usd 2 "..."Stops when the API cost reaches this amount
--no-session-persistenceDoes not save the session to disk

Two warnings from the help itself: with -p the workspace trust dialog is skipped, so run it only in folders you trust, and settings files that fail validation are silently ignored. Run Claude Code headless in CI puts these together.

How do you load settings, MCP servers and prompts for one run?

FlagExampleDoes
--settingsclaude --settings ./ci-settings.jsonLoads extra settings from a file or a JSON string
--setting-sourcesclaude --setting-sources userLoads only these settings files: user, project, local
--mcp-configclaude --mcp-config ./mcp.jsonLoads MCP servers from JSON files or strings
--strict-mcp-configclaude --mcp-config ./mcp.json --strict-mcp-configUses only those MCP servers, ignoring the rest
--append-system-promptclaude --append-system-prompt "Answer in German."Adds to the default system prompt
--agentclaude --agent reviewerRuns the session as one of your agents
--plugin-dirclaude --plugin-dir ./my-pluginLoads a plugin for this session only

How do you work on several things at once?

Flag or commandExampleDoes
-w, --worktreeclaude -w login-pageCreates a git worktree for the session, so its changes stay apart
--bg, --backgroundclaude --bg "fix the flaky test"Starts the session in the background and prints its ID
claude agentsLists background sessions
claude attach <id>Opens a background session in this terminal

Which flags help when something is broken?

Flag or commandDoes
--safe-modeStarts with CLAUDE.md, skills, plugins, hooks, MCP servers and other customisations off; permissions and your login work normally
--bareMinimal mode: skips hooks, plugin sync, auto-memory and CLAUDE.md discovery
-d, --debugDebug output, optionally filtered: --debug=hooks,mcp
--debug-file <path>Writes the debug log to a file
claude doctorChecks the installation; /doctor inside a session can also fix issues

If Claude Code behaves strangely, claude --safe-mode is the quickest test: if the problem is gone, it is in your configuration, and you can turn things back on one at a time.

Where can you check this?

Can you see which flags a headless run needs?

Config Studio for Claude Code explains every file Claude Code reads and its headless runs, with the flags taken from Claude Code's own help, and writes the settings and the claude -p command for you. Nothing changes on your computer until you run its install script yourself.

The tool

Do it in your browser.

Claude Code

Config Studio for Claude Code

Every file Claude Code reads, explained: what each setting does, where it lives, which file wins, and an editor that writes it for you.

About the toolOpen tool
Keep reading

More from the blog.

Data · KPIsHow to calculate NPS (Net Promoter Score), with examplesNPS is the share of promoters (9 or 10) minus the share of detractors (0 to 6). The formula with a worked example, why passives still count, why NPS is not a percentage, how many answers you need before a change means anything, benchmarks, and DAX, SQL and Excel.4 min readDesign · MotionHow to make a toggle switch in CSS, the accessible wayA toggle switch is a button or checkbox with role="switch", styled as a track and a knob. Two versions to copy, a button with four lines of JavaScript and a checkbox with no JavaScript at all, with the springy slide, the focus ring, the reduced-motion rule and what screen readers need.3 min read

Every post