---
title: AI・CIから利用する
description: >-
  mcms-cliをAIエージェントやCIから安定して実行するための入出力契約を説明します。`--json`のレスポンス、終了コード、`.ok`による成否判定、コマンド仕様の検索、タスクガイドの参照方法を確認し、書き込み処理で検証とdry-runを組み込む実装例を紹介します。
sidebar:
  order: 5
noindex: false
---
mcms-cliは、AIエージェントやCIが結果を機械判定できることを重視しています。

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

## JSON契約

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

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

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

## 終了コード

| コード | 意味 |
|---:|---|
| 0 | 成功 |
| 1 | 分類できないエラー |
| 2 | 入力エラー |
| 3 | 認証エラー |
| 4 | 権限エラー |
| 5 | ネットワークまたはタイムアウト |
| 6 | 競合 |

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

## CLI仕様を検索する

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

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

microcms spec --json
```

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

```bash
microcms docs list --source auto --json

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

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

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

```bash
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`を外して作成します。

```bash
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`で結果を確認します。


## 関連ページ

- [コンテンツを安全に操作する](/content-operations)
- [コマンドリファレンス](/command-reference)