CLI Overview

claude is the command that starts Claude Code. Alone, it opens a chat in your terminal. With -p, it answers once and exits. Scripts and CI jobs use it this way. Flags change one run. Subcommands do separate jobs, such as sign-in, plugins, and background sessions.

The claude program is on your PATH. Run it in a project folder. Run claude --help for the list. Each flag is its own switch. A flag is on when you pass it. Some flags have a --no- twin, such as --no-chrome. You can also set the same choice in a settings file or an environment variable. A subcommand runs only when you call it.

Example

claude                                   # chat
claude "explain this project"            # chat with a first prompt
claude -p "list the TODOs" > todos.txt   # one answer, then exit
git diff | claude -p "review this diff"  # pipe in text

Ways to Start

Source: the official CLI Reference and Run Claude Code Programmatically pages.

Command	Status	What it does
claude	Documented: An official docs page names this item.	Starts an interactive session.
claude "query"	Documented: An official docs page names this item.	Starts an interactive session with a first prompt.
claude -p "query"	Documented: An official docs page names this item.	Prints one answer and exits. It skips the trust dialog. Use it only in folders you trust.
cmd | claude -p "query"	Documented: An official docs page names this item.	Prints one answer for the text that you pipe in.
claude -c, claude -r "<session>"	Documented: An official docs page names this item.	Continues or resumes a session (see Sessions and Storage).
claude --bg "query"	Documented: An official docs page names this item.	Starts a background session. claude agents lists the sessions.
claude --bare	Documented: An official docs page names this item.	Starts with no hooks, plugins, MCP servers, auto memory, or CLAUDE.md discovery. It sets CLAUDE_CODE_SIMPLE=1.
claude --safe-mode	Documented: An official docs page names this item.	Starts with all customizations off to debug a broken setup. It sets CLAUDE_CODE_SAFE_MODE=1.
claude --restricted	Documented: An official docs page names this item.	Removes the tools that run code. It also ignores user, project, and local settings.
claude --cloud, --environment, --teleport	Documented: An official docs page names this item.	Work with cloud sessions.

warning

Print mode (-p) skips the trust dialog for the folder. Use it only in folders you trust. It also ignores settings files that fail validation, without any error.

Print Mode Flags

Print mode runs once and prints the result. These flags shape its input and output. Some of them work only together, for example --include-partial-messages needs --output-format stream-json.

Flag	Status	What it does
--output-format text|json|stream-json	Documented: An official docs page names this item.	json gives one result object. stream-json gives one JSON line for each event (see Stream JSON).
--input-format text|stream-json	Documented: An official docs page names this item.	stream-json reads JSON lines from stdin.
--include-partial-messages, --include-hook-events, --forward-subagent-text, --replay-user-messages	Documented: An official docs page names this item.	Add events to the stream, with stream-json only.
--json-schema <schema>	Documented: An official docs page names this item.	Checks the final answer against a JSON Schema.
--max-budget-usd <amount>	Documented: An official docs page names this item.	Stops at a spend limit.
--max-turns <n>	Documented: An official docs page names this item.	Stops after n agent turns. --help hides the flag.
--permission-prompts host|none	Documented: An official docs page names this item.	none denies everything that would ask.
--permission-prompt-tool <tool>	Documented: An official docs page names this item.	Lets an MCP tool answer permission prompts. --help hides the flag.
--no-session-persistence	Documented: An official docs page names this item.	Writes no transcript.
--init, --init-only, --maintenance	Documented: An official docs page names this item.	Run Setup hooks. --help hides the flags.

The result of --output-format json has a usage field. Its cache_creation part is split into ephemeral_1h_input_tokens and ephemeral_5m_input_tokens. Source: the official How Claude Code Uses Prompt Caching page.

How It Works

Claude Code reads your flags first. A flag then wins over the same choice in an environment variable or a settings file, There are a few exceptions. Environment Variables lists them.

Source: the program (claude --help, 2.1.312).

Related Pages

• All Flags lists every flag, including the hidden ones.
• Subcommands lists every claude <command>.
• Environment Variables holds the variables that match many flags.
• Permissions explains --permission-mode and the tool allow lists.
• Sessions and Storage explains -c and -r.
• The Agent Loop shows what runs after startup.