emdash-cli

EmDash CLI

EmDash CLI（emdash、短縮エイリアスは em）は、EmDash CMS インスタンスを管理します。コマンドは次の 2 つのカテゴリに分かれます。

• ローカルコマンドは、プロジェクトファイルまたは設定済みのデータベースを操作します：init、doctor、seed、migrate、export-seed、secrets。
• リモートコマンドは、実行中の EmDash インスタンスと通信します：types、login、logout、whoami、content、schema、media、search、taxonomy、menu、site。

インストールされているバージョンの正確なコマンドとフラグを確認するには、npx emdash --help と npx emdash <command> --help を実行してください。破壊的な変更や一括変更を行う前に、読み取りコマンドで現在の対象を確認してください。このスキルの例は、ユーザーが対象として指定していないインスタンスの変更を許可するものではありません。

認証

リモートコマンドは認証情報を自動的に次の順序で解決します。

1. --token フラグ
2. EMDASH_TOKEN 環境変数
3. emdash login で保存した認証情報
4. 開発用バイパス（localhost のみ。トークンは不要）

開発用バイパスが有効な localhost の開発サーバーでは、クライアントは自動的に認証できます。リモートインスタンスの場合は、emdash login --url https://example.com を実行するか、スコープを限定したトークンを指定してください。

カスタムヘッダーとリバースプロキシ

Cloudflare Access やその他のリバースプロキシの背後にあるサイトでは、すべてのリクエストに認証ヘッダーが必要です。CLI では、--header フラグと環境変数を使ってこれに対応できます。

自動化用のサービストークン

# Provide sensitive headers through the environment in CI.
export EMDASH_HEADERS="CF-Access-Client-Id: xxx
CF-Access-Client-Secret: yyy"
npx emdash whoami --url https://example.com

emdash login --header はカスタムヘッダーを ~/.config/emdash/auth.json に保存し、以降のコマンドで使用できるようにします。サービスシークレットが認証情報ファイルやシェル履歴に書き込まれないよう、CI では環境変数でヘッダーを渡す方法を推奨します。

Cloudflare Access のブラウザーフロー

サービストークンがなく、cloudflared がインストールされている場合、CLI は自動的に次の処理を行います。

1. Access がリクエストをブロックしたことを検出します
2. cloudflared access token を使ってキャッシュ済みの JWT を取得しようとします
3. 取得できない場合は、ブラウザーベースの認証のために cloudflared access login にフォールバックします

この方法は対話型の利用には適していますが、CI には適していません。自動化にはサービストークンを使用してください。

汎用リバースプロキシ認証

--header フラグは、任意の認証方式で使用できます。

# Basic auth
npx emdash login --url https://example.com -H "Authorization: Basic dXNlcjpwYXNz"

# Custom auth header
npx emdash login --url https://example.com -H "X-API-Key: secret123"

クイックリファレンス

データベースのセットアップ

通常のサイト起動には、プロジェクトのパッケージスクリプトを使用してください。最初のリクエスト時に、未適用のマイグレーションが実行され、セットアップが完了する前であれば、同梱されたシードのスキーマと構造が一度だけ適用されます。サンプルコンテンツは、セットアップウィザード、/_emdash/api/setup/dev-bypass、または emdash seed から取得できます。Astro インテグレーションは、サーバーの起動時に emdash-env.d.ts を生成します。

# Start the site with its package script
pnpm dev

# Export an existing database as a seed file
# (the runtime auto-discovers .emdash/seed.json on first boot;
# `mkdir -p` because the directory may not exist yet)
mkdir -p .emdash
npx emdash export-seed > .emdash/seed.json
npx emdash export-seed --with-content=all > .emdash/seed.json

型の生成

# Generate types from local dev server
npx emdash types

# Generate from remote
npx emdash types --url https://example.com

# Custom output path
npx emdash types --output src/types/cms.ts

.emdash/types.ts（TypeScript インターフェース）と .emdash/schema.json を書き込みます。

認証

# Login (OAuth Device Flow)
npx emdash login --url https://example.com

# Check current user
npx emdash whoami

# Logout
npx emdash logout

# Generate an encryption key for deployment
npx emdash secrets generate

コンテンツの CRUD

CLI はエージェント向けに設計されています。作成と更新はデフォルトで自動公開されるため、エージェントは下書きを管理せずに読み取り後の一貫性を得られます。

# List content
npx emdash content list posts
npx emdash content list posts --status published --limit 10

# Get a single item (Portable Text fields converted to markdown)
# Returns draft data if a pending draft exists
npx emdash content get posts 01ABC123
npx emdash content get posts 01ABC123 --raw        # skip PT->markdown conversion
npx emdash content get posts 01ABC123 --published   # ignore pending drafts

# Create content (auto-publishes by default)
npx emdash content create posts --data '{"title": "Hello", "body": "# World"}'
npx emdash content create posts --file post.json --slug hello-world
npx emdash content create posts --draft --data '...'  # keep as draft
cat post.json | npx emdash content create posts --stdin

# Update (requires --rev from a prior get, auto-publishes by default)
npx emdash content update posts 01ABC123 --rev MToyMDI2... --data '{"title": "Updated"}'
npx emdash content update posts 01ABC123 --rev MToyMDI2... --draft --data '...'  # keep as draft

# Delete (soft delete)
npx emdash content delete posts 01ABC123

# Lifecycle
npx emdash content publish posts 01ABC123
npx emdash content unpublish posts 01ABC123
npx emdash content schedule posts 01ABC123 --at 2026-03-01T09:00:00Z
npx emdash content restore posts 01ABC123

スキーマ管理

# List collections
npx emdash schema list

# Get collection with fields
npx emdash schema get posts

# Create collection
npx emdash schema create articles --label Articles --description "Blog articles"

# Delete a collection after inspecting it and confirming the target
npx emdash schema get articles
npx emdash schema delete articles

# Add field
npx emdash schema add-field posts body --type portableText --label "Body Content"
npx emdash schema add-field posts featured --type boolean --required

# Remove field
npx emdash schema remove-field posts featured

schema add-field は、npx emdash schema add-field --help に表示されるフィールドタイプに対応しています。製品全体のスキーマには、コマンドから作成できるとは限らない追加のフィールドタイプもあります。

メディア

# List media
npx emdash media list
npx emdash media list --mime image/png

# Upload
npx emdash media upload ./photo.jpg --alt "A sunset" --caption "Bristol, 2026"

# Get / delete
npx emdash media get 01MEDIA123
npx emdash media delete 01MEDIA123

検索

npx emdash search "hello world"
npx emdash search "hello" --collection posts --limit 5

タクソノミー

npx emdash taxonomy list
npx emdash taxonomy terms categories
npx emdash taxonomy add-term categories --name "Tech" --slug tech
npx emdash taxonomy add-term categories --name "Frontend" --parent 01PARENT123

メニュー

npx emdash menu list
npx emdash menu get primary

サイトのエクスポートとインポート

emdash site はサイト全体（コンテンツモデル、コンテンツ、履歴、設定、メディア。ただしユーザーとシークレットは除く）を .emdash サイトパッケージにコピーし、パッケージを空のサイトにインポートします。トークンには admin が必要です。emdash login のトークンにはこの権限があるほか、transfer:export、transfer:analyze、transfer:execute スコープを指定する方法もあります。INSUFFICIENT_SCOPE エラーは、トークンがそのいずれも持っていないことを意味します。パッケージにはすべてのエントリーと、作成者およびコメント投稿者のメールアドレスが含まれます。データベースのバックアップと同様に扱ってください。

# Export (re-run the same command to resume after an interruption)
npx emdash site export --url https://old.example.com --output site.emdash
npx emdash site export --url https://old.example.com --output site.emdash --no-comments

# Import, step 1: upload and analyze; prints the plan and its digest
npx emdash site import site.emdash --url https://new.example.com --analyze
npx emdash site import site.emdash --url https://new.example.com --analyze \
  --map-principal [email protected][email protected] --use-target-title

# Import, step 2: execute exactly the reviewed plan
npx emdash site import site.emdash --url https://new.example.com --plan sha256:<hex> --confirm

# Follow up on an import by operation id
npx emdash site import status <operation-id> --url https://new.example.com
npx emdash site import resume <operation-id> [site.emdash] --url https://new.example.com
npx emdash site import receipt <operation-id> --url https://new.example.com

# Stop an import, or lift the write block a failed or cancelled import leaves
# (neither deletes what the import wrote; --yes skips the prompt)
npx emdash site import cancel <operation-id> --url https://new.example.com
npx emdash site import abandon <operation-id> --url https://new.example.com

プラン（ソースサイトとの違い、警告、ブロッカー、プリンシパルのマッピング）をユーザーに提示し、--confirm を実行する前に確認を得てください。実行するとターゲットサイトに書き込み、完了するまでターゲットサイトへの他の書き込みをブロックします。site import はプランにブロッカーがある場合に終了コード 2 で終了し、site import status はインポートが失敗、キャンセルまたは放棄された場合、あるいは期限切れの場合に終了コード 1 で終了します。インポートをキャンセルまたは放棄するのは、ユーザーから依頼された場合に限ってください。放棄するとサイトに部分的なデータが残り、次のインポートの前にリセットする必要があります。--map-principal は <principal id or email>=<user id, email, or none> を受け取り、繰り返し指定できます。判定フラグは --analyze と併用した場合にのみ機能し、変更のたびに新しいプランダイジェストが生成されます。インポート中も公開サイトは非表示にならないため、コマンドが receiptDigestValid: true を含むレシートを出力するまで、ターゲットを非公開にしておいてください。

下書きと公開

CLI はデフォルトで create と update の実行時に自動公開します。つまり、次のとおりです。

• create はアイテムを作成し、直ちに公開します
• update はアイテムを更新し、下書きリビジョンが作成された場合は公開します
• get は保留中の下書きがある場合、その下書きデータを返します（例：管理画面から作成した下書き）

create／update で自動公開をスキップするには --draft を使用します。保留中の下書きを無視して取得するには get で --published を使用します。

リビジョンに対応するコレクションでは、編集内容は下書きリビジョンとして保存されます。CLI が透過的に処理するため、エージェントはコレクションがリビジョンを使用するかどうかを把握する必要はありません。

JSON 出力

すべてのリモートコマンドは、機械可読な出力を得るために --json に対応しています。標準出力がパイプに接続されている場合は、自動的に有効になります。emdash site は常に進行状況を標準エラー出力に書き込むため、標準出力には JSON の結果だけが出力されます。エラーは { "error": { "code", "message" } } の形式です。

# Pipe to jq
npx emdash content list posts --json | jq '.items[].slug'

# Use in scripts
ID=$(npx emdash content create posts --data '{"title":"Hello"}' --json | jq -r '.id')

編集のワークフロー

コンテンツ編集の仕組み（Portable Text／Markdown の変換、_rev トークン、raw モード）の詳細については、EDITING-FLOW.md を参照してください。