Tech Article

公開 2026年3月3日

更新 2026年3月4日

microCMS CLI v0.4.0：運用・自動化のための6機能を追加

microCMS CLI v0.4.0で追加した6機能（content export/import、schema diff、content diff、content bulk、types sync）の概要と、既存APIの組み合わせで運用・自動化を実現する設計意図を解説。

Prerequisites

- 前回記事「microCMS CLIを作ってみた」の内容
- microCMSの基本概念（Content API / Management API）
- シェル/CLIの基本操作

Key Points

- 既存API変更なし・CLI側ロジックのみで運用機能を実現する設計制約
- export/importによるデータ移行、schema diffによるCI連携、content diffによるレビューワークフロー
- content bulkの操作定義ファイルによる作業のコード化
- 機能の組み合わせで想定するワークフロー例（CI、環境移行、コンテンツレビュー）

はじめに

以前、microCMS向けのCLI（mcms-cli）を個人開発で作り、AIエージェントに触らせてみた体験を記事にしました。そのときのCLIは、コンテンツのCRUD、スキーマ取得、型生成、メディア操作といった基本操作を一通りカバーしている状態でした。

v0.4.0では、その基本操作の上に「運用・自動化・開発体験」を改善する6つの機能を追加した。この記事では、各機能の概要と、なぜこれらを追加したのかの背景をまとめました。

共通の設計方針

今回追加した6機能には共通の制約（microCMS側のAPI追加や変更を前提としないこと）があります。
すべて既存のContent APIとManagement APIの組み合わせと、CLI側のロジックだけで実現しています。

結果として、APIが提供する情報をCLI側で組み合わせ、加工し、運用に使える形にするというアプローチに統一しました。

また、v0.3.x以前から維持している設計方針はそのまま引き継いでいます。

--json 出力は { ok, data, meta } / { ok, error, meta } の構造を固定
書き込み系コマンドはすべて --dry-run をサポート
--json / --plain / --table の出力モードを統一
連続API呼び出し時のインターバル制御を共通ユーティリティとして実装

content export：コンテンツ一括エクスポート

なぜ作ったか

microCMSにはコンテンツの一括ダウンロード機能がありません。

たとえば、バックアップ、環境移行（ステージングから本番へ）、データ分析の起点として、全コンテンツをローカルファイルに書き出す手段があるといいのかと思いました。

特にAIエージェントとの連携を考えると、コンテンツを一括でローカルに持ってきて、加工してから書き戻すというワークフローは自然に発生しそうです。その入口としてexportが必要なのかと思いました。

使い方

# 特定エンドポイントのエクスポート
microcms content export tech_articles --out contents.json --json

# CSV形式で出力
microcms content export tech_articles --out contents.csv --format csv --json

# 全エンドポイントを一括エクスポート（list APIのみ、object APIはスキップ）
microcms content export --all --out backup/ --json

実現方法

既存の content list --all のページネーションロジックを再利用しています。

listContent() を totalCount まで繰り返し呼び出し、結果をマージしてJSON / CSV形式で書き出します。

--all フラグでは、Management APIのエンドポイント一覧取得を組み合わせて全エンドポイントを順次処理してます。

content import：コンテンツ一括インポート

なぜ作ったか

content export の対になる機能。

環境間でのデータ移行、初期データセットアップ、テストデータ投入を1コマンドで完結させるために作りました。

手作業で content create を繰り返す運用を排除する意図です。

使い方

# インポート
microcms content import tech_articles --file contents.json --json

# dry-run（バリデーションのみ）
microcms content import tech_articles --file contents.json --dry-run --json

# upsert（既存があれば更新、なければ作成）
microcms content import tech_articles --file contents.json --upsert --json

実現方法

content export の出力形式をそのまま読み込み、各アイテムに対して createContent() を順次呼び出します。

--upsert 指定時は id の存在有無で updateContent() と createContent() を切り替えます。

レート制限を考慮したインターバル制御と、[3/50] Created: article-001 のような進捗表示にも対応しています。

--strict-warnings オプションで警告をエラーとして扱うこともでき、非JSON入力時の進捗表示にも対応しました。

schema diff：スキーマ変更検知

なぜ作ったか

microCMSの管理画面でフィールドを追加・削除・変更したとき、フロントエンドの型定義やバリデーションとの乖離に気づけないことがあります。

管理画面での操作はコードのdiffとして残らないため、スキーマの変更が暗黙的に行われてしまう懸念があります。

たとえば、CIに組み込むことで「スキーマ変更に起因する型エラー」を未然に防ぐ、というのがこともできるのかと思い作りました。

使い方

# ベースラインとの差分を確認
microcms schema diff --baseline microcms-schema.json --json

# 差分があればexit 1（CI用）
microcms schema diff --baseline microcms-schema.json --exit-code --json

実現方法

--baseline で指定したローカルJSONファイル（schema pull の出力）と、Management APIから取得した現在のリモートスキーマをフィールド単位で比較します。

追加・削除・変更（kind、required、allowed valuesなど）を検出し、差分を出力します。

--exit-code フラグを使えば、差分がある場合にexit code 1を返します。

GitHub ActionsなどのCIパイプラインに組み込んで、スキーマ変更を自動的にキャッチできるようになります。

content diff：本番 vs 下書き差分表示

なぜ作ったか

microCMSの下書きプレビュー機能を使う運用で、「下書きで何が変わったか」をレビューする手段がダッシュボード以外にはありません。

フィールド単位の差分をCLIで確認できれば、コンテンツの変更にもコードレビュー的なワークフローを適用できるのかと思い作りました。

使い方

# 本番と下書きの差分を表示
microcms content diff tech_articles article-001 --draft-key abc123 --json

実現方法

本番コンテンツと下書きコンテンツをそれぞれContent APIから取得し、フィールド単位で比較します。

下書き取得には draftKey パラメータを使います。

--json 出力時は { added, removed, changed } の構造で返し、plain/table出力時はdiff風の可読形式で表示します。

content bulk：一括操作

なぜ作ったか

複数コンテンツの作成・更新・削除・ステータス変更を、1つの操作定義ファイルにまとめて実行したかったからです。

マイグレーション、初期データ投入、一括ステータス変更など、手順書ベースで行っていた作業をコードとして管理・再現可能にする機能として使えるのかと思います。

使い方

# 操作定義ファイルを実行
microcms content bulk --file operations.json --json

# dry-run（バリデーションのみ、API呼び出しなし）
microcms content bulk --file operations.json --dry-run --json

操作定義ファイルは以下のような形式。

{
  "operations": [
    { "action": "create", "endpoint": "blogs", "payload": { "title": "New Post" } },
    { "action": "update", "endpoint": "blogs", "id": "abc123", "payload": { "title": "Updated" } },
    { "action": "delete", "endpoint": "blogs", "id": "old-post" },
    { "action": "status", "endpoint": "blogs", "id": "abc123", "status": "PUBLISH" }
  ]
}

実現方法

操作定義JSONをZodでバリデーションし、各操作を順次実行します。

--dry-run 時はバリデーションのみ実行し、--validate-payload を指定した場合のみスキーマ照合も行います。

失敗時の挙動は --stop-on-error（明示指定時）と --continue-on-error の両方をサポートしました。

結果は { succeeded, failed, skipped, results } のサマリー形式で返します。

types sync：スキーマ取得＋型生成のワンコマンド化

なぜ作ったか

これまで型定義を更新するには schema pull → types generate の2ステップが必要になっていました。

開発中に「スキーマ変更→型更新」のサイクルを何度も回す場面では、これを1コマンドに統合したかったからになります。

使い方

# スキーマ取得と型生成を一度に
microcms types sync --out microcms-types.d.ts --json

# スキーマJSONも同時に保存（schema diffとの連携用）
microcms types sync --out microcms-types.d.ts --schema-out microcms-schema.json --json

実現方法

内部で schema pull 相当の処理を実行し、取得したスキーマを直接 types generate 相当のロジックに渡します。

--schema-out 指定時はスキーマJSONもファイル保存するので、schema diff のベースラインとしてそのまま使えます。

機能の組み合わせ：想定しているワークフロー

今回追加した6機能は、単体で使うこともできますが、組み合わせることで運用ワークフローが組み立てられるように意識して設計しました。

いくつか例を挙げると・・・

CI連携：スキーマ変更の自動検知

# 開発開始時にスキーマと型を同期
microcms types sync --out src/types/microcms.d.ts --schema-out microcms-schema.json

# CIでスキーマ変更を検知
microcms schema diff --baseline microcms-schema.json --exit-code --json

types sync で生成したスキーマJSONをリポジトリにコミットしておき、CIで schema diff --exit-code を実行します。

管理画面でフィールドが変更された場合、CIが失敗して気づけるようになります。

環境移行：ステージングから本番へ

# ステージング環境のコンテンツをエクスポート
MICROCMS_API_KEY=staging_key microcms content export blogs --out staging-data.json --json

# 本番環境にインポート
MICROCMS_API_KEY=prod_key microcms content import blogs --file staging-data.json --upsert --json

コンテンツレビュー：下書きの差分確認

# 下書きの変更内容を確認
microcms content diff blogs article-001 --draft-key abc123 --json

# 問題なければステータスを変更
microcms content bulk --file publish-operations.json --json

まとめ

v0.4.0では、CLIの役割を「基本操作のインターフェース」から「運用・自動化のツール」に一歩広げるようなイメージで作りました。

前回の記事で「出力の予測可能性が重要」と書いたのですが、今回の6機能でもその方針は維持しています。

引き続き、実際の運用の中で足りないものを見つけて改善していきたいなと思っています。

npm: https://www.npmjs.com/package/@mrmtsu/mcms-cli
GitHub: https://github.com/mrmtsu/mcms-cli
前回の記事: microCMS CLIを作ってみた

Tech Article

公開 2026年3月3日

更新 2026年3月4日

microCMS CLI v0.4.0：運用・自動化のための6機能を追加

Prerequisites

- 前回記事「microCMS CLIを作ってみた」の内容
- microCMSの基本概念（Content API / Management API）
- シェル/CLIの基本操作

Key Points

- 既存API変更なし・CLI側ロジックのみで運用機能を実現する設計制約
- export/importによるデータ移行、schema diffによるCI連携、content diffによるレビューワークフロー
- content bulkの操作定義ファイルによる作業のコード化
- 機能の組み合わせで想定するワークフロー例（CI、環境移行、コンテンツレビュー）

はじめに

共通の設計方針

結果として、APIが提供する情報をCLI側で組み合わせ、加工し、運用に使える形にするというアプローチに統一しました。

また、v0.3.x以前から維持している設計方針はそのまま引き継いでいます。

--json 出力は { ok, data, meta } / { ok, error, meta } の構造を固定
書き込み系コマンドはすべて --dry-run をサポート
--json / --plain / --table の出力モードを統一
連続API呼び出し時のインターバル制御を共通ユーティリティとして実装

content export：コンテンツ一括エクスポート

なぜ作ったか

microCMSにはコンテンツの一括ダウンロード機能がありません。

使い方

# 特定エンドポイントのエクスポート
microcms content export tech_articles --out contents.json --json

# CSV形式で出力
microcms content export tech_articles --out contents.csv --format csv --json

# 全エンドポイントを一括エクスポート（list APIのみ、object APIはスキップ）
microcms content export --all --out backup/ --json

実現方法

既存の content list --all のページネーションロジックを再利用しています。

listContent() を totalCount まで繰り返し呼び出し、結果をマージしてJSON / CSV形式で書き出します。

--all フラグでは、Management APIのエンドポイント一覧取得を組み合わせて全エンドポイントを順次処理してます。

content import：コンテンツ一括インポート

なぜ作ったか

content export の対になる機能。

環境間でのデータ移行、初期データセットアップ、テストデータ投入を1コマンドで完結させるために作りました。

手作業で content create を繰り返す運用を排除する意図です。

使い方

# インポート
microcms content import tech_articles --file contents.json --json

# dry-run（バリデーションのみ）
microcms content import tech_articles --file contents.json --dry-run --json

# upsert（既存があれば更新、なければ作成）
microcms content import tech_articles --file contents.json --upsert --json

実現方法

content export の出力形式をそのまま読み込み、各アイテムに対して createContent() を順次呼び出します。

--upsert 指定時は id の存在有無で updateContent() と createContent() を切り替えます。

レート制限を考慮したインターバル制御と、[3/50] Created: article-001 のような進捗表示にも対応しています。

--strict-warnings オプションで警告をエラーとして扱うこともでき、非JSON入力時の進捗表示にも対応しました。

schema diff：スキーマ変更検知

なぜ作ったか

microCMSの管理画面でフィールドを追加・削除・変更したとき、フロントエンドの型定義やバリデーションとの乖離に気づけないことがあります。

管理画面での操作はコードのdiffとして残らないため、スキーマの変更が暗黙的に行われてしまう懸念があります。

たとえば、CIに組み込むことで「スキーマ変更に起因する型エラー」を未然に防ぐ、というのがこともできるのかと思い作りました。

使い方

# ベースラインとの差分を確認
microcms schema diff --baseline microcms-schema.json --json

# 差分があればexit 1（CI用）
microcms schema diff --baseline microcms-schema.json --exit-code --json

実現方法

追加・削除・変更（kind、required、allowed valuesなど）を検出し、差分を出力します。

--exit-code フラグを使えば、差分がある場合にexit code 1を返します。

GitHub ActionsなどのCIパイプラインに組み込んで、スキーマ変更を自動的にキャッチできるようになります。

content diff：本番 vs 下書き差分表示

なぜ作ったか

microCMSの下書きプレビュー機能を使う運用で、「下書きで何が変わったか」をレビューする手段がダッシュボード以外にはありません。

フィールド単位の差分をCLIで確認できれば、コンテンツの変更にもコードレビュー的なワークフローを適用できるのかと思い作りました。

使い方

# 本番と下書きの差分を表示
microcms content diff tech_articles article-001 --draft-key abc123 --json

実現方法

本番コンテンツと下書きコンテンツをそれぞれContent APIから取得し、フィールド単位で比較します。

下書き取得には draftKey パラメータを使います。

--json 出力時は { added, removed, changed } の構造で返し、plain/table出力時はdiff風の可読形式で表示します。

content bulk：一括操作

なぜ作ったか

複数コンテンツの作成・更新・削除・ステータス変更を、1つの操作定義ファイルにまとめて実行したかったからです。

使い方

# 操作定義ファイルを実行
microcms content bulk --file operations.json --json

# dry-run（バリデーションのみ、API呼び出しなし）
microcms content bulk --file operations.json --dry-run --json

操作定義ファイルは以下のような形式。

{
  "operations": [
    { "action": "create", "endpoint": "blogs", "payload": { "title": "New Post" } },
    { "action": "update", "endpoint": "blogs", "id": "abc123", "payload": { "title": "Updated" } },
    { "action": "delete", "endpoint": "blogs", "id": "old-post" },
    { "action": "status", "endpoint": "blogs", "id": "abc123", "status": "PUBLISH" }
  ]
}

実現方法

操作定義JSONをZodでバリデーションし、各操作を順次実行します。

--dry-run 時はバリデーションのみ実行し、--validate-payload を指定した場合のみスキーマ照合も行います。

失敗時の挙動は --stop-on-error（明示指定時）と --continue-on-error の両方をサポートしました。

結果は { succeeded, failed, skipped, results } のサマリー形式で返します。

types sync：スキーマ取得＋型生成のワンコマンド化

なぜ作ったか

これまで型定義を更新するには schema pull → types generate の2ステップが必要になっていました。

開発中に「スキーマ変更→型更新」のサイクルを何度も回す場面では、これを1コマンドに統合したかったからになります。

使い方

# スキーマ取得と型生成を一度に
microcms types sync --out microcms-types.d.ts --json

# スキーマJSONも同時に保存（schema diffとの連携用）
microcms types sync --out microcms-types.d.ts --schema-out microcms-schema.json --json

実現方法

内部で schema pull 相当の処理を実行し、取得したスキーマを直接 types generate 相当のロジックに渡します。

--schema-out 指定時はスキーマJSONもファイル保存するので、schema diff のベースラインとしてそのまま使えます。

機能の組み合わせ：想定しているワークフロー

今回追加した6機能は、単体で使うこともできますが、組み合わせることで運用ワークフローが組み立てられるように意識して設計しました。

いくつか例を挙げると・・・

CI連携：スキーマ変更の自動検知

# 開発開始時にスキーマと型を同期
microcms types sync --out src/types/microcms.d.ts --schema-out microcms-schema.json

# CIでスキーマ変更を検知
microcms schema diff --baseline microcms-schema.json --exit-code --json

types sync で生成したスキーマJSONをリポジトリにコミットしておき、CIで schema diff --exit-code を実行します。

管理画面でフィールドが変更された場合、CIが失敗して気づけるようになります。

環境移行：ステージングから本番へ

# ステージング環境のコンテンツをエクスポート
MICROCMS_API_KEY=staging_key microcms content export blogs --out staging-data.json --json

# 本番環境にインポート
MICROCMS_API_KEY=prod_key microcms content import blogs --file staging-data.json --upsert --json

コンテンツレビュー：下書きの差分確認

# 下書きの変更内容を確認
microcms content diff blogs article-001 --draft-key abc123 --json

# 問題なければステータスを変更
microcms content bulk --file publish-operations.json --json

まとめ

v0.4.0では、CLIの役割を「基本操作のインターフェース」から「運用・自動化のツール」に一歩広げるようなイメージで作りました。

前回の記事で「出力の予測可能性が重要」と書いたのですが、今回の6機能でもその方針は維持しています。

引き続き、実際の運用の中で足りないものを見つけて改善していきたいなと思っています。

npm: https://www.npmjs.com/package/@mrmtsu/mcms-cli
GitHub: https://github.com/mrmtsu/mcms-cli
前回の記事: microCMS CLIを作ってみた