CLI 參考
Perch CLI 的每個指令，包括在 shell 執行的 perch 子指令，以及在互動工作階段內使用的斜線指令。
Perch CLI 是終端機中的完整操作代理。它使用與桌面應用程式相同的引擎與引用檢查工具，從你目前所在的資料夾工作。本頁是完整指令參考：在 shell 執行的 perch 子指令、設定工作階段的全域旗標，以及 Perch 執行後輸入的斜線指令。
安裝與登入
npm install -g perchai-cli # Node 18+
perch login # opens a browser tab, saves your session
perch # start working in the current folder兩種執行方式
有兩種模式，差別在於留在工作階段中，或執行單一任務後結束。
- 互動式。 不帶引數執行
perch，在目前目錄開啟聊天。它會讀取其中的檔案、接受以日常語言交代的任務，並保留對話串。下方的斜線指令可在它工作時引導它。 - 單次執行。 執行
perch run "<task>"，完成單一任務後返回。加入--json可取得機器可讀的輸出。撰寫腳本或使用管線時，採用這種形式。
perch # interactive session in .
perch run "Check March invoices for duplicates." # one task, then exit
perch run "Draft the venue section" --persona quill --jsonShell 指令
在 shell 中以 perch <command> 執行的指令。
| 指令 | 用途 |
|---|---|
perch | 在目前目錄開啟互動式 Perch 聊天。 |
perch login | 開啟瀏覽器登入，並儲存此終端機的工作階段。 |
perch status | 顯示已儲存的驗證與應用程式連線狀態。 |
perch logout | 清除已儲存的 CLI 驗證工作階段。 |
perch skills [name] | 列出 Perch 的核心技能，或印出一項技能的內容。 |
perch run "<task>" | 透過操作代理執行單一自然語言任務。 |
perch ap evidence <folder> | 準備應付帳款稽核證據、案例、指標與圖譜成品。 |
perch ap packet <folder> | 產生完整的應付帳款稽核資料包與報告。 |
perch test ap <folder> | 執行證據準備與資料包產生，並輸出通過／失敗紀錄。 |
perch byok use <provider> | off | 讓此終端機的回合使用帳號中儲存的雲端金鑰，或回到 Perch。 |
perch byok list | status | test | set | remove | 不離開終端機即可管理帳號中的金鑰。 |
perch byolm set <url> <model> | 將 Perch 指向你自己的本機模型（Ollama、LM Studio、llama.cpp）。 |
perch byolm status | clear | test | 顯示、移除或測試本機模型。 |
全域旗標
這些旗標會設定工作階段，可傳給 perch 或 perch run：
| 旗標 | 值 | 用途 |
|---|---|---|
--cwd <dir> | 任何路徑 | 從目前資料夾以外的資料夾工作。 |
--permission <mode> | default、auto_review、take_the_wheel、plan | 設定 Perch 不詢問就能執行的範圍。請參閱權限模式。 |
--mode <mode> | ask、agents、plan | 設定工作階段的聊天模式。 |
--persona <persona> | saffron、quill | 以指定語氣開始。請參閱角色。 |
--model <tier> | standard、standard max、pro、pro max | 為執行指定 Roost 等級。 |
--thinking <on|off> | on、off | 切換所選模型的延伸思考。 |
--thread <id> | 對話串識別碼 | 繼續特定對話串（搭配 perch run）。 |
--json | 不適用 | 輸出機器可讀的內容（搭配 perch run）。 |
斜線指令
進入互動工作階段後，在提示處輸入斜線指令。Perch 工作時，你也可以輸入引導文字並按 Enter；Ctrl-C 停止目前回合，Ctrl-E 展開詳細資訊。
本節列出指令。各指令何時適用，以及會傳回什麼，請參閱斜線指令。
執行工作
| 指令 | 用途 |
|---|---|
/goal <objective> | 跨回合自主朝目標工作，直到完成審查通過。 |
/goal [status|pause|resume|clear] | 檢查或控制目前目標。結束程式後仍會保留，因此 /goal resume 可在之後的工作階段使用。 |
/verify [text] | 依已建立索引的來源，重新檢查上一個答案或貼上的文字。 |
/verify --changed | 只重新檢查自上次 /verify 後來源改變的陳述。 |
工作階段與說明
| 指令 | 用途 |
|---|---|
/help | 顯示完整指令清單。 |
/status | 顯示工作目錄、驗證、模式、角色、權限與對話串。 |
/context | 顯示上下文用量表與壓縮詳細資訊。 |
/clear | 清除此終端機工作階段的本機對話記憶。 |
/exit | 離開 Perch CLI。 |
帳號
| 指令 | 用途 |
|---|---|
/login | 透過瀏覽器 OAuth 登入。 |
/logout | 清除已儲存的 CLI 驗證資料。 |
引導工作
| 指令 | 用途 |
|---|---|
/persona [saffron|quill] | 顯示或切換語氣。角色。 |
/mode [ask|agents|plan] | 顯示或設定聊天模式。 |
/permission [mode] | 顯示或設定後續回合的自主程度。權限模式。 |
/model [tier|name] | 顯示或設定模型，可選 Roost 等級或指定確切模型。模型等級。 |
/thinking [on|off] | 顯示或切換所選模型的延伸思考。 |
/byok [provider|off] | 顯示或切換此終端機回合使用的已儲存雲端金鑰。自備 API 金鑰。 |
/local-tools [on|off] | 顯示或切換本機 shell 與檔案工具。 |
/cwd [dir] | 顯示或變更工作目錄。 |
/thread [new|id] | 顯示、重設或設定目前對話串識別碼。 |
/permissions 是別名
/permissions 與 /permission 的功能相同，兩種寫法都可使用。記憶、用量與技能
| 指令 | 用途 |
|---|---|
/memory-audit <text> | 檢查筆記是否會儲存到記憶，以及原因。記憶。 |
/usage | 顯示 Perch Token 內含用量與此工作階段的用量。 |
/skills [name] | 列出 Perch 的核心技能，或顯示一項技能的內容。 |
委派工作
| 指令 | 用途 |
|---|---|
/delegate <task> | 將範圍明確的任務交給背景代理非同步執行，並供審閱。 |
/bg <task> | /delegate 的簡寫。 |
當任務可獨立完成，且你想繼續工作而非看著它執行時，請使用 /delegate。代理會在背景執行，再傳回結果供審閱，因此長時間工作不會阻塞工作階段。
權限模式
權限模式控制 Perch 在停下詢問前能做多少事。在工作階段中用 /permission 設定，或啟動時用 --permission 設定。
Perch 分兩步判斷。首先會立即執行一組固定規則：讀取檔案、在工作區內編輯，以及執行專案本身的建置與測試指令，都會直接進行；強制推送、改寫歷史紀錄與大量刪除，一律停下等你確認；敏感路徑封鎖清單中的位置（金鑰、憑證、系統資料夾）在所有模式都會遭拒。剩下的是固定規則無法自行判定、較少數但會帶來實際影響的動作，各模式的差別就在如何處理這些動作。
| 模式 | 不詢問即可執行的內容 |
|---|---|
| Default | 僅讀取。每次寫入、指令、傳送與刪除都會先詢問你。 |
| Auto Review | 可復原的低、中風險工作會自行執行。超出此範圍、會帶來實際影響的每項動作，都由獨立審查者檢查，只有不確定時才詢問你。 |
| Take the Wheel | 所有動作，不詢問。 |
| Plan | 唯讀。變更資料的工具會維持封鎖，直到你核准計畫。 |
從嚴格模式開始
Auto Review 如何判斷
Auto Review 是不用全程介入、仍會在帶來實際影響的工作前把關的模式。它不會在每次寫入或指令前暫停，而是將固定規則無法放行的動作交給獨立審查者，在執行前做出判定：
- Allowed 動作會執行，回合持續而不打斷你。
- Blocked 動作不會執行。Perch 會被要求尋找更安全的方式達成目標，繼續工作，而非繞過封鎖。
- 當審查者無法判定、同類動作連續遭封鎖數次，或遇到根本不會自動審查的最高風險動作時，Perch 會詢問你：強制推送與大量刪除一律停下等你確認。
審查者只會看到你的要求與 Perch 即將採取的動作，不會看到其他內容。它不讀取檔案內容或指令輸出，因此藏在網頁或文件內的指示無法說服它核准某件事。若審查者無法使用，Perch 會詢問你，而非猜測。這些檢查會使用少量內含用量，換來能無人看管執行、卻不盲目行動的模式。
Auto Review 的界線在於能否復原，而非難易程度。編輯可復原的檔案，與傳送電子郵件屬於不同類別，審查者也會以不同方式處理。
模型等級
/model 與 --model 接受 Roost 等級，讓 Roost 為每項任務選擇有能力處理的模型，按標準費率計費：
auto：讓 Roost 選擇。standard、standard max：日常工作。pro、pro max：最困難的任務。
需要全程使用已知模型時，你也可以指定確切模型（例如在 Pro 使用 /model claude-opus-5.5，或特定的 GLM、Kimi、MiniMax、DeepSeek 或 Qwen 版本）。不帶引數執行 /model，即可查看目前選擇與完整清單。
自備模型
依模型在哪台電腦上執行，分為兩個指令。
perch byok 使用帳號中儲存的雲端金鑰執行回合。金鑰本身以加密方式儲存在帳號中，因此在網頁加入的金鑰在這裡已經可用；選取則由各裝置分別設定。
perch byok list # keys saved on your account
perch byok use openai # run this terminal's turns on that key
perch byok status # what turns are running on right now
perch byok off # go back to Roost你也可以在此新增與測試金鑰，包括自己的相容 OpenAI 端點：
perch byok set openai --key sk-...
perch byok set custom --key sk-... --url https://api.example.com/v1 --model acme/model-x
perch byok test # one real request against the selected key
perch byok remove openaiperch byolm 將 Perch 指向你自行執行的模型，例如 Ollama、LM Studio 或 llama.cpp，以取代 Roost。端點不會離開你的電腦，因此這個指令僅限 CLI。
perch byolm set http://localhost:11434/v1 llama3.1 # register a local model
perch byolm test # probe that it responds
perch byolm status # show the current local model
perch byolm clear # go back to Roost使用任一方式的回合都不計入 Perch Tokens，如果端點失敗，Perch 也不會悄悄退回託管模型。請參閱自備 API 金鑰。
連接工具
CLI 會連接 MCP 伺服器，取得資料夾以外的功能。在 .perch/mcp.json 加入伺服器後，已連接工具就會與內建工具一起出現。請參閱 MCP 伺服器。
代理瀏覽器僅限桌面版，因此 CLI 無法執行瀏覽器工作。如果以終端機為主的工作流程需要它，請在桌面應用程式執行該部分。
