microcms-cli

README

microcms-cli

microcms-cli は、microCMS の Content API と Management API をコマンドラインから扱うための Go 製 CLI です。 複数サービスの切り替え、API スキーマのキャッシュ、コンテンツ取得、運用情報の確認、バックアップを 1 つのツールにまとめます。

curl -fsSL https://raw.githubusercontent.com/hsblabs/microcms-cli/main/install.sh | sh

microcms service add
microcms service scan
microcms content list blogs --limit 5 --json
microcms management api schema blogs
microcms backup --out ./backup

🚀 Getting Started

前提条件

• microCMS のサービス ID
• Content API Key
• Management API を使う場合は Management API Key（Content API Keyと併用可能）
• Go 1.26 以降でのビルド環境、または GitHub Releases から取得できる配布バイナリ

インストール

インストーラスクリプト

curl -fsSL https://raw.githubusercontent.com/hsblabs/microcms-cli/main/install.sh | sh
microcms --help

特定バージョンを入れる場合:

curl -fsSL https://raw.githubusercontent.com/hsblabs/microcms-cli/main/install.sh | sh -s -- --version v0.1.0

ソースからビルド

git clone https://github.com/hsblabs/microcms-cli.git
cd microcms-cli
make build
./microcms --help

go install を使う場合

go install github.com/hsblabs/microcms-cli@latest
microcms-cli --help

go install で配置される実行ファイル名は microcms-cli です。README の他の例は、配布バイナリと make build の出力名に合わせて microcms を使っています。

クイックスタート

1. サービスを登録する

service add は対話形式でサービス ID と API キーを登録します。

microcms service add

API キーは設定ファイルに平文保存されず、暗号化された値を保存し、復号用の鍵は OS キーチェーンに保管します。

2. スキーマを取得して補完と検証に使う

microcms service scan

service scan は Management API から API 一覧とスキーマを取得し、ローカルキャッシュに保存します。これにより endpoint 名の補完や、content / management コマンドでの入力検証が効くようになります。

3. コンテンツを取得する

microcms content list blogs --limit 5 --json
microcms content get blogs abc123 --json

4. 運用情報を確認する

microcms management service get
microcms management api list
microcms management api schema blogs

5. バックアップする

microcms backup --out ./backup

✨ Features / Specification

コマンド体系

コマンド	役割
service add/list/use/current/remove/scan	サービス登録、切り替え、スキーマキャッシュ更新
content list/get	Content API からコンテンツを取得
management service/api/member/media/content meta	Management API から運用情報やスキーマを取得
backup	サービス全体のバックアップをローカルに保存
config get/set/list/unset	CLI 設定の参照・更新
completion	bash / zsh / fish / powershell 向け補完スクリプトを生成
uninstall	バイナリ、設定、キャッシュ、補完ファイルを削除

サービス管理

• 複数の microCMS サービスをローカルに登録できます。
• アクティブサービスを保持し、毎回 service ID を指定しなくても操作できます。
• --service を使うと、そのコマンドだけ別サービスを対象にできます。
• service scan により、API 一覧と各 endpoint のスキーマをキャッシュします。
• API キーは暗号化して保存し、一覧表示時もマスキングされます。

microcms service list
microcms service use my-blog
microcms service current
microcms service scan --force

Content API 操作

Content API はコンテンツ取得に特化しています。content 系コマンドは、--format / --json を明示しない場合でも JSON 出力を優先します。

microcms content list blogs --limit 10 --fields id,title,publishedAt
microcms content list blogs --filters 'category[equals]news' --orders -publishedAt
microcms content get banner
microcms content get blogs abc123

利用できる主なフラグ:

フラグ	説明
--limit	取得件数
--offset	オフセット
--fields	取得フィールドを絞り込み
--orders	ソート順
--filters	microCMS の filter 式

Management API 操作

Management API では、サービス運用やスキーマ確認に必要な情報を取得できます。

microcms management service get
microcms management api list
microcms management api schema blogs
microcms management member list
microcms management media list
microcms management content meta list blogs

Management 系コマンドは Management API Key を設定しておくのが安全です。未設定時は Content API Key を流用しますが、権限不足で失敗する可能性があります。

バックアップ

backup はアクティブサービスの内容をタイムスタンプ付きディレクトリに保存します。

microcms backup --out ./backup
microcms backup --out ./backup --download-media
microcms backup --out ./backup --dry-run
microcms backup --out ./backup --skip-schema

出力イメージ:

backup/
  <service-id>/
    20260422T1200Z/
      service.json
      apis.json
      manifest.json
      schemas/
        blogs.schema.json
      contents/
        blogs/
          index.json
          items/
            abc123.json
        banner/
          object.json
      media/
        index.json
        hero.jpg

バックアップの特徴:

• API ごとにコンテンツを分けて保存
• manifest.json に件数や実行結果を記録
• --download-media でメディア本体も取得
• --parallel で並列度を調整
• --dry-run で実行前に対象 API を確認

設定と自動化

設定は次の優先順位で解決されます。

1. 既定値
2. 設定ファイル
3. 環境変数
4. コマンドラインフラグ

設定ファイルの保存先:

• ~/.config/microcms/config.json
• ~/.config/microcms/service/*.json
• ~/.cache/microcms/scan/*.json

設定例:

{
  "activeService": "my-blog",
  "http": {
    "timeout": "45s"
  },
  "output": {
    "format": "json",
    "pretty": true,
    "color": "auto"
  },
  "scan": {
    "ttl": "24h"
  },
  "backup": {
    "parallelism": 8
  },
  "log": {
    "level": "info"
  }
}

主な環境変数:

環境変数	説明	既定値
MICROCMS_ACTIVE_SERVICE	アクティブサービス ID	なし
MICROCMS_HTTP_TIMEOUT	HTTP タイムアウト	30s
MICROCMS_HTTP_RETRY_ENABLED	リトライの有効化	true
MICROCMS_HTTP_RETRY_MAX_ATTEMPTS	最大リトライ回数	5
MICROCMS_FORMAT	既定の出力形式	table
MICROCMS_COLOR	色付き出力の制御	auto
MICROCMS_SCAN_TTL	スキャンキャッシュの TTL	24h
MICROCMS_BACKUP_PARALLELISM	バックアップ並列数	4
MICROCMS_LOG_LEVEL	ログレベル	info
MICROCMS_LOG_HTTP	HTTP ログの出力	false

共通フラグ:

フラグ	説明
-s, --service	対象サービスを一時的に上書き
--format	table, json, yaml を選択
--json	--format json のショートハンド
--verbose	詳細出力
-q, --quiet	非エラー出力を抑制
--debug	HTTP リクエストを含むデバッグ出力
--no-color	色付き出力を無効化
--no-input	対話入力を無効化
-f, --force	確認プロンプトをスキップ

シェル補完

補完スクリプトを生成できます。

microcms completion bash
microcms completion zsh
microcms completion fish
microcms completion powershell

例:

microcms completion zsh > "${fpath[1]}/_microcms"

🤝 Contributing

開発用セットアップ:

git clone https://github.com/hsblabs/microcms-cli.git
cd microcms-cli
make build
go test ./...

リリース用のローカル確認:

make snapshot

不具合修正、ドキュメント改善、機能提案の Pull Request を歓迎します。

👥 Contributors

コントリビューション歓迎です。参加者一覧は GitHub の contributors graph を参照してください。

📄 License

MIT License です。