Claude Code CLI 指令完整參考

這篇 Claude Code CLI 指令教學將帶你完整認識 Claude Code 的命令列介面（CLI）。無論你是在終端機中直接使用 claude 指令，還是透過管道（pipe）串接其他工具，掌握 CLI 的各種參數與子指令，能讓你的開發工作流程更加高效。本文涵蓋所有主要 CLI 指令、旗標（flags）、子指令，以及實用的使用範例。

claude 主指令與基本用法

claude 是 Claude Code 的核心指令，啟動後會進入互動式對話模式。你可以在這個模式中與 Claude 進行自然語言對話，讓它幫你閱讀程式碼、編輯檔案、執行指令等。以下是最基本的使用方式：

# 啟動互動式對話
claude

# 帶入初始提示啟動
claude "請幫我分析這個專案的架構"

# 非互動模式（print mode）：執行完畢後直接退出
claude -p "解釋這個函數的功能"

# 搭配管道處理內容
cat error.log | claude -p "分析這些錯誤日誌"

# 繼續上一次的對話
claude -c

# 恢復指定的對話（透過 ID 或名稱）
claude -r "auth-refactor" "完成這個 PR"

其中 -p（或 --print）模式特別適合用於自動化腳本和 CI/CD 流程，因為它不會進入互動介面，執行完畢後會直接輸出結果並退出。

CLI 旗標完整參考（CLI Flags）

Claude Code 提供了豐富的 CLI 旗標來自訂行為。以下按功能分類介紹最重要的旗標，注意 claude --help 不一定會列出所有旗標，因此以下列表比 --help 的輸出更為完整。

模型與效能相關

旗標	說明	範例
`--model`	設定使用的模型，可用別名（sonnet、opus）或完整名稱	`claude --model opus`
`--effort`	設定模型的努力程度：low、medium、high、max（僅 Opus 4.6）	`claude --effort high`
`--fallback-model`	當預設模型過載時自動切換（僅 print 模式）	`claude -p --fallback-model sonnet "query"`
`--max-turns`	限制代理回合數（僅 print 模式）	`claude -p --max-turns 3 "query"`
`--max-budget-usd`	設定 API 花費上限（僅 print 模式）	`claude -p --max-budget-usd 5.00 "query"`

對話管理

旗標	說明	範例
`--continue` / `-c`	繼續當前目錄中最近的對話	`claude -c`
`--resume` / `-r`	恢復指定的對話（ID 或名稱）	`claude -r auth-refactor`
`--name` / `-n`	為對話設定名稱，方便之後恢復	`claude -n "my-feature"`
`--fork-session`	恢復對話時建立新的分支（搭配 -r 或 -c）	`claude -r abc123 --fork-session`
`--session-id`	使用指定的 UUID 作為對話 ID	`claude --session-id "550e..."`
`--no-session-persistence`	停用對話持久化，不儲存到磁碟（僅 print 模式）	`claude -p --no-session-persistence "query"`

輸出與格式

旗標	說明	範例
`--print` / `-p`	非互動模式，輸出回應後退出	`claude -p "query"`
`--output-format`	指定輸出格式：text、json、stream-json	`claude -p --output-format json "query"`
`--input-format`	指定輸入格式：text、stream-json	`claude -p --input-format stream-json`
`--json-schema`	取得符合 JSON Schema 的結構化輸出（僅 print 模式）	`claude -p --json-schema '{...}' "query"`
`--verbose`	啟用詳細日誌，顯示完整的逐回合輸出	`claude --verbose`

權限與安全

旗標	說明	範例
`--permission-mode`	設定權限模式：default、acceptEdits、plan、auto、dontAsk、bypassPermissions	`claude --permission-mode plan`
`--allowedTools`	設定不需要確認就能執行的工具	`claude --allowedTools "Bash(git log *)" "Read"`
`--disallowedTools`	禁止使用的工具（從模型上下文移除）	`claude --disallowedTools "Edit"`
`--tools`	限制可用的內建工具	`claude --tools "Bash,Edit,Read"`
`--dangerously-skip-permissions`	跳過所有權限提示（等同 bypassPermissions 模式）	`claude --dangerously-skip-permissions`
`--enable-auto-mode`	在 Shift+Tab 循環中啟用 auto 模式	`claude --enable-auto-mode`

系統提示詞（System Prompt）

Claude Code 提供四個旗標來自訂系統提示詞，在互動與非互動模式中都能使用：

旗標	說明	範例
`--system-prompt`	完全取代預設的系統提示詞	`claude --system-prompt "你是 Python 專家"`
`--system-prompt-file`	從檔案載入系統提示詞（取代預設）	`claude --system-prompt-file ./prompt.txt`
`--append-system-prompt`	在預設提示詞後附加自訂文字	`claude --append-system-prompt "使用 TypeScript"`
`--append-system-prompt-file`	從檔案載入並附加到預設提示詞後	`claude --append-system-prompt-file ./rules.txt`

大多數情況下，建議使用 --append-system-prompt 來保留 Claude Code 的內建能力，同時加入你的需求。只有在需要完全控制系統提示詞時，才使用 --system-prompt。

工作目錄與環境

旗標	說明	範例
`--add-dir`	新增額外的工作目錄讓 Claude 讀寫檔案	`claude --add-dir ../apps ../lib`
`--worktree` / `-w`	在獨立的 git worktree 中啟動 Claude	`claude -w feature-auth`
`--bare`	精簡模式：跳過自動載入 hooks、skills、plugins、MCP、CLAUDE.md	`claude --bare -p "query"`
`--chrome`	啟用 Chrome 瀏覽器整合	`claude --chrome`
`--no-chrome`	停用 Chrome 瀏覽器整合	`claude --no-chrome`
`--ide`	啟動時自動連接到 IDE	`claude --ide`

MCP 與外掛

旗標	說明	範例
`--mcp-config`	從 JSON 檔案載入 MCP Server 設定	`claude --mcp-config ./mcp.json`
`--strict-mcp-config`	僅使用 –mcp-config 指定的 MCP Server	`claude --strict-mcp-config --mcp-config ./mcp.json`
`--plugin-dir`	載入指定目錄的外掛	`claude --plugin-dir ./my-plugins`
`--disable-slash-commands`	停用所有 skills 與 commands	`claude --disable-slash-commands`

遠端與協作

旗標	說明	範例
`--remote`	在 claude.ai 上建立新的遠端工作階段	`claude --remote "修復登入問題"`
`--remote-control` / `--rc`	啟動互動式對話並啟用遠端控制	`claude --rc "My Project"`
`--teleport`	將網頁版的工作階段拉到本機終端機	`claude --teleport`
`--from-pr`	恢復與特定 GitHub PR 關聯的工作階段	`claude --from-pr 123`

子指令完整參考（Subcommands）

除了主要的 claude 指令外，Claude Code 還提供多個子指令來管理不同功能。以下逐一介紹：

claude auth：帳號驗證管理

claude auth 用於管理你的 Anthropic 帳號登入狀態：

# 登入帳號
claude auth login

# 使用 SSO 登入
claude auth login --sso

# 使用 Anthropic Console（API 計費）登入
claude auth login --console

# 登出帳號
claude auth logout

# 檢查登入狀態（輸出 JSON 格式）
claude auth status

# 以人類可讀格式顯示狀態
claude auth status --text

claude mcp：MCP Server 管理

claude mcp 用於設定和管理 Model Context Protocol（MCP）Server，讓 Claude 能夠連接外部工具和資料來源：

# 新增 MCP Server（使用 stdio transport）
claude mcp add my-server -- node /path/to/server.js

# 新增 MCP Server（使用 HTTP transport）
claude mcp add my-api --transport http --url https://api.example.com/mcp

# 移除 MCP Server
claude mcp remove my-server

# 列出所有已設定的 MCP Server
claude mcp list

# 將 Claude Code 自己作為 MCP Server 啟動
claude mcp serve

MCP Server 的設定會儲存在 .mcp.json（專案層級）或 ~/.claude/（使用者層級）中，可以與團隊共享或個人使用。

claude update：更新 Claude Code

如果你使用原生安裝方式（推薦），Claude Code 會自動在背景更新。但你也可以手動觸發更新：

# 更新到最新版本
claude update

# 查看當前版本
claude --version

若是透過 Homebrew 或 WinGet 安裝的使用者，需要使用對應的套件管理器來更新：brew upgrade claude-code 或 winget upgrade Anthropic.ClaudeCode。

claude plugin：外掛管理

claude plugin（也可以用 claude plugins）用於管理 Claude Code 的外掛系統：

# 安裝外掛
claude plugin install code-review@claude-plugins-official

# 列出已安裝的外掛
claude plugin list

# 移除外掛
claude plugin remove code-review

claude agents：代理人管理

claude agents 可以列出所有已設定的子代理人（Subagents），方便你了解當前專案可用的代理人配置：

# 列出所有代理人（按來源分組）
claude agents

claude auto-mode：自動模式設定

claude auto-mode 用於查看和管理自動模式的分類器規則：

# 列印內建的自動模式分類器規則（JSON 格式）
claude auto-mode defaults

# 匯出為檔案
claude auto-mode defaults > rules.json

# 查看套用設定後的有效設定
claude auto-mode config

claude remote-control：遠端控制

claude remote-control 啟動遠端控制伺服器，讓你可以從 claude.ai 或 Claude App 控制本機的 Claude Code：

# 啟動遠端控制伺服器
claude remote-control

# 指定名稱
claude remote-control --name "My Project"

實用的 CLI 組合技巧

Claude Code 遵循 Unix 哲學，可以與其他工具無縫串接。以下是一些實用的組合範例：

搭配管道處理

# 分析最近的日誌輸出
tail -200 app.log | claude -p "分析這些日誌中的異常"

# 自動化翻譯工作
claude -p "將新的字串翻譯成法文並建立 PR"

# 批次檢查變更的檔案
git diff main --name-only | claude -p "檢查這些變更的檔案是否有安全問題"

# 分析 Git 提交紀錄
git log --oneline -20 | claude -p "總結最近的開發進展"

自動化腳本範例

# 取得 JSON 格式的分析結果
claude -p --output-format json "列出專案中所有 TODO 項目"

# 設定花費上限的自動化任務
claude -p --max-budget-usd 2.00 "重構 auth 模組"

# 在獨立的 worktree 中執行任務
claude -w feature-branch "實作新的使用者註冊功能"

# 使用精簡模式加速腳本執行
claude --bare -p "快速修正語法錯誤"

CI/CD 整合範例

# GitHub Actions 中的自動 Code Review
claude -p --output-format json \
  --max-turns 5 \
  --max-budget-usd 1.00 \
  "檢查最新的 PR 變更是否有潛在問題"

# 限制回合數的自動化修復
claude -p --max-turns 3 "修復 lint 錯誤並提交"

進階旗標速查表

以下整理了一些較進階但實用的旗標，供你快速查閱：

旗標	說明
`--agent`	為當前工作階段指定代理人
`--agents`	透過 JSON 動態定義自訂子代理人
`--betas`	在 API 請求中加入 Beta 標頭（僅 API Key 使用者）
`--channels`	設定要監聽通知的 MCP Server（Research Preview）
`--debug`	啟用除錯模式，可選擇性過濾類別（如 “api,hooks”）
`--debug-file`	將除錯日誌寫入指定檔案
`--init`	執行初始化 hooks 並啟動互動模式
`--init-only`	僅執行初始化 hooks 後退出
`--maintenance`	執行維護 hooks 並啟動互動模式
`--setting-sources`	指定要載入的設定來源（user、project、local）
`--settings`	從 JSON 檔案載入額外設定
`--teammate-mode`	設定 Agent Team 顯示模式：auto、in-process、tmux
`--tmux`	為 worktree 建立 tmux 工作階段（需搭配 –worktree）
`--version` / `-v`	顯示目前版本號

常見問題與注意事項

–help 沒有列出的旗標

Claude Code 的 --help 輸出不一定包含所有可用的旗標。部分旗標是進階功能或實驗性功能，雖然沒有在 help 中列出，但仍然可以正常使用。建議參考官方文件取得最完整的資訊。

Print 模式 vs 互動模式

許多旗標（如 --max-turns、--max-budget-usd、--json-schema、--no-session-persistence）僅在 Print 模式（-p）下可用。這是因為這些功能主要設計用於自動化場景。如果你在互動模式下使用這些旗標，可能不會生效。

System Prompt 旗標的互斥性

--system-prompt 和 --system-prompt-file 是互斥的，不能同時使用。但 --append-system-prompt 和 --append-system-prompt-file 可以與任一取代旗標搭配使用。

總結

Claude Code 的 CLI 提供了極為豐富的功能，從基本的互動對話到進階的自動化腳本都能勝任。掌握這些指令和旗標，你可以在日常開發中更靈活地運用 Claude Code：用 -p 進行快速查詢、用 --model 切換模型、用 --worktree 在獨立環境中工作，或用各種子指令管理 MCP Server 和外掛。

如果你還沒安裝 Claude Code，建議從安裝教學開始。若想學習更多操作技巧，可以參考下方的延伸閱讀。

延伸閱讀

ㄚ槌