mcms-cli

English | 日本語

Unofficial project. This CLI is not affiliated with, endorsed by, or maintained by microCMS.

AI/CI friendly CLI for microCMS with stable --json output and deterministic exit codes.

Naming

• GitHub repository name: mcms-cli
• npm package name: @mrmtsu/mcms-cli
• command you run: microcms
• local storage identifier (config dir / keychain service): mcms-cli

microcms as the command name is intentional for readability.
This project is unofficial, and that is explicitly stated in this README.

Install

npm i -g @mrmtsu/mcms-cli
# or
npx @mrmtsu/mcms-cli --help

Agent Skill

This repository includes a Codex/Claude-compatible skill at skills/mcms-cli/SKILL.md.

npx skills add mrmtsu/mcms-cli --skill mcms-cli

FAQ

Is this the official microCMS CLI?

No. This is an unofficial community project and is not affiliated with microCMS.

How do I install it quickly?

Use npm i -g @mrmtsu/mcms-cli and run microcms --help.

Why are there different names (mcms-cli, @mrmtsu/mcms-cli, microcms)?

mcms-cli is the repository/storage identifier, @mrmtsu/mcms-cli is the npm package, and microcms is the command for readability.

Auth

This MVP uses API keys (not OAuth).

# Recommended for CI/non-interactive:
export MICROCMS_SERVICE_DOMAIN=<service-domain>
export MICROCMS_API_KEY=<api-key>

# Optional: use a named profile
microcms auth profile add <profile-name> --service-domain <service-domain> --set-default
microcms auth profile list --json
# Note: profile add only saves the service domain. Save API key separately via login.
printf '%s' '<api-key>' | microcms auth login --profile <profile-name> --api-key-stdin

# Or store key in keychain:
printf '%s' '<api-key>' | microcms auth login --service-domain <service-domain> --api-key-stdin
# Interactive TTY prompt (hidden input):
microcms auth login --service-domain <service-domain> --prompt
microcms auth status --json

Resolution order for API key:

1. --api-key / --api-key-stdin
2. MICROCMS_API_KEY
3. OS keychain for selected profile (if available)
4. OS keychain entry for resolved service domain

Resolution order for service domain:

1. --service-domain
2. MICROCMS_SERVICE_DOMAIN
3. selected profile in config (--profile, MICROCMS_PROFILE, default profile)
4. config file value ($XDG_CONFIG_HOME/mcms-cli/config.json)

Commands

Core API operations

microcms api list --json
microcms api info <endpoint> --json
microcms member get <memberId> --json

microcms content list <endpoint> --json
microcms content list <endpoint> --all --json
microcms content get <endpoint> <id> --json
microcms content meta list <endpoint> --json
microcms content meta get <endpoint> <id> --json
microcms content status set <endpoint> <id> --status PUBLISH --json
microcms content created-by set <endpoint> <id> --member <memberId> --json
microcms content create <endpoint> --file payload.json --json
microcms content create <endpoint> --file payload.json --dry-run --json
microcms content update <endpoint> <id> --file payload.json --json
microcms content delete <endpoint> <id> --json
microcms content diff <endpoint> <id> --draft-key <draftKey> --json
microcms content export <endpoint> --out backup/notes.json --json
microcms content export <endpoint> --out backup/notes.csv --format csv --json
microcms content export --all --out backup/ --json
microcms content import <endpoint> --file backup/notes.json --json
microcms content import <endpoint> --file backup/notes.json --dry-run --json
microcms content import <endpoint> --file backup/notes.json --dry-run --strict-warnings --json
microcms content import <endpoint> --file backup/notes.json --upsert --interval 200 --json
microcms content bulk --file operations.json --json
microcms content bulk --file operations.json --dry-run --json
microcms content bulk --file operations.json --dry-run --validate-payload --json
microcms content bulk --file operations.json --dry-run --strict-warnings --json
microcms content bulk --file operations.json --stop-on-error --json
microcms content bulk --file operations.json --continue-on-error --json

microcms media list --json
microcms media list --limit 20 --image-only --file-name logo --json
microcms media list --token <token> --json
microcms media upload <path> --json
microcms media upload <path> --dry-run --json
microcms media delete --url <media-url> --json
microcms validate <endpoint> --file payload.json --json

• content export --all exports list APIs. Object APIs are skipped.
• content bulk --dry-run checks operation-file structure without API calls.
• Add --validate-payload (or --strict-warnings) when you want schema-based payload checks.

Docs and Agent references (no API key / service domain required)

microcms docs list --source auto --json
microcms docs get --category content-api --file "コンテンツ一覧取得API.md" --json
microcms search "content list" --scope all --json
microcms spec --json

• docs get: fetch official microCMS documentation markdown content.
• search: search command/spec references and docs metadata (titles/filenames), not full doc body.

Schema / Type helpers

microcms schema pull --out microcms-schema.json --json
microcms schema pull --format json-schema --out schema.json --json
microcms schema pull --format json-schema --include-extensions --out schema.json --json
microcms schema pull --format json-schema --endpoints blogs --out blogs-schema.json --json
microcms schema diff --baseline microcms-schema.json --json
microcms schema diff --baseline microcms-schema.json --exit-code --json
microcms types generate --schema microcms-schema.json --out microcms-types.d.ts --json
microcms types sync --out microcms-types.d.ts --json
microcms types sync --out microcms-types.d.ts --schema-out microcms-schema.json --json

--format json-schema uses @mrmtsu/microcms-schema-adapter to convert microCMS schemas to JSON Schema (draft-07).

If type generation is your primary goal, we recommend using wato787/microcms-cli. It provides strong coverage for complex schemas, including relation resolution, discriminated unions for repeaters, and recursive custom field typing.

Config and completion

microcms config doctor --json
microcms completion install zsh --json
microcms completion uninstall --json

Auth profile management

microcms auth profile list --json
microcms auth profile add <name> --service-domain <service> [--set-default] --json
microcms auth profile use <name> --json
microcms auth profile remove <name> --json

validate is schema-aware when API metadata is available (required/unknown/type/enum-like checks).

Global options:

• --json
• --plain
• --table
• --select <fields>
• --profile <name>
• --service-domain <serviceDomain>
• --api-key <apiKey> (less secure)
• --api-key-stdin
• --timeout <ms>
• --retry <count>
• --retry-max-delay <ms>
• --verbose
• --no-color

Completion scripts use dynamic endpoint suggestions via microcms completion endpoints (internal helper). --retry is applied to retry-safe requests (GET) by default.

JSON contract (v0)

Success:

{
  "ok": true,
  "data": {},
  "meta": {
    "requestId": null,
    "version": "0.x"
  }
}

Error:

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

error.details is included only when --verbose is enabled.

Exit codes

• 0: success
• 2: invalid input
• 3: auth error
• 4: permission error
• 5: network/timeout
• 6: conflict
• 1: unknown error

Development

npm install
npm run lint
npm run format:check
npm run typecheck
npm run test
npm run build

Notes

• api list/info and media list/upload use microCMS Management API.
• Default management API base URL is https://<serviceDomain>.microcms-management.io.
• You can override with MICROCMS_MANAGEMENT_API_BASE_URL.
• Content API base URL is https://<serviceDomain>.microcms.io.
• You can override content API base URL with MICROCMS_CONTENT_API_BASE_URL (primarily for tests).
• For contract tests without network, use MICROCMS_CONTENT_MOCK_FILE to run content CRUD against a local JSON fixture store.
• MICROCMS_*_BASE_URL overrides only allow localhost or microcms domains.
• Documentation commands use bundled microcms-document-mcp-server by default (no extra user setup required).
• docs, search, and spec do not require MICROCMS_API_KEY / MICROCMS_SERVICE_DOMAIN.
• search is for command/spec references and docs metadata (titles/filenames). Use docs get to read official documentation markdown content.
• You can override the MCP executable path with MICROCMS_DOC_MCP_COMMAND when needed.

Disclaimer

• This is an unofficial community project and is not affiliated with microCMS.
• The software is provided "as is" under the MIT License, without warranty.
• Validate behavior in your environment and take backups before production use.
• You are responsible for API key management and all operations executed with this CLI.

OSS Docs

• Contributing
• Security
• Changelog