Claude Code CLI 教學:常用指令與旗標完整參考(Windows 實測)

Claude Code 的 CLI 是功能最完整的使用方式:所有斜線指令、管道輸入、腳本自動化都從這裡來。這篇 Claude Code CLI 教學把常用指令和旗標整理成一份參考,並以 Windows PowerShell 實際執行的畫面說明。

本文內容對照 2026 年 11 月的官方 CLI reference,實測版本為 Claude Code v2.1.322。指令與旗標增加得很快,完整清單請以官方文件為準。

還沒安裝的話,在 PowerShell 執行這一行:

Plaintext
irm https://claude.ai/install.ps1 | iex

如果你主要在 VS Code 裡工作,可以先看 Claude Code VS Code 教學。

Claude Code CLI 基本用法

指令作用
claude啟動互動式工作階段
claude "問題"啟動並直接送出第一句提示
claude -p "問題"回答完就結束,不進互動模式
cat 檔案 | claude -p "問題"把檔案內容用管道送進去
claude -c接續目前資料夾最近的一次對話
claude -r開啟選單,挑一個過去的對話接續
claude -r "名稱" "問題"依名稱或 ID 接續指定對話

啟動與檢查

在專案資料夾裡輸入 claude 就會進入互動模式。第一次在某個資料夾執行時,會先問你是否信任這個資料夾。

Claude Code CLI 啟動後的主畫面
Claude Code CLI 啟動後的主畫面(這張是在 VS Code 的整合終端機裡執行)

遇到問題時先跑這兩個:

Bash
claude --version
claude doctor

claude doctor 會列出安裝狀態與設定檔的錯誤,不會啟動工作階段,也不會改動任何東西。

在 PowerShell 執行 claude --version 與 claude doctor 的輸出
claude doctor 會顯示安裝方式、版本、自動更新狀態,最後告訴你有沒有發現問題

一次性問答:-p

加上 -p(--print)會直接輸出答案然後結束,適合快速提問或寫進腳本:

Bash
claude -p "用一句話說明 report.py 在做什麼"
claude -p 一次性問答:輸出答案後直接結束
加上 -p,回答完就回到命令提示字元

管道輸入

把其他指令的輸出接給 Claude:

Bash
cat report.py | claude -p "用三點以內列出這段程式可能的問題"
git diff main --name-only | claude -p "檢查這些檔案有沒有安全問題"

在 PowerShell 裡 cat 是 Get-Content 的別名,可以直接用。網路上常見的 tail -200 app.log 是 Linux 寫法,PowerShell 要改成:

PowerShell
Get-Content app.log -Tail 200 | claude -p "分析這些日誌裡的異常"
用管道把 report.py 的內容交給 claude -p 分析
把 report.py 的內容用管道送給 Claude 分析

接續對話

  • claude -c:直接回到這個資料夾最近的一次對話。
  • claude -r:開啟可搜尋的選單。在 VS Code 擴充套件裡開的對話也會出現在這裡。
  • claude -n "名稱":啟動時幫對話取名,之後用 claude -r "名稱" 找回來。
claude --resume 的對話選單,可搜尋並接續過去的對話
claude –resume 的對話選單,預設只列出目前資料夾的對話,按 Ctrl+A 可以看所有專案

常用旗標

旗標可以組合使用,例如 claude --model sonnet --permission-mode plan。要注意 claude --help 不會列出所有旗標,沒列出來不代表不能用。

以 claude --model sonnet --permission-mode plan 啟動後的畫面
指定 Sonnet 並以 plan 模式啟動,畫面上方顯示模型,左下角顯示 plan mode on

模型與效能

旗標說明範例
--model指定模型,可用別名(sonnet、opus、haiku、fable)或完整名稱claude --model sonnet
--effort推理強度:low、medium、high、xhigh、max、ultracode,可用等級依模型而定claude --effort high
--fallback-model主要模型過載或無法使用時自動改用的模型,可用逗號列出多個claude --fallback-model sonnet
--autocompact設定這次工作階段的自動壓縮門檻(需 v2.1.221 以上)claude --autocompact 500k
--max-turns限制執行回合數,只在 -p 模式有效claude -p --max-turns 3 "..."
--max-budget-usd預估花費到達上限就停止,只在 -p 模式有效;實際花費可能略超過claude -p --max-budget-usd 2 "..."

對話管理

旗標說明範例
--continue、-c接續目前資料夾最近的對話claude -c
--resume、-r依 ID 或名稱接續,不帶參數則開啟選單claude -r "auth-refactor"
--name、-n幫對話取名claude -n "my-feature"
--fork-session接續時另開新的 session,不動到原本的claude -r abc123 --fork-session
--session-id指定 session ID(必須是 UUID)
--no-session-persistence不儲存對話,只在 -p 模式有效claude -p --no-session-persistence "..."

輸出與格式

旗標說明範例
--print、-p輸出答案後結束claude -p "..."
--output-format-p 模式的輸出格式:text、json、stream-jsonclaude -p "..." --output-format json
--input-format-p 模式的輸入格式:text、stream-json
--json-schema要求輸出符合指定的 JSON Schema,只在 -p 模式有效
--verbose顯示完整的逐回合輸出claude --verbose

權限與安全

旗標說明範例
--permission-mode啟動時的權限模式:default(別名 manual)、acceptEdits、plan、auto、dontAsk、bypassPermissionsclaude --permission-mode plan
--allowedTools這些工具執行時不再詢問claude --allowedTools "Read"
--disallowedTools拒絕規則;只寫工具名稱會把該工具整個移除claude --disallowedTools "Bash(rm *)"
--tools限制可用的內建工具claude --tools "Bash,Edit,Read"
--dangerously-skip-permissions略過權限詢問,等同 --permission-mode bypassPermissions
--safe-mode停用所有自訂項目(CLAUDE.md、skills、plugins、hooks、MCP 等),用來排查設定壞掉的問題claude --safe-mode

舊教學常見的 --enable-auto-mode 已在 v2.1.111 移除。Auto 模式現在預設就在 Shift+Tab 的切換循環裡,要直接以 Auto 啟動請用 --permission-mode auto。

--dangerously-skip-permissions 只建議在沒有網路的隔離環境使用,平常開發用 Auto 或 Plan 模式就夠了。

系統提示詞

旗標行為
--system-prompt取代整個預設提示詞
--system-prompt-file用檔案內容取代
--append-system-prompt接在預設提示詞後面
--append-system-prompt-file把檔案內容接在預設提示詞後面

這幾個旗標可以組合,例如先用 --system-prompt 取代,再用 --append-system-prompt 補一句。一般情況建議用 append:預設提示詞裡有工具使用的指引,整個取代掉容易讓 Claude 變得不好用。專案的固定規範則寫在 CLAUDE.md,不必每次帶旗標。

Bash
claude -p --append-system-prompt "一律用繁體中文回答" "摘要 README.md"

工作目錄與環境

旗標說明範例
--add-dir額外加入可讀寫的資料夾claude --add-dir ../shared
--worktree、-w在獨立的 git worktree 裡啟動claude -w feature-auth
--bare精簡模式:不載入 hooks、skills、plugins、MCP、CLAUDE.md,腳本呼叫啟動較快claude --bare -p "..."
--ide啟動時自動連上 IDE(剛好只有一個可用時)claude --ide
--chrome、--no-chrome啟用或停用 Chrome 瀏覽器整合claude --chrome
--desktop在 Claude 桌面版 App 開啟目前資料夾,終端機不啟動工作階段claude --desktop

MCP 與外掛

旗標說明範例
--mcp-config從 JSON 檔或字串載入 MCP Serverclaude --mcp-config ./mcp.json
--strict-mcp-config只用 --mcp-config 指定的,忽略其他 MCP 設定
--plugin-dir只在這次工作階段載入指定資料夾或 .zip 的 pluginclaude --plugin-dir ./my-plugin
--disable-slash-commands停用所有 skills 與指令

雲端與遠端

旗標說明範例
--cloud建立雲端工作階段。舊的 --remote 是它的別名,已不建議使用claude --cloud "修正登入的 bug"
--teleport把雲端工作階段接回本機終端機claude --teleport
--remote-control、--rc啟動互動工作階段並開啟 Remote Control,可從 claude.ai 或手機 App 接手claude --rc "My Project"
--from-pr開啟與某個 PR 關聯的對話選單claude --from-pr 123

子指令

claude auth:帳號登入

Bash
claude auth login            # 登入
claude auth login --console  # 改用 Console 帳號,以 API 用量計費
claude auth status --text    # 查看目前登入狀態
claude auth logout           # 登出

claude auth status 預設輸出 JSON,加 --text 才是給人看的格式。已登入時結束代碼是 0、未登入是 1,寫腳本時可以拿來判斷。

要在 CI 或腳本裡使用訂閱帳號,用 claude setup-token 產生長效 token。它只會把 token 印在終端機、不會儲存,請自行妥善保管。

claude mcp:MCP Server 管理

Bash
# 新增本機(stdio)Server
claude mcp add my-server -- node C:\path\to\server.js

# 新增遠端(HTTP)Server
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer YOUR_GITHUB_PAT"

claude mcp list              # 列出已設定的 Server
claude mcp remove my-server  # 移除
claude mcp login sentry      # 直接跑 OAuth 登入,不必進 /mcp 面板
claude mcp logout sentry     # 清除儲存的 OAuth 憑證

claude mcp add 只會儲存設定,不會驗證憑證對不對。加完之後用 claude mcp list 確認,它會直接顯示每個 Server 的連線狀態。

claude mcp list 列出已設定的 MCP Server 與連線狀態
claude mcp list 會列出每個 Server 的位址與連線狀態,需要登入的會標示 Needs authentication

延伸閱讀:Claude Code 的 MCP Server 設定。

claude update 與 claude install

Bash
claude update           # 更新到最新版
claude install stable   # 安裝或重裝指定版本:stable、latest 或版本號

用官方安裝腳本裝的版本會在背景自動更新,平常不用手動跑。用 WinGet 裝的預設不會自動更新,要自己執行 winget upgrade Anthropic.ClaudeCode。

claude plugin:外掛管理

Bash
claude plugin install code-review@claude-plugins-official

claude plugins 是同一個指令的別名。其他子指令請看官方 plugin reference,或這篇 Claude Code Plugins。

claude auto-mode:Auto 模式規則

Bash
claude auto-mode defaults   # 印出內建的分類規則(JSON)
claude auto-mode config     # 印出套用你的設定後實際生效的規則
claude auto-mode reset      # 還原成預設,會先詢問確認

背景工作階段

這是比較新的功能:把工作丟到背景跑,終端機馬上可以做別的事。

Bash
claude --bg "幫 report.py 補上單元測試"   # 在背景啟動,會印出 session ID
claude agents                # 開啟 agent view,監看所有背景工作階段
claude logs 7c5dcf5d         # 看某個工作階段最近的輸出
claude attach 7c5dcf5d       # 接回終端機繼續互動
claude stop 7c5dcf5d         # 停止
claude rm 7c5dcf5d           # 從清單移除

詳細說明請看官方 agent view 文件。

claude remote-control:遠端控制

Bash
claude remote-control

以伺服器模式啟動(本機不開互動畫面),讓你從 claude.ai 或手機 App 操作這台電腦上的 Claude Code。如果想要本機也能同時操作,改用 claude --rc。

其他子指令

指令作用
claude doctor印出安裝與設定的診斷資訊,唯讀
claude import把其他 coding agent 的設定帶進 Claude Code
claude purge刪除某個專案在本機的所有 Claude Code 資料(對話紀錄、編輯歷史等),可加 --dry-run 先預覽
claude ultrareview以非互動方式執行 ultrareview,結果印到標準輸出

實用的組合技巧

搭配 git

Bash
git diff main --name-only | claude -p "檢查這些變更的檔案有沒有安全問題"
git log --oneline -20 | claude -p "總結最近的開發進展"

輸出 JSON 給腳本用

加上 --output-format json,輸出會變成一個 JSON 物件。在 PowerShell 裡用 ConvertFrom-Json 接起來,就能直接取用欄位:

Plaintext
$r = claude -p --safe-mode --output-format json "用一句話說明 report.py" | ConvertFrom-Json
$r.result
$r | Select-Object num_turns, duration_ms, total_cost_usd, is_error
在 PowerShell 用 ConvertFrom-Json 取用 claude -p 的 JSON 輸出欄位
答案在 result 欄位,另外還能取得回合數、耗時、預估花費與是否出錯

常用的欄位有這幾個:

欄位內容
resultClaude 的回答
is_error這次執行是否出錯
num_turns執行了幾個回合
duration_ms總耗時(毫秒)
total_cost_usd預估花費(美元)
session_id這次對話的 ID,可以拿來 --resume

範例裡加了 --safe-mode,是為了不讓個人的 CLAUDE.md 和 hooks 影響輸出。我自己的全域設定會在工作完成時跳 Windows 通知,沒加這個旗標的話,回答後面會多出一段和問題無關的文字,JSON 裡也會多一筆被拒絕的指令紀錄。寫腳本時建議都加上。

限制回合與花費

無人看管的腳本一定要設上限:

Bash
claude -p --max-turns 5 --max-budget-usd 1 "檢查最新的變更有沒有潛在問題"

花費上限是依客戶端的估算值判斷,實際金額可能略超過,設定時要留一點空間。

在獨立的 worktree 裡開工

Bash
claude -w feature-register "實作新的使用者註冊功能"

Claude 會在 .claude/worktrees/feature-register 建立獨立的工作目錄,不會動到你目前的分支,適合同時跑好幾個任務。

CI/CD

在 CI 裡通常會用 --bare 加快啟動,並明確指定可用的工具:

Bash
claude --bare -p --max-turns 3 --allowedTools "Read" "檢查這次變更的程式碼品質"

要注意 --bare 模式不會讀取訂閱帳號的登入,需要改用 API Key 驗證。完整做法請看 Claude Code Headless 模式與 CI/CD。

進階旗標速查表

旗標說明
--agent指定這次工作階段使用的 agent
--agents用 JSON 動態定義自訂 subagent
--bg、--background以背景 agent 啟動並立刻返回
--exec搭配 --bg,把一個 shell 指令當成背景工作執行
--advisor為這次工作階段啟用 advisor 工具並指定模型
--settings指定設定檔路徑或 JSON 字串,覆蓋同名的設定
--setting-sources指定要載入哪些設定來源:user、project、local
--debug除錯模式,可加分類篩選,例如 --debug='mcp,startup'
--debug-file把除錯紀錄寫到指定檔案
--init-only執行 Setup 與 SessionStart hooks 後結束,不開始對話
--include-partial-messages輸出串流中的部分訊息,需搭配 -p 與 stream-json
--permission-prompts-p 模式下由誰回答權限詢問;設為 none 會直接拒絕
--teammate-modeagent team 的顯示方式
--tmux為 worktree 建立 tmux session,需搭配 --worktree
--version、-v顯示版本號

想快速查一個旗標時,直接在終端機看說明:

Bash
claude --help
claude mcp --help
claude --help 的輸出,列出可用的旗標
claude –help 的第一頁。記得它不會列出全部旗標

常見問題

claude –help 沒列出的旗標可以用嗎?

可以。官方文件明確說明 --help 不會列出所有旗標,完整清單要看官方 CLI reference。

-p 模式和互動模式差在哪?

項目互動模式-p 模式
啟動方式claudeclaude -p "..."
適合來回討論、逐步修改單次提問、腳本、CI
權限詢問會停下來問你沒有人可以回答,需要核准的動作會被跳過,要事先用旗標設定好
專屬旗標--max-turns、--max-budget-usd、--output-format、--json-schema

PowerShell 說找不到 claude

裝完後要重開終端機視窗,PATH 才會生效。另外,只裝 VS Code 擴充套件是不會有 claude 指令的,CLI 要另外安裝。

出現「this sign-in can end at any time」警告

執行 claude -p 時如果看到 Warning: this sign-in can end at any time from now until ...,代表登入憑證快到期了。這只是提醒,指令仍會正常執行。執行 claude auth login 重新登入一次就會消失。如果是 CI 或無人看管的腳本,改用 claude setup-token 產生長效 token。

設定改壞了,Claude Code 啟動後行為很怪

先用 claude --safe-mode 啟動。它會停用 CLAUDE.md、skills、plugins、hooks、MCP 等所有自訂項目,若這樣就正常,問題就出在你的設定裡,再用 claude doctor 找是哪個設定檔有錯。

總結

  • 日常只需要記住四個:claude、claude -c、claude -r、claude -p。
  • 出問題先跑 claude doctor,設定壞掉用 claude --safe-mode。
  • 寫腳本用 -p 搭配 --output-format json 和 --safe-mode,並設好 --max-turns 與 --max-budget-usd。
  • Windows 的管道用 PowerShell 寫法,cat 可用,tail 改成 Get-Content -Tail。
  • --enable-auto-mode、--remote 這些舊旗標已經換掉了,看到舊教學要留意。