操作指南 / 2.1.220

Claude Code CLI 完整使用指南

一條實務路徑：選擇執行模式、保存上下文、限制權限、連接工具，最後驗證實際載入的功能。

開啟完整參考資料 →
00

學習路線

01

選擇執行模式

互動模式適合協作；print mode 適合有邊界的自動化；background mode 適合持續執行的工作。

02

保存 session 連續性

接續此專案最近 session、依 ID 或名稱恢復，並在不遺失 transcript 的情況下 attach 背景工作。

03

設定權限邊界

Permission mode、allowed tools、sandbox settings 與 safe mode 共同決定 agent 能做什麼。

04

有意識地連接 MCP

先選設定 scope、檢查 approval 與 health，再獨立完成遠端 server 的認證。

05

組合 plugins、skills 與 hooks

Plugin 負責分發元件；skill 教工作流程；hook 觀察或限制生命週期事件。

06

維運 agents 並辨識差異

監控背景 sessions、讀取 logs，且在推測行為前使用 doctor 與來源帳本。

01

CHAPTER / 01

執行模式

同一個 executable 支援三種不同操作方式。輸出格式、持久化與權限行為不同，因此應明確選擇。
Manifest 命令
claude runtime-confirmed

Start Claude Code interactively, run a headless prompt, or manage a session.

claude
相關旗標
-p, --print

Print a non-interactive response and exit.

none
--background, --bg

Control Claude Code background behavior.

none
--output-format

Select print-mode output: text, json, or stream-json.

none
Manifest 操作手冊

Run Claude Code headlessly

Use print mode with bounded turns, structured output, and explicit permissions for scripts and CI.

  1. 步驟 01 Start with a bounded text run claude -p --max-turns 8 "Review the current diff"

    Print mode writes the final response and exits.

  2. 步驟 02 Request machine-readable output claude -p --output-format json --json-schema '{"type":"object"}' "Summarize the diff"

    JSON output and a schema make downstream parsing explicit.

  3. 步驟 03 Grant only required tools claude -p --allowed-tools "Read" "Grep" "Bash(git diff *)" "Review this change"

    Narrow permission rules keep automation bounded.

02

CHAPTER / 02

Session 連續性

Session 狀態是重要資產。替關鍵工作命名、明確 resume，並分清 attach、restart 與刪除。
Manifest 命令
claude runtime-confirmed

Start Claude Code interactively, run a headless prompt, or manage a session.

claude
claude attach runtime-confirmed

Attach this terminal to a background session.

claude logs runtime-confirmed

Print recent terminal output for a background session.

相關旗標
-c, --continue

Continue the most recent conversation in the current directory.

none
-r, --resume

Resume a session by ID or name, or open the session picker.

none
-n, --name

Name the session.

none
Manifest 操作手冊

Continue or resume a session

Continue the latest conversation, resume a named session, or attach to a background session.

  1. 步驟 01 Continue the latest project session claude --continue

    Loads the most recent conversation associated with this directory.

  2. 步驟 02 Resume a named session claude --resume auth-refactor

    Resumes by session ID or user-assigned name.

  3. 步驟 03 Attach to a background session claude attach 7c5dcf5d

    Connects the current terminal while the session keeps running.

03

CHAPTER / 03

權限與安全操作

從能完成任務的最小權限開始。繞過權限的旗標是例外的高風險邊界，不是便利的預設。
Manifest 命令
claude runtime-confirmed

Start Claude Code interactively, run a headless prompt, or manage a session.

claude
相關旗標
--permission-mode

Start in a selected permission mode.

review
--allowed-tools, --allowedTools

Grant matching tools without a permission prompt.

review
--safe-mode

Control Claude Code safe mode behavior.

none
--dangerously-skip-permissions

Control Claude Code dangerously skip permissions behavior.

high
Manifest 操作手冊

Design permission boundaries

Choose a permission mode, add narrow allow rules, and keep bypass mode visibly high risk.

  1. 步驟 01 Start in plan mode claude --permission-mode plan

    Plan mode supports repository analysis before edits.

  2. 步驟 02 Allow specific read-only commands claude --allowed-tools "Read" "Grep" "Bash(git diff *)"

    Tool-pattern rules are safer than broad shell access.

  3. 步驟 03 Troubleshoot customizations safely claude --safe-mode

    Safe mode disables project customizations, hooks, plugins, skills, and MCP.

04

CHAPTER / 04

MCP：連接終端機之外的工具

MCP server 可加入 tools、resources 與 prompts。設定 scope、專案核准與 OAuth 認證是三件不同的事。
Manifest 命令
claude mcp add runtime-confirmed

Add a stdio, SSE, or HTTP MCP server.

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
claude mcp get runtime-confirmed

Inspect one configured MCP server and its approval state.

claude mcp get sentry
claude mcp login runtime-confirmed

Run the OAuth flow for a configured remote MCP server.

claude mcp login sentry --no-browser
claude mcp serve runtime-confirmed

Expose Claude Code tools as a local stdio MCP server.

claude mcp serve
Manifest 操作手冊

Add and authenticate an MCP server

Register a server at the intended scope, inspect it, and run OAuth separately when required.

  1. 步驟 01 Add a remote server claude mcp add --transport http sentry https://mcp.sentry.dev/mcp --scope user

    Choose local, user, or project scope deliberately.

  2. 步驟 02 Inspect approval and health claude mcp get sentry

    Unapproved project servers remain pending and are not connected.

  3. 步驟 03 Authenticate over SSH claude mcp login sentry --no-browser

    Prints an authorization URL rather than opening a browser.

05

CHAPTER / 05

Plugins、skills 與 hooks

Plugin 可封裝 skills、commands、agents、hooks 與 MCP 設定；安裝後仍要確認實際載入的元件。
Manifest 命令
claude plugin marketplace add runtime-confirmed

Register a plugin marketplace source.

claude plugin marketplace add anthropics/claude-plugins-official
claude plugin install runtime-confirmed

Install a plugin from a configured marketplace.

claude plugin install code-review@claude-plugins-official
claude plugin details runtime-confirmed

Show a plugin component inventory and projected token cost.

claude plugin details code-review
claude plugin validate runtime-confirmed

Validate plugin structure and metadata.

claude plugin validate ./my-plugin --strict
相關旗標
--plugin-dir

Load plugins from directories for this session.

review
Manifest 操作手冊

Install plugins and inspect skills and hooks

Add a trusted marketplace, install at a scope, then inspect the loaded skills and hooks in-session.

  1. 步驟 01 Add a marketplace claude plugin marketplace add anthropics/claude-plugins-official

    Marketplace sources determine which plugins are installable.

  2. 步驟 02 Install at project scope claude plugin install code-review@claude-plugins-official --scope project

    Project scope shares plugin policy with the repository.

  3. 步驟 03 Inspect runtime components

    Use /skills, /hooks, and /plugin inside Claude Code to verify what loaded.

06

CHAPTER / 06

Agents 與背景工作

背景 session 可持續執行，而 agent view 與 logs 形成可觀測、可操作的控制面。
Manifest 命令
claude agents runtime-confirmed

Open agent view or query active background sessions.

claude agents --json
claude logs runtime-confirmed

Print recent terminal output for a background session.

claude stop runtime-confirmed

Stop a background session while retaining its conversation.

claude respawn runtime-confirmed

Restart a background session with its conversation intact.

相關旗標
--agent

Use a named agent for this session.

review
--agents

Define session subagents with a JSON object.

review
--background, --bg

Control Claude Code background behavior.

none
Manifest 操作手冊

Launch and monitor agents

Define a session agent, start work in the background, and inspect active sessions as JSON.

  1. 步驟 01 Start a named agent in the background claude --background --agent reviewer "Review the current branch"

    The command returns a session ID for later management.

  2. 步驟 02 List active agents claude agents --json

    JSON mode supports external monitoring and orchestration.

  3. 步驟 03 Read recent output claude logs 7c5dcf5d

    Inspect progress without attaching to the session.

07

CHAPTER / 07

Headless 自動化

Print mode 為 scripts 設計。限制 turns 與成本、選定輸出格式，並只授予工作所需工具。
Manifest 命令
claude runtime-confirmed

Start Claude Code interactively, run a headless prompt, or manage a session.

claude
相關旗標
-p, --print

Print a non-interactive response and exit.

none
--max-turns

Limit agentic turns in print mode.

none
--max-budget-usd

Stop print-mode execution at an approximate dollar budget.

none
--json-schema

Validate print-mode structured output against a JSON Schema.

none
--input-format

Select print-mode input: text or stream-json.

none
--output-format

Select print-mode output: text, json, or stream-json.

none
Manifest 操作手冊

Run Claude Code headlessly

Use print mode with bounded turns, structured output, and explicit permissions for scripts and CI.

  1. 步驟 01 Start with a bounded text run claude -p --max-turns 8 "Review the current diff"

    Print mode writes the final response and exits.

  2. 步驟 02 Request machine-readable output claude -p --output-format json --json-schema '{"type":"object"}' "Summarize the diff"

    JSON output and a schema make downstream parsing explicit.

  3. 步驟 03 Grant only required tools claude -p --allowed-tools "Read" "Grep" "Bash(git diff *)" "Review this change"

    Narrow permission rules keep automation bounded.

08

CHAPTER / 08

看懂證據標記

Root help 沒列出不代表旗標不存在；官方文件有寫，也不代表所有平台或方案都能使用。
runtime-confirmed 已安裝版本
docs-confirmed 官方文件
conditional 條件式
source-preview 公開資產預覽
historical 僅歷史資料
操作原則
  1. 優先使用明確 scope，不依賴環境中隱含的設定。
  2. 把 transcripts、settings 與 credentials 視為不同狀態領域。
  3. 在無人值守執行前，驗證實際載入的 tools 與 permissions。
  4. 當 runtime help 與文件有差異時，依來源與 availability 標記判讀。
來源 01 Claude Code 2.1.220 recursive local help runtime-help / release 來源 02 Official Claude Code CLI reference official-docs / reference 來源 03 Official Claude Code commands reference official-docs / reference 來源 04 Official Claude Code settings reference official-docs / reference 來源 05 Published Claude Code settings JSON Schema json-schema / reference 來源 06 Official Claude Code environment variables reference official-docs / reference 來源 07 Public Claude Code v2.1.220 plugin assets official-source / preview 來源 08 @anthropic-ai/claude-code 2.1.220 package metadata package-metadata / reference