Claude Code CLI Documentation: Commands, Flags and Settings

The Claude Code CLI documentation boils down to one command, claude, plus a few dozen flags and subcommands. Type claude in a project folder and you get an interactive session. Add -p and you get one answer, printed to the terminal, with no session to manage. Almost everything else is a variation on those two.

Here is the short version:

• claude starts a session. claude -p "query" answers once and exits.
• claude -c continues your last conversation. claude -r resumes a specific one.
• claude update, claude doctor and claude auth handle maintenance and sign-in.
• Flags like --model, --permission-mode and --add-dir change one session without touching your settings files.
• Settings live in ~/.claude/settings.json (you) and .claude/settings.json (the project).

This post is a working reference for the terminal side. Commands you type inside a session, like /compact or /model, are covered in our Claude Code slash commands guide.

How to get Claude Code and run it in your terminal

Claude Code is Anthropic's agentic coding tool. It reads your codebase, edits files and runs commands. The same engine runs in the terminal, in IDE extensions, in a desktop app and in the browser, so Claude Code is not an IDE. It is a command-line agent that can plug into one.

Install and set up

The setup page lists the official install routes. The recommended one is the native installer:

# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

Homebrew (brew install --cask claude-code) and WinGet (winget install Anthropic.ClaudeCode) also work, but they don't auto-update. The docs list macOS 13.0+, Windows 10 1809+ or Ubuntu 20.04+, and 4 GB+ of RAM as the floor.

Open a new terminal window afterwards and check it:

claude --version
claude doctor

claude doctor prints read-only diagnostics about your install and settings files without starting a session. It is the first thing to run when something feels off.

How to access Claude Code the first time

You need a Claude subscription or an Anthropic Console account to use most surfaces. Plans change often, so check Anthropic's own pricing page rather than any blog. On first launch, claude walks you through sign-in in the browser. You can also sign in ahead of time with claude auth login.

Then cd into a project and run claude. That is the whole answer to "how can I talk to Claude Code": you type plain English at its prompt.

Claude Code CLI commands

The official CLI reference is the source of truth, and it grows with nearly every release. These are the commands most people actually use.

Starting and resuming sessions

You can also pipe content straight in, which is where -p earns its keep:

cat logs.txt | claude -p "explain these errors"

Name a session with -n "my-feature-work" and you can come back to it later with claude --resume my-feature-work. Run claude -r with no argument to get a picker instead.

Maintenance, sign-in and logout

How to log out of Claude Code: run claude auth logout from your shell, or type /logout inside a session. The authentication docs note that logging out also resets your first-launch setup, so the next claude walks you through sign-in again. That is the clean way to switch accounts.

For CI, claude setup-token generates a long-lived OAuth token and prints it once. It doesn't save it anywhere, so copy it into the CLAUDE_CODE_OAUTH_TOKEN variable of whatever runs your pipeline.

MCP, plugins and background sessions

• claude mcp manages Model Context Protocol servers. The everyday subcommands are claude mcp add, claude mcp list, claude mcp get and claude mcp remove. Our MCP server configuration guide covers scopes and the .mcp.json file.
• claude plugin installs and manages plugins.
• claude agents opens agent view to watch parallel background sessions. Start one with claude --bg "investigate the flaky test", then use claude attach, claude logs and claude stop with its ID.

Mistype a subcommand and Claude Code suggests the closest match instead of starting a session. claude udpate prints Did you mean claude update?.

Claude Code CLI flags worth knowing

The reference makes a point worth repeating: claude --help doesn't list every flag. If you can't find one there, check the docs before assuming it's gone. Flags apply to one run only and override your settings files for that run.

Model, permissions and working directories

--permission-mode accepts default, acceptEdits, plan, auto, dontAsk and bypassPermissions. The difference between --allowedTools and --tools trips people up: the first skips the prompt for a tool, the second removes tools from the menu entirely. The trade-offs behind each mode are in our Claude Code permissions guide.

--dangerously-skip-permissions is the same as --permission-mode bypassPermissions. The name is the warning.

Sessions and system prompt

• --continue / -c and --resume / -r load earlier conversations. Add --fork-session to branch off a new session ID instead of reusing the old one.
• --name / -n labels a session so you can resume it by name.
• --worktree / -w starts Claude in an isolated git worktree, handy for running two tasks on one repo.
• --append-system-prompt adds your own rules to the default prompt. --system-prompt replaces it entirely, which drops the built-in tool guidance, so the append form is the safer default.
• --settings loads a settings file or inline JSON for this session only.
• --verbose and --debug show what's happening under the hood when a run misbehaves.

Print-mode flags

These only matter with -p:

Claude Code settings files

Flags last one session. Settings persist. The settings documentation describes four files:

When the same key is set in several places, the order from highest to lowest is: managed settings, command line (--settings), project local, shared project, user. So a flag beats your personal file, but nothing beats what your organization enforces.

Two practical details:

• Installing Claude Code doesn't create any settings file. Claude Code writes ~/.claude/settings.json the first time you change certain options in /config, and .claude/settings.local.json the first time you answer "Yes, and don't ask again" on a permission prompt.
• ~/.claude.json is different. Claude Code writes it for itself to hold account details, MCP servers and per-project state. You don't need to edit it.

To see which managed source applies to you, run /status inside a session.

Headless mode: running Claude Code from scripts

"Headless" just means -p with no human at the keyboard. A typical CI-style call looks like this:

claude -p "Find and fix type errors in src/" \
  --output-format json \
  --permission-mode acceptEdits \
  --max-turns 5

The JSON output gives your script something to parse. --allowedTools decides which actions run without approval, and --max-turns keeps a stuck run from looping. Sign-in for unattended runs usually comes from CLAUDE_CODE_OAUTH_TOKEN or an API key rather than a browser login.

Exit codes, streaming JSON and CI patterns get their own walkthrough in our Claude Code headless mode guide.

How Claude Code works under the hood

Anthropic's explainer on how Claude Code works describes an agentic loop in three phases: gather context, take action, verify results. The model does the reasoning. Claude Code is the harness around it that supplies tools, such as file search, edits and shell commands, and manages what the model sees.

That framing explains the CLI's shape. Every flag above adjusts one part of the loop:

• --model and --effort change the reasoning
• --tools, --allowedTools and --permission-mode change which actions are allowed
• --add-dir, --append-system-prompt and --bare change what context gets loaded

Once you see it that way, the reference stops looking like a long list and starts looking like a set of dials.

Running Claude Code setups without the terminal

If you're comfortable in a shell, the CLI is the fastest way to work with Claude Code. If the install, sign-in and flag-tuning are where you keep stalling, Taku mirrors a working AI setup into a desktop workspace and runs it, so you can use a power user's configuration without rebuilding their environment first. Taku is in Beta, and the Mac app is available now.

FAQ

Where is the official Claude Code CLI documentation?

Anthropic publishes it at code.claude.com under the CLI reference page. It lists every command and flag, and it changes with nearly every release, so treat it as the source of truth over any third-party list.

What is the difference between Claude Code CLI commands and slash commands?

CLI commands and flags run from your shell before a session starts, like claude -p or claude --model opus. Slash commands run inside a session, like /compact or /logout.

How do I log out of Claude Code?

Run claude auth logout in your terminal, or type /logout inside a session. The next time you run claude, it takes you through sign-in again.

How do I run Claude Code in the terminal without an interactive session?

Use claude -p "your prompt". It prints the answer and exits. Add --output-format json if a script needs to parse the result.

Is Claude Code an IDE?

No. It's a command-line agent. It also has extensions for VS Code and JetBrains IDEs, a desktop app and a web version, all running the same agent.

How do I change Claude Code settings?

Use /config inside a session for common options, or edit ~/.claude/settings.json for personal defaults and .claude/settings.json for project-wide ones. For a single run, pass --settings or a specific flag.

How do I update Claude Code?

Run claude update. Native installs also update themselves in the background. Homebrew and WinGet installs don't, so use brew upgrade claude-code or winget upgrade Anthropic.ClaudeCode there.