EmDash CLI（命令为 emdash，短别名为 em）是用于管理 EmDash CMS 实例的命令行工具。其命令分为两类：本地命令操作项目文件或已配置的数据库，包括 init、doctor、seed、migrate、export-seed 和 secrets；远程命令与运行中的 EmDash 实例通信，包括 types、login、logout、whoami、content、schema、media、search、taxonomy、menu 和 site。可通过 npx emdash --help 及 npx emdash <command> --help 查看已安装版本的确切命令与标志。
认证方面，远程命令按以下顺序自动解析认证：--token 标志、EMDASH_TOKEN 环境变量、emdash login 存储的凭据、仅限 localhost 的开发绕过。对于启用了开发绕过的本地开发服务器，客户端可自动认证；对于远程实例，可运行 emdash login --url https://example.com 或提供限定范围的令牌。位于 Cloudflare Access 或其他反向代理之后的站点需要在每个请求上附加认证头，CLI 通过 --header 标志和环境变量支持此需求。在 CI 中建议通过环境变量提供敏感头（如 EMDASH_HEADERS），避免将服务密钥写入凭据文件或 shell 历史。若未配置服务令牌且已安装 cloudflared，CLI 会自动检测 Access 拦截、尝试通过 cloudflared access token 获取缓存 JWT，并回退到 cloudflared access login 进行浏览器认证；此方式适用于交互使用，不适合 CI。--header 标志也支持任意认证方案，如 Basic auth 或自定义 API Key 头。
数据库设置方面，正常站点启动应使用项目的 package 脚本；首次请求会运行待处理的迁移，并在设置完成前应用捆绑 seed 的 schema 与结构一次；示例内容来自设置向导、/_emdash/api/setup/dev-bypass 或 emdash seed。Astro 集成会在服务器启动时生成 emdash-env.d.ts。可使用 emdash export-seed 将现有数据库导出为 seed 文件，运行时会在首次启动时自动发现 .emdash/seed.json。
类型生成方面，emdash types 可从本地开发服务器或远程实例生成类型，并写入 .emdash/types.ts（TypeScript 接口）和 .emdash/schema.json，支持 --output 自定义输出路径。
内容 CRUD 方面，CLI 为智能体设计，创建和更新默认自动发布，使智能体获得写后读一致性而无需管理草稿。content list 支持按状态和数量过滤；content get 会将 Portable Text 字段转换为 markdown，并返回待处理草稿数据（可用 --raw 跳过转换，--published 忽略待处理草稿）；content create 支持 --data、--file、--slug、--draft、--stdin；content update 需要来自先前 get 的 --rev，默认自动发布，可用 --draft 保留为草稿；content delete 为软删除。生命周期命令包括 publish、unpublish、schedule（--at 指定时间）、restore。
Schema 管理方面，schema list 列出集合，schema get 获取集合及字段，schema create 创建集合，schema delete 删除集合（建议先检查并确认目标），schema add-field 添加字段（支持 --type、--label、--required 等），schema remove-field 移除字段。schema add-field 支持 --help 打印的字段类型；完整产品 schema 支持更多字段类型，但不一定能通过此命令创建。
媒体方面，media list 可列出媒体（支持 --mime 过滤），media upload 上传文件（支持 --alt、--caption），media get 和 media delete 用于获取与删除。搜索方面，emdash search 提供全文检索，支持 --collection 和 --limit。分类法方面，taxonomy list 列出分类法，taxonomy terms 列出术语，taxonomy add-term 添加术语（支持 --name、--slug、--parent）。菜单方面，menu list 列出菜单，menu get 获取指定菜单。
站点导出与导入方面，emdash site 可将整个站点（内容模型、内容、历史、设置和媒体，但不含用户或密钥）复制为 .emdash 站点包，并将包导入空站点。令牌需要 admin 权限（emdash login 令牌具备），或 transfer:export、transfer:analyze 和 transfer:execute 范围；INSUFFICIENT_SCOPE 错误表示令牌两者皆无。站点包包含所有条目以及作者和评论者的电子邮件地址，应视为数据库备份对待。导出命令可重复运行以在中断后恢复。导入分两步：先 --analyze 上传并分析，打印计划及其摘要；再以 --plan sha256:<hex> --confirm 执行已审查的计划。可通过 operation id 查询状态、恢复、获取回执，或取消/放弃导入。执行 --confirm 前应向用户展示计划（与源站点的差异、警告、阻塞项、主体映射）并获得确认；导入会写入目标站点并在完成前阻止其他写入。site import 在计划存在阻塞项时退出码为 2，site import status 在导入失败、取消、放弃或过期时退出码为 1。仅在用户要求时取消或放弃导入；放弃会在站点上留下部分数据，之后需重置才能再次导入。--map-principal 接受 <principal id 或 email>=<user id、email 或 none> 且可重复；决策标志仅与 --analyze 一起使用，每次更改都会产生新的计划摘要。导入期间公共站点不会被隐藏，因此目标站点应保持私有，直到命令打印出 receiptDigestValid: true 的回执。
草稿与发布方面，CLI 在创建和更新时默认自动发布：create 创建条目并立即发布；update 更新条目，若创建了草稿修订则发布；get 在存在待处理草稿（例如来自管理界面）时返回草稿数据。在 create/update 上使用 --draft 可跳过自动发布；在 get 上使用 --published 可忽略待处理草稿。支持修订的集合将编辑存储为草稿修订，CLI 透明处理，智能体无需知道集合是否使用修订。
JSON 输出方面，所有远程命令支持 --json 以获得机器可读输出，当 stdout 被管道传输时自动启用。emdash site 始终将进度写入 stderr，因此 stdout 仅包含 JSON 结果；错误格式为 { "error": { "code", "message" } }。可用于 jq 管道或脚本中提取 ID 等。
关于内容编辑的更多细节（Portable Text/markdown 转换、_rev 令牌和原始模式）可参阅 EDITING-FLOW.md。