---
title: "microCMS CLIを作ってみた"
canonical_url: "https://y-brew.vercel.app/tech/microcms-cli"
markdown_url: "https://y-brew.vercel.app/tech/microcms-cli/markdown"
blocks_url: "https://y-brew.vercel.app/tech/microcms-cli/blocks"
published: "2026-02-21"
updated: "2026-02-23"
last_reviewed: "2026-02-23"
tags: []
intent: ["case_study"]
evergreen: false
key_points: ["Agentic Coding時代におけるCMS操作のボトルネックとCLI導入意図", "--json出力と終了コード固定がAI自動化に効く理由", "validate/createの判定ズレなど、実運用で見えた改善ポイント", "実際にmedia listを追加したフィードバックループの記録"]
prerequisites: ["microCMSの基本概念（Content API / Management API）", "シェル/CLIの基本操作", "AIエージェント（Codex/Claude Codeなど）の利用経験があると読みやすい"]
section_headings: ["背景：Agentic CodingでCMSの使われ方が変わりつつある", "なぜAPIやMCPだけでなくCLIなのか", "CLIの概要", "コマンド体系", "設計で意識したこと", "最小の利用例", "AIエージェントに実際に触らせてみた", "やったこと", "うまくいったこと", "見つかった課題", "フィードバックから改善したこと", "この体験から感じたこと", "現時点でのまとめ"]
---

# microCMS CLIを作ってみた

## TL;DR
microCMS向けCLIを個人開発し、AIエージェント運用で有効だった設計（安定したJSON出力・終了コード設計・validate→createフロー）と、検証で見つかった課題（validateとcreateの差分、media list不足）を実例ベースで整理した検証ログです。

## Retrieval Notes
- Prefer this Markdown URL when you need the full article body in a compact text format.
- Prefer the block JSON at https://y-brew.vercel.app/tech/microcms-cli/blocks when you need article structure instead of prose.
- Cite the canonical HTML page at https://y-brew.vercel.app/tech/microcms-cli when linking to the source.
- Treat updated and last_reviewed as freshness signals.

## Key Points
- Agentic Coding時代におけるCMS操作のボトルネックとCLI導入意図
- --json出力と終了コード固定がAI自動化に効く理由
- validate/createの判定ズレなど、実運用で見えた改善ポイント
- 実際にmedia listを追加したフィードバックループの記録

## Prerequisites
- microCMSの基本概念（Content API / Management API）
- シェル/CLIの基本操作
- AIエージェント（Codex/Claude Codeなど）の利用経験があると読みやすい

## Section Guide
- 背景：Agentic CodingでCMSの使われ方が変わりつつある
- なぜAPIやMCPだけでなくCLIなのか
- CLIの概要
  - コマンド体系
  - 設計で意識したこと
  - 最小の利用例
- AIエージェントに実際に触らせてみた
  - やったこと
  - うまくいったこと
  - 見つかった課題
  - フィードバックから改善したこと
  - この体験から感じたこと
- 現時点でのまとめ

## Article

## 背景：Agentic CodingでCMSの使われ方が変わりつつある

Claude CodeやCodex、CursorといったAIエージェントが、開発ワークフローの中で直接コードを書き、ツールを操作する場面が増えてきた。いわゆるAgentic Codingと呼ばれる流れの中で、CMSもその操作対象になりつつある。

コンテンツの取得や作成、スキーマの確認、型の生成——これまで管理画面やAPIドキュメントを見ながら人間が手動で行っていた操作を、AIエージェントが開発の流れの中で自然に行うケースが出てきている。

microCMSにはマネジメントAPIが用意されているし、MCP（Model Context Protocol）サーバーも公式で提供されている。APIとしてのインターフェースはすでにある。ただ、CLIがなかった。AIエージェントがより効率的にmicroCMSを操作する手段として、CLIがあると便利ではないかと考え、個人開発で作ってみた。

## なぜAPIやMCPだけでなくCLIなのか

マネジメントAPIがあり、MCPサーバーもある中で、なぜCLIを作ったのか。いくつかの理由がある。

**シェルが叩ける環境なら動く。** MCPはクライアント側が対応している必要がある。対応状況はエージェントや環境によってまちまちで、使える場面が限られることがある。CLIはシェルさえあれば動くので、エージェントの種類を選ばない。実際に、今回Claude CodeとCodexの両方で同じCLIを使うことができた。

**1コマンド＝1操作の明確さ。** APIを叩くには、認証ヘッダーの設定、エンドポイントURLの構築、リクエストボディの組み立てが必要になる。CLIなら `microcms content list tech_articles --json` のように、コマンドライン一行で操作が完結する。AIエージェントにとって「何をすれば何が起きるか」が予測しやすい。

**パイプやスクリプトとの組み合わせ。** `microcms content list ... --json | jq '.items[0]'` のように、既存のUNIXツールチェインとそのまま組み合わせられる。AIエージェントはシェルスクリプトを書くのが得意なので、この親和性は実用上大きい。

**AIエージェント以外の用途にも使える。** MCPはAIエージェント専用のプロトコルだが、CLIはGitHub ActionsやデプロイスクリプトなどのCI/CDでもそのまま使える。一つのツールで用途が広い点は、作る側にとっても使う側にとってもメリットがある。

また、MCPサーバーを接続するとツール定義がコンテキストウィンドウに載るため、接続しているだけでトークンを消費する。CLIの場合は必要なときにコマンドを実行するだけなので、コンテキストへの影響が比較的小さいという側面もある。

## CLIの概要

### コマンド体系

`auth` / `api` / `content` / `media` の基本操作に加え、`schema pull` と `types generate` による型生成フロー、`validate` による投稿前の軽量チェック、`docs` / `search` / `spec` による参照系操作を備えている。

参照系（`docs` / `search` / `spec`）はMCPを内部的に利用する構成にしており、APIキーなしで使える。

### 設計で意識したこと

AIエージェントから使われることを前提に、2つのことを意識した。

-   `--json` **出力を安定させる。** 成功時は `{"ok":true,"data":...,"meta":...}`、失敗時は `{"ok":false,"error":{"code","message","retryable"...},"meta":...}` というトップレベル構造を固定している。エージェントが `ok` を見て分岐し、`error.code` でハンドリングできるようにした。
-   **失敗時の終了コードを固定する。** エージェントがシェルスクリプトの中でエラーハンドリングの分岐を書きやすいようにしている。

### 最小の利用例

```bash
# API確認
microcms api list --json

# コンテンツ確認
microcms content list tech_articles --json

# 投稿前の軽量チェック
microcms validate tech_articles --file payload.json --json

# 公式ドキュメント参照（APIキー不要）
microcms docs list --json
microcms docs get --category content-api --file "コンテンツ一覧取得API.md"
```

## AIエージェントに実際に触らせてみた

CLIを作っただけでは「AIエージェントに向いているはず」という仮説にすぎない。実際にエージェントに触らせてみて、何が起きるかを確認した。

### やったこと

Codexに対して、CLIを使ったmicroCMSへの入稿ワークフローを一通り試させた。具体的には以下の操作を行った。

-   `config doctor` で環境確認
-   `api list` / `api info` でAPI構造の把握
-   `validate` で投稿前のペイロード検証
-   `content create` / `content update` でコンテンツの作成・更新
-   `content list` / `content get` で結果の確認
-   `media upload` でメディアファイルのアップロード
    

### うまくいったこと

**JSON出力の構造が一定であること**が、エージェントの自動化にとって大きかった。Codexは `ok` フィールドを見て成功・失敗を判断し、失敗時は `error.code` でハンドリングするスクリプトを自然に書いていた。出力構造が安定しているおかげで、エージェント側のパース処理が壊れにくい。

`api info` **→** `validate` **→** `content create` **の流れがシンプル**だった点も良かった。エージェントがスキーマを確認し、ペイロードを検証してから投稿する、という入稿ワークフローを自然に組み立てていた。

また、失敗時に `--verbose` を付けるとAPIの生メッセージ（例：`has unexpected data type`）まで見えるため、エージェントが原因を特定して次の一手を考えやすかった。

### 見つかった課題

`validate` **と** `content create` **の型判定にズレがあった。** 具体的には、セレクトフィールドに `kind: ["learning"]` を送ると、`validate` は `Field type mismatch: kind expected string` で失敗するが、`content create` は成功するケースがあった。逆に `kind: "learning"` で `content create` すると、API側で `has unexpected data type` が返った。事前検証のルールと実APIの受理条件が一致していない場面がある。

`media list` **コマンドがなかった。** 既存メディアのURLを確認したい場面で、CLIだけでは完結できなかった。結果的にMCPサーバーの `microcms_get_media` を補助的に使って対応した。CLIだけでワークフローを完結させるには、一覧取得も必要だという気づきだった。

**ネットワークエラーのメッセージが粗い。** 通信の揺れが `UNKNOWN_ERROR: fetch failed` にまとまることがあり、原因の切り分けがしづらい場面があった。`--retry 5 --timeout 20000` を付けることで安定したが、エラーメッセージ自体の粒度は改善の余地がある。

### フィードバックから改善したこと

Codexとのやり取りで見つかった `media list` の不足は、実際にコマンドを追加して対応した。CLIだけでメディアの一覧取得からアップロード、コンテンツ作成までを完結できるようになった。

この改善は、自分だけで使っていたら気づかなかったかもしれない。エージェントに一通りのワークフローを通させることで「ここが足りない」が具体的に見えた、というのは収穫だった。

### この体験から感じたこと

AIエージェントにCLIを触らせてみて感じたのは、**出力の予測可能性**が想像以上に重要だということ。JSON構造が固定されていること、終了コードが定義されていること、`--verbose` で詳細が見えること——これらがあるとエージェントは自律的にエラーハンドリングを組み立てられる。逆にこれが不安定だと、エージェントの挙動も不安定になる。

もう一つは、**エージェントに実際に使わせることが最良のテスト**だということ。人間が使うときには気にならない粒度の問題（`media list` がない、`validate` と `create` の整合性など）が、エージェントのワークフローでは明確なブロッカーになる。「AIフレンドリー」を謳うなら、AIに実際に触らせてみるのが一番早い。

## 現時点でのまとめ

このCLIはまだ検証段階にある。ただ、実際にAIエージェントに触らせてみたことで、「CMSにとってAIフレンドリーなインターフェースとは何か」について、いくつかの感触を得ることができた。

出力構造の安定性、コマンド体系の明確さ、エラー情報の粒度——こうした地味な部分が、AIエージェントにとっての使いやすさを左右する。派手な機能よりも、予測可能性の高さが重要だと感じている。

Agentic Codingの流れは今後も加速していくと思う。その中でCMSの操作がどう変わっていくのか、引き続き実運用の中で観察していきたい。

* * *

-   microCMS 公式ドキュメント: [https://document.microcms.io/](https://document.microcms.io/)
-   npm: [https://www.npmjs.com/package/@mrmtsu/mcms-cli](https://www.npmjs.com/package/@mrmtsu/mcms-cli)
-   GitHub: [https://github.com/mrmtsu/mcms-cli](https://github.com/mrmtsu/mcms-cli)