Claude Code CLI Commands Guide

Claude Code is a command-line tool, and knowing its flags is the difference between typing the same options every session and running it exactly right every time. This guide covers every CLI flag, what it does, and when to reach for it.

If you want to build strong foundations alongside the CLI reference, the Claude Code course covers the prompting workflow and project setup that make these flags most effective.

The basic invocation is claude [options] [prompt]. You can start an interactive session, pass a one-shot prompt, or run Claude Code non-interactively in a pipeline. Three modes to know:

• Interactive session, run claude with no arguments. Claude Code reads your CLAUDE.md and waits for input
• One-shot prompt, pass a prompt as an argument. Claude Code runs it and exits
• Headless / CI, use --headless for non-interactive pipeline execution

How to Start Claude Code

When you run claude with no arguments, it opens an interactive session in your current directory. Claude Code reads your CLAUDE.md file (if one exists), indexes your project, and waits for input.

When you pass a prompt as an argument, Claude Code runs that prompt and exits. This is useful for scripting and CI/CD pipelines where you want a specific action without an interactive session.

# Interactive session
claude

# One-shot prompt
claude "Review the changes in my last commit and flag any issues"

Interactive mode is for development work. One-shot mode is for automation. Knowing which to use keeps your workflows clean.

All CLI Flags

The table below covers every major flag available in Claude Code. Flags can be combined. The most common combinations are shown in the examples section.

Flag Reference

—plan / -p

Plan mode shows you what Claude Code intends to do before it does anything. No files are written, no commands are run. You see the proposed changes as a list, then decide whether to approve.

claude --plan "Refactor the authentication module to use async/await"

Use this flag whenever you are about to make a change to a file you have not recently reviewed, or whenever the task involves more than two files.

The cost of reviewing a plan is seconds. The cost of reviewing an unexpected change is much higher.

—model

Claude Code defaults to a model set in your configuration. You can override it per-session with --model.

claude --model claude-opus-4-8 "Architect the new payment processing module"
claude --model claude-sonnet-4-6 "Fix the typo in the README"

• claude-opus-4-8, use for complex architectural work, refactoring decisions, and tasks where accuracy matters more than speed
• claude-sonnet-4-6, use for routine tasks, quick fixes, and high-volume automation

—continue / -c

This flag resumes the most recent Claude Code session, including its context and history.

It does not reload CLAUDE.md from scratch. It picks up where the last session ended.

claude --continue

Do this: Use --continue when you stepped away and want to pick up a task mid-stream. Avoid this: Do not use it when you want a clean slate, use /clear inside a session or start a fresh claude session instead.

—headless

Headless mode disables all interactive prompts. Claude Code will not ask for confirmations. It will execute and exit.

This flag is required for use in CI/CD pipelines and automated scripts.

claude --headless "Run the linter and fix all auto-fixable issues"

Always pair --headless with --allowedTools to restrict what Claude Code can do. In non-interactive mode, there is no human in the loop to catch unexpected behavior.

—output-format

Controls how Claude Code formats its output. The three options are:

claude --headless --output-format json "List all TODO comments in the codebase"

Use json or stream-json when Claude Code’s output feeds into another tool, a dashboard, or a log aggregator.

—max-turns

This flag limits how many agentic turns Claude Code can take before stopping.

A turn is one round of Claude Code calling tools, getting results, and deciding what to do next.

claude --max-turns 5 "Investigate why the build is failing"

• Low --max-turns (3–5), use for exploratory tasks where you want Claude Code to report back rather than go deep
• High or omitted, use for complex multi-step tasks that require many sequential actions

—allowedTools

Whitelists the tools Claude Code is permitted to use. Any tool not in the list is unavailable for that session.

Tool names are the internal names Claude Code uses.

claude --allowedTools "Read,Grep,Glob" "Find all files that import from the legacy auth module"

This is the single most important security flag for CI/CD use:

• Read-only analysis: restrict to Read, Grep, Glob
• File modification tasks: add Edit and Write
• Command execution tasks: add Bash only when explicitly needed

—disallowedTools

The inverse of --allowedTools. Everything is available except the listed tools.

claude --disallowedTools "Bash" "Refactor the utils module"

• Use --disallowedTools when you want to allow most capabilities but block one specific tool
• Use --allowedTools when you want to permit only a small, explicit set

—add-dir

Adds a directory outside your current working directory to Claude Code’s context.

Claude Code can then read and modify files in that directory.

claude --add-dir ../shared-utils "Update the API client to use the new shared auth helper"

Use this flag in monorepo setups where your project depends on code in a sibling directory.

Without it, Claude Code cannot see files outside the directory where you started it.

—no-update-settings

Prevents Claude Code from writing to any settings files during the session.

This is useful in shared environments or CI/CD where you do not want automated processes modifying configuration.

claude --headless --no-update-settings "Generate a test coverage report"

Practical Command Examples

CI/CD: Read-only code review

Run Claude Code in a CI pipeline to review a pull request without modifying anything:

claude \
  --headless \
  --output-format json \
  --allowedTools "Read,Grep,Glob" \
  --max-turns 10 \
  "Review the diff in this PR for security issues, hardcoded credentials, and missing error handling. Output findings as JSON."

Local: Plan before a large refactor

Before touching a module with complex dependencies:

claude --plan --model claude-opus-4-8 \
  "Refactor the database connection layer to use a connection pool. Update all files that call db.connect() directly."

Scripted: Fix lint errors across a repo

Run Claude Code as a post-commit hook to auto-fix lint errors:

claude \
  --headless \
  --allowedTools "Read,Edit,Bash" \
  --max-turns 8 \
  "Run eslint --fix on all staged files"

Analysis: Find all usages of a deprecated function

claude \
  --headless \
  --output-format json \
  --allowedTools "Read,Grep,Glob" \
  "Find every file that calls legacyFetch() and list the file path and line number for each call"

Combining Flags Effectively

A few combinations that come up often in real workflows:

• Safe exploration: --plan --allowedTools "Read,Grep,Glob", lets Claude Code research a codebase and propose a plan without touching anything
• Automated fix pipeline: --headless --allowedTools "Read,Edit,Bash" --max-turns 10 --output-format json, the standard CI/CD combination for tasks that need to modify files and report results
• High-accuracy one-shot: --model claude-opus-4-8 --plan, for architectural decisions where you want the most capable model and a review step before execution

Start with fewer permissions and add more as needed. It is much easier to expand what Claude Code can do than to undo what it did.

Take Claude Code Further with Phos

Phos is a CCA-F certified Claude partner with 400+ AI engagements across engineering teams.

If you are building Claude Code into your development workflows or CI/CD pipelines and want expert guidance on configuration, security, and scaling, we can help.

Talk to the Phos team to learn how we help teams use Claude Code safely at scale.

FAQ

Can I set default flags so I do not have to type them every session?

Yes. Claude Code reads a settings file where you can set default model, allowed tools, and other preferences.

You can also create shell aliases, for example, alias cc='claude --model claude-sonnet-4-6 --plan' in your ~/.bashrc or ~/.zshrc.

Does --headless work without a CLAUDE.md file?

Yes, but the output quality will be lower. Without CLAUDE.md, Claude Code has no context about your project conventions, stack, or constraints.

In CI/CD, store your CLAUDE.md in the repository so every headless run has full project context.

What happens if I set —max-turns too low?

Claude Code stops after reaching the turn limit and reports what it accomplished. It does not partially complete a file edit. It finishes the current action before stopping.

If the task is not complete, run Claude Code again with --continue to pick up where it left off.

Is —allowedTools case-sensitive?

Yes. Tool names are case-sensitive. Use Read, Edit, Grep, Glob, Bash, and Write exactly as shown.

An incorrectly cased tool name will result in Claude Code not recognizing it, effectively blocking that tool even if you intended to allow it.