CLI 參考

EmDash CLI 提供了用於資料庫設定、型別產生、內容建立與編輯、Schema 管理、媒體以及站台匯出與匯入的指令。

安裝

CLI 包含在 emdash 套件中。使用以下指令安裝：

npm install emdash

使用 npx emdash 執行指令，或將腳本新增到 package.json。該執行檔也可簡寫為 em。

使用站台的套件腳本（例如 pnpm dev）啟動站台。套件腳本會啟動 Astro；EmDash 整合會產生 emdash-env.d.ts，而執行階段會在第一次請求時執行待處理的遷移，並在設定完成之前一次性套用內建種子的 Schema 和結構。種子中的範例內容只有在管理員於設定精靈中選擇時才會套用。

身分驗證

連線到執行中的 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]

該指令會將每項檢查回報為通過、警告或失敗，並在有檢查失敗時以非零狀態結束。

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 執行個體的 Schema 產生 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. 從執行個體取得 Schema
2. 產生 TypeScript 型別定義
3. 將型別寫入輸出檔案
4. 在旁邊寫入 schema.json 以供參考

emdash login

使用 OAuth 裝置流程（OAuth Device Flow）登入 EmDash 執行個體。

npx emdash login [options]

選項

行為

1. 從執行個體探索身分驗證端點
2. 如果是 localhost 且未設定身分驗證，則自動使用開發繞過
3. 否則啟動 OAuth 裝置流程——顯示一組代碼並開啟瀏覽器。你輸入代碼後，管理頁面會在你核准之前列出 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——請重新讀取後再試。

如果有人在管理後台中開啟了該條目，伺服器會回傳 409，代碼為 ENTRY_LOCKED，訊息中會指明持有者。請等待對方完成，或 傳入 --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 站台套件，並將站台套件匯入到空站台中。站台遷移指南說明了站台套件包含什麼、目標站台需要什麼，以及如何閱讀匯入計畫。

權杖需要 admin 範圍（emdash login 的權杖具有該範圍），或相應的遷移範圍：匯出需要 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 和 receiptDigestValid，後者表示回條的 receiptDigest 是否與其內容相符。

以下形式透過操作 ID 對某個匯入進行操作：

cancel 和 abandon 會要求確認。傳入 --yes 可略過提示；使用 --json 或 stdout 不是終端機時，也會略過提示。當 stdin 不是終端機且上述兩種情況都不適用時，指令會以 INVALID_ARGUMENT 失敗。拒絕提示不會變更任何內容，並以結束碼 1 結束。兩者的 JSON 結果都是 { operationId, state, operation }。

匯入指令使用以下結束碼：

emdash export-seed

將資料庫 Schema 和內容匯出為種子檔案。直接對本機 SQLite 檔案進行操作。

資料庫必須包含已安裝的 EmDash 版本所知的每一個遷移。如果指令 回報存在待處理的遷移，請執行 npx emdash migrate，然後再次匯出。如果資料庫是由較新版本的 EmDash 遷移的， 請先升級已安裝的版本再匯出。匯出 以唯讀方式開啟資料庫，且自身從不套用遷移。

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

選項

輸出格式

匯出的種子檔案包含：

• 設定：站台標題、標語、社群連結
• 集合：所有集合定義及其欄位
• 區塊型別：每個保留的版本以及每種型別的使用中版本指標
• 分類法：分類法定義和詞彙
• 選單：帶選單項目的導覽選單
• 重新導向：狀態為 301、302、307 或 308 的重新導向規則
• 小工具區域：小工具區域和小工具
• 區段：可重複使用的內容區塊
• 內容（如有請求）：帶有 $media 參照和 $ref: 語法（便於移植）的條目

已排程的條目會作為草稿匯出，因為種子中沒有發布時間的欄位。匯出會略過 emdash seed 會拒絕的內容，並在 stderr 上給出警告：狀態為 410 或 451 的重新導向規則、共用同一來源的額外規則（舊資料庫中可能出現），以及 slug 中包含小寫字母、數字和連字號以外字元的區段。

媒體 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 上輸出警告。

圖片和檔案欄位，以及重複器（repeater）的圖片子欄位，會作為 $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-env.d.ts

當本機開發伺服器啟動時，Astro 整合會在專案根目錄產生 emdash-env.d.ts。在透過執行中的開發站台變更 Schema 之後，它會重新整理該檔案。這些宣告擴充了 EmDashCollections，因此像 getEmDashCollection("posts") 這樣的呼叫會推斷出本機資料庫中定義的欄位。

該檔案是自動產生的，屬於本機 Astro 開發工作流程。你不需要執行 emdash types 來建立它。

.emdash/types.ts

emdash types 指令會取得執行中執行個體的 Schema，並寫出獨立的 TypeScript 介面。當 Schema 位於遠端 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 的原始 Schema 匯出。使用預設輸出路徑時，該檔案為 .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。