# @bettercms-ai/cli 中文文档

规范地址：https://npmcn.com/package/%40bettercms-ai/cli/

版本：0\.16\.2
npm 元数据更新时间：2026-11-02T11:06:36.561Z
中文译文更新时间：2026-11-08T00:20:16.466Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bettercms-ai/cli
原文对照：https://npmcn.com/package/%40bettercms-ai/cli/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：535 kB，4 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20
- 运行依赖：2 个
- 首次发布：2026-09-07T03:37:56.105Z
- 最新版本发布：2026-11-02T11:06:36.319Z
- 近 30 天下载量：4426（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：40（近 12 个月 40 个）

## 中文简介

在本地进行一个BetterCMS项目:签名,复制源,安装依赖.

## 安装

```sh
npm install @bettercms-ai/cli
```

也可以使用：`pnpm add @bettercms-ai/cli`、`yarn add @bettercms-ai/cli`、`bun add @bettercms-ai/cli`

## README

# @ bettercms-ai/ cli (英语)

在你自己的机器上做一个BetterCMS项目.

```bash
npx @bettercms-ai/cli@latest init --project-id <id>
```

复制命令( 上面有您的工程的 ID ) **这个项目的工作 当地** 按钮。 要求节点20或更新.

## 图标

| 命令 | 它会做什么 |
| --- | --- |
| `init --project-id <id> [--agent <name>] [--repo <folder|GitHub URL>] [--dir <path>|.] [--framework <name>] [--no-launch] [--no-sections] [--push|--no-push] [--authoring <components|fields>] [--forms-email <address>]` | 将您签入, 获取源( 或者在无头项目上, 使用您的前端或从启动器启动), 安装依赖性, 预填 `.env`,安装代理技能,包装每个页面的段落,以便遵循 CMS 命令(不是在无头上),在工程上打开你的编码代理. |
| `status [--project-id <id>] [--json] [--gate]` | 什么是活的,什么是建设,以及设置是否完成. 缓存登录的默认值 . |
| `pull-content [--dir <path>]` | 无头:一个被改造的站点的第一个建设步骤(`bettercms pull-content && <build>`) (中文(简体) ). 将已发布的内容写入页面即刻显示其代码导入,因此重建显示已发布的内容. 没有钥匙. |
| `derive [--project-id <id>] [--dir <path>] [--no-build] [--json]` | 无头:在这里建立和运行你的前端,让每个页面都作为访客看到它,然后将页面发送到BetterCMS,它产生它们的字段和今天的拷贝. 你的密码永远不变. |
| `deploy --to <vercel|netlify|cloudflare> [--name <site>] [--dir <out>] [--no-hook] [--json]` | 将这个寄存器通过主机自己的CLI和浏览器的登录设置在自己的主机上,在那里设置站点的BetterCMS地址,并注册主机的部署钩,这样每个发布者都会重建. |
| `env push [--project-id <id>] [--all]` | 设置此寄存器的工程变量 `.env` 文档。 打印名称, 永远不值 . |
| `bridge [--project <id>] [--once]` | 将这台机器作为执行器保存在仪表板上. |
| `whoami` | 缓存的签入——项目,工作空间,API,令牌过期. 离线. |
| `logout` | 忘记了缓存的登录。 同上,注:. |
| `--version` 编号 : `--help` | 已安装的版本 / 此用法 . |

| 旗帜 | 默认 | 这是什么 |
| --- | --- | --- |
| `--project-id <id>` | `init`: 需要 `status`: 缓存的签名 | 拟进行的项目. |
| `--dir <path>` | 项目弹片 | 目录 `init` 创造。 一定已经不存在了. |
| `--api <rung|url>` | `prod` | 一个叫"一跑"的人 `prod`, (中文(简体) ), `dev`, (中文(简体) ), `local` - 或者一个完整的URL. 还有 `BETTERCMS_API_URL`。 。 。 . |
| `--json` | 关 | `status` 仅:逐字打印API响应. |
| `--agent` | 安装的,其他要求 | `init` 仅限: `claude`, (中文(简体) ), `codex`, (中文(简体) ), `opencode`, (中文(简体) ), `cursor` 或者说 `gemini` (单位:千美元) `BETTERCMS_AGENT`; 记住 `~/.bettercms/cli-prefs.json`。 。 。 . |
| `--framework` | 项目,其他的问 | `init` 仅仅,没有前端的无头:启动器(`next`, (中文(简体) ), `astro`, (中文(简体) ), `react-ts`) (中文(简体) ). |
| `--no-launch` | 关 | `init` 仅:打印下一个步骤,而不是打开编码代理. |
| `--no-sections` | 关 | `init` 只:离开页面文件(skip step 7). |
| `--repo` | 连接的仓库 | `init` 仅: 使用此文件夹或 GitHub URL 作为站点代码 . |
| `--push` 编号 : `--no-push` | 请求 | `init` 仅仅: 推动BetterCMS的设置 承诺随它去(`--no-push`:从来没有. |
| `--authoring` | 请求 | `init` 仅:编辑器如何构建页面, `components` 或者说 `fields`。 。 。 . |
| `--forms-email` | 请求 | `init` 仅:当网站表格发送提交材料时(`""` 保持网站自己的处理. |
| `--gate` | 关 | `status` 仅:打印设置出闸(每检查总和,最差的五页,下个修补),出站出站出站出站出站出站出站出站出站不全. |

两者 `--flag value` 财务报告和审定财务报表 `--flag=value` 工作时 未知旗帜被拒绝,没有被忽略.

## 环境

`--api` 取一个名字,所以没有人会记得一个主机名:

| 名称 | API 密码 |
| --- | --- |
| `prod` (默认) | `https://api.bettercms.ai` |
| `dev` | `https://dev-api.bettercms.ai` |
| `local` | `http://localhost:3000` |

```bash
npx @bettercms-ai/cli@latest init --project-id <id> --api dev
```

满 `https://` URL仍然有效. 命令上拒绝一个不是粗话的空话 线条,列出哪些是——它从未作为主机名发送给DNS.

Dev API 开机了 **`bettercms.ai`** 而其余的德瓦庄园则在 `bettercms.dev` (磁盘) `app.bettercms.dev`, MCP 软件 `mcp.bettercms.dev`) (中文(简体) ). `bettercms.dev` 拥有通配符 DNS 记录,所以 `dev-api.bettercms.dev` 解析并回答 nginx 404 。 使用 `--api dev` 编辑 没有问题出现.

每个rung缓存在它自己的来源下输入 `~/.bettercms/cli-credentials.json`,所以切换从来不给另一个 rung 的标志 - 但第一个反对新来的指令要求你批准.

签名是 **全球, 而不是每个目录**数字 : `init` 或者说 `status` 为另一个项目替换 缓存的赠款,所以没有 `status` 之后报告其他项目. `status` 打印 完全出于这个原因,在第一条线上的项目编号.

## `init`

1.  **让你加入.** OAuth 设备代码随工程同时打开您的浏览器 预选。 批准它在那里。 如果浏览器无法打开,则会打印链接。 补助金 缓存于 `~/.bettercms/cli-credentials.json`,所以下一次运行是沉默的——除非 缓存赠款是用于不同的项目,在这种情况下,再次向您询问.
2.  **读取工程** ——它的 swit(目录名称)和工作空间.
3.  **取出出处.** 连接的 GitHub Repo 被复制 `git clone` -没有GitHub 登录: BetterCMS 将克隆人自己的读取权限借给该寄存器(一个小时,从未) 写在克隆人身上),而git从不提示. 如果克隆仍然不能工作,或者没有 连接回波,最新部署的构建被下载并解开.
4.  **安装依赖关系** 使用软件包管理器的锁文件名称 - `bun.lock`编号 : `bun.lockb` 包子 包子 包子, `pnpm-lock.yaml` →, `yarn.lock` 纱线,否则npm。 一个项目 没有 `package.json` 跳过此步骤。 如果安装失败, `init` 用命令警告 重新在目录内运行并继续进行; 停止会留下一个封存重运行的文件夹 .
5.  **预填 `.env`** 从 `.env.example` 当有一个和没有 `.env` 然而: `BETTERCMS_API_URL` 编号 : `PUBLIC_BCMS_API_URL` 编号 : `BCMS_API_URL` 设置为 API,以及 `BETTERCMS_WORKSPACE` 编号 : `PUBLIC_BCMS_WORKSPACE` 编号 : `BCMS_WORKSPACE` 给工作空间的子弹. 所有其它的一行——包括你的钥匙——都和原来一样.
6.  **设置您的编码代理**一样 `npm create sanity`: 运行 `npx -y @bettercms-ai/install@latest --global --mcp --api <rung>`在终端里,它问 "为这些编辑配置BetterCMS MCP和代理技能?" (Claude Code, Codex CLI, Cursor, ), VS代码,Zed;没有它就使用它找到的编辑器. 每个被选中的编辑器都会得到BetterCMS 技能(全部24: `bettercms`, (中文(简体) ), `bettercms-migrate` 财务报告和审定财务报表 `bettercms-abm`,加上 单独 `bettercms-*` 和主机MCP的用户级配置。 一个API,即 命名为 rung 或 https 都不可能只获得这些技能 。 失败只能用命令警告.
7.  **环绕每页的章节** 因此网站的自建使得它们按照CMS页面的顺序排列 列出它们,并按各节的间隔和样式,并绘制编辑器中添加的一节: `npx -y @bettercms-ai/convert@latest --sections`,带有来自API的项目页面列表. 它运行是否安装了代理 。 先是干盘,其计划被印出: 每页, 每一节和它得到的插槽 每一页都有它单独留下的原因 一样 运行为真,然后检查是否没有类或样式符号与 `HEAD`,然后是一个当地 执行它写的文件: `chore(bettercms): render sections from BetterCMS`。 。 。 . **它从不推**永远不修补 留下你独创的一切 如果一个文件 如果样式检查或一个 SDK安装失败, 它把文件放回去 。 一个不是 git 仓库的目录被包裹 而不执着。 包装只添加 `<BcmsSections>` 和每个部分的一个插槽标记 : 任何部分的标记,道具,阶级或风格都会改变,第二跑则不会改变任何东西. 何时 存储器 `@bettercms-ai` SDK 上一个日期 `<BcmsSections>`,其范围在 `package.json` 并且软件包管理器安装它(修改是在同一承诺中)。 什麽 上面有BetterCMS的录音 所以安装门知道哪些路线被包裹了 被拒绝. `--no-sections` 跳过台阶.
8.  **在项目上打开 Claude 代码**,连接到BetterCMS,并且已经发送了第一个提示.. 和以前一样,现在为您输入。 需求 `claude` 在你身边 `PATH` (单位:千美元)`npm install -g @anthropic-ai/claude-code`;没有它,或者没有终端,或者与 `--no-launch`, (中文(简体) ), `init` 打印下一步和要运行的命令。 重运行 `init` 在同一目录中重新使用现有的检查并重新打开 Claude 代码而不是 无法使用“ 已经存在 ” 。 设定 `BETTERCMS_AGENT_MODEL` 以命名 Claude 代码模型 使用; 未设置, 这是您自己的默认值 .
9.  **读取设置的门并打印出来** 当代理退出,不管它退出,在一个屏幕上 无论网站大小如何:网页已建立、创建和出版;每行计算1行 检查(文本、图像、链接、区域、样式、SVG、数字、属性文本),每个 `editable/total`· ; 5个最差的路线,除注解外的每一个记录; 用于修复关闭大多数项目(`Next`); 剩下的前五个项目,每个项目都有工具 调用它; 下面的两个命令。 检查尚未计量( 项目) 在该检查存在之前设置的指纹) `UNMEASURED` 替换份额,以及 `Unmeasured` 线条命名它们:既不是失败也不是通过,再有一个设置运行它们。 虽然 门不完整 `init` 退出 3 并打印在同一位置重新打开代理的命令 网站。 之后 `--no-launch`,或没有终点站,大门被打印出来 `init` 仍为退出 0:只要求它取出网站. 无法读取的门( 更古老的 API, 网络) 以一行表示,不是失败.

```
Setup     incomplete: 23 items left
Pages     18 built, 18 created, 16 published
Text      41210/52008 (79%) characters editable
Images    36/61 (59%) editable
Links     402/410 (98%) editable
Sections  52/61 (85%) stamped and movable
Style     UNMEASURED: setup has not counted this on the live build
SVGs      20/44 (45%) editable
Numbers   12/12 (100%) editable
Attrs     70/96 (72%) editable (alt, aria-label, title, placeholder)
Open      text 7, svg 6, style 4, image 3, published 2, seo 1
Unmeasured style: not a failure and not a pass. Setup measures them (editor_setup { force: true })
Routes    7 of 18 pass (page, text, images, links, sections, style; worst first)
  /services      draft      text 310/2400     images 0/4      links 12/12    sections 1/9    style ?      fails: published, text, image, sections
  /blog/post-1   published  text 900/2400     images 2/4      links 12/12    sections 3/3    style ?      svg 0/3  fails: text, image, svg
  …
  … and 13 more
Next      bind-elements closes 16 of 23: get_conversion_brief {"complete":true}

Left to do:
  1. 12% of the visible text on /services is a field's (310 of 2400 characters; the bar is 98%).
     fix (bind-elements): get_conversion_brief {"complete":true}
  2. 1 of 9 sections on /services are a stamped root the editor can find: the rest are not drawn from the page's blocks.
     fix (run-sections-conversion): componentize_sections {"codemod":true,"digest":"<digest from get_componentize_plan>"}
  …
  … and 18 more

Resume the agent:  npx @bettercms-ai/cli@latest init --project-id proj_abc123
Read this again:   npx @bettercms-ai/cli@latest status --gate --project-id proj_abc123
```

### 读取密钥

`init` 不刻薄 API 密钥: 一个小时的登录不能留下一个永远不会过期的密钥. 发布的内容不需要( SDK 读取自 `BCMS_PROJECT_ID`) (中文(简体) ). 当前端 配置读取一个,编码代理器用 `create_delivery_key` 工具,一个命名, 仅读密钥列表于 **工程 – 设置 – API 密钥**,并写入 `.env`。 。 。 .

### 无头项目

一个无头项目的网站 由它自己的主机建造,所以 `init` 不需要部署源:它使用 你的头端。 在文件夹中运行( 或者通过) `--repo <folder|GitHub URL>`) (中文(简体) ). 开始运行 `bettercms derive`:它建立网站,运行网站,让每个页面都像访客一样看到它(在您所看到的 本地 Chrome, Chromium 或 Edge, 所以复制一个在浏览器中获取的组件也会读取)并发送 这些页面到BetterCMS, 它的页面,字段和今天的拷贝 从它们,就像它 从它建立的地方。 然后代理转换原地的代码: 每字变为读取 它的地盘, 标记不变。 它部署与 `bettercms deploy --to <host>`,记录 站点 URL (`set_front_end`),运行 `derive` 同样的,布置量度 所运送的,只停止 何时 `get_next_steps` 报告 `receipt.complete` (数量) `receipt.frontEnd` 以行及其出门.

```bash
npx @bettercms-ai/cli@latest derive            # in the front end's folder
BETTERCMS_BROWSER=none npx @bettercms-ai/cli@latest derive   # read the HTML as served
```

`init` 永远不要从开始 除非你要求一个: `--framework <next|astro|react-ts>`,或 "启动器"在它的问题, 对于一个完全没有前端的项目.

## `status`

```
$ bettercms status
Project   proj_abc123
State     idle
Live      a1b2c3d since 2026-01-01T00:00:00.000Z
Serving   staging — promote pending (production a1b2c3d)
Editor    https://bettercms.ai/acme/projects/acme-site/visual
```

`Serving` 仅出现在使用中/生产分拆的项目. `Live` 读取 `nothing deployed yet` 直到第一次出版,和 `State` 包含API本身的理由,当 构建失败 : `State failed — <reason>`。 。 。 .

`--json` 逐字打印 API 回复 - `state`, (中文(简体) ), `lastLiveSha`, (中文(简体) ), `liveAt`, (中文(简体) ), `publishing`, (中文(简体) ), `failed`, (中文(简体) ), `error`, (中文(简体) ), `slot`, (中文(简体) ), `productionSha`, (中文(简体) ), `awaitingPromote`, (中文(简体) ), `canvas`, (中文(简体) ), `editorUrl`这是 (单位:千美元) **非交互式**:如果签名需要浏览器,则退出 1 `Sign-in needed for <id>. Run the command once without --json to approve it.` 而不是说 打开一个。 运行 `status` 一次没有 `--json` 在新机器上,然后写下来.

`status` 需要同样的 `artifact:write` 作为部署的赠款,默认设备给予的 携带。 一个收缩的角色看到API自己的403句而不是状态行.

A 类 `Setup` 当 API 报告设置闸口时, 直行如下 : `complete`, (中文(简体) ), `not judged` (没什么 活的,或项目是无头的),或 `incomplete: N items left`。 。 。 . `status --gate` 打印 整个大门,作为 `init` 当代理退出时执行, 当它不完整时则退出 3, 所以一个脚本 等会再说吧. `--json --gate` 将门加到JSON上作为 `setupGate`。 。 。 .

## `deploy`

```
$ bettercms deploy --to vercel
Host      Vercel (acme-site)
URL       https://acme-site-a1b2c3.vercel.app
Env       BCMS_API_URL, BCMS_WORKSPACE, BCMS_PROJECT_ID, PUBLIC_BCMS_API_URL, …
Rebuilds  on every publish (deploy hook registered with BetterCMS)
```

Sanity模式:东道主自己的CLI(`vercel`, (中文(简体) ), `netlify`, (中文(简体) ), `wrangler`运行 `npx`() 标志 中,创建或链接网站并部署此目录。 你们的主人 符号留在CLI的自有店里;BetterCMS从不看到. 礛 `deploy`数字 :

1.  在主机上设置网站的 BetterCMS 地址—— `BCMS_API_URL`, (中文(简体) ), `BCMS_WORKSPACE`, (中文(简体) ), `BCMS_PROJECT_ID`,无前缀并在您框架的公用前缀下(`NEXT_PUBLIC_`, (中文(简体) ), `PUBLIC_`, (中文(简体) ), `VITE_`(中文(简体) ). 发布的内容不需要密钥,所以没有设置任何秘密;
2.  在BetterCMS上注册主机的部署钩,所以每个发布者都会重建网站.

| 东道主 | 站点 | 在发布后重建 |
| --- | --- | --- |
| 维塞尔 | `vercel link` (创建项目), `vercel git connect` | 一旦项目从您的 GitHub 仓库中建立起来 . |
| 净化 | `netlify init` 在终端中(创建网站并连接仓库); `netlify sites:create` 没有 | 一旦网站从你的仓库里建立起来. |
| 云雾花 | 本地建筑,然后 `wrangler deploy --assets <dir>`: 拥有静态资产的工人(在第一次部署时创建) | 否:本地上传无部署钩. 重运行 `deploy` 在发布后,或将寄存器连接到Workers Builds. |

在BetterCMS自己的建筑旁边添加了钩子 主机在那里不断建设,所以编辑器继续工作,并切换出出品主机 保持一个仪表板的决定。 复跑再用其钩. 注册需要企业号 计划;没有计划,现场仍然部署 `deploy` 说出版社不会重建它.

CI中没有浏览器: 设置主机自己的符号 —— `VERCEL_TOKEN`, (中文(简体) ), `NETLIFY_AUTH_TOKEN`,或 `CLOUDFLARE_API_TOKEN` 与 `CLOUDFLARE_ACCOUNT_ID`. 没有一个人, `deploy` 出口 1 和名称 这个. `--json` 指纹 `{ provider, site, url, env, hook }` 从不打开浏览器。 云飞 需求 `--dir` 当框架不是Astro,Vite,Nuxt,Gatsby或Create React App时.

## 退出代码

| 代码 | 含义 |
| --- | --- |
| 0 个 | 结束了。 还有 `whoami` 签字后 `logout` 那时没什么好澄清的. |
| 1个 | 命令失败了——原因位于stderr的最后一行. |
| 2个 | 命令行本身是错误的:命令未知,旗帜不明,或者一面旗帜丢失了它的值. |
| 3个 | `init` 财务报告和审定财务报表 `status --gate` 仅:设置出闸未完成. 所剩之物由上面所印出,并有恢复的命令. |
| 其他项目 | 退出代码 `git` 或打印错误的软件包管理器. |

## 解决问题

-   **"必须克隆..."** ——安装git后再重跑.
-   **一个私人的Repo 要求证书** - 这是Git自己的提示;设置了SSH代理或 一个证书助手 重新运行.
-   **"你批准了一个不同的项目..."** 同意屏幕只预选项目; 重新运行,并选择命令中的一个.
-   **"这个项目还没有部署源头"** ——连接一个 GitHub repo 或发布一次.
-   **"状态需要 - project -id, 或者运行更好的cms init先。"** - 没有缓存 这个机器还没有。 传出ID,或跑 `init`。 。 。 .
-   **"Sign -in需要为. 运行命令一次没有--Json批准它"** —— 说 `--json` 从不打开浏览器 。 不运行同一命令 `--json`,批准它,然后重新运行.
-   **"Could not reach https://api.bettercms.ai:"我无法到达https://api** - DNS, TLS, 代理, 或30 s请求 暂停 。 检查网络或点 `--api` 可以到达的地方.
-   **"API的意外反应"** - 一个不是JSON预期的2xx尸体 将 API 改为 API .

## 常见问题

### @bettercms-ai/cli 是什么？

在本地进行一个BetterCMS项目:签名,复制源,安装依赖\.

### 如何安装 @bettercms-ai/cli？

在项目目录运行 npm install @bettercms-ai/cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 bettercms，可以用 npx bettercms 直接运行。

### @bettercms-ai/cli 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/bettercms-ai\_\_cli 是否存在。

### @bettercms-ai/cli 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @bettercms-ai/cli 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @bettercms-ai/cli 可以商用吗？

@bettercms-ai/cli 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @bettercms-ai/cli 的下载量有多少？

根据 npm 官方下载统计，@bettercms-ai/cli 在 2026/10/08 – 2026/11/06 这 30 天内被下载 4,426 次，日均约 148 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bettercms-ai/cli 还在维护吗？

最新版本 0\.16\.2 发布于 2026/11/02（6 天前）；至今共发布 40 个版本，其中过去 12 个月发布了 40 个；首次发布于 2026/09/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。