emdash-plugin CLI｜EmDash情報局

このページで分かること

@emdash-cms/plugin-cli（コマンド名 emdash-plugin）の役割、インストール方法、コマンドの一覧
init・build・dev・validate・bundle・publish の各コマンドが作るもの・確かめるもの
公開後の状態の確認（info）、パッケージのプロフィールの更新（update-package）、自動リリースの設定（profile setup、release setup など）

難易度: 上級
読む時間: 8分
前提知識: はじめてのサンドボックス型プラグイン／ターミナル・Node.js・npmの最低限

このページの目次

@emdash-cms/plugin-cli は、サンドボックス型プラグインの雛形を作り、ビルド、検証、公開をします。公開者のサインイン、パッケージのプロフィール、プラグインレジストリの検索、自動リリースも管理します。インストールされるコマンドは emdash-plugin です。

CLIは、パッケージのプロフィールとリリースの公開者のIDとして、Atmosphereアカウントを使います。

CLIのインストール

pnpm dlx @emdash-cms/plugin-cli init で作成したプラグインには、バージョンを固定した開発用の依存パッケージとして、CLIが最初から含まれています。既存のプラグインでは、ほかのコマンドを使う前にCLIを追加します。

pnpm add -D @emdash-cms/plugin-cli

各コマンドがプラグインにインストールされたバージョンで動くように、例では pnpm exec emdash-plugin を使います。pnpm dlx は1回だけ実行する init コマンドに使い、繰り返し実行するビルド、ログイン、リリースのコマンドには使いません。

コマンド

CLIには次のコマンドがあります。

emdash-plugin init [name]                    Scaffold a new sandboxed plugin
emdash-plugin build                          Build dist/ (plugin.mjs, manifest.json, index.mjs)
emdash-plugin dev                            Watch sources and rebuild on change
emdash-plugin bundle                         Pack dist/ + assets into a registry tarball
emdash-plugin validate [path]                Validate emdash-plugin.jsonc against the schema
emdash-plugin publish                        Build, upload, and publish a release
emdash-plugin update-package [--yes]         Preview or apply package-profile changes
emdash-plugin profile setup                  Prepare the signed package profile for delegated releases
emdash-plugin release setup                  Create the delegated-release GitHub Actions workflow
emdash-plugin release plan                   Plan repository releases for GitHub Actions
emdash-plugin release prepare <slug[@ver]>   Prepare one repository package for GitHub Actions
emdash-plugin login <handle-or-did>          Sign in with your Atmosphere account
emdash-plugin logout [--did <did>]           Revoke the active session
emdash-plugin whoami                         Show stored sessions
emdash-plugin switch <did>                   Switch the active publisher session
emdash-plugin search <query>                 Free-text registry search
emdash-plugin info <handle-or-did> <slug>    Show package details or listing-check status

現在の引数とフラグは、emdash-plugin <command> --help で確認します。validate、publish、update-package、search、info、login、whoami など、スクリプトから使うことを想定したコマンドは、ヘルプに --json が記載されていればJSONで出力できます。検索系のコマンドは、--registry-url <url> または環境変数 EMDASH_REGISTRY_URL を受け付けます。

人が読むための出力では、プラグインレジストリのパッケージを @<publisher-handle>/<slug> と表示します。ビルドの診断でnpmのパッケージ名を示す必要がある場合は、npm package というラベルを付けて表示します。

次の例は、ほとんどのプラグインが package.json に追加する2つのスクリプトです。

package.json

{
	"scripts": {
		"build": "emdash-plugin build",
		"dev": "emdash-plugin dev"
	}
}

本サイトの補足

やさしい解説

サンドボックス型プラグインは、雛形作り（init）、ビルド（build）、検証（validate）、公開（publish）をすべて emdash-plugin コマンドで進めます。init だけは pnpm dlx で実行し、それ以外はプラグインにインストールされたCLIを pnpm exec emdash-plugin で実行します。こうすると、どのコマンドもプラグインにインストールされた同じバージョンで動きます。

`init`

init で新しいプラグインを作成します。

pnpm dlx @emdash-cms/plugin-cli init my-plugin

このコマンドは、emdash-plugin.jsonc、src/plugin.ts、package.json、tsconfig.json、vitest.config.ts、workerdを使うテスト、README、AGENTS.md、ローカルの creating-plugins スキル、パッケージマネージャーの設定を生成します。.agents/skills と .claude/skills は正本の skills ディレクトリへのリンクで、.claude/CLAUDE.md は AGENTS.md へのリンクです。そのため、CodexとClaudeが同じプロジェクトのガイドを使います。ソースは、SandboxedPlugin 型の定数に代入して既定のエクスポートとした、1つのルートから始まります。テストは、EmDashの本番用のサンドボックスのラッパーとホストのブリッジを通じて、そのルートを呼び出します。

対話式のセットアップでは、公開者（publisher）、作成者（author）、セキュリティの連絡先、ソースリポジトリを尋ね、書き込む前にプロジェクトの概要をすべて表示します。必須フィールドは飛ばせません。

CLIは、npm、pnpm、Yarn、Bunのどれから起動されたかを検出し、それに合ったコマンドを生成します。この選択は --package-manager で上書きできます。pnpmの雛形には、esbuild に必要な、レビュー済みのビルドスクリプトのポリシーが含まれます。

対話なしのセットアップでは、所有者のメタデータを明示的に指定する必要があります。スクリプトでは次の形を使います。

pnpm dlx @emdash-cms/plugin-cli init my-plugin --yes \
  --publisher did:plc:abc123def456 \
  --author-name "Jane Doe" \
  --security-email security@example.com

--use-detected を渡すと、現在有効な公開者のセッションと、ローカルのGitの作成者やリポジトリのメタデータを使うことを選べます。このフラグがない場合、--yes を付けても、身元にかかわるローカルの既定値はコピーされません。

`build`

build は、emdash-plugin.jsonc、src/plugin.ts、省略可能な同じ階層の package.json を読み込み、次のファイルを出力します。

成果物	内容
`dist/plugin.mjs`（＋ `dist/plugin.d.mts`）	フックとルートです。プロセス内（`plugins: []`）と、サンドボックスのローダー（`sandboxed: []`）の両方から読み込まれます。
`dist/manifest.json`	プラグインのマニフェストで、`src/plugin.ts` から読み取ったフックとルートを含みます。`bundle` はこのファイルをそのまま含めます。npmの利用者は、JSONCのソースを解析せずにこのファイルを読み込みます。
`dist/index.mjs`（＋ `dist/index.d.mts`）	サイトが `astro.config.mjs` でインポートするディスクリプターのモジュールです。同じ階層に `package.json` がある場合だけ出力されます。プラグインレジストリ専用のプラグインでは、インポートするものがないため出力されません。

dist/ はビルドの出力です。コミットしないでください。雛形の .gitignore は dist/ を除外しています。npmパッケージをパックまたは公開する前に emdash-plugin build を実行し、package.json の files のリストが生成された成果物を含められるようにします。

`dev`

src/**、emdash-plugin.jsonc、package.json を監視し、150 msのデバウンスでビルドし直します。ビルドは1つずつ順番に実行されます。ビルドし直しに失敗した場合は、最後に成功した dist/ をそのまま残します。そのため、ワークスペースやファイルのリンクでプラグインをインポートしているサイトは、次にビルドが成功するまで動き続けます。Ctrl-Cで、実行中の処理を終えてから停止します。

実際のサイトで開発するには、プラグインのディレクトリで pnpm dev を実行し、pnpm add file:../path/to/plugin でサイトにインストールします。プラグインの既定のエクスポートをインポートし、emdash({ sandboxed: [...] }) に渡します。設定の全体は、はじめてのプラグインのチュートリアルで説明しています。

`validate`

現在のディレクトリのマニフェストを検証します。別のプラグインのディレクトリを渡すこともできます。

emdash-plugin validate          # ./emdash-plugin.jsonc
emdash-plugin validate path/    # a specific directory

オフラインのスキーマチェックで、tsc と同じ形式の file:line:column の診断を出力します。マニフェストのフィールドをまたぐルールも確認します。ネットワークは使いません。コミット前やCIのチェックに適しています。マニフェストのリファレンスも参照します。

`bundle`

bundle は、build の上に重ねた薄いパッケージングの処理です。

build を実行して dist/ を作ります。
バンドルを検証します。Node.jsの組み込みモジュールのインポートがないこと、大きすぎるファイルがないこと、権限（Capability）の宣言に矛盾がないことを確認します。
省略可能なアセット（README、アイコン、スクリーンショット）を集めます。
tarballにまとめます。tarballの中では、plugin.mjs は backend.js（プラグインレジストリが想定するファイル名）としてパックされます。出力は dist/<slug>-<version>.tar.gz です。

--validate-only はtarballの作成を省きますが、dist/ の成果物は作ります。「検証」は「先にビルドする」ことを含むためです。

`publish`

publish は、プラグインをビルドして検証し、パッケージと掲載用の画像を自分のPDSにアップロードしてから、リリースのレコードを書き込みます。

emdash-plugin login alice.example.com
emdash-plugin publish

publish は、プロフィールのフィールドをマニフェストから読み込み、公開者の固定を強制します。ライセンス、作成者、セキュリティの連絡先などのパッケージの情報は、マニフェストに書いておきます。以前のプロフィール用のフラグと --no-manifest は、従来のスクリプトによる公開のために引き続き使えます。そうした流れを保守する場合は、先に publish --help を確認してください。

外部でホストしているパッケージのバンドルを使うには、--url <https-url> を渡します。CLIは、公開の前にそのURLをダウンロードして検証します。--local <path> を追加すると、ローカルのtarballがダウンロードした内容と一致することを確認できます。

ローカルでのリリースの流れの全体は、バンドルと公開に従います。

`info`

info は、アグリゲーターから承認済みのパッケージの詳細を表示します。公開後は、リリースのバージョンと --watch を渡すと、現在のプロフィールとリリースの掲載チェックの状況を追えます。

emdash-plugin info plugins.emdashcms.com audit-log --version 0.2.2 --watch

承認前は、このコマンドはラベラーから直接状態を読み取り、パッケージの識別子とチェックの状態だけを表示します。未承認のパッケージのメタデータをアグリゲーターから返すことはありません。パッケージとリリースが公開されると、承認済みの詳細と、正規のプラグインページのURLを表示します。監視はCtrl-Cで止められます。止めても、公開済みのレコードや掲載チェックには影響しません。

別のラベラーを使うプラグインレジストリを確認する場合は、--labeler-url <origin> または EMDASH_LABELER_URL を使います。

本サイトの補足

やさしい解説

publish で公開したリリースは、プラグインレジストリの掲載チェックを経て一覧に表示されます。info に --watch を付けると、そのチェックの状態を追えます。承認されるまでは、パッケージの識別子とチェックの状態だけが表示され、承認後は詳細とプラグインページのURLが表示されます。監視をCtrl-Cで止めても、公開済みのレコードや掲載チェックには影響しません。

`update-package`

リリースを作らずに既存のパッケージのプロフィールを変えるには、update-package を使います。このコマンドは emdash-plugin.jsonc のプロフィールのフィールドを読み込み、現在の署名付きのプロフィールを取得して、変更案を表示します。

emdash-plugin update-package

--yes を渡さない限り、このコマンドは変更内容を試すだけ（ドライラン）です。

emdash-plugin update-package --yes

書き込みは、現在のレコードのCIDを前提条件として使います。コマンドが読み取ったあとに別のプロセスがプロフィールを変更した場合、新しいレコードを上書きせずに STALE_RECORD で失敗します。マニフェストから省略可能なプロパティを削除しても、公開済みの値は変わりません。置き換えたい値を明示的に指定します。

`profile setup`

profile setup は、公開者が所有するパッケージのプロフィールを、自動リリースのために準備します。プロフィールがない場合は emdash-plugin.jsonc から作成し、有効なプロフィールがすでにある場合は、パッケージのメタデータを置き換えずに、委任リリースの設定を追加します。

対話式のセットアップは、プラグインのディレクトリで実行します。モノレポの別の場所から実行する場合は、--dir <plugin-directory> を渡します。

emdash-plugin profile setup

フラグ	既定値	説明
`--dir <path>`	現在のディレクトリ	プラグインのソースのディレクトリです。
`--repository <url>`	マニフェストの `repo`、次にGitの `origin`	正規の公開GitHubリポジトリのURLです。対話式のセットアップでは、検出したGitHubのリモートをあらかじめ入力し、見つからない場合は尋ねます。
`--confirmation <mode>`	`escalation-only`	権限が増えるときだけ確認する場合は `escalation-only`、すべてのリリースで確認する場合は `always` を使います。
`--yes`、`-y`	`false`	確認せずに既定のポリシーを受け入れます。対話なしの実行でプロフィールを変更する場合は必須です。

このコマンドは、現在のCLIのログインを使ってプロフィールを書き込みます。別の署名付きリポジトリを置き換えることは拒否します。現在のアカウントがマニフェストのpublisherと一致しない場合は、emdash-plugin switch <did> を実行します。プロフィールを公開したあと、手動でのリリースには emdash-plugin publish を、GitHub Actionsには emdash-plugin release setup を案内します。

`release setup`

release setup は、1つのプラグインのディレクトリからパッケージのプロフィールのセットアップを実行し、Gitリポジトリのルートに共有の .github/workflows/emdash-release.yml を1つ作成します。入れ子になったプラグインのパッケージは、同じワークフローを使い回します。プラグインのディレクトリで実行するか、--dir <plugin-directory> を渡します。リポジトリのルートからは、どのパッケージのプロフィールを準備するかが分からないためです。

emdash-plugin release setup

profile setup のフラグに加えて、次のワークフローのオプションを受け付けます。

フラグ	既定値	説明
`--service-url <origin>`	`https://releases.emdashcms.com`	生成されたActionが使うHTTPSのオリジンです。
`--action-ref <ref>`	`main`	リリース用のActionを含む、EmDashのリポジトリのrefです。
`--trigger <mode>`	`auto`	リリースのきっかけです。`changesets`、`tags`、`manual` のどれかです。`auto` は、`.changeset/config.json` がある場合にChangesetsを選択肢に出します。
`--force`	`false`	生成済みの既存のワークフローを置き換えます。このフラグがない場合、セットアップは既存のファイルを変更しません。

対話式のターミナルでChangesetsを検出した場合、セットアップはEmDashのプラグインをどうリリースするかを尋ねます。Follow Changesets releases を選ぶと、emdash-plugin.jsonc を含むパッケージについて、Changesetsと同じバージョンを公開します。ほかの選択肢では、<slug>@<version> のタグに従うか、手動での実行だけを許可します。対話なしの場合、auto は、有効なルートの設定があればChangesetsを、なければパッケージのタグを選びます。

Changesets用のワークフローは、再利用可能なワークフローです。既存のChangesetsの公開ジョブのあとに呼び出し用のジョブを1つ追加し、そのジョブの公式の公開済みパッケージのJSON出力を渡します。EmDash専用の非公開パッケージには、privatePackages.version: true と privatePackages.tag: true が必要です。どちらかがない場合、セットアップは警告を出します。

このコマンドは、生成したワークフローをプッシュしません。最初の自動実行で、GitHubのOpenID Connectを使ってリポジトリの接続リクエストが作成されます。Actionsのシークレットは必要ありません。ワークフローの確認、リリースサービスの承認、リポジトリの接続、最初のリリースの公開は、自動リリースに従います。

`release plan`

release plan は、生成されたワークフローが使います。--published-packages <json> を指定すると、Changesets Actionの出力を emdash-plugin.jsonc を含むパッケージに対応付け、バージョンを確認し、JSONのセレクターのマトリクスを GITHUB_OUTPUT に書き込みます。--package <slug[@version]> を指定すると、手動用のセレクターを1つ検証します。このコマンドは、パッケージのビルドも公開もしません。

`release prepare`

release prepare は、生成されたワークフローがパッケージを特定するために使うコマンドです。リポジトリの中から1つのプラグインのマニフェストを見つけ、省略可能なタグのバージョンを確認し、パッケージをビルドして、パッケージ、公開者、ディレクトリ、バンドルの出力を GITHUB_OUTPUT に書き込みます。

生成されたワークフローは、パッケージのタグを自動で渡します。

emdash-plugin release prepare gallery@1.2.3

ワークフローを手動で実行する場合は、プラグインのIDだけを渡します。コマンドは、そのパッケージのマニフェストのバージョンを使います。プラグインIDの重複、パッケージが見つからない場合、バージョンの不一致は、来歴（provenance）が作成される前に失敗します。

プログラムから使うAPI

CLIのプログラム用の関数をインポートすると、Node.jsからプラグインをビルドまたはバンドルできます。

import { buildPlugin, bundlePlugin } from "@emdash-cms/plugin-cli";

await buildPlugin({ dir: "./my-plugin" });
const result = await bundlePlugin({ dir: "./my-plugin" });

検索や認証情報の補助関数は、@emdash-cms/registry-client からインポートします。

本サイトの補足 · AIへの依頼文

AIに聞いてみよう

目的：emdash-plugin CLIのコマンドのうち、今の作業に必要なものと、その順番を確かめる

EmDashの公式ドキュメント「The emdash-plugin CLI」
（https://docs.emdashcms.com/plugins/creating-plugins/cli/）をもとに、
次の作業に必要なemdash-pluginのコマンドと、実行する順番を教えてください。

やりたい作業：
・（例：既存のプラグインを初めてプラグインレジストリに公開する／GitHub Actionsで自動リリースにする、など）

条件：
・コマンドはプラグインにインストールしたCLIを pnpm exec emdash-plugin で実行する前提にする
・各コマンドについて、何を読み込み、何を作る・書き込むのかを説明する
・ページに書かれていないフラグは使わず、不明な点は --help で確認する手順を示す

回答する前に、必ず公式ドキュメントの現在の内容を確認してください。
EmDash Docs MCP（https://docs.emdashcms.com/mcp）が使える場合は、それで確認してください。

自分で確認すること

AIが示したコマンドが、このページの「コマンド」の一覧に載っている
使うフラグが、pnpm exec emdash-plugin <command> --help の表示に載っている
update-package を使う場合、--yes を付けずに実行したときは変更案が表示されるだけで、プロフィールが書き換わっていない

訳の誤りを報告する