emdash-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

EmDash CLI

The EmDash CLI (

emdash

ec

) manages EmDash CMS instances. Commands fall into two categories:

Local commands — work directly on a SQLite file, no running server needed:
```
init
```
,
```
dev
```
,
```
seed
```
,
```
export-seed
```
,
```
auth secret
```
Remote commands — talk to a running EmDash instance via HTTP:
```
types
```
,
```
login
```
,
```
logout
```
,
```
whoami
```
,
```
content
```
,
```
schema
```
,
```
media
```
,
```
search
```
,
```
taxonomy
```
,
```
menu
```

EmDash CLI（

emdash

或

ec

）用于管理EmDash CMS实例。命令分为两类：

本地命令 —— 直接操作SQLite文件，无需运行服务器：
```
init
```
、
```
dev
```
、
```
seed
```
、
```
export-seed
```
、
```
auth secret
```
远程命令 —— 通过HTTP与运行中的EmDash实例通信：
```
types
```
、
```
login
```
、
```
logout
```
、
```
whoami
```
、
```
content
```
、
```
schema
```
、
```
media
```
、
```
search
```
、
```
taxonomy
```
、
```
menu
```

Authentication

认证

Remote commands resolve auth automatically:

```
--token
```
flag
```
EMDASH_TOKEN
```
env var
Stored credentials from
```
emdash login
```
Dev bypass (localhost only — no token needed)

For local dev servers, just run the command — auth is handled automatically. For remote instances, run

emdash login --url https://my-site.pages.dev

first.

远程命令会自动解析认证信息，优先级如下：

```
--token
```
参数
```
EMDASH_TOKEN
```
环境变量
```
emdash login
```
存储的凭据
开发环境绕过（仅本地主机生效，无需令牌）

对于本地开发服务器，直接运行命令即可——认证会自动处理。对于远程实例，请先运行

emdash login --url https://my-site.pages.dev

。

Custom Headers & Reverse Proxies

自定义请求头与反向代理

Sites behind Cloudflare Access or other reverse proxies need auth headers on every request. The CLI supports this via

--header

flags and environment variables.

部署在Cloudflare Access或其他反向代理后的站点，需要在每个请求中携带认证头。CLI支持通过

--header

参数和环境变量实现此功能。

Service Tokens (Recommended for CI/Automation)

服务令牌（推荐用于CI/自动化）

bash

undefined

bash

undefined

Single header

单个请求头

npx emdash login --url https://my-site.pages.dev
--header "CF-Access-Client-Id: xxx.access"
--header "CF-Access-Client-Secret: yyy"

Short form

简写形式

npx emdash login -H "CF-Access-Client-Id: xxx" -H "CF-Access-Client-Secret: yyy"

Via environment (newline-separated)

通过环境变量（换行分隔）

export EMDASH_HEADERS="CF-Access-Client-Id: xxx CF-Access-Client-Secret: yyy" npx emdash login --url https://my-site.pages.dev


Headers are persisted to `~/.config/emdash/auth.json` after login, so subsequent commands inherit them automatically.

export EMDASH_HEADERS="CF-Access-Client-Id: xxx CF-Access-Client-Secret: yyy" npx emdash login --url https://my-site.pages.dev


登录后，请求头会持久化到`~/.config/emdash/auth.json`，后续命令会自动继承这些配置。

Cloudflare Access Browser Flow

Cloudflare Access浏览器流

If you don't have service tokens and

cloudflared

is installed, the CLI will automatically:

Detect when Access blocks the request
Try to get a cached JWT via
```
cloudflared access token
```
Fall back to
```
cloudflared access login
```
for browser-based auth

This works for interactive use but isn't suitable for CI. Use service tokens for automation.

如果你没有服务令牌且已安装

cloudflared

，CLI会自动执行以下操作：

检测Access是否拦截请求
尝试通过
```
cloudflared access token
```
获取缓存的JWT
回退到
```
cloudflared access login
```
进行基于浏览器的认证

此方式适用于交互式使用，但不适合CI环境。自动化场景请使用服务令牌。

Generic Reverse Proxy Auth

通用反向代理认证

The

--header

flag works with any auth scheme:

bash

undefined

--header

参数适用于任何认证方案：

bash

undefined

Basic auth

基础认证

npx emdash login --url https://example.com -H "Authorization: Basic dXNlcjpwYXNz"

Custom auth header

自定义认证头

npx emdash login --url https://example.com -H "X-API-Key: secret123"

undefined

npx emdash login --url https://example.com -H "X-API-Key: secret123"

undefined

Quick Reference

快速参考

Database Setup

数据库设置

bash

undefined

bash

undefined

Initialize database with migrations

初始化数据库并执行迁移

npx emdash init

Start dev server (runs migrations, starts Astro)

启动开发服务器（执行迁移，启动Astro）

npx emdash dev

Start dev server and generate types from remote

启动开发服务器并从远程生成类型

npx emdash dev --types

Apply a seed file

应用种子文件

npx emdash seed .emdash/seed.json

Export database as seed

将数据库导出为种子文件

npx emdash export-seed > seed.json npx emdash export-seed --with-content > seed.json

undefined

npx emdash export-seed > seed.json npx emdash export-seed --with-content > seed.json

undefined

Type Generation

类型生成

bash

undefined

bash

undefined

Generate types from local dev server

从本地开发服务器生成类型

npx emdash types

Generate from remote

从远程实例生成类型

npx emdash types --url https://my-site.pages.dev

Custom output path

自定义输出路径

npx emdash types --output src/types/cms.ts


Writes `.emdash/types.ts` (TypeScript interfaces) and `.emdash/schema.json`.

npx emdash types --output src/types/cms.ts


生成`.emdash/types.ts`（TypeScript接口）和`.emdash/schema.json`文件。

Authentication

认证操作

bash

undefined

bash

undefined

Login (OAuth Device Flow)

登录（OAuth设备流）

npx emdash login --url https://my-site.pages.dev

Check current user

查看当前用户

npx emdash whoami

Logout

登出

npx emdash logout

Generate auth secret for deployment

生成用于部署的认证密钥

npx emdash auth secret

undefined

npx emdash auth secret

undefined

Content CRUD

内容CRUD

The CLI is designed for agents. Create and update auto-publish by default so agents get read-after-write consistency without managing drafts.

bash

undefined

CLI专为Agent设计。默认情况下，创建和更新操作会自动发布，这样Agent无需管理草稿即可实现读写一致性。

bash

undefined

List content

列出内容

npx emdash content list posts npx emdash content list posts --status published --limit 10

Get a single item (Portable Text fields converted to markdown)

获取单个条目（Portable Text字段转换为Markdown）

Returns draft data if a pending draft exists

如果存在待处理草稿，则返回草稿数据

npx emdash content get posts 01ABC123 npx emdash content get posts 01ABC123 --raw # skip PT->markdown conversion npx emdash content get posts 01ABC123 --published # ignore pending drafts

npx emdash content get posts 01ABC123 npx emdash content get posts 01ABC123 --raw # 跳过PT转Markdown的转换 npx emdash content get posts 01ABC123 --published # 忽略待处理草稿

Create content (auto-publishes by default)

创建内容（默认自动发布）

npx emdash content create posts --data '{"title": "Hello", "body": "# World"}' npx emdash content create posts --file post.json --slug hello-world npx emdash content create posts --draft --data '...' # keep as draft cat post.json | npx emdash content create posts --stdin

npx emdash content create posts --data '{"title": "Hello", "body": "# World"}' npx emdash content create posts --file post.json --slug hello-world npx emdash content create posts --draft --data '...' # 保留为草稿 cat post.json | npx emdash content create posts --stdin

Update (requires --rev from a prior get, auto-publishes by default)

更新内容（需要之前get操作返回的--rev参数，默认自动发布）

npx emdash content update posts 01ABC123 --rev MToyMDI2... --data '{"title": "Updated"}' npx emdash content update posts 01ABC123 --rev MToyMDI2... --draft --data '...' # keep as draft

npx emdash content update posts 01ABC123 --rev MToyMDI2... --data '{"title": "Updated"}' npx emdash content update posts 01ABC123 --rev MToyMDI2... --draft --data '...' # 保留为草稿

Delete (soft delete)

删除内容（软删除）

npx emdash content delete posts 01ABC123

Lifecycle

生命周期操作

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

undefined

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

undefined

Schema Management

Schema管理

bash

undefined

bash

undefined

List collections

列出集合

npx emdash schema list

Get collection with fields

获取包含字段的集合

npx emdash schema get posts

Create collection

创建集合

npx emdash schema create articles --label Articles --description "Blog articles"

Delete collection

删除集合

npx emdash schema delete articles --force

Add field

添加字段

npx emdash schema add-field posts body --type portableText --label "Body Content" npx emdash schema add-field posts featured --type boolean --required

Remove field

删除字段

npx emdash schema remove-field posts featured


Field types: `string`, `text`, `number`, `integer`, `boolean`, `datetime`, `select`, `multiSelect`, `image`, `file`, `reference`, `portableText`, `json`, `slug`, `url`. See `FIELD_TYPE_TO_COLUMN` in `packages/core/src/schema/types.ts` for the authoritative list.

npx emdash schema remove-field posts featured


字段类型包括：`string`、`text`、`number`、`integer`、`boolean`、`datetime`、`select`、`multiSelect`、`image`、`file`、`reference`、`portableText`、`json`、`slug`、`url`。权威列表请查看`packages/core/src/schema/types.ts`中的`FIELD_TYPE_TO_COLUMN`。

Media

媒体管理

bash

undefined

bash

undefined

List media

列出媒体

npx emdash media list npx emdash media list --mime image/png

Upload

上传媒体

npx emdash media upload ./photo.jpg --alt "A sunset" --caption "Bristol, 2026"

Get / delete

获取/删除媒体

npx emdash media get 01MEDIA123 npx emdash media delete 01MEDIA123

undefined

npx emdash media get 01MEDIA123 npx emdash media delete 01MEDIA123

undefined

Search

搜索

bash

npx emdash search "hello world"
npx emdash search "hello" --collection posts --limit 5

bash

npx emdash search "hello world"
npx emdash search "hello" --collection posts --limit 5

Taxonomies

分类法

bash

npx emdash taxonomy list
npx emdash taxonomy terms categories
npx emdash taxonomy add-term categories --name "Tech" --slug tech
npx emdash taxonomy add-term categories --name "Frontend" --parent 01PARENT123

bash

npx emdash taxonomy list
npx emdash taxonomy terms categories
npx emdash taxonomy add-term categories --name "Tech" --slug tech
npx emdash taxonomy add-term categories --name "Frontend" --parent 01PARENT123

Menus

菜单管理

bash

npx emdash menu list
npx emdash menu get primary

bash

npx emdash menu list
npx emdash menu get primary

Drafts and Publishing

草稿与发布

The CLI auto-publishes on

create

and

update

by default. This means:

create
creates the item and immediately publishes it
update
updates the item and publishes if a draft revision was created
get
returns draft data if a pending draft exists (e.g. from the admin UI)

Use

--draft

on create/update to skip auto-publishing. Use

--published

on get to ignore pending drafts.

Collections that support revisions store edits as draft revisions. The CLI handles this transparently — agents don't need to know whether a collection uses revisions or not.

CLI默认在

create

和

update

操作时自动发布，这意味着：

create
创建条目并立即发布
update
更新条目，如果已创建草稿修订版则发布
get
如果存在待处理草稿（比如来自管理UI），则返回草稿数据

在create/update时使用

--draft

参数可跳过自动发布。在get时使用

--published

参数可忽略待处理草稿。

支持修订版的集合会将编辑内容存储为草稿修订版。CLI会透明处理此逻辑——Agent无需了解集合是否使用修订版。

JSON Output

JSON输出

All remote commands support

--json

for machine-readable output. It's auto-enabled when stdout is piped.

bash

undefined

所有远程命令都支持

--json

参数以生成机器可读的输出。当标准输出被管道传输时，会自动启用此模式。

bash

undefined

Pipe to jq

管道到jq

npx emdash content list posts --json | jq '.items[].slug'

Use in scripts

在脚本中使用

ID=$(npx emdash content create posts --data '{"title":"Hello"}' --json | jq -r '.id')

undefined

ID=$(npx emdash content create posts --data '{"title":"Hello"}' --json | jq -r '.id')

undefined

Editing Flow

编辑流程

For details on how content editing works — Portable Text/markdown conversion,

_rev

tokens, and raw mode — see EDITING-FLOW.md.

关于内容编辑的详细说明——包括Portable Text/Markdown转换、

_rev

令牌和原始模式——请查看**EDITING-FLOW.md**。