---
title: Using mcms-cli from AI and CI
description: >-
  Use mcms-cli from AI agents and CI with stable JSON envelopes, exit codes,
  searchable specifications, task guides, validation, and dry-runs.
sidebar:
  order: 5
noindex: false
---
mcms-cli is designed so an AI agent or CI job can decide whether a command succeeded without interpreting human-facing prose.

## Check both JSON and the exit code

A successful JSON response contains `ok: true`; an error contains `ok: false` and a structured error object.

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

Record `meta.requestId` when it is present so an API failure can be correlated during investigation. A robust caller checks both the process exit code and `.ok`.

## Exit codes

| Code | Meaning |
|---:|---|
| 0 | Success |
| 1 | Unclassified error |
| 2 | Invalid input |
| 3 | Authentication failure |
| 4 | Permission failure |
| 5 | Network error or timeout |
| 6 | Conflict |

## Search the command specification

The search and specification commands do not require a microCMS API key.

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

Use `docs list` and `docs get` when the agent needs the source documentation itself.

## Ask for a task guide

```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
```

A safe agent workflow starts with discovery, validates every payload, requires a dry-run for writes, and verifies the remote state after execution.


## Review API creation

`microcms api create` uses the Management API to create an API. The task guide classifies this as a high-risk operation that requires confirmation.

1. Read the procedure with `microcms task guide api-create --json`.
2. Validate the request with `--dry-run --json`.
3. Check the exit code and JSON `.ok` value. Review the API name, endpoint, type, schema, and custom fields.
4. Get human approval before removing `--dry-run` and creating the API.

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

Use `--allow-additional-charge` only after approval to allow a possible charge above the plan limit. After creation, verify the API with `microcms api list --json` and `microcms api info articles --json`.


## Related pages

- [Safe content operations](/en/content-operations)
- [Schemas and types](/en/schema-and-types)
- [Command reference](/en/command-reference)