@celljs/cli

Cell 4 的命令行工具 cell：读取 cell.config.ts，按 preset 构建应用，运行和部署构建产物。设计见仓库的 docs/design/architecture.md，从 3.x 迁移见 docs/migration-4.md。

需要 Node.js ^20.19.0 || >=22.12.0。在项目里安装：

npm install -D @celljs/cli
npx cell build
Copy

命令

Preset

每个 preset 的选项写在 cell.config.ts 里与 preset 同名的字段（如 fc: { region: 'cn-shanghai' }），按 preset 的 schema 校验，未知选项报 CELL_CONFIG_INVALID；切换 preset 时其他 preset 的字段保留不报错。

cloudflare

cell build --preset cloudflare          # 构建到 .cell/output
cell preview                            # wrangler dev，在 workerd（Cloudflare 的运行时）中运行，默认 8787 端口
cell deploy --preset cloudflare --dry-run   # 构建并执行 wrangler deploy --dry-run，输出计划，不上传
cell deploy --preset cloudflare         # 构建并部署，输出 workers.dev 地址
Copy

• 运行方式：Cell 后端（Express）运行在 Workers 的 node:http 服务端上（需要 nodejs_compat），由 @celljs/express-adapter 的 http 入口提供，与 node preset 相同。前端（public/）由 Cloudflare 作为静态资源直接返回，只有不匹配静态文件的请求进入 Worker。产物只支持 ESM，--format cjs 报 CELL_CONFIG_CONFLICT。
• 启动时机：Workers 只允许在模块加载阶段生成代码（new Function，Express 的依赖会用到），只允许在处理请求时做 I/O。所以应用的模块在 Worker 启动时加载，Application.start() 和 onStart 在第一个请求时执行（ApplicationHost.beforeStart）。模块加载失败会让 Worker 启动失败，wrangler dev / wrangler deploy 直接报出。
• Cloudflare 的配置写在项目根目录的 wrangler.jsonc 或 wrangler.json（可选，按 Cloudflare 文档的写法）：name、compatibility_date、vars、KV / D1 / R2 等绑定、routes 都在这里。构建时 Cell 以它为基础生成 .cell/output/wrangler.json，并设置：main（项目里写了会被忽略并警告）、有前端时的 assets.directory、compatibility_flags 里的 nodejs_compat。没有配置文件时，name 取自 package.json 的包名（如 @acme/shop → acme-shop），compatibility_date 默认 2026-03-17，这也是允许的最早日期（node:http 服务端与 node:tty 从这天起默认可用）。wrangler.toml 不支持，请改写成 wrangler.jsonc。
• 单页应用：有前端时默认 assets.not_found_handling: "single-page-application"：浏览器导航到不存在的路径时由 Cloudflare 返回 index.html（与 Node.js 上 @celljs/serve-static 的 spa 一致），API 等其他请求仍进入 Worker；在 wrangler.jsonc 里写了 not_found_handling 就以项目为准。Worker 里没有前端文件，@celljs/serve-static 发现没有前端目录时直接放行，未知路径得到正常的 404。
• 自定义域名：域名的 DNS 托管在 Cloudflare 时，在 wrangler.jsonc 里写 "routes": [{ "pattern": "app.example.com", "custom_domain": true }]，部署时 Cloudflare 自动创建 DNS 记录和证书，deployment.url 报告这个域名。国内网络无法访问 *.workers.dev，面向国内访问时要绑定自定义域名。
• 应用配置：vars 和 secrets（wrangler secret put）进入 process.env，所以 cell.yml 里的 ${env.X} 和 CELL_BACKEND__* 变量照常生效。
• Wrangler：不是 Cell 的依赖。项目装了 wrangler 就用项目的，否则由 npx --yes wrangler@4 在第一次使用时安装（npm 缓存）。凭据由 Wrangler 管理：设置 CLOUDFLARE_API_TOKEN（必要时加 CLOUDFLARE_ACCOUNT_ID），或执行一次 npx wrangler login。也可以不用 cell deploy，直接执行 npx wrangler deploy --config .cell/output/wrangler.json。
• Workers Builds（Cloudflare 的 CI，设置 WORKERS_CI=1）里自动选用 cloudflare preset：构建命令 npx cell build，部署命令 npx cell deploy --skip-build。
• wrangler dev 会在项目根目录创建 .wrangler/，请加入 .gitignore。

fc、scf、lambda

三个函数平台的做法相同：Cell 服务端原样运行，产物目录整体打成 zip 作为函数代码；部署器直接调用云 API（请求签名自己实现：阿里云 ACS3、腾讯云 TC3、AWS SigV4），不需要云 SDK 或云厂商 CLI。函数名默认取包名（@acme/shop → shop），可用 name 指定；env 写入函数的环境变量（另带 NODE_ENV=production），cell.yml 里的 ${env.X} 和 CELL_BACKEND__* 照常生效。

• 代码包直接随请求上传，上限：FC 100 MB、SCF 20 MB、Lambda 50 MB（zip 后），超出报 CELL_DEPLOY_PACKAGE_TOO_LARGE。体积大多来自 build.external 留在 server/node_modules 的包。
• 没有凭据时 --dry-run 照样给出计划（动作为 deploy，并警告不知道函数是否已存在）；有凭据时查询云端，动作是 create 或 update。实际部署缺凭据报 CELL_DEPLOY_CREDENTIALS_MISSING，云 API 的错误报 CELL_DEPLOY_API_ERROR / CELL_DEPLOY_UNAUTHORIZED，消息里带云厂商的错误码和请求 ID。
• 函数计算的默认域名 fcapp.run 会让浏览器下载 HTML 页面，网页应用请绑定自定义域名；API 不受影响。
• 镜像里的 Node.js 较旧（FC 20.10、SCF 18.15）：服务端 bundle 自带 import.meta.dirname / filename 的补丁。

vercel

cell build --preset vercel     # .vercel/output（Build Output API v3）
cell preview                   # Node.js 运行函数的 bundle，前端取自 .vercel/output/static
cell deploy --preset vercel    # vercel deploy --prebuilt，不在 Vercel 上再构建
Copy

• 前端放在 static/ 由 Vercel CDN 返回（/assets/* 带一年的 immutable 缓存头）；其他请求进入函数 functions/index.func（nodejs22.x），函数里的 Cell 服务端处理 API，并用其中的 public/index.html 做单页回退。vercel build 留在 .vercel/output 的文件在构建时清除。
• 选项：project（默认取包名）、scope（团队）、environment（production 默认 / preview）、runtime、memory、maxDuration、regions（逗号分隔）。输出目录固定 .vercel/output（--out-dir 到别处时部署报 CELL_DEPLOY_OUTPUT_MISMATCH）；不接受 --single / --compile。
• Vercel CLI 不是依赖：项目装了就用项目的，否则 npx --yes vercel@65。凭据：VERCEL_TOKEN，或执行一次 npx vercel login；项目不存在时自动创建（--create-if-missing）。
• Vercel 的构建环境（VERCEL=1）里自动选用 vercel preset。.vercel/ 请加入 .gitignore。

cell dev

• 一个端口：Vite 提供前端页面和模块（HMR），/favicon.ico 与组件的 assets 和构建产物里的位置一致，其余请求交给后端。
• 后端不打包，在 Vite 的 server 环境里由 module runner 加载：Cell 包和项目源码经过 Cell 插件（生成的 DI 容器与配置写到 .cell/generated/），其他依赖由 Node 直接加载。入口通过 ApplicationHost（@celljs/core）把请求处理函数交给 cell dev，不自己监听端口。
• 后端用到的文件变化时：先停止旧应用（触发 onStop），再从新的模块重新启动，并触发 dev:reload。启动失败时请求返回 500 和 CellError（CELL_DEV_BACKEND_FAILED），保存后自动重试。
• 项目或组件的 cell*.yml、package.json、cell.config.* 变化时：重新解析工具链并在同一端口重启，再次触发 dev:ready。配置写错时报错并等待下一次修改。
• 源码里的 require() 和项目内的 CommonJS 文件（如生成的 prisma client）照常可用。
• POST /_cell/mcp：运行中应用的 MCP 端点（Streamable HTTP，JSON 响应），工具有 get_errors（后端启动错误、失败的重载、5xx 请求、错误日志）、list_routes、list_bindings、get_config（${...} 已求值）、recent_requests、logs。只接受本机来源（无 Origin 或回环地址），其他来源返回 403。
• --json：就绪时 stdout 输出一行结果（url、port、mode、targets、mcp，后端启动失败时带 backendError），之后应用和 Vite 的输出都走 stderr。收到 SIGINT / SIGTERM 时停止应用并以 0 退出。
• React Fast Refresh 等框架插件由组件的 toolchain 模块提供（模块宿主完成后）；在那之前前端修改会整页刷新，CSS 热替换。

cell build

单文件（--single）：先构建前端，再把 public/ 的全部文件（页面、脚本、favicon、组件的 assets）以 base64 写进服务端 bundle，启动时注册到 Symbol.for('@celljs/serve-static/assets')，@celljs/serve-static 从内存返回它们（Content-Type、ETag / 304、Cache-Control 与从磁盘时一致，单页应用回退到 index.html）。产物只有 server/index.mjs 和 manifest.json（single: true，没有 public），把这一个文件拷到任意目录用 node index.mjs 即可运行。项目只有后端时与不加 --single 相同（会提示）；build.external 等留在 server/node_modules 的包仍要放在它旁边。也可在 cell.config.ts 写 build: { single: true }。

可执行文件（--compile）：在单文件 bundle 的基础上编译成 .cell/output/app（Windows 目标为 app.exe），拷到没有 Node.js 和 node_modules 的机器也能运行；manifest.json 记录 executable，cell preview 直接运行它。

留在 bundle 外的包（build.external、组件的 optionalDependencies，通常是原生模块）无法放进可执行文件，报 CELL_COMPILE_EXTERNALS 并列出它们。cloudflare、vercel preset 的前端由平台托管，不接受 --single / --compile。

cell info

接受与 cell build 相同的 --preset、-m、--format、--out-dir 等选项，描述同样参数下 cell build 会用到的内容；另有：

只读取 package.json、cell*.yml、cell.config.ts 和 manifest.json，不运行项目代码，不执行 hooks。--json 结果的主要字段：

warnings 会提前指出不起作用或会让 cell build 失败的设置：没有组件提供 preset 的入口、-m 指定的 mode 没有任何 cell.<mode>.yml（附拼写建议）、使用了尚未提供的 single / compile、不生效的 CELL_FRONTEND__* / CELL_BACKEND__* 变量。

cell check

--json 结果：passed、summary（errors / warnings / info 计数）、issues（每条带 check、level、code、message，可能有 file、line、column、hint）、checks（每项的耗时、问题数、跳过原因）。不加 --json 时按编译器格式输出 src/a.ts:3:5 error TS2322 …，info 不显示。

cell init

npx @celljs/cli init backend my-app     # 或 fullstack：React 前端 + 后端，经 RPC 调用
cd my-app && npm install && npx cell agent sync && npx cell dev
Copy

从不提问；目录非空时报 CELL_INIT_NOT_EMPTY，模板不存在时报 CELL_TEMPLATE_NOT_FOUND（带拼写建议）。项目依赖 @celljs/* 的 ^<cli 版本>，测试用 bun test + createTestApp()。为 coding agent 生成：AGENTS.md（Cell 指南，与版本匹配）、.agents/skills/cell/SKILL.md、CLAUDE.md（@AGENTS.md）、.mcp.json（npx cell mcp）。

cell agent sync

把 @celljs/cli 自带的 Cell 指南和已安装组件、toolchain 模块（addDocs 目录）的 AGENTS.md 片段写进 AGENTS.md 的 <!-- cell:begin --> … <!-- cell:end --> 之间（其余内容保持不变；没有标记时追加到末尾），并重写 .agents/skills/cell/SKILL.md。升级 Cell 或增减组件后执行一次。

cell config get

cell config get cell.server.port --why
# cell.server.port (backend) = 8080
#   node_modules/@celljs/web/cell.yml: 3000
#   cell.yml [backend]: 8080
Copy

键可写 a.b.c、items[0].name。--json 结果有 value、layers（file、component、section、value）、env（设置了该键或其上下级的 CELL_<TARGET>__* 变量）、expressions（后端值含 ${...}，服务端启动时求值）。键不存在时报 CELL_CONFIG_KEY_NOT_FOUND，带最接近的键。

cell docs

cell docs <query> [--limit n]：在各组件的 README.md、docs/ 和模块 addDocs() 的目录里按标题分段检索，返回最匹配的段落和 file:line。

cell mcp

在 stdio 上运行 MCP 服务器（每行一条 JSON-RPC 消息），直到 stdin 关闭。工具都对应同名命令的 --json 结果：

不提供部署工具：实际部署由人执行 cell deploy。

之后是 toolchain 模块用 addMcpTool 注册的工具（与内置工具重名的会被忽略并警告）；cell.config.*、package.json 或模块文件变化后自动重新加载。每个工具标注 readOnlyHint / openWorldHint；参数按 inputSchema 校验，失败时返回 isError 和 CellError。stdout 只有协议消息，模块和 hooks 的输出都走 stderr。

在 agent 中配置（项目根目录下运行）：

// Claude Code / Cursor / CodeBuddy：.mcp.json 或 .cursor/mcp.json
{ "mcpServers": { "cell": { "command": "npx", "args": ["cell", "mcp"] } } }
Copy

# Codex：~/.codex/config.toml
[mcp_servers.cell]
command = "npx"
args = ["cell", "mcp"]
Copy

cell dev 运行时，另外把 http://127.0.0.1:<port>/_cell/mcp 配成 HTTP 类型的 MCP 服务器即可查看运行中的应用。

cell preview

产物由哪个 preset 构建，就按它的方式运行：node、cli、fc、scf、lambda 用 Node.js 运行 server/index.mjs（标准输入输出继承当前终端），cloudflare 用 wrangler dev，vercel 用 Node.js 运行函数里的 bundle 并从 static/ 返回前端。

cell deploy

先 plan 后 apply：计划列出要部署的资源（resources，每项有 type、name、action、details），--dry-run 到此为止。依次触发 deploy:before（闸门，hooks 里的命令失败会取消部署）、deploy:plan、deploy:done 事件。部署工具（Wrangler、Vercel CLI）的输出在 --json 时走 stderr。--json 结果：preset、deployer、dryRun、plan，实际部署时还有 deployment（url，以及 details.versionId）。

通用选项

命令从不交互提问。退出码：成功 0，执行失败 1，用法错误（未知命令、选项、取值）2。

--json 输出

{"schemaVersion":1,"command":"build","ok":true,"root":"/app","preset":"node","format":"esm","mode":["production"],"targets":["backend"],"outDir":".cell/output","entry":"@celljs/express-adapter/lib/node/http-application-entry","durationMs":480,"warnings":[]}
Copy

失败时：

{"schemaVersion":1,"command":"build","ok":false,"error":{"code":"CELL_PRESET_NOT_FOUND","message":"Unknown preset 'nod'. Available: node.","hint":"Did you mean 'node'?","docs":"https://cell.cellbang.com/errors/cell-preset-not-found"},"warnings":[]}
Copy

schemaVersion 不变时，字段只增不改。

cell.config.ts

可选。只放工具链配置；应用配置（@Value 读取的内容）写在 cell.yml。

import { defineConfig } from '@celljs/cli';

export default defineConfig({
    preset: 'node',
    targets: ['frontend', 'backend'],
    modules: ['!@celljs/serve-static', { source: '@x/ui', runtime: false }],
    build: { format: 'esm', external: ['sharp'], sourcemap: false, outDir: '.cell/output' },
    vite: {},
    hooks: { 'build:before': 'prisma generate' },
});
Copy

其他顶层字段是 toolchain 模块的选项，值必须是对象。文件支持 .ts/.mts/.cts/.js/.mjs/.cjs，同时存在多个报 CELL_CONFIG_AMBIGUOUS。命令行参数优先于配置文件。

用环境变量覆盖配置

cell.yml 里已有的任意键都可以用环境变量覆盖，不用改文件：

CELL_BACKEND__SERVER__PORT=8080 cell preview      # 服务端启动时应用：cell.server.port
CELL_FRONTEND__API_BASE=/api cell build           # 构建前端时应用：cell.apiBase
Copy

__ 分隔层级，第一段先在顶层找、再到 cell 下找（CELL__… 总是指 cell），一个键只能由一个变量设置，不区分大小写并忽略 _、-；值按原值类型转换（JSON 写法的有限数、true / false、对象和数组用 JSON，原值为 null 时是 JSON 就按 JSON），整体是一个 ${...} 的值保留到求值时再定类型（如 CELL_BACKEND__SERVER__PORT='${env.PORT}'），在 ${...} 求值之前生效。只能覆盖已存在的键，找不到键或类型不符的变量不生效并给出警告：服务端在启动时打印，cell build 检查 CELL_FRONTEND__*，cell info 两种都检查。完整规则见迁移指南 5.3。

hooks

hooks: {
    'build:before': 'prisma generate',
    'output:done': 'cp extra/* "$CELL_OUT_DIR/server/"',
}
Copy

• 命令经 shell 在项目根目录执行，不读标准输入。PATH 最前面是项目及上级目录的 node_modules/.bin。
• 环境变量：CELL_EVENT、CELL_PRESET、CELL_MODE（逗号分隔）、CELL_OUT_DIR（输出目录的绝对路径）。
• cell dev 触发 modules:done → config:resolved → dev:ready，后端重载时 dev:reload，重启时 close 后重新来一遍。
• cell build 依次触发：modules:done → config:resolved → build:before → 构建 → output:done → close。
• build:before 是闸门事件：命令非零退出即取消构建（CELL_BUILD_CANCELLED）。其他事件里非零退出报 CELL_HOOK_FAILED。
• 只接受命令字符串。需要写代码或修改事件对象（build:done、deploy:plan）的扩展写成 toolchain 模块。

toolchain 模块

需要写代码的扩展写成 toolchain 模块：默认导出一个工厂函数，拿到 cell 后注册能力（设计见 docs/design/modules.md）。

// modules/audit.ts，在 cell.config.ts 里写 modules: ['./modules/audit'], audit: { url: '...' }
import type { CellAPI } from '@celljs/kit';

export default function (cell: CellAPI) {
    const { url } = cell.options('audit', { url: 'http://localhost:9000' });
    cell.addVitePlugin({ name: 'audit', transform: code => code }, { env: 'server' });
    cell.on('build:done', event => {
        event.files['audit.json'] = JSON.stringify({ url, targets: event.project.targets });
    });
}
Copy

• 加载顺序固定：依赖里的组件（package.json 的 cell.toolchain，按依赖顺序）→ cell.config.ts 的 modules（本地路径或包名，按书写顺序）。{ source, toolchain: false } 关掉某个组件的模块，'!包名' 连组件一起去掉。
• 工厂只做注册，不启动进程、端口、监听或定时器：cell info 也会执行工厂。
• cell.config.ts 里除 preset、targets、modules、build、vite、hooks 之外的顶层字段都是模块选项，必须由某个模块用 options() 或 addConfigSchema() 认领，否则报 CELL_CONFIG_UNKNOWN_OPTION（附拼写建议）；addConfigSchema 接受 Standard Schema（zod、valibot 等），不合法报 CELL_CONFIG_INVALID。
• 工厂抛错报 CELL_MODULE_ERROR（带模块名）；默认导出不是函数报 CELL_MODULE_INVALID。cell dev 中通知类事件的处理函数出错只报告不中断，cell build 中任何处理函数出错都失败。
• 每个模块注册了什么都列在 cell info --json 的 toolchainModules 里。

错误码

所有失败都以 CellError { code, message, file?, line?, hint, docs } 输出，code 在 4.x 内保持稳定。

测试：createTestApp

import { createTestApp } from '@celljs/cli';

const app = await createTestApp({ root, mode: ['extra'] });   // mode 前面总有 test
const res = await app.fetch('/users', { method: 'POST', headers: { 'content-type': 'application/json' }, body: '{}' });
const { UserService } = await app.import('/src/user-service.ts');   // 后端加载的那份模块
app.get(UserService);                                         // DI 容器里的对象
await app.close();                                            // 停止应用（onStop）
Copy

app.get(X) 中测试从项目源码导入的类或 Symbol('X') 与应用里的不是同一个模块实例（应用在 Vite 的 module runner 里），按类名或 symbol 描述匹配；没有或重名时报 CELL_DI_NO_BINDING / CELL_DI_AMBIGUOUS。要拿到应用用的那一份（重名时、或要用模块里的其他导出），用 app.import()：项目内的文件写 /src/...，包写包名。

在测试进程里像 cell dev 一样从源码加载后端，不构建、不监听端口；请求经内存中的 req/res 对象走完整的 HTTP 处理链，fetch 返回标准 Response。启动失败抛 CellError（如 CELL_DEV_BACKEND_FAILED，带出错文件）；后端没有 HTTP 入口时 fetch 报 CELL_TEST_APP_NO_HTTP。

编程接口

import { CellCli } from '@celljs/cli';

const code = await new CellCli({ stdout, stderr, env }).run(['build', '--json']);
Copy

也导出 defineConfig、ConfigResolver、PresetRegistry、DeployerRegistry、EventBus、HookRunner 等，用于测试和编写工具。