AI・CIから利用する

mcms-cliをAIエージェントやCIから安定して実行するための入出力契約を説明します。`--json`のレスポンス、終了コード、`.ok`による成否判定、コマンド仕様の検索、タスクガイドの参照方法を確認し、書き込み処理で検証とdry-runを組み込む実装例を紹介します。

mcms-cliは、AIエージェントやCIが結果を機械判定できることを重視しています。

機械判定では、人向けメッセージの文字列を解析せず、コマンドの終了コードとJSONの.okを組み合わせて確認します。

JSON契約

成功時はok: true、失敗時はok: falseを返します。

{
  "ok": false,
  "error": {
    "code": "AUTH_FAILED",
    "message": "...",
    "retryable": false
  },
  "meta": {
    "requestId": null,
    "version": "0.x"
  }
}

meta.requestIdが返された場合は、障害調査の相関IDとして記録できます。

終了コード

終了コードだけでなく、JSONの.okも確認します。

CLI仕様を検索する

APIキーやservice domainを設定せずに、コマンド仕様や公式ドキュメントのメタデータを検索できます。

microcms search "api schema" \
  --scope all \
  --json

microcms spec --json

公式ドキュメント本文が必要な場合はdocs getを使います。

microcms docs list --source auto --json

microcms docs get \
  --category content-api \
  --file "コンテンツ一覧取得API.md" \
  --json

タスク単位の手順を取得する

エージェントがコマンドを推測せずに済むよう、タスク候補と実行手順を取得できます。

microcms task suggest "schema export" --json
microcms task guide api-schema-export --json

microcms task suggest "delete content" --json
microcms task guide content-delete --json

AIエージェントには、最初にsearch、spec、task suggestを使わせ、書き込み操作では検証とdry-runを必須にするのが安全です。

関連ページ

• コンテンツを安全に操作する
• コマンドリファレンス