CLI 参考

EmDash CLI 提供数据库设置、类型生成、创建与编辑内容、架构管理、媒体、站点导出与导入以及插件开发的命令。

安装

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

npm install emdash

使用 npx emdash 运行命令，或向 package.json 添加脚本。为简洁起见，二进制文件也可用作 em。

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

身份验证

连接到运行中 EmDash 实例的命令按此顺序解析身份验证：

1. --token 标志 — 命令行上的显式令牌
2. EMDASH_TOKEN 环境变量
3. 存储的凭据 — 来自 ~/.config/emdash/auth.json（由 emdash login 保存）
4. Dev bypass — 若 URL 为 localhost 且无可用令牌，则通过 dev bypass 端点自动身份验证

types、whoami、content、schema、media、search、taxonomy、menu 和 site 命令连接到运行中的实例。身份验证命令有自己的连接选项。面向本地开发服务器时不需要令牌。

通用标志

连接标志因命令而异。下方分组的命令表示该组中的每个子命令。

输出

当命令将结果写入交互式终端时，会格式化为便于阅读。上方带 --json 的命令在设置该标志或输出被管道传输时写入原始 JSON。emdash migrate 仅在使用其显式 --json 选项时发出 JSON。

命令

emdash init

从 package.json 中的模板元数据初始化本地 SQLite 数据库。该命令运行核心迁移，然后应用 emdash.schema 命名的可选 SQL 文件。JSON 种子数据请单独运行 emdash seed。

npx emdash init [options]

没有 --force 时，已初始化的数据库保持不变。此命令直接打开本地 SQLite 文件；部署管理的 D1、PostgreSQL、libSQL 或 Hyperdrive 迁移请使用 emdash migrate。

emdash doctor

检查本地 SQLite 数据库的连接、迁移、集合、表和用户问题。若项目有 Wrangler 配置，该命令还会检查 Cron Trigger 与 EmDash scheduled() 处理程序是否一起配置。

npx emdash doctor [options]

该命令将每项检查报告为通过、警告或失败，并在检查失败时以非零退出。

emdash seed

将 JSON 种子验证或应用到本地 SQLite 数据库。该命令在提供时使用位置路径，然后是 .emdash/seed.json，然后是 package.json 中的 emdash.seed 路径。

npx emdash seed [path] [options]

应用种子会先运行核心迁移。在持续集成中需要在不打开或创建数据库的情况下检查文件时，使用 --validate。

emdash migrate

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

npx emdash migrate [options]
npx emdash migrate --check [options]
npx emdash migrate --status --json [options]
npx emdash migrate --release-lock <id> [options]

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

选项

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

退出码

有关部署顺序、目标凭据和 D1 迁移锁，请参见 Manage Core Database Migrations。

emdash dev（已弃用）

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

emdash types

从运行中 EmDash 实例的架构生成 TypeScript 类型。

npx emdash types [options]

选项

示例

# Generate types from local dev server
npx emdash types

# Generate from remote instance
npx emdash types --url https://my-site.pages.dev

# Custom output path
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 且未配置身份验证，则自动使用 dev bypass
3. 否则启动 OAuth Device Flow — 显示代码并打开浏览器。输入代码后，管理页面会在你批准之前列出 CLI 将获得的权限，以及你的角色不允许的任何请求权限。
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. Read the item, note the _rev
npx emdash content get posts 01ABC123

# 2. Update with the _rev from step 1
npx emdash content update posts 01ABC123 \
  --rev MToyMDI2LTAyLTE0... \
  --data '{"title": "Updated"}'

若自你的 get 以来该项已更改，服务器返回 409 Conflict — 重新读取并重试。

若有人在管理面板中打开了该条目，服务器返回带代码 ENTRY_LOCKED 和指明持有者的消息的 409。等待他们完成，或 传递 --override-lock。同一标志可用于 content delete、 content publish、content unpublish 和 content schedule。

content delete <collection> <id>

npx emdash content delete posts 01ABC123

软删除内容项（移至回收站）。

传递 --override-lock 以删除另一位编辑者已打开的条目。

content publish <collection> <id>

npx emdash content publish posts 01ABC123

传递 --override-lock 以发布另一位编辑者已打开的条目。

content unpublish <collection> <id>

npx emdash content unpublish posts 01ABC123

传递 --override-lock 以取消发布另一位编辑者已打开的条目。

content schedule <collection> <id>

npx emdash content schedule posts 01ABC123 --at 2026-03-01T09:00:00Z

传递 --override-lock 以排期另一位编辑者已打开的条目。

content restore <collection> <id>

npx emdash content restore posts 01ABC123

恢复已移入回收站的内容项。

content translations <collection> <id>

列出该条目翻译组中的每个翻译：

npx emdash content translations posts 01ABC123

结果包括每个翻译的 ID、语言、slug、状态，以及是否为请求的条目。

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 用户和具有 admin 范围的身份验证令牌。

全部内容修复同步运行，在大型站点上可能较慢或昂贵。仅需修复一个集合时优先使用 --collection。

结构化的 complete、partial 和 stale 结果以 0 退出；结构化的 failed 结果以 1 退出。自动化和 cron 作业应使用 --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 site

将整个站点导出为 .emdash 站点包，并将包导入到空站点。站点转移指南 说明了包包含什么、目标站点需要什么，以及如何阅读导入计划。

令牌需要 emdash login 令牌所具有的 admin 范围，或匹配的转移范围：导出用 transfer:export，导入用 transfer:analyze 和 transfer:execute。没有它们的令牌会以 INSUFFICIENT_SCOPE 失败。

进度消息始终到 stderr，结果到 stdout。使用 --json 时，或 stdout 不是终端时，stdout 仅包含 JSON 结果。错误写为 { "error": { "code": "…", "message": "…" } }。代码是服务器的错误代码，加上错误标志的 INVALID_ARGUMENT、恢复的导入仍需要包文件时的 PACKAGE_FILE_REQUIRED，以及 UNKNOWN_ERROR。

命令会以退避重试网络失败以及 408、429 和 5xx 响应。

site export

导出站点并将其写入包文件：

npx emdash site export --output site.emdash

该命令启动导出，推进至完成，并逐文件下载包文件。它检查下载的清单是否与导出的包摘要匹配，若不匹配则在写入任何内容之前以 TRANSFER_PACKAGE_DIGEST_MISMATCH 失败。写入前检查每个文件的大小和 SHA-256 摘要。包写入到 <output>.partial，完成时重命名为输出路径。

该命令将其进度保存在 <output>.partial.json，下载的文件保存在 <output>.parts/ 目录。中断后再次运行同一命令以恢复同一导出；已下载的文件会经检查并复用，命令会报告复用了多少。包写入时两者都会删除。当进度文件是为另一 URL 或另一评论设置写入，或其导出失败或过期时，会被忽略；命令随后开始新导出。

JSON 结果包含 operationId、output、packageDigest、files、bytes 和 resumed。

site import <file>

分两步导入包。先分析，然后确认分析打印的计划摘要：

npx emdash site import site.emdash --analyze
npx emdash site import site.emdash --plan sha256:3f1c… --confirm

--analyze 在本地验证整个包文件，然后找到站点上同一包的现有导入或创建一个。它上传站点尚无的文件，运行分析，并打印计划：包和计划摘要、记录计数、大小、标题和标语选择、每个主体及其映射、「Differences from the source site」下的转换、警告和阻止项。若同一包的先前导入失败、被取消或放弃，或已过期，命令会警告并开始新导入。

决定与导入一起存储，因此不带决定标志的后续 --analyze 运行会保留它们。每次更改决定都会产生新的计划摘要。决定不能与 --plan 组合，--plan 不能与 --analyze 组合。

--plan <digest> --confirm 仅在摘要与当前计划匹配时执行导入，然后推进至完成并打印收据。若自你审查以来计划已更改，命令以 TRANSFER_PLAN_DIGEST_MISMATCH 失败；再次分析并确认新摘要。

--analyze 的 JSON 结果包含 operationId、state、packageDigest、planDigest、executable 和完整的 plan。--confirm 的 JSON 结果包含 operationId、state（complete）、receipt，以及报告收据的 receiptDigest 是否与其内容匹配的 receiptDigestValid。

这些形式通过其操作 ID 操作导入：

cancel 和 abandon 会请求确认。传递 --yes 以跳过提示；使用 --json 或 stdout 不是终端时也会跳过提示。当 stdin 不是终端且两者都不适用时，命令以 INVALID_ARGUMENT 失败。拒绝提示不会更改任何内容，并以代码 1 退出。两者的 JSON 结果均为 { operationId, state, operation }。

导入命令以这些代码退出：

emdash plugin

创建、验证、打包和发布 EmDash 插件。市场登录与登录 CMS 实例是分开的。

plugin init

搭建沙箱或原生插件：

npx emdash plugin init --dir ./my-plugin --name my-plugin --format sandboxed

plugin bundle

验证插件并创建其市场 tarball：

npx emdash plugin bundle --dir ./my-plugin --outDir ./artifacts

plugin validate

运行与 plugin bundle 相同的验证，但不创建 tarball：

npx emdash plugin validate --dir ./my-plugin

可选的 --dir 选择插件目录，默认为当前目录。

plugin publish

将包上传到市场，默认等待其处理结果：

npx emdash plugin publish --tarball ./dist/my-plugin-1.0.0.tar.gz

提供 --tarball，或传递 --build 以先从 --dir 构建。

plugin login

通过 GitHub device flow 向市场进行身份验证。--registry 选择不同的市场，默认为 https://marketplace.emdashcms.com。

npx emdash plugin login

plugin logout

移除保存的市场凭据。可选的 --registry 必须标识与登录时相同的市场。

npx emdash plugin logout

emdash export-seed

将数据库架构和内容导出为种子文件。直接在本地 SQLite 文件上工作。

数据库必须具有已安装 EmDash 版本已知的每个迁移。若命令 报告待处理迁移，请运行 npx emdash migrate，然后再次导出。若数据库由 较新的 EmDash 版本迁移，请在导出前升级已安装版本。导出 以只读方式打开数据库，且自身从不应用迁移。

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

选项

输出格式

导出的种子文件包括：

• Settings：站点标题、标语、社交链接
• Collections：带字段的所有集合定义
• Block types：每个保留的版本以及每种类型的活动版本指针
• Taxonomies：分类法定义和术语
• Menus：带项的导航菜单
• Redirects：状态为 301、302、307 或 308 的重定向规则
• Widget Areas：小部件区域和小部件
• Sections：可复用的内容块
• Content（若请求）：带 $media 引用和 $ref: 语法的条目，便于移植

已排期条目导出为草稿，因为种子没有发布时间字段。导出在 stderr 上警告并省略 emdash seed 会拒绝的内容：状态为 410 或 451 的重定向规则、共享同一源的额外规则（在较旧数据库中可能出现），以及 slug 包含小写字母、数字和连字符以外字符的 section。

媒体 URL

emdash seed 下载每个 $media URL 并将文件上传到目标站点的存储，因此需要它能到达的绝对 http 或 https URL。传入源站点的公开 URL 以写入绝对 URL：

npx emdash export-seed --with-content=all --media-base-url=https://example.com > seed.json

在应用种子时，站点必须在该 URL 下从 /_emdash/api/media/file/ 提供其媒体，且 URL 不得指向 localhost 或私有网络地址，emdash seed 拒绝从这些地址下载。没有 --media-base-url 时，$media URL 是站点相对路径，emdash seed 会跳过它们使字段为空，导出在 stderr 上打印警告。

图像和文件字段，以及中继器的图像子字段，导出为 $media 引用。Portable Text 字段内的图像保留其存储的媒体 ID 和 URL，在不同站点上不会解析。

emdash secrets

生成并检查用于加密插件密钥的密钥。

secrets generate

为你的部署生成 EMDASH_ENCRYPTION_KEY。该密钥用于 在静态时加密插件密钥。

npx emdash secrets generate

将新密钥打印到 stdout。将其管道到你的密钥存储，或用 --write 直接写入本地 .env 文件。Wrangler 和 Cloudflare Vite 插件在本地开发中读取该文件。独立 Node 服务器不会 自动加载 .env；通过进程管理器加载，或通过 服务器的进程环境提供密钥。Node.js 部署 指南 显示了本地命令。

npx emdash secrets generate --write .env

没有 --force 时，--write 拒绝覆盖现有条目。要轮换带有现有加密数据的部署，将生成的密钥前置到现有值，并用逗号分隔密钥。EmDash 用第一个密钥加密新值，并通过 kid 使用较旧条目进行解密。在移除旧密钥之前重新保存每个插件密钥。EmDash 目前不列出存储设置仍使用的密钥 ID，因此请保留你重新保存的凭据清单，并在移除其旧密钥之前验证每个集成。

secrets fingerprint <key>

打印密钥的 8 字符指纹（kid），而不暴露其 值。这在 CI 中对于验证部署了正确的密钥很有用。以下命令打印密钥的指纹：

npx emdash secrets fingerprint emdash_enc_v1_...

emdash auth（已弃用）

auth secret

生成旧版 EMDASH_AUTH_SECRET 值：

npx emdash auth secret

现有安装可以保留此变量以保持稳定的评论者 IP 哈希。它不加密插件密钥。

生成的文件

emdash-env.d.ts

当本地开发服务器启动时，Astro 集成在项目根目录生成 emdash-env.d.ts。它在通过运行中的开发站点进行架构更改后刷新该文件。这些声明扩展 EmDashCollections，因此像 getEmDashCollection("posts") 这样的调用会推断本地数据库中定义的字段。

此文件是自动的，属于本地 Astro 开发工作流。你不需要运行 emdash types 来创建它。

.emdash/types.ts

emdash types 命令获取运行中实例的架构并写入独立的 TypeScript 接口。当架构位于远程 EmDash 实例、工具需要自定义路径的文件，或本地 Astro 开发服务器未运行时使用它：

// Generated by EmDash CLI
// Do not edit manually - run `emdash types` to regenerate

import type { PortableTextBlock } from "emdash";

export interface Post {
	id: string;
	slug: string | null;
	status: string;
	title: string;
	content?: PortableTextBlock[];
	createdAt: Date;
	updatedAt: Date;
	publishedAt: Date | null;
	bylines?: ContentBylineCredit[];
	terms?: Record<string, TaxonomyTerm[]>;
}

远程输出包含独立的集合接口，不扩展 EmDashCollections。它仅在你运行 emdash types 时更改；emdash-env.d.ts 使用模块增强，并作为本地开发的一部分刷新。

.emdash/schema.json

该命令还会在所选 TypeScript 输出旁边写入名为 schema.json 的原始架构导出。使用默认输出路径时，文件为 .emdash/schema.json：

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

一般退出码

大多数命令用 0 表示成功，用 1 表示错误。emdash migrate 还对其 退出码表 中列出的特定结果使用代码 2、3、4 和 130。当导入计划有阻止项时，emdash site import 使用 2。