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

Claude などの AI エージェントに supacms CLI を使わせる方法と推奨プロンプト

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

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

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

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

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

## 設定
- SUPACMS_API_KEY: ${SUPACMS_API_KEY}
- 対象プロジェクト: <PROJECT_SLUG>

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

## CLI の基本コマンド

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

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

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

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

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

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

# エントリの作成（既定は draft。`--publish` で即時公開）
supacms entry create --project <slug> --content-type <contentTypeApiId> --data '<JSON>' [--publish] [--published-at <ISO8601>]

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

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

# エントリのシステム項目（公開日時）の更新
supacms entry system --project <slug> --content-type <contentTypeApiId> --id <entryId> --published-at <ISO8601>

# エントリの公開 / 非公開
supacms entry publish   --project <slug> --content-type <contentTypeApiId> --id <entryId> [--published-at <ISO8601>]
supacms entry unpublish --project <slug> --content-type <contentTypeApiId> --id <entryId>

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

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

## ルール
- 操作前に必ず現在の状態を確認してください（list コマンドで取得）
- apiId は英字始まり・英数字とアンダースコアのみ（例: blogPost, publishedAt）
- 同じ apiId が既に存在する場合はエラーになります（重複チェックを行うこと）
- エントリは作成後 publish コマンドで公開するまで draft 状態です。`--publish` を付ければ作成と同時に公開できます
- 公開中のエントリへの `entry update` は編集版として保存されるだけで、配信APIの出力は変わりません。反映するには `entry publish` をもう一度実行してください。レスポンスは配信中の内容（確定版）を返します
- システム側の `publishedAt`（エントリ直下。カスタムフィールドではない）は `entry system --published-at` で ISO 8601 日時を指定します。`entry create --publish --published-at` / `entry publish --published-at` は公開後に同じエンドポイントを呼びます
- すでに公開済みのエントリの公開日時を直す場合は `entry system --published-at` を使います
- 出力は 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 に渡すのではなく、定義済みスキーマをスクリプトでべき等に適用する場合の参考例です。

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

set -euo pipefail

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

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

  if [ -z "$existing" ]; then
    echo "ContentType 作成: $api_id"
    $CLI content-type create \
      --project "$PROJECT" \
      --name "$name" \
      --api-id "$api_id"
  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 --project "$PROJECT" --content-type "$ct_api_id" | \
    jq -r ".[] | select(.apiId == \"$api_id\") | .apiId")

  if [ -z "$existing" ]; then
    echo "  Field 追加: $api_id ($type)"
    $CLI field add \
      --project "$PROJECT" \
      --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 "完了"

実行方法：

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

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

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

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

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

Claude は JSON 出力をそのまま読み取れます。--pretty フラグなしの JSON を返すと、 Claude が次のコマンドの引数に自動的に使えます（例：取得した id を次の操作に渡す）。

よくあるエラーと対処