Claude Code CLI Reference: Commands, Flags, and Workflows

The top-level claude command has three major personalities. First, it can open an interactive coding session: claude, claude "explain this project", or claude --permission-mode plan. Second, it can run as a non-interactive command with -p/--print, which is what you want for scripts, CI checks, JSON output, and repeatable automation. Third, it can manage the environment around sessions: auth, update/install, background agents, MCP servers, plugins, diagnostics, project state, and remote control.

That separation prevents a common mistake: treating every flag as if it configures the same kind of run. --model, --effort, --permission-mode, --add-dir, and --mcp-config shape a session. --output-format, --json-schema, --max-turns, and --max-budget-usd matter most in print mode. claude agents, attach, logs, stop, respawn, and daemon manage background work. project purge deletes local Claude Code state for a project, so it belongs in cleanup, not normal task flow.

Interactive mode is optimized for human-in-the-loop coding. Run claude in payments-api, start with claude "fix PAY-217", or pass --permission-mode plan to force a read-and-plan pass before edits. You can adjust the session with flags such as --model, --effort, --advisor, --add-dir, --settings, --mcp-config, --plugin-dir, and --worktree. The output is a terminal experience: prompts, tool summaries, diffs, and approval flows.

Print mode, claude -p, is a different contract. It runs the agentic workflow, prints the answer, then exits. That makes it usable from shell scripts, pipes, and CI: cat logs.txt | claude -p "summarize likely root cause", claude -p --output-format json "inspect this diff", or claude -p --max-turns 3 --max-budget-usd 2.00 "triage failing tests". Print mode is also where structured output flags matter, because another program can consume the result.

Claude Code sessions persist locally, which is why --continue and --resume are real workflow tools rather than conveniences. claude -c continues the most recent conversation in the current directory. claude --resume <id-or-name> resumes a specific session or opens a picker. Add --fork-session when you want the old conversation copied into a new session ID so you can try a risky direction without overwriting the original conversation path.

Filesystem isolation is a separate question. A session fork copies conversation state; it does not create a separate checkout. Use --worktree when the task needs an isolated git worktree under .claude/worktrees/, such as testing a refactor while the main checkout stays untouched. Use --bg/--background, /background, claude agents, attach, logs, stop, respawn, and rm when the work should continue outside the foreground terminal. The important distinction is conversation state, file state, and process state: they are related, but not the same thing.

Permission flags decide which tool requests execute without a prompt, which are blocked, and which tools the model even sees. --allowedTools/--allowed-tools pre-approves matching calls. --disallowedTools/--disallowed-tools denies matching calls; a bare tool name can remove that tool from the context, while scoped patterns such as Bash(rm *) deny only matching inputs. --tools restricts built-in tools, and the docs are explicit that it does not affect MCP tools; use a deny rule such as mcp__* or strict MCP config when you need to remove those too.

Modes decide the fallback behavior. --permission-mode plan starts read-only planning. --permission-mode auto uses auto mode. --permission-mode bypassPermissions or --dangerously-skip-permissions removes prompts and should only be used inside a real sandbox. --allow-dangerously-skip-permissions adds bypass mode to the Shift+Tab cycle without starting there. For PAY-217, a reasonable first pass is plan mode plus deny rules for secrets: let Claude read code and propose a route, then approve edits after the plan is visible.

Claude Code can load extra capability at launch or manage it with subcommands. claude mcp configures MCP servers; claude mcp login <name> and logout <name> handle OAuth for configured servers from the command line. --mcp-config loads MCP server definitions from JSON files or strings, while --strict-mcp-config ignores every other MCP configuration and uses only what the current launch supplied. That strict mode is useful for reproducible automation because it avoids invisible tools from user or project settings.

Plugins are managed separately with claude plugin or claude plugins, and session-only plugin loading is available with --plugin-dir or --plugin-url. Settings can come from user, project, local, or explicit --settings; --setting-sources chooses which setting layers load. For a stable PAY-217 review script, prefer explicit settings, strict MCP config, and a narrow tool list. For daily interactive work, use project settings, plugins, and MCP servers so the session feels integrated with the repo.

The CLI also owns health and lifecycle operations. claude auth login, logout, and status handle account state; claude update and claude install [version|stable|latest] handle the binary. claude doctor prints read-only installation and settings diagnostics without starting a session. claude daemon status and daemon stop --any inspect or stop the background-session supervisor. claude logs <id> gives recent output from a background session; claude stop <id> or kill <id> stops one.

Cleanup needs more caution. claude project purge [path] can delete local Claude Code state for a project, including transcripts, task lists, debug logs, file-edit history, prompt history, and the project entry in ~/.claude.json. It has --dry-run, --interactive, --all, and --yes options. That means it is the right tool when you need to clear sensitive local state or reset a broken project record, but the wrong tool for ordinary context cleanup; use /clear, /compact, or a new session when you only want a fresh conversation.