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 の各コマンドは、稼働中のインスタンスに接続します。認証のコマンドは、それぞれ独自の接続オプションを持ちます。ローカルの開発サーバーに接続する場合、トークンは必要ありません。

共通のフラグ

接続のフラグは、コマンドによって異なります。下の表でグループ名で書いたコマンドは、そのグループのすべてのサブコマンドを指します。

出力

コマンドが対話的なターミナルに結果を出力する場合は、読みやすく整形します。上の表で --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]

このコマンドは、それぞれの確認結果を合格（pass）、警告（warning）、失敗（failure）で報告し、失敗した確認がある場合は0以外の終了コードで終了します。

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]

既定では、このコマンドはプロジェクトのルートを見つけて .emdash/migrations.json を読み込みます。プロジェクトにインストールされているEmDashパッケージに照らしてマニフェストを検証し、アダプターのプロジェクト内の実行モジュール（executor）を解決して、SQLを実行する前に変更されない適用先（target）を表示します。

オプション

対話的に人が読める形式で適用する場合は、確認を求めます。非対話的に適用する場合と、--json を使って適用する場合は、その適用先について表示された正確なフィンガープリントが必要です。down や --dry-run はありません。作業が必要かどうかを判断するには --check を使います。

終了コード

デプロイの順番、適用先の認証情報、D1での直列化については、コアDBマイグレーションを参照してください。

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で認証が設定されていない場合は、自動的に開発用バイパスを使います
3. それ以外の場合は、OAuth Device Flowを開始します。コードを表示し、ブラウザを開きます
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 のどちらか1つだけを指定します。リモートで修復するには、管理者（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 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

tarballを作成せずに、plugin bundle と同じ検証を実行します。

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

任意の --dir でプラグインのディレクトリを選択します。既定値はカレントディレクトリです。

plugin publish

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

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

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

plugin login

GitHubのデバイスフローを使って、マーケットプレイスに認証します。--registry で別のマーケットプレイスを選択できます。既定値は https://marketplace.emdashcms.com です。

npx emdash plugin login

plugin logout

保存済みのマーケットプレイスの認証情報を削除します。任意の --registry には、ログインに使ったものと同じマーケットプレイスを指定する必要があります。

npx emdash plugin logout

emdash export-seed

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

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

オプション

出力形式

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

• 設定：サイトのタイトル、キャッチフレーズ、ソーシャルリンク
• コレクション：すべてのコレクションの定義とフィールド
• タクソノミー：タクソノミーの定義とターム
• メニュー：ナビゲーションのメニューと項目
• ウィジェットエリア：ウィジェットエリアとウィジェット
• コンテンツ（指定した場合）：エントリー。別の環境でも使えるように、$media の参照と $ref: の構文を使います

emdash secrets

プラグインの秘密情報の暗号化に使うキーを生成し、確認します。

secrets generate

デプロイ用の EMDASH_ENCRYPTION_KEY を生成します。このキーは、保存されたプラグインの秘密情報の暗号化に使われます。

npx emdash secrets generate

新しいキーを標準出力に表示します。シークレットの保管場所にパイプで渡すか、--write でローカルの .env ファイルに直接書き込みます。同じ .env ファイルは、Nodeが読み込むほか、ローカル開発ではWranglerとCloudflare Viteプラグインも読み込みます。

npx emdash secrets generate --write .env

--write は、--force を指定しない限り既存のエントリーを上書きしません。暗号化済みのデータがあるデプロイでキーを置き換えると、それらの秘密情報を読めなくなるため、この保護は意図的なものです。

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 はモジュールの拡張（module augmentation）を使い、ローカル開発の中で更新されます。

.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 も使います。