CLI リファレンス

EmDash CLI は、データベースのセットアップ、型生成、コンテンツの作成と編集、スキーマ管理、メディア、サイトのエクスポートとインポート、プラグイン開発のコマンドを提供します。

インストール

CLI は emdash パッケージに含まれます。次のコマンドでインストールします。

npm install emdash

npx emdash でコマンドを実行するか、package.json にスクリプトを追加します。バイナリは簡潔さのため em としても利用できます。

パッケージスクリプト（例: pnpm dev）でサイトを起動します。パッケージスクリプトは Astro を起動し、EmDash 統合は emdash-env.d.ts を生成します。一方、ランタイムは最初のリクエストで保留中のマイグレーションを実行し、データベースが空でセットアップが完了していないときに同梱シードを適用します。

認証

実行中の EmDash インスタンスに接続するコマンドは、次の順で認証を解決します。

1. --token フラグ — コマンドライン上の明示的なトークン
2. EMDASH_TOKEN 環境変数
3. 保存された資格情報 — ~/.config/emdash/auth.json（emdash login が保存）
4. Dev bypass — URL が localhost でトークンがない場合、dev bypass エンドポイント経由で自動認証

types、whoami、content、schema、media、search、taxonomy、menu、site コマンドは実行中のインスタンスに接続します。認証コマンドは独自の接続オプションを持ちます。ローカル開発サーバーを対象にする場合、トークンは不要です。

共通フラグ

接続フラグはコマンドごとに異なります。下記のグループ化されたコマンドは、そのグループ内のすべてのサブコマンドを意味します。

出力

コマンドが対話型ターミナルに結果を書き込む場合、読みやすい形式に整形します。上記の --json 付きコマンドは、フラグが設定されているか出力がパイプされているときに生 JSON を書き込みます。emdash migrate は明示的な --json オプションがある場合のみ JSON を出します。

コマンド

emdash init

package.json のテンプレートメタデータからローカル SQLite データベースを初期化します。コマンドはコアマイグレーションを実行し、続けて emdash.schema が指定する任意の SQL ファイルを適用します。JSON シードデータには別途 emdash seed を実行します。

npx emdash init [options]

--force なしでは、初期化済みデータベースはそのまま残ります。このコマンドはローカル SQLite ファイルを直接開きます。デプロイ管理の D1、PostgreSQL、libSQL、Hyperdrive マイグレーションには emdash migrate を使用します。

emdash doctor

ローカル SQLite データベースの接続、マイグレーション、コレクション、テーブル、ユーザーの問題を確認します。プロジェクトに Wrangler 設定がある場合、Cron Trigger と EmDash の scheduled() ハンドラーが一緒に設定されているかも確認します。

npx emdash doctor [options]

各チェックを合格、警告、失敗として報告し、チェックが失敗すると非ゼロで終了します。

emdash seed

JSON シードをローカル SQLite データベースに検証または適用します。コマンドは、指定があれば位置引数のパス、次に .emdash/seed.json、次に package.json の emdash.seed パスを使います。

npx emdash seed [path] [options]

シード適用はまずコアマイグレーションを実行します。データベースを開いたり作成したりせずにファイルを確認する必要がある CI では --validate を使用します。

emdash migrate

Astro ビルドが出力したコアマイグレーションセットを確認または適用します。

npx emdash migrate [options]
npx emdash migrate --check [options]
npx emdash migrate --status --json [options]
npx emdash migrate --release-lock <id> [options]

デフォルトではプロジェクトルートを検出し、.emdash/migrations.json を読みます。プロジェクトにインストールされた EmDash パッケージに対してマニフェストを検証し、アダプターのプロジェクトローカルエグゼキューターを解決し、SQL の前に不変のターゲットを表示します。

オプション

対話的な人間可読の適用とロック解除は確認を求めます。非対話的な適用またはロック解除、および --json を使うすべての適用またはロック解除は、ターゲット用に表示された正確なフィンガープリントが必要です。down や --dry-run はありません。作業が必要かどうかは --check で判断します。

終了コード

デプロイ順序、ターゲット資格情報、D1 マイグレーションロックについては Manage Core Database Migrations を参照してください。

emdash dev（非推奨）

レガシーコマンドは Astro を起動する前にローカル SQLite データベースを初期化・マイグレートします。この動作はサイトが設定したデータベースアダプターを使わず、Cloudflare D1 開発と互換性がありません。既存の呼び出しは、データベース作業の前に非推奨警告を表示するようになりました。

emdash types

実行中の EmDash インスタンスのスキーマから TypeScript 型を生成します。

npx emdash types [options]

オプション

例

# Generate types from local dev server
npx emdash types

# Generate from remote instance
npx emdash types --url https://my-site.pages.dev

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

動作

1. インスタンスからスキーマを取得
2. TypeScript 型定義を生成
3. 出力ファイルに型を書き込み
4. 参照用に横に schema.json を書き込み

emdash login

OAuth Device Flow で EmDash インスタンスにログインします。

npx emdash login [options]

オプション

動作

1. インスタンスから認証エンドポイントを検出
2. localhost で認証が未設定の場合、自動的に dev bypass を使用
3. それ以外は OAuth Device Flow を開始 — コードを表示しブラウザを開きます。コード入力後、管理ページは CLI が受け取る権限と、ロールが許可しない要求権限を、承認前に一覧表示します。
4. 認可をポーリングし、資格情報を ~/.config/emdash/auth.json に保存

保存された資格情報は、同じインスタンスを対象とする以降のすべてのコマンドで自動的に使われます。

emdash logout

ログアウトし、保存された資格情報を削除します。

npx emdash logout [options]

オプション

emdash whoami

現在認証されているユーザーを表示します。

npx emdash whoami [options]

オプション

メール、名前、ロール、認証方法、インスタンス URL を表示します。

emdash content

コンテンツ項目を管理します。すべてのサブコマンドは EmDashClient 経由でリモート API を使います。

content list <collection>

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

content get <collection> <id>

npx emdash content get posts 01ABC123
npx emdash content get posts 01ABC123 --raw

応答には _rev トークンが含まれます。上書き前に現在の状態を見たと確認するため、content update に渡します。

content create <collection>

npx emdash content create posts --data '{"title": "Hello"}'
npx emdash content create posts --file post.json --slug hello-world
cat post.json | npx emdash content create posts --stdin

データは --data、--file、--stdin のいずれか 1 つだけを指定します。--draft が設定されていない限り、新しい項目は自動公開されます。

content update <collection> <id>

現在の状態を見たと証明するため、前回の get の _rev トークンを提供する必要があります。これにより、見ていない変更の上書きを防ぎます。次の手順で項目を読み、そのトークンで更新します。

# 1. Read the item, note the _rev
npx emdash content get posts 01ABC123

# 2. Update with the _rev from step 1
npx emdash content update posts 01ABC123 \
  --rev MToyMDI2LTAyLTE0... \
  --data '{"title": "Updated"}'

get 以降に項目が変わった場合、サーバーは 409 Conflict を返します — 再読み取りして再試行してください。

管理画面で誰かがエントリを開いている場合、サーバーはコード ENTRY_LOCKED と保持者を示すメッセージ付きの 409 を返します。完了を待つか、 --override-lock を渡します。同じフラグは content delete、 content publish、content unpublish、content schedule でも使えます。

content delete <collection> <id>

npx emdash content delete posts 01ABC123

コンテンツ項目をソフト削除します（ゴミ箱へ移動）。

別の編集者が開いているエントリを削除するには --override-lock を渡します。

content publish <collection> <id>

npx emdash content publish posts 01ABC123

別の編集者が開いているエントリを公開するには --override-lock を渡します。

content unpublish <collection> <id>

npx emdash content unpublish posts 01ABC123

別の編集者が開いているエントリの公開を取り消すには --override-lock を渡します。

content schedule <collection> <id>

npx emdash content schedule posts 01ABC123 --at 2026-03-01T09:00:00Z

別の編集者が開いているエントリをスケジュールするには --override-lock を渡します。

content restore <collection> <id>

npx emdash content restore posts 01ABC123

ゴミ箱に入れたコンテンツ項目を復元します。

content translations <collection> <id>

エントリの翻訳グループ内のすべての翻訳を一覧表示します。

npx emdash content translations posts 01ABC123

結果には各翻訳の ID、ロケール、スラッグ、ステータス、および要求されたエントリかどうかが含まれます。

emdash schema

コレクションとフィールドを管理します。

schema list

npx emdash schema list

すべてのコレクションを一覧表示します。

schema get <collection>

npx emdash schema get posts

すべてのフィールド付きでコレクションを表示します。

schema create <collection>

npx emdash schema create articles --label Articles
npx emdash schema create articles --label Articles --label-singular Article --description "Blog articles"

schema delete <collection>

npx emdash schema delete articles
npx emdash schema delete articles --force

--force が設定されていない限り確認を求めます。

schema add-field <collection> <field>

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

schema remove-field <collection> <field>

npx emdash schema remove-field posts featured

emdash media

メディア項目を管理します。

media list

npx emdash media list
npx emdash media list --mime image/png --limit 20

media upload <file>

npx emdash media upload ./photo.jpg
npx emdash media upload ./photo.jpg --alt "A sunset" --caption "Taken in Bristol"

media get <id>

npx emdash media get 01MEDIA123

media delete <id>

npx emdash media delete 01MEDIA123

media repair-usage

1 つのコレクション、またはすべてのコンテンツコレクションのコンテンツメディア使用インデックスを修復します。インポートや直接のデータベース書き込みの後、使用カバレッジが古いまたは信頼できないときに使います。

npx emdash media repair-usage --collection posts
npx emdash media repair-usage --all
npx emdash media repair-usage --all --json

--collection または --all のどちらか一方だけを渡します。リモート修復には Admin ユーザーと admin スコープの認証トークンが必要です。

全コンテンツの修復は同期実行され、大きなサイトでは遅くまたは高コストになることがあります。1 つのコレクションだけ修復する場合は --collection を優先してください。

構造化結果 complete、partial、stale は 0 で終了し、構造化 failed は 1 で終了します。自動化と cron ジョブは --json を使い、終了コード 0 を完全カバレッジとみなすのではなく、status、failedSourceCount、skippedSourceCount、コレクションごとの要約を解析してください。

emdash search

コンテンツ全体の全文検索です。

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

emdash taxonomy

タクソノミーと用語を管理します。

taxonomy list

npx emdash taxonomy list

taxonomy terms <name>

npx emdash taxonomy terms categories
npx emdash taxonomy terms tags --limit 50

taxonomy add-term <taxonomy>

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

emdash menu

ナビゲーションメニューを管理します。

menu list

npx emdash menu list

menu get <name>

npx emdash menu get primary

すべての項目付きでメニューを返します。

emdash site

サイト全体を .emdash サイトパッケージにエクスポートし、空のサイトにパッケージをインポートします。サイト転送ガイド は、パッケージの内容、ターゲットサイトに必要なもの、インポートプランの読み方を説明します。

トークンには emdash login トークンが持つ admin スコープ、または対応する転送スコープが必要です。エクスポートには transfer:export、インポートには transfer:analyze と transfer:execute。それらがないトークンは INSUFFICIENT_SCOPE で失敗します。

進捗メッセージは常に stderr へ、結果は stdout へ行きます。--json の場合、または stdout が端末でない場合、stdout には JSON 結果のみが含まれます。エラーは { "error": { "code": "…", "message": "…" } } として書かれます。コードはサーバーのエラーコードに加え、不正なフラグの INVALID_ARGUMENT、再開インポートがまだパッケージファイルを必要とするときの PACKAGE_FILE_REQUIRED、および UNKNOWN_ERROR です。

コマンドはネットワーク障害と 408、429、5xx 応答をバックオフ付きで再試行します。

site export

サイトをエクスポートし、パッケージファイルに書き込みます。

npx emdash site export --output site.emdash

コマンドはエクスポートを開始し、完了まで進め、パッケージをファイル単位でダウンロードします。ダウンロードしたマニフェストがエクスポートのパッケージダイジェストと一致することを確認し、一致しない場合は何も書き込む前に TRANSFER_PACKAGE_DIGEST_MISMATCH で失敗します。書き込み前に各ファイルのサイズと SHA-256 ダイジェストを確認します。パッケージは <output>.partial に書き込まれ、完了時に出力パスへリネームされます。

コマンドは進捗を <output>.partial.json に、ダウンロードしたファイルを <output>.parts/ ディレクトリに保持します。中断後に同じコマンドを再実行すると同じエクスポートを再開します。既にダウンロードしたファイルは確認して再利用され、再利用した数が報告されます。パッケージ書き込み時に両方とも削除されます。進捗ファイルが別の URL や別のコメント設定用に書かれた場合、またはそのエクスポートが失敗・期限切れの場合は無視され、コマンドは新しいエクスポートを開始します。

JSON 結果には operationId、output、packageDigest、files、bytes、resumed が含まれます。

site import <file>

パッケージを 2 段階でインポートします。まず分析し、分析が表示したプランダイジェストを確認します。

npx emdash site import site.emdash --analyze
npx emdash site import site.emdash --plan sha256:3f1c… --confirm

--analyze はパッケージファイル全体をローカルで検証し、同じパッケージのサイト上の既存インポートを見つけるか作成します。サイトがまだ持っていないファイルをアップロードし、分析を実行し、プランを表示します。パッケージとプランのダイジェスト、レコード数、サイズ、タイトルとタグラインの選択、各プリンシパルとそのマッピング、「Differences from the source site」下の変換、警告、ブロッカー。同じパッケージの以前のインポートが失敗、キャンセル、放棄、または期限切れの場合、コマンドは警告して新しいインポートを開始します。

決定はインポートと一緒に保存されるため、決定フラグなしの後続の --analyze 実行はそれらを保持します。決定の変更ごとに新しいプランダイジェストが生成されます。決定は --plan と併用できず、--plan は --analyze と併用できません。

--plan <digest> --confirm はダイジェストが現在のプランと一致する場合のみインポートを実行し、完了まで進めてレシートを表示します。確認後にプランが変わった場合、コマンドは TRANSFER_PLAN_DIGEST_MISMATCH で失敗します。再分析して新しいダイジェストを確認してください。

--analyze の JSON 結果には operationId、state、packageDigest、planDigest、executable、完全な plan が含まれます。--confirm の JSON 結果には operationId、state（complete）、receipt、およびレシートの receiptDigest が内容と一致するかを報告する receiptDigestValid が含まれます。

これらの形式は操作 ID でインポートを操作します。

cancel と abandon は確認を求めます。プロンプトをスキップするには --yes を渡します。--json の場合や stdout が端末でない場合もプロンプトはスキップされます。stdin が端末でなく、どちらも当てはまらない場合、コマンドは INVALID_ARGUMENT で失敗します。プロンプトを拒否しても何も変わらず、コード 1 で終了します。両方の JSON 結果は { operationId, state, operation } です。

インポートコマンドは次のコードで終了します。

emdash plugin

EmDash プラグインの作成、検証、バンドル、公開を行います。マーケットプレイスへのログインは CMS インスタンスへのログインとは別です。

plugin init

サンドボックスまたはネイティブプラグインをスキャフォールドします。

npx emdash plugin init --dir ./my-plugin --name my-plugin --format sandboxed

plugin bundle

プラグインを検証し、マーケットプレイス用 tarball を作成します。

npx emdash plugin bundle --dir ./my-plugin --outDir ./artifacts

plugin validate

plugin bundle と同じ検証を tarball 作成なしで実行します。

npx emdash plugin validate --dir ./my-plugin

任意の --dir はプラグインディレクトリを選択し、デフォルトは現在のディレクトリです。

plugin publish

バンドルをマーケットプレイスにアップロードし、デフォルトでは処理結果を待ちます。

npx emdash plugin publish --tarball ./dist/my-plugin-1.0.0.tar.gz

--tarball を指定するか、先に --dir からビルドするために --build を渡します。

plugin login

GitHub device flow でマーケットプレイスに認証します。--registry は別のマーケットプレイスを選択し、デフォルトは https://marketplace.emdashcms.com です。

npx emdash plugin login

plugin logout

保存されたマーケットプレイス資格情報を削除します。任意の --registry はログインに使ったのと同じマーケットプレイスを識別する必要があります。

npx emdash plugin logout

emdash export-seed

データベーススキーマとコンテンツをシードファイルとしてエクスポートします。ローカル SQLite ファイルに直接動作します。

データベースは、インストール済み EmDash バージョンが知るすべてのマイグレーションを持っている必要があります。コマンドが 保留マイグレーションを報告したら、npx emdash migrate を実行してから再エクスポートしてください。データベースが より新しい EmDash バージョンでマイグレートされている場合は、エクスポート前にインストール版をアップグレードしてください。エクスポートは データベースを読み取り専用で開き、自身ではマイグレーションを適用しません。

npx emdash export-seed [options] > seed.json

オプション

出力形式

エクスポートされたシードファイルには次が含まれます。

• Settings: サイトタイトル、タグライン、ソーシャルリンク
• Collections: フィールド付きのすべてのコレクション定義
• Block types: 保持された各バージョンと各タイプのアクティブバージョンポインタ
• Taxonomies: タクソノミー定義と用語
• Menus: 項目付きナビゲーションメニュー
• Redirects: ステータス 301、302、307、または 308 のリダイレクト規則
• Widget Areas: ウィジェット領域とウィジェット
• Sections: 再利用可能なコンテンツブロック
• Content（要求時）: 移植性のための $media 参照と $ref: 構文付きエントリ

スケジュール済みエントリは下書きとしてエクスポートされます。シードには公開時刻のフィールドがないためです。エクスポートは stderr 上の警告付きで、emdash seed が拒否するものを除外します。ステータス 410 または 451 のリダイレクト規則、同じソースを共有する余分な規則（古いデータベースで可能）、スラッグに小文字・数字・ハイフン以外の文字を含むセクション。

メディア URL

emdash seed は各 $media URL をダウンロードし、ターゲットサイトのストレージにアップロードするため、到達可能な絶対 http または https URL が必要です。絶対 URL を書くにはソースサイトの公開 URL を渡します。

npx emdash export-seed --with-content=all --media-base-url=https://example.com > seed.json

シード適用中、サイトはその URL の下の /_emdash/api/media/file/ からメディアを提供する必要があり、URL は localhost やプライベートネットワークアドレスを指してはなりません。emdash seed はそれらからのダウンロードを拒否します。--media-base-url がない場合、$media URL はサイト相対パスとなり、emdash seed はスキップしてフィールドを空のままにし、エクスポートは stderr に警告を出します。

画像とファイルのフィールド、およびリピーターの画像サブフィールドは $media 参照としてエクスポートされます。Portable Text フィールド内の画像は保存されたメディア ID と URL を保持し、別サイトでは解決しません。

emdash secrets

プラグインシークレットの暗号化に使うキーを生成・検査します。

secrets generate

デプロイ用の EMDASH_ENCRYPTION_KEY を生成します。キーは 保存時のプラグインシークレットの暗号化に使われます。

npx emdash secrets generate

新しいキーを stdout に出力します。シークレットストアへパイプするか、--write で ローカルの .env ファイルに直接書き込みます。Wrangler と Cloudflare Vite プラグインはローカル開発でそのファイルを読みます。スタンドアロンの Node サーバーは .env を自動読み込みしません。プロセスマネージャー経由で読み込むか、 サーバーのプロセス環境でキーを提供してください。Node.js デプロイ ガイド にローカルコマンドがあります。

npx emdash secrets generate --write .env

--write は --force なしでは既存エントリの上書きを拒否します。既存の暗号化データがあるデプロイをローテーションするには、生成したキーを既存値の前に置き、キーをカンマで区切ります。EmDash は最初のキーで新しい値を暗号化し、復号には古いエントリを kid で使います。古いキーを削除する前に、すべてのプラグインシークレットを再保存してください。EmDash は現在、保存設定がまだ使うキー ID を一覧表示しないため、再保存する資格情報の一覧を保持し、古いキーを削除する前に各統合を検証してください。

secrets fingerprint <key>

値を露出させずにキーの 8 文字フィンガープリント（kid）を表示します。 正しいキーがデプロイされたことを検証する CI で有用です。次のコマンドはキーのフィンガープリントを表示します。

npx emdash secrets fingerprint emdash_enc_v1_...

emdash auth（非推奨）

auth secret

レガシーの EMDASH_AUTH_SECRET 値を生成します。

npx emdash auth secret

既存インストールはこの変数を保持して、安定したコメント投稿者 IP ハッシュを保てます。プラグインシークレットは暗号化しません。

生成ファイル

emdash-env.d.ts

Astro 統合は、ローカル開発サーバー起動時にプロジェクトルートに emdash-env.d.ts を生成します。実行中の開発サイト経由で行われたスキーマ変更の後にファイルを更新します。宣言は EmDashCollections を拡張するため、getEmDashCollection("posts") のような呼び出しはローカルデータベースで定義されたフィールドを推論します。

このファイルは自動で、ローカル Astro 開発ワークフローに属します。作成のために emdash types を実行する必要はありません。

.emdash/types.ts

emdash types コマンドは実行中インスタンスのスキーマを取得し、スタンドアロンの TypeScript インターフェイスを書き込みます。スキーマがリモート EmDash インスタンスにある場合、ツールがカスタムパスのファイルを必要とする場合、またはローカル Astro 開発サーバーが動いていないときに使います。

// Generated by EmDash CLI
// Do not edit manually - run `emdash types` to regenerate

import type { PortableTextBlock } from "emdash";

export interface Post {
	id: string;
	slug: string | null;
	status: string;
	title: string;
	content?: PortableTextBlock[];
	createdAt: Date;
	updatedAt: Date;
	publishedAt: Date | null;
	bylines?: ContentBylineCredit[];
	terms?: Record<string, TaxonomyTerm[]>;
}

リモート出力はスタンドアロンのコレクションインターフェイスを含み、EmDashCollections は拡張しません。emdash types を実行したときだけ変わります。emdash-env.d.ts はモジュール拡張を使い、ローカル開発の一環として更新されます。

.emdash/schema.json

コマンドは選択した TypeScript 出力の横に、生のスキーマエクスポート schema.json も書き込みます。デフォルト出力パスではファイルは .emdash/schema.json です。

{
  "version": "a1b2c3d4",
  "collections": [
    {
      "slug": "posts",
      "label": "Posts",
      "fields": [...]
    }
  ]
}

環境変数

パッケージスクリプト

便利のため、よく使うコマンドを package.json スクリプトとして追加します。

{
	"scripts": {
		"dev": "astro dev",
		"types": "emdash types",
		"export-seed": "emdash export-seed",
		"db:reset": "rm -f data.db"
	}
}

一般的な終了コード

ほとんどのコマンドは成功に 0、エラーに 1 を使います。emdash migrate は 終了コード表 に記載の特定結果に 2、3、4、130 も使います。emdash site import はインポートプランにブロッカーがあるとき 2 を使います。