CLI 參考

EmDash CLI 提供管理 EmDash CMS 執行個體的命令 — 資料庫設定、型別產生、內容 CRUD、結構描述管理、媒體等。

安裝

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

npm install emdash

使用 npx emdash 執行命令或將指令碼新增到 package.json。二進位檔案也可簡寫為 em。

驗證

與執行中的 EmDash 執行個體通訊的命令按以下順序解析驗證：

1. --token 旗標 — 命令列上的明確權杖
2. EMDASH_TOKEN 環境變數
3. 儲存的憑證 來自 ~/.config/emdash/auth.json（由 emdash login 儲存）
4. 開發繞過 — 如果 URL 是 localhost 且沒有可用權杖，則透過開發繞過端點自動驗證

大多數命令接受 --url（預設 http://localhost:4321）和 --token 旗標。當針對本機開發伺服器時，不需要權杖。

常用旗標

這些旗標在所有遠端命令上可用：

輸出

當 stdout 是 TTY 時，CLI 使用 consola 美化列印結果。當透過管道傳輸或設定 --json 時，它輸出原始 JSON 到 stdout — 適合 jq 或其他工具。

命令

emdash dev

啟動具有自動資料庫設定的開發伺服器。

npx emdash dev [options]

選項

範例

# 啟動開發伺服器
npx emdash dev

# 自訂連接埠
npx emdash dev --port 3000

# 啟動前從遠端產生型別
npx emdash dev --types

行為

1. 檢查並執行待處理的資料庫遷移
2. 如果設定了 --types，從遠端執行個體產生 TypeScript 型別（URL 來自 EMDASH_URL 環境變數或 package.json 中的 emdash.url）
3. 使用設定的 EMDASH_DATABASE_URL 啟動 Astro 開發伺服器

emdash types

從執行中的 EmDash 執行個體的結構描述產生 TypeScript 型別。

npx emdash types [options]

選項

範例

# 從本機開發伺服器產生型別
npx emdash types

# 從遠端執行個體產生
npx emdash types --url https://my-site.pages.dev

# 自訂輸出路徑
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 中的恰好一個提供資料。除非設定了 --draft，否則新項目會自動發布。

content update <collection> <id>

您必須提供來自先前 get 的 _rev 權杖以證明您已看到目前狀態。這可以防止覆寫您未看到的變更。以下步驟讀取一個項目，然後使用該權杖更新它：

# 1. 讀取項目，記下 _rev
npx emdash content get posts 01ABC123

# 2. 使用步驟 1 中的 _rev 更新
npx emdash content update posts 01ABC123 \
  --rev MToyMDI2LTAyLTE0... \
  --data '{"title": "Updated"}'

如果項目自您的 get 以來已變更，伺服器傳回 409 Conflict — 重新讀取並重試。

content delete <collection> <id>

npx emdash content delete posts 01ABC123

軟刪除內容項目（移至資源回收筒）。

content publish <collection> <id>

npx emdash content publish posts 01ABC123

content unpublish <collection> <id>

npx emdash content unpublish posts 01ABC123

content schedule <collection> <id>

npx emdash content schedule posts 01ABC123 --at 2026-03-01T09:00:00Z

content restore <collection> <id>

npx emdash content restore posts 01ABC123

還原已刪除的內容項目。

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

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 export-seed

將資料庫結構描述和內容匯出為種子檔案。直接在本機 SQLite 檔案上運作。

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

選項

輸出格式

匯出的種子檔案包括：

• 設定：網站標題、標語、社交連結
• 集合：所有帶有欄位的集合定義
• 分類：分類定義和術語
• 選單：帶有項目的導覽選單
• 小工具區域：小工具區域和小工具
• 內容（如果要求）：帶有 $media 參照和 $ref: 語法的條目，以實現可攜性

emdash secrets generate

為您的部署產生 EMDASH_ENCRYPTION_KEY。該金鑰用於加密靜態外掛程式祕密。

npx emdash secrets generate

將新金鑰列印到 stdout。將其管道傳輸到您的祕密儲存，或使用 --write 直接寫入開發檔案。以下命令將金鑰寫入 .dev.vars 或 .env：

npx emdash secrets generate --write .dev.vars
npx emdash secrets generate --write .env

--write 拒絕在沒有 --force 的情況下覆寫現有條目。在具有現有加密資料的部署中取代金鑰將使這些祕密無法讀取，因此保護是有意的。

emdash secrets fingerprint <key>

列印金鑰的 8 字元指紋（kid）而不暴露其值。這在 CI 中很有用，可以驗證部署了正確的金鑰。以下命令列印金鑰的指紋：

npx emdash secrets fingerprint emdash_enc_v1_...

產生的檔案

.emdash/types.ts

emdash types 命令為每個集合產生 TypeScript 介面：

// Generated by EmDash CLI
// Do not edit manually - run `emdash types` to regenerate

import type { PortableTextBlock } from "emdash";

export interface Post {
	id: string;
	title: string;
	content: PortableTextBlock[];
	publishedAt: Date | null;
}

.emdash/schema.json

該命令還為工具編寫原始結構描述匯出：

{
  "version": "a1b2c3d4",
  "collections": [
    {
      "slug": "posts",
      "label": "Posts",
      "fields": [...]
    }
  ]
}

環境變數

Package 指令碼

為方便起見，將 CLI 命令新增為 package.json 指令碼：

{
	"scripts": {
		"dev": "emdash dev",
		"types": "emdash types",
		"export-seed": "emdash export-seed",
		"db:reset": "rm -f data.db"
	}
}

結束代碼