Skip to content
SupaCMS Docs

AI エージェントからの操作

supacms CLI はサブコマンド形式・JSON 出力に特化しており、AI エージェント（Claude など）からの操作に向いています。 このページでは、AI にスキーマ定義を任せるための推奨プロンプトと典型的なワークフローを紹介します。

なぜ CLI が AI に向いているか

観点CLI（supacms）Web UI
操作方法コマンド一発ブラウザ操作
出力JSON（parse 可能）HTML
エラー終了コード + JSONダイアログ
自動化スクリプト化可能不可

システムプロンプト（推奨テンプレート）

AI にスキーマ管理を任せるときは、以下のスニペットをシステムプロンプトまたは会話の冒頭に含めてください。

あなたは SupaCMS のコンテンツ管理アシスタントです。
以下の CLI ツールを使ってコンテンツタイプ・フィールド・メディア・エントリを操作してください。


## 設定
- SUPACMS_API_KEY: ${SUPACMS_API_KEY}
- 対象スペース: <SPACE_SLUG>


各コマンドに --api-key $SUPACMS_API_KEY を付けるか、環境変数 SUPACMS_API_KEY を設定してください。


## CLI の基本コマンド


# ContentType の作成
supacms content-type create --space <slug> --name <名前> --api-id <apiId> --api-key <key>


# ContentType の一覧
supacms content-type list --space <slug> --api-key <key>


# フィールドの追加
supacms field add \
  --space <slug> \
  --content-type <contentTypeApiId> \
  --name <名前> --api-id <apiId> \
  --type <タイプ> [--required] [--config '<JSON>'] \
  --api-key <key>


# フィールドの一覧
supacms field list --space <slug> --content-type <contentTypeApiId> --api-key <key>


# メディアのアップロード
supacms media upload --space <slug> --file <パス> [--alt <代替テキスト>] --api-key <key>


# メディアの一覧
supacms media list --space <slug> --api-key <key>


# エントリの作成（常に draft）
supacms entry create --space <slug> --content-type <contentTypeApiId> --data '<JSON>'


# エントリの一覧
supacms entry list --space <slug> --content-type <contentTypeApiId> [--status draft|published]


# エントリの更新
supacms entry update --space <slug> --content-type <contentTypeApiId> --id <entryId> --data '<JSON>'


# エントリの公開 / 非公開
supacms entry publish   --space <slug> --content-type <contentTypeApiId> --id <entryId>
supacms entry unpublish --space <slug> --content-type <contentTypeApiId> --id <entryId>


# エントリの削除
supacms entry delete --space <slug> --content-type <contentTypeApiId> --id <entryId>


## フィールドタイプ
short_text / long_text / rich_text / integer / decimal / boolean / datetime / json / url / media


## ルール
- 操作前に必ず現在の状態を確認してください（list コマンドで取得）
- apiId は英字始まり・英数字とアンダースコアのみ（例: blogPost, publishedAt）
- 同じ apiId が既に存在する場合はエラーになります（重複チェックを行うこと）
- エントリは作成後 publish コマンドで公開するまで draft 状態です
- 出力は JSON なので jq などでパースして確認できます
- media フィールドに画像を紐づける場合は先に media upload でアップロードしてください

タスク別プロンプト例

新しいコンテンツタイプを設計・作成させる

「myblog」スペースにブログ記事のコンテンツタイプを作成してください。
必要なフィールドを考えて全て追加してください。

AI はまず content-type list で現状を確認し、ContentType を作成してフィールドを追加します。

既存のスキーマにフィールドを追加させる

「myblog」スペースの「blogPost」コンテンツタイプに
SEO 用のメタディスクリプション（最大 160 文字）フィールドを追加してください。

スキーマをまるごと移行させる

以下の定義に従ってスペース「ecommerce」にコンテンツタイプとフィールドを作成してください。


## 商品（product）
- 商品名（name）: short_text, 必須, 最大 100 文字
- 説明（description）: long_text
- 価格（price）: decimal, 必須
- 在庫あり（inStock）: boolean, デフォルト true
- 公開日（publishedAt）: datetime


## カテゴリ（category）
- カテゴリ名（name）: short_text, 必須
- スラッグ（slug）: short_text, 必須


まず現在のスペースの状態を確認してから実行してください。

エントリを作成して公開させる

「myblog」スペースの「blogPost」コンテンツタイプに
以下の内容でエントリを作成し、公開してください。


タイトル: はじめての記事
本文: SupaCMS を使ってみました。とても使いやすいです。

AI はエントリを作成（draft）→ 内容を確認 → publish の順で操作します。

複数のエントリをまとめてインポートさせる

以下のデータを「myblog」スペースの「blogPost」コンテンツタイプに
エントリとして一括作成してください。作成後はすべて公開状態にしてください。


[
  {"title": "記事1", "body": "本文1"},
  {"title": "記事2", "body": "本文2"},
  {"title": "記事3", "body": "本文3"}
]

ワークフロースクリプト例

AI に渡すのではなく、定義済みスキーマをスクリプトでべき等に適用する場合の参考例です。

scripts/apply-schema.sh
#!/usr/bin/env bash
# スキーマ定義をべき等に適用するスクリプト例


set -euo pipefail


SPACE="${SUPACMS_SPACE:-myblog}"
CLI="bun run apps/cli/src/index.ts"


# ContentType が存在しなければ作成（エラーを無視して list で確認する方式）
create_ct_if_missing() {
  local name="$1" api_id="$2" description="${3:-}"
  local existing
  existing=$($CLI content-type list --space "$SPACE" | \
    jq -r ".[] | select(.apiId == \"$api_id\") | .apiId")


  if [ -z "$existing" ]; then
    echo "ContentType 作成: $api_id"
    $CLI content-type create \
      --space "$SPACE" \
      --name "$name" \
      --api-id "$api_id" \
      ${description:+--description "$description"}
  else
    echo "ContentType スキップ（既存）: $api_id"
  fi
}


# Field が存在しなければ追加
add_field_if_missing() {
  local ct_api_id="$1" name="$2" api_id="$3" type="$4"
  shift 4
  local existing
  existing=$($CLI field list --space "$SPACE" --content-type "$ct_api_id" | \
    jq -r ".[] | select(.apiId == \"$api_id\") | .apiId")


  if [ -z "$existing" ]; then
    echo "  Field 追加: $api_id ($type)"
    $CLI field add \
      --space "$SPACE" \
      --content-type "$ct_api_id" \
      --name "$name" \
      --api-id "$api_id" \
      --type "$type" \
      "$@"
  else
    echo "  Field スキップ（既存）: $api_id"
  fi
}


# ---- スキーマ定義 ----


create_ct_if_missing "ブログ記事" "blogPost" "ブログの記事コンテンツ"


add_field_if_missing blogPost "タイトル"   title       short_text --required --config '{"maxLength":200}'
add_field_if_missing blogPost "本文"       body        rich_text  --required
add_field_if_missing blogPost "公開日"     publishedAt datetime   --config '{"includeTime":false}'
add_field_if_missing blogPost "スラッグ"   slug        short_text --required --config '{"maxLength":100}'


echo "完了"

実行方法：

Terminal window
# 環境変数を事前にエクスポートしている場合
SUPACMS_SPACE=myblog bash scripts/apply-schema.sh


# または直接渡す場合
SUPACMS_URL=https://your-supacms.com \
SUPACMS_API_KEY=sk-... \
SUPACMS_SPACE=myblog \
  bash scripts/apply-schema.sh

Claude に渡す MCP / ツール設定のヒント

Claude Code から直接操作させる場合は、シェルコマンドを実行させるだけで機能します。

# 環境変数が設定済みであれば Claude Code 上でそのまま実行できます
! bun run apps/cli/src/index.ts content-type list --space myblog --pretty

よくあるエラーと対処

エラー原因対処
UnauthorizedAPIキーが無効または対象スペースと一致しないキーとスペース slug を確認
apiId already exists同じ apiId が既に存在するfield list / content-type list で確認してからスキップ
Invalid request body--config の JSON が不正、または必須パラメータ不足--type とそれに対応した config を確認
Not Foundスペース slug や content-type apiId が間違っているcontent-type list で正しい値を確認
Invalid file type対応していない MIME タイプのファイルJPEG / PNG / GIF / WebP / SVG のいずれかを使用
File too largeファイルサイズが 10MB を超えているファイルを圧縮・リサイズしてから再試行
必須フィールド "xxx" が存在しませんエントリの必須フィールドが --data に含まれていないfield list でフィールド定義を確認し required フィールドをすべて含める
エントリのステータス遷移が不正ですすでに published なエントリを再度 publish しようとしたentry list でステータスを確認してから操作する