official/cli スキル
あなたは、CLIを通じてGlyphサーバーを制御するAIです。このスキルは、glyphコマンドの全表面と、--helpからはわかりにくい規則(特に、他のクライアントとの競合を防ぐワークスペーススコープの規律、および障害時に機械的に分岐するための終了コード/エラーコードの規律)の地図です。
セットアップ
glyph は、タスクまたはセッションを起動するときに、必要なものを環境に注入します。
GLYPH_SERVER— サーバーURL(CLIはこれを自動的に使用します)GLYPH_WORKSPACE— ワークスペースUUID(ワークスペーススコープのコマンドはこれを継承します)
クイック確認:
glyph health # 終了コード0 ⇒ CLIが動作し、サーバーに到達可能
glyph workspace current --json | jq # ワークスペースが解決されたことを確認
コマンド表面の概要
ワークスペーススコープのすべてのコマンドは --server / --workspace-id / --output / --json を継承し、以下の共通終了コードテーブルに従います。サブコマンドグループ:
| グループ | 目的 | 参照 |
|---|---|---|
workspace | ワークスペースの作成/一覧表示/表示/更新/削除/リロード、現在のIDの表示 | references/commands.md#workspace |
session | インタラクティブセッションの管理(一覧表示/新規作成/表示/削除/端末の起動) | references/commands.md#session |
task | ワンショットタスクのディスパッチ、一覧表示(--origin によるスコープ指定を含む)、検査、アクティビティの追跡、キャンセル、削除 | references/commands.md#task |
schedule | Cronトリガータスクランチャー(作成/一覧表示/パッチ/有効化/無効化/実行/プレビュー/タスク一覧表示) | references/commands.md#schedule |
catalog | エージェント、スキル、MCPのインストール/同期/有効化/無効化 | references/commands.md#catalog |
workflow | ワークフローのシード、ライブDAGの読み取り/変更(展開、update-spec による未開始ノードの仕様パッチ)、人間ノードへの応答、終了 | references/commands.md#workflow |
runtime | 登録済みランタイムの一覧表示(copilotなど) | references/commands.md#runtime |
| サーバー検査 | health, config, status, logs — ライフサイクルなし | references/commands.md#server-inspection |
| サーバーライフサイクル | serve / start / stop / restart — このスキルの範囲外 | — |
ワークスペースの規律
ワークスペーススコープのすべてのコマンドには、明示的なセレクターが必要です。CLIは環境から GLYPH_WORKSPACE を読み取ります(既に設定されています)。そのため、コマンドはそのまま動作します:
glyph task dispatch --agent writer --brief "..."
別のワークスペースで操作するには、コマンドごとに --workspace-id <id> を渡します:
glyph task list --workspace-id ws-Y
CLIは、サーバー側の共有「現在のワークスペース」状態を参照しません。セレクターはプロセスローカルであり、他のクライアント(他のCLIセッション、ダッシュボードタブ、同じサーバー上のAIエージェント)からの干渉を受けません。
出力の規律
- 解析用には、常に
--jsonを渡してください。 人間向け/テーブル形式は安定した契約ではありません。列の順序や見出しはリリース間で変更されます。 - アクティビティのストリーミングには、
jq -cにパイプして 1イベントを1行に保ちます。 - 消費する可能性が高いすべての
--json形状はreferences/json-shapes.mdに文書化されています。jqフィルターを記述する前に参照してください。ほとんどの形状にはオプションフィールド(対応する行がnullでない場合に存在する)があり、それを利用する必要があります。
エラーの規律
エラーはstderrに常に code を伴います:
agent "writer" is not ready: prereqs not acknowledged (HTTP 409, EntryNotReadyError)
agent: acme/writer
cause: prereqs not acknowledged
fix: glyph catalog agent ack-prereqs acme/writer
fix: 行は、次のコマンドそのものです。完全な code カタログ(すべてのエラー名 + 典型的なHTTP + 修復方法)は references/error-codes.md にあります。特に:
EntryNotReadyErrorは、最も頻繁に遭遇する分岐です。エージェントがack-prereqsを必要とするか、disabledであるか、missingDepsがあるか、blockedDeps(再帰的)があるかを説明する構造化されたreasonを伴います。理由テーブルはreferences/error-codes.md#entrynotreadyerror-reasonsにあります。
終了コード
| コード | 意味 | 対処方法 |
|---|---|---|
| 0 | 成功 | 続行 |
| 1 | 一般的なエラー(ワークスペース欠落を含む) | stderrを読む。通常はフラグ/envの欠落 |
| 2 | 使用法エラー(必須フラグの欠落、削除されたサブコマンド) | 呼び出しを修正。そのまま再試行しないでください |
| 3 | サーバーに到達不可 | ユーザーに glyph start または --server の確認を依頼 |
| 4 | サーバーが4xx/5xxを返した | stderrの code を読み、references/error-codes.md を参照 |
終了コード2は 「コマンド自体が間違っている」 ことを意味します。呼び出しを変更せずに再試行しないでください。終了コード4は「サーバーがこれを拒否した」ことを意味します。code フィールドを読むと、次のアクションがわかります。
落とし穴
- タスクを待つには、
glyph task activity <tid> --followを使用してください(リアルタイムSSE)。シェルループでtask listをポーリングすると、サイクルを無駄にし、実際のイベントに遅れます。 - 「これまでの経過」のワンショットスナップショットには、
--followを削除してください —glyph task activity <tid> --jsonは、1回の呼び出しで現在のアクティビティとtotalItemsを返します。--followはタスクが終了するまでブロックします。 - 削除する前に終了させてください。 単純な
task rm <tid>は、タスクが終了状態(succeeded/failed/cancelled)である必要があります。まだ実行中の場合は、最初にglyph task cancel <tid>を実行し、次にtask rmを実行します。--purgeは、ワークディレクトリとランタイム状態も削除したい場合にのみ使用してください(事後分析用のstderr.logは失われます)。session rmとworkspace rmでも同じ区別があります。 --followは、常に表示されたlast seq:で再開してください。 クリーン終了(event: endまたはストリームクローズ)時と、ストリーム途中のエラー終了時の両方で、CLIは stderr にlast seq: <N>を出力します。次の--follow呼び出しで--after <N>を渡すと、ギャップや重複なく再開できます。Ctrl+Cは例外です(stderrがフラッシュされません)。代わりに、最後の stdout NDJSON アイテムからシーケンス番号を取得します(... | tail -1 | jq .seq)。完全な再開プレイブックはreferences/playbooks.md#monitor-a-long-running-taskにあります。- ワークスペースIDは常に
glyph workspace list --json | jqから取得してください。 ダッシュボードのURLフラグメントはリリース間で変化するため、ワイヤー契約として使用できません。 schedule patchはスパースです — 渡したフラグのみがワイヤーを経由します。フィールドを削除するには、--clear-details/--clear-runtimeを渡します(空の--details ""は省略とみなされ、クリアとしては扱われません)。
参考文献(重要な作業の前に必読)
references/commands.md— グループごとのサブコマンドリファレンス(workspace / session / task / schedule / catalog / workflow / runtime / server inspection)。一度ざっと読み、参照用に保持してください。references/playbooks.md— マルチステップの目標指向プレイブック(エージェントのインストールと確認、ディスパッチと待機、タスクの監視、エントリの同期、クリーンアップ、新しいワークスペースのオンボード、ローカルエージェントの即席作成)。references/json-shapes.md— 一般的な--jsonペイロード形状と、具体的なフィールドリストおよびオプション性の注記。references/error-codes.md— サーバーが発行するすべてのcode値と、それを修正するための対応するglyphコマンド。