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]

套用種子會先執行核心遷移。在持續整合中需要在不開啟或建立資料庫的情況下檢查檔案時，使用 --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 之一恰好提供一種方式提供資料。除非設定 --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、語言、slug、狀態，以及是否為要求的項目。

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

修復一個集合或每個內容集合的內容媒體使用索引。在匯入或直接資料庫寫入之後，當使用涵蓋過時或不可信時使用。

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

恰好傳遞 --collection 或 --all 之一。遠端修復需要 Admin 使用者和具有 admin 範圍的身分驗證權杖。

全部內容修復同步執行，在大型網站上可能較慢或昂貴。僅需修復一個集合時優先使用 --collection。

結構化的 complete、partial 和 stale 結果以 0 結束；結構化的 failed 結果以 1 結束。自動化和 cron 作業應使用 --json 並解析 status、failedSourceCount、skippedSourceCount 以及每個集合的摘要，而不是將結束 0 視為完整涵蓋。

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>

分兩步匯入套件。先分析，然後確認分析列印的計畫摘要：

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，或傳遞 --build 以先從 --dir 建置。

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 的重新導向規則、共用同一來源的額外規則（在較舊資料庫中可能出現），以及 slug 包含小寫字母、數字和連字號以外字元的 section。

媒體 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

沒有 --force 時，--write 拒絕覆寫現有項目。要輪換帶有現有加密資料的部署，將產生的金鑰前置到現有值，並用逗號分隔金鑰。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。