CLI 参考

EmDash CLI 提供用于管理 EmDash CMS 实例的命令——包括数据库设置、类型生成、内容 CRUD、模式管理、媒体等。

安装

CLI 包含在 emdash 包中：

npm install emdash

使用 npx emdash 运行命令，或将脚本添加到 package.json。为了简洁，二进制文件也提供了 em 别名。

认证

与运行中的 EmDash 实例通信的命令（除 init、seed、export-seed 和 auth secret 外）按以下顺序解析认证：

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 init

使用核心模式和可选的模板数据初始化数据库。

npx emdash init [options]

选项

行为

1. 从 package.json 读取 emdash 配置
2. 如需要则创建数据库文件
3. 运行核心迁移（创建系统表）
4. 如已配置则运行模板 schema.sql
5. 如已配置则运行模板 seed.sql

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. 启动 Astro 开发服务器并设置 EMDASH_DATABASE_URL

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 设备流登录 EmDash 实例。

npx emdash login [options]

选项

行为

1. 从实例发现认证端点
2. 如果是 localhost 且未配置认证，自动使用开发绕过
3. 否则启动 OAuth 设备流——显示代码并打开浏览器
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 中的一个提供数据。

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 seed

将种子文件应用到数据库。此命令直接操作本地 SQLite 文件（无需运行服务器）。

npx emdash seed [path] [options]

参数

选项

种子文件解析

命令按以下顺序查找种子文件：

1. 位置参数（如提供）
2. .emdash/seed.json（约定）
3. package.json 中 emdash.seed 字段的路径

emdash export-seed

将数据库模式和内容导出为种子文件。直接操作本地 SQLite 文件。

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

选项

输出格式

导出的种子文件包含：

• 设置：站点标题、标语、社交链接
• 集合：所有集合定义及字段
• 分类法：分类法定义和术语
• 菜单：导航菜单及项目
• 小工具区域：小工具区域和小工具
• 内容（如请求）：带有 $media 引用和 $ref: 语法的条目，便于移植

emdash auth secret

为部署生成安全的认证密钥。

npx emdash auth secret

输出适用于 EMDASH_AUTH_SECRET 的随机密钥。

生成的文件

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

环境变量

包脚本

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

退出码