# @applet-one/cli 中文文档

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

版本：0\.4\.5
npm 元数据更新时间：2026-10-29T18:54:34.451Z
中文译文更新时间：2026-11-06T16:58:14.450Z
软件包许可：UNLICENSED

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

原始 npm 页面：https://www.npmjs.com/package/%40applet-one/cli
原文对照：https://npmcn.com/package/%40applet-one/cli/?lang=original
项目主页：https://applet.one/

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

- 包体积（解压后）：159 kB，20 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20
- 运行依赖：5 个
- 首次发布：2026-09-23T13:33:10.446Z
- 最新版本发布：2026-10-29T18:54:34.172Z
- 近 30 天下载量：2676（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：28（近 12 个月 28 个）

## 中文简介

使用 Cloudflare 工作程序创建、部署和管理

## 安装

```sh
npm install @applet-one/cli
```

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

## README

# 小程序 CLI

与 Applet 创建、部署和管理应用程序.

## 安装

```sh
npm install -g @applet-one/cli
```

需要20号或更新的节点。 CLI及其Miniflare/workerd运行时间是Applet开发与部署的唯一要求;pnpm只用于运行启动脚本. Wrangler是直接Cloudflare部署的可选程序.

## 快开始

```sh
applet init my-app
cd my-app
pnpm install
pnpm dev
```

要将脚手架插入当前目录, 请运行 `applet init .` 从启动文件不存在的文件夹中;文件夹名称成为应用名称.

启动器是一个单级的应用程序: `app.js` 出口 `class App extends DurableObject` 并服务每个请求; Applet 提供工人配置(绑定) `APP`,迁移,默认处理器,备份端点). 它与代理在聊天中通过Applet MCP服务器所构建的形状相同,因此一个项目可以在终端和聊天之间移动. 自有项目 `wrangler.jsonc` 继续工作.

签名并放入现场:

```sh
applet login
applet push      # save a hosted draft for chat editing; does not publish
applet deploy    # or: build and deploy from here
```

## 在同一个应用程序上聊天和CLI

```sh
applet pull my-app     # download an app built in chat into an empty directory (links it)
applet push            # send the project's source files back; refuses when the app was edited in chat since the last pull
applet pull            # fetch the edits an agent made; refuses to overwrite local files that differ (--force)
applet deploy          # build/publish locally; no editable source upload
applet deploy --sync-source # explicitly sync source, startup-check it and publish
```

连结在 `.applet/link.json`现有 **`app_id` 权威**:链接命令通过ID解决当前应用程序名称/工作空间,因此重命名不会重定项目目标. 缓存 `app_name` 显示元数据; 仅使用 ID 链接也有效。 删除或无法访问的ID在不出现名字倒置或自动替换的情况下失败,甚至使用 `--force`。错误的链接无法关闭 。 拒绝一个与链接目标相冲突的明确的应用程序名称或配置的工作空间;为另一个应用程序使用单独的目录. API 原产地绑定和再链接命令不是此迭代的一部分 。 不需要链接文件迁移;源修改和每个文件的同步基线得到保存.

Push 只接受无依赖性项目( 相对导入; 沙盒运行文件按原样运行); npm 依赖性保留的项目 `applet deploy`. 与 CLI 一起部署且从未被推入的应用程序在聊天中被列为不可编辑.

### 可选主机浏览器预览

当服务配置了浏览器预览时, `applet push` 打印 a **私人预览** 链接与活应用程序 URL 分开. `deploy --sync-source --json` 包括返回的 `preview` 没有单独预览请求的元数据。 仅本地部署仍然不会上传可编辑源或提供主机预览;使用本地工具尝试本地更改.

主机预览被绑定在源版本上,需要浏览器登录,共享沙盒测试数据——而不是活数据. 源编辑后旧链接冲突. 可提供性并不证明启动/出版;打开它从不出版,出版也从来不需要预览/批准访问. 预览使用保留的兄弟会主机名 `applet.works`,只有主机平台会话;兄弟会起源不是单独的饼干网站. 在启用协调预览路由推出之前, 不发布 URL .

## 自定义应用程序 URL (Pro)

一个管理员可以为您的账户启用自定义的 URL; 联系我们请求访问 。 从现有应用的项目目录中 :

```sh
applet url                         # canonical URL and any pending change
applet url check sunny-weather      # advisory availability; claims nothing
applet url set sunny-weather        # interactive confirmation
applet url set sunny-weather --yes  # explicit noninteractive confirmation
```

名称被普通化为小写,并必须包含由连字符分隔出的两个或多个单词,每个单词至少有3个ASCII字母(无数字),最多共32个字符. 譬如说, `sunny-weather` 或者说 `bread-and-bot`。现有的 URL 保持不变;设置当前名称仍为不开放 。 其他应用程序声称的平台名称和名称不详。 应用程序必须已远程存在; 选择一个名称不会创建或部署它 。 一个未部署的应用程序的URL在首次成功部署后就可被达到.

**之前的URL停止了没有重定向的工作,其名称可以被另一个应用程序立即使用.** 旧的书签、嵌入物、网络呼声和认证回调可能会到达其他应用程序。 返回的访客也可能将与旧来源相关的饼干或浏览器存储器暴露给其新所有者. 浏览器存储, cookie, 和登录不会转移至新来源 。 有意更新集成和链接.

这只改变主机公共地址,而不是项目名称、不可改变的应用程序身份、状态或秘密。 它不写本地文件, 并添加不 `applet.jsonc` 设置。 调用保存您选择的 URL 。 撤销能力会阻挡新的变化,但保持已有的URL活动.

CLI最多等待一分钟接受操作. 在不完全或不确定的结果上运行 `applet url` 检查峡谷URL和待操作。 关闭/取消客户端不会回滚服务器操作 。 仅使用元数据进行定期恢复;不假定失败并声称有其他名称.

## 把密码和秘密放在一起

```sh
applet deploy --secrets-file /secure/path/secrets.json
# Or a dotenv file (Node.js 20.12+):
applet deploy --secrets-file /secure/path/credentials.env
```

这对 **首次部署** 以及重新部署。 A 类 `.json` 文件必须是 UTF-8 对象映射名称到字符串值;其他扩展使用 dotenv 解析. JSON完全保留了字符串; dotenv引用规则适用. 在源树外使用被保护的文件, 并且永远不执行 。 文件必须包含1–100个秘密,非空值可达5个KiB UTF-8,总载荷为1个米B以下. 需要两个 `deployments:write` 财务报告和审定财务报表 `apps:write`。 。 。 .

密码和提供的秘密进入 **同名 Cloudflare 出版物**,用于替换当前值的应用名称;省略的秘密被保留,而不是删除。 数值通过同步认证的请求发送,从未被放入文物,队列,数据库,审计记录或CLI输出. 拒绝将选定的机密文件导入工人代码。 没有自动的有价值重试。 如果出版工作中断或结果不确定,则先检查部署情况并核实综合情况,然后再按预定的目前资格进行重新试验。 这不能保证立即刷新已运行的持久对象 .

## 部署的应用程序机密

```sh
applet secrets set API_KEY              # TTY prompt, echo disabled
applet secrets set API_KEY --stdin      # exact UTF-8 stdin, including trailing newline
applet secrets list --json              # sorted names/types only
applet secrets delete API_KEY --yes     # explicit noninteractive confirmation
```

从应用程序的项目目录中运行;不需要建立/上载或Cloudflare登录. 价值从不被接受为参数、旗帜或环境变量。 用于外壳自动化 `printf` 而不是说 `echo` 当后行的新行不是意图时; 管道来自安全源,而不是在 shell 历史中输入一个真实值. `--no-input` 需求 `--stdin` 用于设定或 `--yes` 用于删除。 变异还只支持元数据 `--json`。 。 。 .

名称必须匹配 `[A-Za-z_][A-Za-z0-9_]*`,最多128个字符; `APPLET_`编号 :`__APPLET_` 前缀和与 vars/ DO 绑定相撞被保留。 值必须非空并最多为5 KiB UTF-8. 白空/ Unicode 保存. 键 `apps:write` 可更改全权证书; `apps:read` 可列出姓名.

对于独立的秘密命令,部署安全处理缺失的代码 `env.API_KEY`,然后设置并启用/使用集成。 永不部署的应用程序返回 `APP_NOT_DEPLOYED`; 使用 `applet deploy --secrets-file PATH` 在第一次出版期间提供全权证书。 Cloudflare 保留值;没有获得值命令 。 代码可以读取/过滤它自己的秘密并打印它们可以泄露它们来应用日志——没有自动编辑或端到端加密.

当地 `applet dev`,设置多腾v `KEY=value` 输入 **点缀 `.dev.vars`** (节点20.12+). 本地条目覆盖普通 vars , 绝不是 DO 绑定 。 此文件不是通过构建/部署自动读取,从不输入文物. 您可以明确发布其值 : `applet deploy --secrets-file .dev.vars`。从不将证书输入 vars/ 配置/ 来源或承诺 `.dev.vars`。 。 。 .

发布旨在保留当前机密;应用删除删除了基础脚本/绑定. 活地旋转/删除并不能保证瞬间的全球传播。 现有的可持久对象实例可以保留更古老的构造器环境,而新对象则看到更新后的约束;核实实际的集成情况并在需要时在其签发服务中吊销证书。 打开 `SECRET_OUTCOME_UNCERTAIN`,并用预期的当前值进行刻意重试:延迟重试可以覆盖更新的旋转. 没有带有背景价值的重复。 出版物总是要求保护。 见 [应用机密指南](https://applet.one/dashboard/docs/secrets) 整个工作流程、当地发展和安全指导的仪表板.

### 已知问题:现有持久物体可能不会立即刷新秘密

**状态:开放.** 成功的秘密更新确认配置发布, 而不是立即刷新每个运行对象 。 现有的可持久物体可以保留其较早的构造器环境:新添加的秘密可能仍然无法使用,而旋转或被删除的秘密通过运行代码仍然可以使用.

在生产测试中,一个现有物体一直保持其旧环境 **投票3分钟** 而新对象则收到更新后的约束。 三分钟是一个观察窗口, **不是一个刷新截止日期**我们没有规定最长的刷新时间,也没有保证立即重新开始工作。 不要假设重新调配代码会迫使已有对象刷新 .

第一次启动时使用 `applet deploy --secrets-file PATH` 以一起发布代码和证书;这不能保证对现有对象进行更新。 更改后验证真正的整合 。 取消旧的证书, 在发售服务处撤销它—— 撤销 Cloudflare 绑定不会抹去运行代码已经持有的复制件 .

## 出版物出处和来源选择

CLI 0.4.5+记录文物SHA-256和工作流程启动时捕获的可选基特承诺/肮脏状态. Git元数据是一种痕量,而不是来源/艺术等同的证据. `deploy --json` 区分声称的和服务器验证的来源。 链接 `status --json` 包含 `linked_deployment` 犬科元数据/证明没有额外的发现呼叫;它不声称现场HTTP验证. 本地独有的出版保留了主机-来源等同性,即使修改之前是同步的.

`push` 财务报告和审定财务报表 `deploy --sync-source` 选择一次文件。 选择荣誉根/ 取消 `.gitignore` 规则和根 `.appletignore` 覆盖, 不包括点文件、 依赖性、 构建输出、 符号链接、 常见的证书/ 机密 JSON 文件名和提供的秘密文件 。 受保护的除外情形不能被忽略的否定所推翻。 在可避免远程写入前被排除/不支持的故障前飞行所需的配置,切入点或导入. 这是一个共享政策, **不是通用的秘密扫描仪**: 从不将证书嵌入其他包含的文件。 CLI 报告选定的计数/字节;结构化的部署结果包括选定的路径. 全球基特排除和 `.git/info/exclude` 不适用;在项目中继续共享排除 `.gitignore`编号 :`.appletignore`。 。 。 .

出版物记录了被检查的现场部署情况。 如果另一个出版物先赢, `LIVE_DEPLOYMENT_CHANGED` 拒绝应用程序协调员提出的呆板要求; 检查/核对,而不是盲目重试。 仅在本地部署后主机发布需要同步(CLI: `deploy --sync-source`或明确MCP替换范围 `expected_live_deployment_id` 与 `replace_live: true`。这是一个操作参数,而不是在已授权替换时必须的额外批准/审查步骤。 根源冲突仍在审查中;不使用一刀切的武力取代合并.

最后确定的文物字节储存在15分钟的PUT装机能力之外。 下载核实记录摘要,包括遗留文物; `ARTIFACT_INTEGRITY_ERROR` 不更改活代码/数据。 服务器准备从不队列或持续隐藏秘密值:合并同步加 `--secrets-file` 通过同步认证出版物完成已准备的文物。 启动检查仍未收到平台直播秘密;没有沙盒中的这些证书,应用程序必须安全启动.

**升级要求:** 新的最后敲定合同需要一个出版基地。 年长的客户/遗产排队工作,不发生任何故障 `PUBLICATION_BASE_REQUIRED`;使用CLI0.4.5+并检查后再编写出新的出版物。 现有的现场部署、来源、状态、秘密和联系都保留下来.

## 图标

-   `applet init <project-name|.>` ——创建启动应用程序(`app.js` 与 `class App`(a) 私人准入; `.` 如果生成的路径未被使用, 脚手架将当前目录( 使用它的文件夹名称作为应用程序名称) .
    
-   `applet pull [app-name] [--force]` ——将应用程序的源文件下载到当前目录并链接;链接的项目解决了不可变的应用程序ID;否则名称默认与目录名称. 添加数 `package.json`, (中文(简体) ), `README.md` 财务报告和审定财务报表 `.gitignore` 当它们失踪时,它们会变成一个单一的应用程序.
    
-   `applet push [app-name] [--publish [--wait]] [--force]` ——上传源文件(`.js .mjs .ts .md .json .jsonc`,不包括 `node_modules`,构建产出和本地状态) **草案**,在需要时创建应用程序。 它不默认发布. `--publish` 明确公布经启动检查的修订; `--wait` 需要,并等待最多为25秒(待决时退出2;报告启动/发布失败后退出1)。 自上次拉出后在聊天中编辑后拒绝并拒绝 npm 导入 .
    
-   `applet migrate-config` - 将遗产一分为二 `applet.jsonc` 输入标准 `wrangler.jsonc` 和 Applet 唯一的主机设置。 保留原件为 `applet.legacy.jsonc`;拒绝相互冲突的Wrangler文件或现有的备份. 仅本地;不需要登录或部署.
    
-   `applet version` 编号 : `applet --version` ——打印已安装的CLI版本.
    
-   `applet login` ——通过Applet认证.
    
-   `applet logout` ——签名并删除已保存的登录.
    
-   `applet status [--json]` 检查认证状况; `--json` 发出一个机器可读的结果.
    
-   `applet dev [--host HOST] [--port PORT]` - 在当地管理微型工地/工人;当地持久目标状态持续 `.applet/dev`。在源更改后重新启动命令.
    
-   `applet build --dry-run` ——验证配置并构建出不上传的文物摘要.
    
-   `applet deploy [--sync-source] [--secrets-file PATH] [--json] [--wait-ms 0..120000]` ——审定/建设并明确公布当地项目,可选附资证. **没有可编辑的源上传或自动链接**,甚至连连线项目. `--sync-source` 选择选择选定的源上传/链接、主机启动验证和发布 **服务器制造的该精确快照的文物** (不是单独构建的本地捆绑);冲突或启动失败阻碍发布(成功上传的草稿仍然保存). 此快捷键支持无依赖源; 普通的文物部署支持捆绑npm依赖. 提供的秘密文件从来没有被推出。 现有应用访问被保留;新应用默认为私有,除非主机配置明确公开请求. 使用 `applet access` 改变现有受众。 遗产组合仍然有效.
    
    `--json` 发布一个结构化结果,其中包含目标、文物摘要、可用时的同步修订、部署ID、验证事实和结果;进展到标准. `--wait-ms` 限定出版等待( 默认为 120000 ms) 。 已过期的等待报告待决,2号出口; `--wait-ms 0` 报告接受不等待。 有待完成的工作继续进行,没有重新提交。 构建/启动验证不是活的功能验证. 局部测试可以被连锁在一个外壳呼叫中,例如. `pnpm test && applet deploy --json`; 在核实实际整合之前,不要声称真实正确。 没有源代码同步,主机-源代码等同性未知;这不会覆盖主机草稿或更新其本地同步基线.
    
-   `applet url [set NAME [--yes] | check NAME]` ——检查或明确更改主机公共URL;自定义更改需要账户访问. 没有本地文件更改 .
    
-   `applet access` ——展示本地和现场接入. `applet access private` 更改JSONC和活应用程序; `applet access public --yes` 在明确确认后,亦然。 在首次部署前, 命令只更改 JSONC 。 在浏览器中打开一个私有的应用程序 URL , 在需要时可重新定向到 Applet 登录 。 没有app-host会话的 API 请求收到401; CLI 令牌不能提出一般运行时间请求.
    
-   Wrangler仍然可以直接部署Cloudflare: `wrangler deploy`. Wrangler不需要用于Applet管理的部署.
    
-   `applet logs [--limit N]` ——按时间顺序显示最近24小时(默认为100)的最新1–100个已部署的应用程序日志条目 。 包括部署结果`deployment:`),运行时日志,以及发送失败;它不运行尾或显示 `applet dev` 输出。 成功部署甚至在应用程序处理请求之前就创建一个条目 。 部署条目来自Applet的部署记录,而不是Cloudflare工人日志. 在 Applet 启用可观察性后, 日志收集从部署时开始; 先前的事件无法恢复 。 Cloudflare保留工人日志3天免费或7天付费。 您的应用程序控制台信息可能包含敏感数据; 避免登录证书或个人信息 .
    
-   `applet backup` ——下载该app配置的状态备份. 项目必须启用顶级 `backup` 内 `applet.jsonc` (遗产: `applet.backup`出口目前限于10个米B.
    
-   `applet delete [app-name] [--yes] [--no-input]` ——永久从任何目录中删除一个被命名为主机的应用程序,或者省略名称以使用当前工程的应用程序. 无 `--yes`,CLI要求确认; `--no-input` 禁用提示和要求 `--yes`。 。 。 .
    

工人田地只属于Wrangler配置; `applet.jsonc` 包含 `access`, (中文(简体) ), `backup`选项 `workspace`选择 `$schema`。 。 。 .

### 个人和团队工作空间

命令默认为您的个人工作空间, 不论会员命令如何 。 要选择在仪表盘中创建的团队, 请从您的项目目录中运行 :

```sh
applet workspace list          # accessible workspace slugs, types and roles
applet workspace use my-team   # persist this project's selection
applet status --json           # inspect the selected workspace and apps
```

`workspace list --json` 返回可访问的工作空间为 JSON,并在项目之外工作. `workspace use` 保存 `"workspace": "my-team"` 内 `applet.jsonc` (遗产合并文件: `applet.workspace`),保留注释和其他设置。 它不移动或部署应用程序。 将一个已经链接的项目切换到另一个工作空间被拒绝,以避免默默地重新定位其应用;取而代之的是使用单独的目录. 您可以再次选择您的个人工作空间 。 这个范围状态,拉出/推出,部署,秘密,日志,访问,URL,备份,删除到该工作空间. 如果访问被删除, CLI 将明显失败; 它永远不会回到另一个工作空间. 对于第一次拉入空目录, 创建 `applet.jsonc` 在运行前使用工作空间设置 `applet pull APP`。 。 。 .

团队编辑器可以创建/编辑/部署应用,读取日志并管理机密. 只有所有者才能删除应用程序,更改访问/URL,或取回备份;编辑器部署不得请求访问更改. 团队成员覆盖所有当前和未来应用. 编辑器是值得信赖的代码作者:部署的代码可以访问生产数据和秘密. 文件与沙盒数据是共享的;每个应用程序使用一个活动编辑器/代理,因为同时发生的更改可能相互覆盖. 私有已发布的浏览器 URL 仍然只有所有者(和管理员). 取消会员资格会阻碍下一个请求,尽管已经启动的出版可能完成。 团队的创建和会员管理需要仪表板的签入,而不是CLI/承接人标志.

没有主机设置, 将部署新应用程序 **私营** 访问; 保留现有的访问。 工人项目默认没有备份;单等应用程序允许备份. 直接Wrangler部署不强制Applet私人访问,也不包括它的备份帮助器. Wrangler TOML和环境分辨率目前尚未被Applet支持;使用Wrangler配置并不能提供Wrangler完全的特性等同. 见 [`docs/applet-project-config-v1.md`](https://npmcn.com/package/docs/applet-project-config-v1.md) 关于能力和移徙细节.

App名不是主机名标签. 使用应用 API 部署后打印或返回的生成的 URL .

设定 `APPLET_API_URL` 来使用非默认的 Applet API 端点.

## 常见问题

### @applet-one/cli 是什么？

使用 Cloudflare 工作程序创建、部署和管理

### 如何安装 @applet-one/cli？

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

### @applet-one/cli 支持 TypeScript 吗？

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

### @applet-one/cli 支持 ESM 还是 CommonJS？

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

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

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

### @applet-one/cli 可以商用吗？

@applet-one/cli 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @applet-one/cli 的下载量有多少？

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

### @applet-one/cli 还在维护吗？

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