Using mcms-cli from AI and CI

Use mcms-cli from AI agents and CI with stable JSON envelopes, exit codes, searchable specifications, task guides, validation, and dry-runs.

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.

{
  "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.

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

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.

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

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.