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を必須にするのが安全です。

APIを作成するときの確認

microcms api createはManagement APIを使ってAPIを新規作成します。タスクガイドではリスクの高い操作として扱われ、実行前の確認を求めます。

1. microcms task guide api-create --jsonで手順を確認します。
2. --dry-run --jsonを付けて作成内容を検証します。
3. 終了コードとJSONの.okを確認し、API名、endpoint、type、スキーマ、カスタムフィールドを確認します。
4. 人が内容を確認して承認した後に、--dry-runを外して作成します。

microcms api create \
  --file articles-api.json \
  --name articles \
  --endpoint articles \
  --type list \
  --dry-run \
  --json

プラン上限を超える追加料金を許可する場合だけ、承認を得たうえで--allow-additional-chargeを指定します。作成後はmicrocms api list --jsonとmicrocms api info articles --jsonで結果を確認します。

関連ページ

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