CLI 參考

EmDash CLI 提供管理 EmDash CMS 實例的命令 — 資料庫設定、型別生成、內容 CRUD、結構管理、媒體等。

安裝

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

npm install emdash

使用 npx emdash 執行命令或在 package.json 中新增腳本。為簡便起見，二進位檔也可透過 em 使用。

認證

使用共享遠端客戶端的命令按以下順序解析認證：

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

這些命令接受 --url（從 EMDASH_URL，回退到 http://localhost:4321）和 --token 旗標。認證命令有自己的連線選項。指向本地開發伺服器時不需要權杖。

通用旗標

這些旗標在使用共享遠端客戶端的命令中可用：

輸出

當 stdout 是 TTY 時，CLI 使用 consola 印出格式化結果。當透過管道傳輸或設定了 --json 時，在 stdout 輸出原始 JSON — 適合 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": "已更新"}'

如果項目在你的 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 "部落格文章"

schema delete <collection>

npx emdash schema delete articles
npx emdash schema delete articles --force

schema add-field <collection> <field>

npx emdash schema add-field posts body --type portableText --label "正文內容"
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 "日落" --caption "攝於布里斯托"

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

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

將資料庫結構和內容匯出為種子檔案。

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

選項

輸出格式

匯出的種子檔案包含：

• 設定：網站標題、標語、社群連結
• 集合：所有集合定義及欄位
• 分類法：分類法定義和詞彙
• 選單：導覽選單及項目
• 小工具區域：小工具區域和小工具
• 內容（如果請求）：包含 $media 參照和 $ref: 語法的條目

emdash secrets generate

為你的部署生成 EMDASH_ENCRYPTION_KEY。該金鑰用於加密靜態儲存的外掛程式密鑰。

npx emdash secrets generate

將新金鑰印出到 stdout。管道到你的密鑰儲存，或使用 --write 直接寫入本地 .env 檔案：

npx emdash secrets generate --write .env

emdash secrets fingerprint <key>

印出金鑰的 8 字元指紋（kid），不暴露其值：

npx emdash secrets fingerprint emdash_enc_v1_...

產生的檔案

.emdash/types.ts

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

// 由 EmDash CLI 產生
// 不要手動編輯 - 執行 `emdash types` 重新產生

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": [...]
    }
  ]
}

環境變數

套件腳本

將 CLI 命令新增為 package.json 腳本：

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

結束碼