CLIリファレンス
Perch CLIのすべてのコマンド。シェルから実行するperchサブコマンドと、対話セッション内で使うスラッシュコマンド。
Perch CLIは、ターミナルで動くフル機能のオペレーターです。デスクトップアプリと同じエンジンと出典チェッカーで動き、今いるフォルダから作業します。このページは完全なコマンドリファレンスです。シェルから実行する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 --jsonシェルコマンド
シェルからperch <command>として実行するコマンドです。
| コマンド | 動作 |
|---|---|
perch | 現在のディレクトリで対話形式のPerchチャットを開きます。 |
perch login | ブラウザでのサインインを開き、このターミナルのセッションを保存します。 |
perch status | 保存済みの認証とアプリ接続の状態を表示します。 |
perch logout | 保存済みのCLI認証セッションを消去します。 |
perch skills [name] | Perchのコアスキルを一覧表示するか、ひとつのスキルの本文を表示します。 |
perch run "<task>" | 自然言語のタスクを一件、オペレーターに実行させます。 |
perch ap evidence <folder> | AP監査の証拠、案件、指標、グラフのアーティファクトを準備します。 |
perch ap packet <folder> | 完全なAP監査パケットとレポートを生成します。 |
perch test ap <folder> | evidence + packetを実行し、合否のレシートを出力します。 |
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> | スレッド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 | cwd、認証、モード、ペルソナ、権限、スレッドを表示します。 |
/context | コンテキストメーターと圧縮の詳細を表示します。 |
/clear | このターミナルセッションのローカルの会話メモリを消去します。 |
/exit | Perch CLIを終了します。 |
アカウント
| コマンド | 動作 |
|---|---|
/login | ブラウザのOAuthでサインインします。 |
/logout | 保存済みのCLI認証を消去します。 |
作業の操舵
| コマンド | 動作 |
|---|---|
/persona [saffron|quill] | 口調の表示または切り替え。ペルソナ。 |
/mode [ask|agents|plan] | チャットモードの表示または設定。 |
/permission [mode] | 以降のターンでPerchが確認なしでどこまで進められるかの表示または設定。権限モード。 |
/model [tier|name] | モデルの表示または設定。Roostティアか、モデルの固定指定です。モデルティア。 |
/thinking [on|off] | 選択中のモデルの拡張思考の表示または切り替え。 |
/byok [provider|off] | このターミナルのターンを実行する、保存済みクラウドキーの表示または切り替え。自分のAPIキーを使う。 |
/local-tools [on|off] | ローカルのシェルとファイルツールの表示または切り替え。 |
/cwd [dir] | 作業ディレクトリの表示または変更。 |
/thread [new|id] | 現在のスレッド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は、手離れよく使えて、それでも影響のある作業の前に番人を置くモードです。書き込みやコマンドのたびに一時停止する代わりに、固定ルールで判断できなかったものを個別のレビュアーに送り、その操作が実行される前に判定を下します。
- 許可された操作は実行され、ターンはあなたを中断せずに続きます。
- ブロックされた操作は実行されません。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は、Roostの代わりに、Ollama、LM Studio、llama.cppなど、自分で動かしているモデルにPerchを接続します。エンドポイントがあなたのマシンの外に出ることはありません。これが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 Tokenにはカウントされません。また、エンドポイントに障害が起きても、Perchが黙ってホスト型モデルに切り替えることはありません。自分のAPIキーを使うを参照してください。
ツールの接続
CLIは、フォルダの外の機能のためにMCPサーバーに接続できます。.perch/mcp.jsonで追加すると、接続したツールが組み込みのツールと並んで表示されます。MCPサーバーを参照してください。
エージェントブラウザはデスクトップ専用のため、CLIではブラウザ操作を使えません。ターミナル主体のワークフローから必要な場合は、その部分をデスクトップアプリで実行してください。
