mcms-cli

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:

--api-key / --api-key-stdin
MICROCMS_API_KEY
OS keychain for selected profile (if available)
OS keychain entry for resolved service domain

Resolution order for service domain:

--service-domain
MICROCMS_SERVICE_DOMAIN
selected profile in config (--profile, MICROCMS_PROFILE, default profile)
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 when --verbose is enabled. For payload validation failures (validate, content import/content bulk with payload checks), error.details is always included to make CI diagnostics easier.

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.

Name		Name	Last commit message	Last commit date
Latest commit History 65 Commits
.github		.github
skills/mcms-cli		skills/mcms-cli
src		src
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
.oxfmtrc.json		.oxfmtrc.json
CHANGELOG.ja.md		CHANGELOG.ja.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.ja.md		README.ja.md
README.md		README.md
SECURITY.md		SECURITY.md
package-lock.json		package-lock.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

mcms-cli

Naming

Install

Agent Skill

FAQ

Is this the official microCMS CLI?

How do I install it quickly?

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

Auth

Commands

Core API operations

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

Schema / Type helpers

Config and completion

Auth profile management

JSON contract (v0)

Exit codes

Development

Notes

Disclaimer

OSS Docs

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

License

mrmtsu/mcms-cli

Folders and files

Latest commit

History

Repository files navigation

mcms-cli

Naming

Install

Agent Skill

FAQ

Is this the official microCMS CLI?

How do I install it quickly?

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

Auth

Commands

Core API operations

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

Schema / Type helpers

Config and completion

Auth profile management

JSON contract (v0)

Exit codes

Development

Notes

Disclaimer

OSS Docs

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

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

Packages