コマンドリファレンス

supacms CLI の全コマンド一覧と使い方

project

project info

supacms project info --project <slug> [--api-key <key>] [--pretty]

プロジェクトの名前・プロジェクトIDと、.env に設定すべき SUPACMS_API_URL の値を確認できます。

{
  "id": "01abc...",
  "slug": "supa-media",
  "name": "Supa Media",
  "apiBaseUrl": "https://cms.supa.ai"
}

api-key

初回のAPIキーはウェブUIから発行する必要があります（CLI の使いかたを参照）。 CLIの api-key コマンドは、既存のキーを使って追加のキーを管理する用途に使います。

api-key create

supacms api-key create --project <slug> --name <表示名>
  [--preset <editor|admin>]
  [--permissions <p1,p2,...>]

どちらも省略すると permission なしのキーになり、公開コンテンツ取得のみに使えます。permission の一覧は API の使いかたを参照してください。

editor はスキーマの変更（content-type create / content-type update / field add / field update）とAPIキーの発行を含みません。これらが必要な場合は admin を使ってください。

発行できる permission は発行元キーの範囲内に限られます。

supacms api-key create --project my-site --name "コンテンツ投入用" --preset editor
supacms api-key create --project my-site --name "スキーマ構築用" --preset admin
supacms api-key create --project my-site --name "配信用"

レスポンスに key フィールドが含まれます。このキーは作成時にしか確認できません。安全な場所に保管してください。

api-key list

supacms api-key list --project <slug>

content-type

content-type create

supacms content-type create \
  --project <slug> \
  --name <表示名> \
  --api-id <apiId>

apiId は英字で始まる英数字・アンダースコアの組み合わせ（例: blogPost、product_detail）。

content-type list

supacms content-type list --project <slug>

content-type update

supacms content-type update \
  --project <slug> \
  --api-id <現在のapiId> \
  --name <新しい表示名> \
  [--preview-url <URLテンプレート> | --clear-preview-url]

--preview-url には、管理画面の「画面プレビュー」で開くURLを指定します。http(s) で始まり {entryId} と {draftKey} の両方を含む必要があります（例: https://example.com/preview?id={entryId}&draftKey={draftKey}）。省略すると現在の設定を保ち、--clear-preview-url で削除します。

field

field add

supacms field add \
  --project <slug> \
  --content-type <contentTypeApiId> \
  --name <表示名> \
  --api-id <apiId> \
  --type <フィールドタイプ> \
  [--required] \
  [--config '<JSON>'] \
  [--ref-content-type-id <uuid>] \
  [--multiple]

--type reference の場合は --ref-content-type-id が必須です。--multiple を付けると複数参照が可能になります。 --type select の場合は --config に options 配列が必須です。--multiple を付けると複数選択が可能になります。 その他の --type に指定できる値とそれぞれの --config はフィールドタイプ一覧を参照してください。

field list

supacms field list \
  --project <slug> \
  --content-type <contentTypeApiId>

field update

supacms field update \
  --project <slug> \
  --content-type <contentTypeApiId> \
  --api-id <現在のfieldApiId> \
  --name <新しい表示名> \
  --type <フィールドタイプ> \
  [--new-api-id <新しいfieldApiId>] \
  [--required] \
  [--config '<JSON>'] \
  [--ref-content-type-id <uuid>] \
  [--multiple]

--new-api-id を指定するとフィールドIDを変更します。既存エントリの data キーと参照も合わせて変わります。変更先のキーが既存エントリに残っている場合は失敗します。

media

media upload

supacms media upload \
  --project <slug> \
  --file <ファイルパス> \
  [--alt <代替テキスト>] \
  [--no-compress] \
  [--no-webp] \
  [--api-key <key>]

対応フォーマット: JPEG / PNG / GIF / WebP / SVG（最大 10MB）

既定では JPEG / PNG / WebP を最大幅 1920px に縮小し WebP に変換します。--no-compress で縮小を、--no-webp で形式変換をスキップできます。GIF と SVG は変換しません。

{
  "id": "01938f...",
  "projectId": "...",
  "filename": "hero.webp",
  "mimeType": "image/webp",
  "size": 204800,
  "url": "https://cms.spcdn.dev/media/myproject/01938f...",
  "alt": "ヒーロー画像",
  "createdAt": "2026-08-05T09:00:00.000Z"
}

media list

supacms media list --project <slug> [--api-key <key>]

entry

エントリはコンテンツタイプのスキーマに基づいた実際のコンテンツデータです。作成の既定は draft です。--publish を付けると作成と同時に公開でき、--published-at に未来の日時を足すと予約公開になります。

entry create

supacms entry create \
  --project <slug> \
  --content-type <contentTypeApiId> \
  --data '<JSON>' \
  [--publish] \
  [--published-at <ISO8601>] \
  [--api-key <key>]

--data の代わりに --file <path> で JSON ファイルを指定することもできます。--published-at は --publish と一緒に使い、その未来の日時に公開を予約します（予約公開）。省略時の公開日時は実行時刻です。必要な permission は entry:publish だけです。

supacms entry create \
  --project myblog \
  --content-type blogPost \
  --file ./entry.json \
  --publish \
  --published-at 2026-10-01T09:00:00+09:00

entry list

supacms entry list \
  --project <slug> \
  --content-type <contentTypeApiId> \
  [--status draft|published] \
  [--filters '<expr>'] \
  [--limit <n>] \
  [--offset <n>] \
  [--api-key <key>]

--limit は取得件数の上限（1〜100）、--offset は取得開始位置です。--limit の省略時は 100 件で、100 を超える値はエラーになります。API の limit / offset と同じ意味です。レスポンスの totalCount は status に一致するエントリの総数です。

--filters はフィールド値で絞り込みます。フォーマットは <fieldApiId>[equals|contains]<value> です。 equals は slug などのテキストと単一参照、contains は複数参照に使います。

# slug が一致する記事
supacms entry list \
  --project myblog \
  --content-type blogPost \
  --filters 'slug[equals]hello-world'

# author フィールドが特定のエントリ（著者）を参照している記事一覧
supacms entry list \
  --project myblog \
  --content-type blogPost \
  --filters 'author[equals]<authorEntryId>'

# tags フィールドに特定のタグを含む記事一覧（multiple=true の場合）
supacms entry list \
  --project myblog \
  --content-type blogPost \
  --filters 'tags[contains]<tagEntryId>'

# 公開済みの最新100件を取得（`--limit` 省略時も 100）
supacms entry list \
  --project myblog \
  --content-type blogPost \
  --status published \
  --limit 100

entry update

supacms entry update \
  --project <slug> \
  --content-type <contentTypeApiId> \
  --id <entryId> \
  --data '<JSON>' \
  [--api-key <key>]

--data と --file は排他です。システム側の publishedAt を直す場合は entry system を使います。

公開中（published）のエントリを更新すると、変更は編集版として保存され、配信APIの出力は変わりません。配信へ反映するには entry publish を実行してください。非公開（draft）のエントリはこれまでどおり即座に更新されます。

entry update のレスポンスは配信中の内容（確定版）を返します。編集版を含む最新の内容は entry preview のURL、または管理画面のプレビューで確認します。

entry system

supacms entry system \
  --project <slug> \
  --content-type <contentTypeApiId> \
  --id <entryId> \
  --published-at <ISO8601> \
  [--api-key <key>]

公開済みエントリのシステム側 publishedAt を ISO 8601 日時で更新します。非公開エントリには使えません。entry:updateSystem permission が必要です（新しい editor / admin プリセットに含まれます。既存キーは再発行が必要です）。

entry publish / unpublish

supacms entry publish   --project <slug> --content-type <contentTypeApiId> --id <entryId> [--published-at <ISO8601>] [--api-key <key>]
supacms entry unpublish --project <slug> --content-type <contentTypeApiId> --id <entryId> [--api-key <key>]

--published-at に未来の日時を渡すと、その時刻まで配信されない「予約中」のエントリになります（予約公開）。必要な permission は entry:publish だけです。予約を取り消すには entry unpublish で非公開に戻します。

--published-at に渡せるのは未来の日時だけで、過去の日時は 422 になります。すでに配信中のエントリの公開日時を過去にさかのぼって直す場合は entry system を使ってください。予約中のエントリなら、別の未来日時を渡して予約日時を変更できます。--published-at を省略して送れば、その場で即時公開に切り替わります。

予約中のエントリを編集すると変更は編集版に入るため、予約時刻に公開されるのは編集版ではなく確定版の内容です。 予約公開に変更を含めるには、予約時刻より前に --published-at へ現在の予約日時と同じ値を渡して entry publish を実行してください。予約日時は保たれたまま、編集版が反映されます。--published-at を省略すると即時公開になり、予約が消費されます。

公開中のエントリに編集版があるときの entry publish は、編集版を配信へ反映します（publishedAt は初回公開時の値のまま）。編集版がない公開中のエントリに送ると 409 になります。entry unpublish も編集版があれば反映してから非公開にします。

entry preview

supacms entry preview --project <slug> --content-type <contentTypeApiId> --id <entryId> [--rotate] [--api-key <key>]

下書きを含む最新の編集内容を確認するためのプレビューURLと draftKey を返します。entry:createDraftKey が必要です（editor プリセットに含まれます）。

{
  "draftKey": "6f1c2d3e-4b5a-4c6d-9e8f-7a6b5c4d3e2f",
  "expiresAt": "2026-10-17T05:00:00.000Z",
  "expiresInSeconds": 86400,
  "previewUrl": "https://example.com/preview?id=...&draftKey=6f1c2d3e-4b5a-4c6d-9e8f-7a6b5c4d3e2f"
}

• 有効なキーがあるあいだは同じキーと有効期限を返します。キーは発行から24時間有効です

• previewUrl はコンテンツにプレビューURLが設定されていないと null です。content-type update --preview-url で設定できます

• --rotate を付けると新しいキーを発行し、それまでに共有したプレビューURLは開けなくなります

entry delete

supacms entry delete \
  --project <slug> \
  --content-type <contentTypeApiId> \
  --id <entryId> \
  [--api-key <key>]

install-skill

Claude Code スキルを R2 からダウンロードしてプロジェクトにインストールします。

supacms install-skill <skill-name>

スキルファイルは .claude/skills/<skill-name>/SKILL.md に保存されます。Claude Code はプロジェクトルートの .claude/skills/ を自動で読み込むため、追加の設定は不要です。

使用例

# 対話形式でエントリを公開する supacms-publish スキルをインストール
supacms install-skill supacms-publish

スキルを最新版に更新する場合も同じコマンドを実行してください（上書きされます）。

init

カレントディレクトリに .env.example を生成します。

supacms init \
  --project <slug> \
  --content-type <contentTypeApiId> \
  [--api-key <key>]

SUPACMS_API_URL には project info で取得した実際のURLが自動で入ります。

SUPACMS_API_URL=https://cms.supa.ai
SUPACMS_API_KEY=
SUPACMS_PROJECT_SLUG=supa-media
SUPACMS_CONTENT_TYPE_API_ID=article

.env にコピーして SUPACMS_API_KEY を埋めるとすぐに使えます。

フィールドタイプ一覧

# maxLength 付き short_text
supacms field add --type short_text --config '{"maxLength": 200}' ...

# 重複を禁止する short_text（同じコンテンツタイプ内で値がユニークになる）
supacms field add --type short_text --config '{"unique": true}' ...

# 時刻なしの datetime
supacms field add --type datetime --config '{"includeTime": false}' ...

# 選択した項目の変更日時を記録する（任意フィールド）
# trackedFieldIds は field list が返す対象項目の id（UUID）に置き換える
supacms field add --project your-project --content-type article --name '本文更新日時' --api-id contentUpdatedAt --type datetime --config '{"includeTime":true,"trackContentChanges":true,"trackedFieldIds":["01994e2e-1b7e-7000-8000-000000000000"]}'

# config 不要な場合は省略可
supacms field add --type rich_text ...

# reference フィールド（単一参照）
supacms field add --project myblog --content-type blogPost \
  --name "著者" --api-id author \
  --type reference \
  --ref-content-type-id <authorContentTypeId> \
  --required

# select フィールド（単一選択）
supacms field add --project myblog --content-type blogPost \
  --name "カテゴリ" --api-id category \
  --type select \
  --config '{"options":["news","blog"]}'

# select フィールド（複数選択）
supacms field add --project myblog --content-type blogPost \
  --name "タグ" --api-id tags \
  --type select \
  --config '{"options":["TypeScript","Effect"]}' \
  --multiple

# reference フィールド（複数参照）
supacms field add --project myblog --content-type blogPost \
  --name "タグ" --api-id tags \
  --type reference \
  --ref-content-type-id <tagContentTypeId> \
  --multiple

出力フォーマット

デフォルトは JSON 形式（AI が parse しやすい）。--pretty で人間向けの整形表示になります。

supacms content-type list --project myproject --pretty

エラー時は JSON 形式でエラーを出力し、終了コード 1 で終了します。

{ "error": "apiId already exists: blogPost" }

実行例

スキーマ定義からエントリ公開まで

# 1. ContentType を作成
supacms content-type create \
  --project myblog \
  --name "ブログ記事" \
  --api-id blogPost

# 2. フィールドを追加
supacms field add --project myblog --content-type blogPost \
  --name "タイトル" --api-id title \
  --type short_text --required --config '{"maxLength": 200}'

supacms field add --project myblog --content-type blogPost \
  --name "本文" --api-id body \
  --type rich_text --required

# 3. エントリを作成（draft）
export SUPACMS_API_KEY=sk-...
supacms entry create \
  --project myblog \
  --content-type blogPost \
  --data '{"title": "はじめての記事", "body": "本文です。"}' \
  --pretty

# 4. 公開する
supacms entry publish \
  --project myblog \
  --content-type blogPost \
  --id <entryId>

著者を reference フィールドで紐づける

API_KEY=sk-...

# 1. 著者用 ContentType を作成
supacms content-type create \
  --project myblog --name "著者" --api-id author \
  --api-key $API_KEY

supacms field add --project myblog --content-type author \
  --name "名前" --api-id name --type short_text --required \
  --api-key $API_KEY

# 2. 記事用 ContentType に著者 reference フィールドを追加
#    （先に `content-type list` で author の ContentType ID を確認）
AUTHOR_CT_ID=$(supacms content-type list --project myblog | jq -r '.[] | select(.apiId=="author") | .id')

supacms field add --project myblog --content-type blogPost \
  --name "著者" --api-id author \
  --type reference \
  --ref-content-type-id $AUTHOR_CT_ID \
  --required \
  --api-key $API_KEY

# 3. 著者エントリを作成
export SUPACMS_API_KEY=$API_KEY
AUTHOR_ID=$(supacms entry create \
  --project myblog --content-type author \
  --data '{"name": "田中太郎"}' | jq -r '.id')

# 4. 記事エントリを作成（著者を紐づける）
supacms entry create \
  --project myblog --content-type blogPost \
  --data "{\"title\": \"はじめての記事\", \"author\": \"$AUTHOR_ID\"}" \
  --pretty

# 5. 逆引き：著者の記事一覧を取得
supacms entry list \
  --project myblog \
  --content-type blogPost \
  --filters "author[equals]$AUTHOR_ID"

画像付きコンテンツを公開する

API_KEY=sk-...

supacms content-type create \
  --project myblog --name "ブログ記事" --api-id blogPost \
  --api-key $API_KEY

supacms field add --project myblog --content-type blogPost \
  --name "タイトル" --api-id title --type short_text --required \
  --api-key $API_KEY

supacms field add --project myblog --content-type blogPost \
  --name "アイキャッチ" --api-id eyecatch --type media \
  --api-key $API_KEY

# 画像をアップロードして ID を取得
supacms media upload \
  --project myblog \
  --file ./hero.png \
  --alt "ヒーロー画像" \
  --api-key $API_KEY --pretty

# エントリを作成（media フィールドには取得した id を渡す）
export SUPACMS_API_KEY=$API_KEY
supacms entry create \
  --project myblog \
  --content-type blogPost \
  --data '{"title": "画像付き記事", "eyecatch": "01938f..."}' \
  --pretty