apidog-cli

Apidog CLI

Apidog CLI を使用して、ユーザーのリクエストを完了します。ペイロードを記憶に頼って推測しないでください。次の操作を決める際は、--help、cli-schema、cli-schema validate、および agentHints.nextSteps を優先してください。

新しいセッションの確認

• Apidog CLI のタスクを初めて処理する際は、CLI が利用可能かを簡単に確認します。apidog --version、apidog --help を実行してください。
• apidog が見つからない場合、またはバージョンを出力できない場合は、先に CLI をインストールします。npm install -g apidog-cli@latest
• インストール後、apidog login --with-token <TOKEN> を実行します。API アクセストークンは、Apidog アプリまたは Web コンソールで取得します。ユーザーアバター → アカウント設定 → API アクセストークン。
• 毎回デフォルトでアップグレードしないでください。コマンドでバージョンが古すぎる、コマンドが不明、または古い CLI が原因と思われるパラメーターの問題が返された場合や、ユーザーのタスクで新しい機能が必要な場合に限り、アップグレードを提案してください。

基本的な使い方

apidog --help
apidog <command> --help
apidog <command> <subcommand> --help

一般的なグローバルオプション：

--project <projectId>     Project ID
--branch <branchName>     Branch name; pure numeric values are compatible with legacy branchId
--access-token <token>    Override current login token
--api-base-url <url>      Private deployment URL

ログインとプロジェクト

• ログインしていない場合は、API アクセストークンをユーザーに求め、apidog login --with-token <TOKEN> を実行します。
• Apidog CLI のトークンは ~/.apidog/config.toml に保存されます。ログにトークンを出力したり、リポジトリにコミットしたり、チャットの要約に含めたりしないでください。
• ユーザーがプロジェクトを指定しない場合は、まず現在のワークスペースに .apidog/settings.json があるか確認します。一般的に使用されるデフォルトの projectId が含まれている場合は、そのプロジェクトを優先してください。
• プロジェクト ID は「プロジェクト設定」→「基本設定」→「プロジェクト ID」で取得するようユーザーに案内してください。または、まず apidog project list を実行し、コマンドの対象プロジェクトをユーザーに確認してください。
• ローカルの設定ファイルを書き込む前に、ユーザーに確認してください。

書き込みワークフロー

必須：create または update を実行する前に、リソース定義とデータ形式を完全に取得し、実際に書き込む前に cli-schema validate を実行してください。

1. スキーマを取得します。apidog cli-schema get <schemaKey>
2. JSON データファイルを生成します。
3. 検証します。apidog cli-schema validate <schemaKey> --file <path>
4. validate が成功した場合にのみ、実際の create または update コマンドを実行します。

コマンドの出力後は、続行または復旧のため、JSON 出力内の agentHints.nextSteps を優先して確認してください。

まず CLI の事実を確認

• 具体的なコマンド、オプション、スキーマキーは、現在の CLI 出力に従う必要があります。apidog <command> --help、apidog cli-schema list、および agentHints.nextSteps を確認してください。
• このスキルの内容が現在の CLI 出力と矛盾する場合は、現在の CLI 出力に従い、このスキルの事実に関する説明を更新してください。

CLI の書き込み権限に関する説明

• AI（CLI ソース）の権限により書き込みがブロックされた場合、ユーザーがすでに希望を指定していない限り、ユーザーに代わって選択しないでください。対象ブランチで直接編集権限を有効にするか、AI ブランチを通じて対象ブランチのデータを編集するか、ユーザーに確認してください。
• main ブランチ、sprint ブランチ、または一般ブランチのデータを直接編集するには、ユーザーに Apidog クライアント 2.8.32 以降で直接編集権限を有効にするよう依頼してください。「プロジェクト設定」→「機能設定」→「AI 機能設定」→「外部 AI 編集権限」。
• ユーザーが AI ブランチを選択した場合のワークフローは次のとおりです。 step1：AI ブランチを作成し、ソースブランチを指定します。 step2：必要に応じて、ソースブランチのリソースをインポート（pick-to）します。 step3：ユーザーのリクエストに応じて AI ブランチを編集します。 step4：完了後、マージリクエストを作成するか、マージするかをユーザーに確認します。
• CLI からマージまたはマージリクエストを直接実行する場合は、ソースブランチと対象ブランチの両方で直接編集権限が有効になっている必要があります。そうでない場合は、該当するブランチ種別の権限を有効にするようユーザーに伝えるか、クライアントで手動でマージするよう案内してください。

AI ブランチ

• AI ブランチは、ソースブランチを直接汚染せずに、AI／自動化がプロジェクトのリソースを変更するための隔離されたブランチです。
• ソースブランチとの差分がない状態が24時間続いたAIブランチは、自動的にアーカイブされます。
• AI ブランチは空の状態で開始され、ソースのリソースを自動的に複製しません。既存のソースリソースを編集または削除する前に、AI ブランチにインポートしてください。
• AI ブランチで新たに作成したリソースは、事前にインポートする必要はありません。
• AI ブランチの変更は自動的には書き戻されません。完了後、すぐにマージするか、マージリクエストを作成するか、ユーザーに確認してください。
• 対象のメインブランチが保護されている場合は、直接マージせず、merge-request を優先してください。

ユーザーへの確認が必要な操作

• ログイントークン、ローカル設定への書き込み、プライベートデプロイ URL。
• AI ブランチの作成／切り替え、ソースリソースの AI ブランチへのインポート。
• 削除、アーカイブ、上書きインポート、一括更新などの破壊的な操作。
• マージ／マージリクエストによるAIブランチの変更の反映。
• CLI をアップグレードするかどうか。

復旧

問題	対応
ログインしていない	apidog login --with-token <TOKEN>
プロジェクトが不明	apidog project list
パラメーターが不明	apidog <command> --help
パラメーターまたはスキーマのエラー	先に cli-schema get / cli-schema validate を実行
AI による書き込みがブロックされた	AI ブランチ／権限の切り替えについて説明し、ユーザーに選択を求める
プライベートデプロイ	--api-base-url https://your-server を追加