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. 開発用バイパス — URL が localhost でトークンがない場合、開発用バイパスエンドポイントで自動的に認証します

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]

このコマンドは各チェックを成功、警告、失敗のいずれかとして報告し、チェックが失敗した場合は 0 以外のコードで終了します。

emdash seed

JSON シードを検証するか、ローカルの SQLite データベースに適用します。コマンドは、位置引数のパスが指定されていればそれを使い、なければ .emdash/seed.json、さらに package.json の emdash.seed パスの順に使用します。

npx emdash seed [path] [options]

シードを適用すると、最初にコアのマイグレーションが実行されます。データベースを開いたり作成したりせずにファイルだけを確認したい場合は、継続的インテグレーションで --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 マイグレーションロックについては、コアデータベースのマイグレーションを管理するを参照してください。

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://example.com

# 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 で認証が設定されていない場合は、開発用バイパスを自動的に使用します
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 ジョブでは、終了コード 0 を完全なカバレッジと見なすのではなく、--json を使用して 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、receiptDigestValid が含まれ、receiptDigestValid はレシートの receiptDigest がその内容と一致するかどうかを示します。

次の形式は、オペレーション ID を指定してインポートを操作します。

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

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

emdash export-seed

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

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

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

オプション

出力形式

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

• 設定: サイトタイトル、タグライン、ソーシャルリンク
• コレクション: フィールドを含むすべてのコレクション定義
• ブロックタイプ: 保持されているすべてのバージョンと、各タイプのアクティブなバージョンへのポインター
• タクソノミー: タクソノミーの定義とターム
• メニュー: 項目を含むナビゲーションメニュー
• リダイレクト: ステータス 301、302、307、308 のリダイレクトルール
• ウィジェットエリア: ウィジェットエリアとウィジェット
• セクション: 再利用可能なコンテンツブロック
• コンテンツ（要求した場合）: ポータビリティのための $media 参照と $ref: 構文を含むエントリ

シードには公開時刻を表すフィールドがないため、予約済みのエントリは下書きとしてエクスポートされます。エクスポートでは、emdash seed が拒否するものを、stderr に警告を表示したうえで除外します。具体的には、ステータス 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-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 を使用します。