CLI 参考

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

安装

CLI 包含在 emdash 包中。使用以下命令安装：

npm install emdash

使用 npx emdash 运行命令或将脚本添加到 package.json。二进制文件也可以用简写 em 来调用。

使用包脚本启动站点，例如 pnpm dev。包脚本启动 Astro；EmDash 集成生成 emdash-env.d.ts，运行时在首次请求时运行待执行的迁移，并在数据库为空且设置未完成时应用内置的种子。

身份验证

使用共享远程客户端的命令按以下顺序解析身份验证：

1. --token 标志 — 命令行上的显式令牌
2. EMDASH_TOKEN 环境变量
3. 存储的凭证 来自 ~/.config/emdash/auth.json（由 emdash login 保存）
4. 开发绕过 — 如果 URL 是 localhost 且没有可用令牌，自动通过开发绕过端点进行身份验证

这些命令接受 --url（来自 EMDASH_URL，回退到 http://localhost:4321）和 --token 标志。身份验证命令有自己的连接选项。当目标是本地开发服务器时，不需要令牌。

通用标志

这些标志可用于使用共享远程客户端的命令：

输出

对于使用共享远程客户端的命令，当输出是 TTY 时使用 consola 美化打印，当通过管道或设置了 --json 时变为原始 JSON。emdash migrate 仅在使用其显式 --json 选项时输出 JSON。

命令

emdash migrate

检查或应用由 Astro 构建发出的核心迁移集。

npx emdash migrate [options]
npx emdash migrate --check [options]
npx emdash migrate --status --json [options]

默认情况下，该命令发现项目根目录并读取 .emdash/migrations.json。它验证清单与项目安装的 EmDash 包是否匹配，解析适配器的项目本地执行器，并在执行任何 SQL 之前打印不可变目标。

选项

交互式人类可读应用会请求确认。非交互式应用和每次使用 --json 的应用都需要为目标打印的确切指纹。没有 down 或 --dry-run；使用 --check 来确定是否需要工作。

退出码

参见管理核心数据库迁移了解部署顺序、目标凭证和 D1 序列化。

emdash dev（已弃用）

此旧版命令在启动 Astro 之前初始化并迁移本地 SQLite 数据库。该行为不使用站点配置的数据库适配器，且与 Cloudflare D1 开发不兼容。现有调用现在在执行任何数据库工作之前会打印弃用警告。

emdash types

从运行中的 EmDash 实例的 schema 生成 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. 从实例获取 schema
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 三者之一提供数据。除非设置了 --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

media repair-usage

修复一个集合或所有内容集合的内容媒体使用索引。在导入或直接数据库写入后当使用覆盖率已过时或不可信时使用。

npx emdash media repair-usage --collection posts
npx emdash media repair-usage --all
npx emdash media repair-usage --all --json

传入 --collection 或 --all 之一。远程修复需要管理员用户和具有 admin 范围的身份验证令牌。

全内容修复同步运行，在大型站点上可能很慢或开销大。当只需要修复一个集合时优先使用 --collection。

结构化的 complete、partial 和 stale 修复结果以 0 退出；结构化的 failed 结果以 1 退出。自动化和定时任务应使用 --json 并解析 status、failedSourceCount、skippedSourceCount 和每个集合的摘要，而不是将退出 0 视为完整覆盖。

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

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

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

选项

输出格式

导出的种子文件包含：

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

emdash secrets generate

为部署生成 EMDASH_ENCRYPTION_KEY。该密钥用于加密静态存储的插件密钥。

npx emdash secrets generate

将新密钥打印到标准输出。将其通过管道传入您的密钥存储，或使用 --write 直接写入本地 .env 文件。同一 .env 文件由 Node 读取，在本地开发中也由 Wrangler 和 Cloudflare Vite 插件读取：

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

该命令还写入原始 schema 导出以供工具使用：

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

环境变量

包脚本

为方便起见，将常用命令添加为 package.json 脚本：

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

退出码