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"
	}
}

退出码