capigo-api

Capigo CLI オペレーター

Capigo を操作する際は、通常 capigo を使用してください。インストール済みのバイナリは自己説明型であり、Public API は今後も拡張されるため、このスキルではコマンドツリーや API リファレンスを重複して説明するのではなく、確認手順を案内します。

1. 環境と認証の事前確認

新しい環境やセッションを開始するたびに、まずシェル標準の検索機能（POSIX シェルでは command -v capigo、PowerShell では Get-Command capigo）で実行ファイルを特定し、次を実行します。

capigo version

バージョン確認、ヘルプ、事前確認、実行には、特定した実行ファイルを一貫して使用してください。異なるビルドから取得したヘルプを参照しながら別のビルドでコマンドを実行すると、フラグや機能に関する誤ったエラーが発生します。

シェルで capigo が見つからない場合：

1. 読み取り専用の確認を使って、OS、アーキテクチャ、シェル、利用可能なパッケージマネージャーを調べます。
2. Capigo CLI がインストールされていないことをユーザーに伝え、公式インストールガイドを案内します：https://github.com/vtech-com/capigo-api-sdk#installation。
3. 検出したマシンに適したインストール方法を優先して案内します。たとえば Homebrew がある場合は、brew install --cask vtech-com/tap/capigo を提案します。このガイドでは、GitHub Releases と Go を使ったインストールについても、各プラットフォーム固有の注意点とともに説明しています。
4. バイナリが見つからないという理由だけで、ソフトウェアをインストールしたり、マシンに変更を加えたりしないでください。ユーザーの許可を待ち、その後 capigo version で結果を確認します。

バージョン確認が成功したら、読み取り専用の認証・接続確認を実行します。

capigo health

終了コードと標準出力の error オブジェクトに基づいて結果を解釈します。

• 終了コード 0：API に接続でき、設定されたキーが受け入れられています。続行します。
• 終了コード 2：キーが未設定、不正な形式、または拒否されています。capigo auth login --help を実行し、https://platform.capigo.app にサインインしてキーを作成または取得するようユーザーに伝え、サポートされているログインコマンドをローカルで実行するよう依頼します。その後、capigo health を再実行します。コード AUTH_MISSING_HEADER は初回実行時のケースです。キーがまったく設定されていないため、CLI は API に到達していません。一時的な問題ではないため、ユーザーがログインするまで再試行しないでください。
• 終了コード 6：接続に失敗しています。DNS、ネットワークアクセス、または設定された API URL を調査してください。認証の問題と誤って判断したり、ユーザーに再ログインを求めたりしないでください。
• それ以外のゼロ以外の終了コード：エラーオブジェクトと capigo help exit-codes を確認してから、復旧手順を案内します。

事前確認に capigo auth whoami を使用しないでください。/me ルートは実装されていないため、404 が返されても設定されたキーが有効かどうかは分かりません。

認証情報はユーザーのものです。API キーをチャットに貼り付けるよう求めたり、復元のために認証情報ファイルや環境変数を調べたり、キーを表示したり、例に記載したり、シェルトレースに露出させたりしないでください。capigo auth login --help を参照するようユーザーを案内し、サポートされている手順でローカルにキーを入力してもらいます。

キーでアクセスできるワークスペースは1つです

キーは作成された1つのワークスペースに紐づけられています。どのワークスペースかは、プラットフォームの API キーページで確認できます。 この紐づけはすべてのリクエストでサーバー側から強制されるため、CLI から何を送信しても変わりません。

• 別のワークスペースを指定すると、--tenant、CAPIGO_TENANT、または別のキーに紐づく default_tenant のいずれを使っても、終了コード 3 で失敗します。キーは有効ですが、指定されたワークスペースはそのキーに紐づいていません。
• ワークスペースを指定しなくても、アクセス範囲が広がることはありません。リクエストで読み取れるのは引き続きキーのワークスペースだけです。また、CLI は解決したテナントを報告するため、テナントを解決していない場合、meta にテナント名は表示されません。回答がどのワークスペースに属するかを確認する必要がある場合は、キーに紐づくワークスペースを --tenant に指定してください。取得される行は同じで、meta.tenant が表示されます。
• capigo tenants list は、このキーのアクセス範囲を示すものではありません。アカウントが所属するワークスペースを一覧表示しますが、キーのアクセス範囲には絞り込まれません。そのため、アカウントのディレクトリとして扱い、現在のキーで指定できるワークスペースの一覧とは見なさないでください。
• 古いキーにはワークスペースが紐づいておらず、アカウントが所属するすべてのワークスペースにアクセスできるものがあります。キーのプレフィックスや作成時期からアクセス範囲を推測せず、API キーページで確認するか、実行しようとしていた呼び出しの終了コードで判断してください。

そのため、複数のワークスペースで作業するには、ワークスペースごとに1つのキーが必要です。キーごとにプロファイルを用意するか、呼び出しごとに CAPIGO_API_KEY と CAPIGO_TENANT を設定してください。--profile フラグはなく、プロファイルを作成するコマンドもありません。2つ目のプロファイルを作るには、~/.capigo/config.json を手動で編集します。

2. 現在のコマンド一覧を確認する

capigo version が成功したら、組み込みヘルプを段階的に確認します。

capigo --help
capigo <group> --help
capigo <group> <command> --help

ユーザーの意図に関連するグループとコマンドだけを読みます。実行可能なコマンドのページには、目的、使い方、フラグ、制約、例、出力が記載されています。記憶を頼りにコマンドを組み立てたり、フラグを推測したり、このスキルをコマンド一覧として扱ったりしないでください。

必要に応じて、複数のコマンドに共通する仕様をバイナリから確認します。

capigo help tenancy
capigo help output
capigo help exit-codes
capigo help soft-delete
capigo help versioning

CLI の表記と動作については、インストール済みのヘルプを優先してください。ヘルプはそのビルドに対応したものです。ヘルプとこのスキルの内容が異なる場合は、ヘルプに従い、スキルのメンテナーに相違点を報告してください。

3. 計画、実行、検証

呼び出しの前に、次の手順を実行します。

1. リクエストを、機械的に実行できる Capigo の意図に変換します。
2. ヘルプからグループとコマンドを確認します。
3. フラグや JSON を組み立てる前に、末端のコマンドのヘルプを読みます。
4. テナントを解決します。書き込み先のテナントが曖昧な場合は、書き込む前に確認してください。ユーザーがリソース、変更内容、テナントをすでに明確に指定している場合は、重ねて確認を求めないでください。タスクの作成には、後述する別の担当者選択ゲートが適用されます。キーは1つのワークスペースに紐づいていることを忘れないでください。書き込み時はデフォルト設定に任せず、そのワークスペースを明示的に指定してください。そうすれば、後で検証できるように meta.tenant が標準出力に表示されます。
5. references/cli-conventions.md の規約に従います。

呼び出しの後に、次の手順を実行します。

1. 標準出力に含まれる単一の JSON ドキュメントを解析します。
2. data を信頼する前に、error キーがあるか確認します。部分的な結果には両方が含まれる場合があります。
3. 書き込みの場合は、意図したテナントや変更が使われたと思い込まず、meta.tenant と返されたオブジェクトを検証します。
4. 認証情報、生の認証ヘッダー、無関係なテナントのデータを開示せずに結果を報告します。

4. コマンドの欠落と失敗への対処

想定したコマンドが見つからない場合は、ルートと関連するグループのヘルプを再確認してください。推測した名前は、その機能が利用できない証拠にはなりません。操作は隣接するグループにある場合や、インストールされている CLI が現在の API より古い場合があります。

コマンドが失敗した場合：

1. 標準出力の error オブジェクトを読み、特に message、next、request_id、および capability_note があれば確認します。
2. リーフコマンドのヘルプと capigo help exit-codes を読みます。
3. マスキングされた HTTP トレースが実際に必要な場合に限り、--verbose を使用します。
4. 一時的なネットワークエラーやレート制限への応答など、エラーの分類上リトライが適切な場合に限り、再試行します。検証、認証、権限、競合、または結果が不明確な書き込みについて、むやみに再試行しないでください。

書き込みの失敗は、API にその機能がないことの証明にはなりません。リソースの再作成、識別子の変更、テナント処理の回避といった、破壊的な復旧手順をでっち上げないでください。

5. 公開 API 仕様は必要最小限に利用する

公開仕様：https://platform.capigo.app/api/openapi

通常のユーザー操作では、CLI のヘルプを確認したら、capigo で実行してください。次のいずれかに当てはまる場合に限り、仕様を開きます。

• ユーザーが公開 API の契約について明示的に質問している、またはインテグレーションを構築している場合。
• この SDK を開発またはレビューしている場合。
• CLI の機能不足がライブヘルプで確認されており、「この CLI では公開されていない」のか「公開 API に存在しない」のかを判別する必要がある場合。
• バージョンの不一致や、不正確なヘルプ／仕様の記載を調査する必要がある場合。

SDK リポジトリ内では、作業対象のリリースに対応する、バージョン管理された api/openapi.json を優先してください。現在公開されている契約を確認するには、公開 URL を使用します。仕様で定義されるのは API のパスとスキーマであり、インストールされている CLI のフラグ表記ではありません。仕様にエンドポイントが見つかっても、通常のテナント操作で CLI を迂回する根拠にはなりません。不足している機能を報告するか、アップグレードを推奨してください。生の HTTP 呼び出しを行うのは、ユーザーのタスクが公開 API インテグレーションの構築またはテストであり、その作業が別途許可されている場合に限ります。

6. 必要な場合に限り、特殊ケースのガイダンスを読み込む

ほとんどの操作では、同梱のドメインガイドは必要ありません。リーフヘルプで十分です。

関係を作成、たどる、または変更する操作では、リーフヘルプを読んだ後に、関連するドメインリファレンスだけを読み込みます。

• references/domains/products.md：製品、バリエーション、製品リファレンス、製品プロパティ（capigo property-definitions）。
• references/domains/tasks.md：タスク、担当者、サブタスク、コメントとメンション、ラベル（--label、capigo labels list）。
• references/domains/boards.md：タスクをボードまたはリストに配置する場合、またはコードでボードを読み取る場合。
• references/domains/wms.md：capigo wms 配下のすべての操作（倉庫、ロケーション、在庫状況、4 種類の在庫ドキュメント）。

製品の作成時、および properties またはプロパティ定義への書き込み時は、リーフヘルプを読んだ後に products.md を読みます。タスクまたはサブタスクの作成時、あるいはコメントの投稿時は、関連するリーフヘルプを読んだ後に tasks.md を読みます。ボードへの配置を行う場合に限り、boards.md も読みます。capigo wms への書き込み時、および WMS の読み取り結果をユーザーに報告する場合は、wms.md を読みます。判定結果、null のコスト、ステータスは誤って報告しやすいためです。無関係な一覧表示や検索では、ドメインリファレンスを読み込まないでください。

対象範囲

このスキルが対象とするのは、Capigo CLI の操作と公開 API の調査です。組織の製品コード、バーコード、命名、承認、データガバナンスに関するポリシーは定めていません。これらについては、ユーザー自身のポリシーまたは組織固有の別のスキルに従ってください。