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

退出代码