# @pplethai/cli 中文文档

规范地址：https://npmcn.com/package/%40pplethai/cli/

版本：0\.6\.0
npm 元数据更新时间：2026-11-02T03:52:46.683Z
中文译文更新时间：2026-11-02T05:49:40.315Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40pplethai/cli
原文对照：https://npmcn.com/package/%40pplethai/cli/?lang=original
项目主页：https://github.com/PPLEThai/pple-platform#readme
源码仓库：https://github.com/PPLEThai/pple-platform

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

- 包体积（解压后）：426 kB，38 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22
- 运行依赖：0 个
- 首次发布：2026-07-20T01:59:48.087Z
- 最新版本发布：2026-11-02T03:52:46.522Z
- 已发布版本数：12（近 12 个月 12 个）

## 中文简介

Builder的终端工具：在ple ID和活动应用程序之间的三个命令，以及Builder可以在控制台中执行的所有其他操作。

## 安装

```sh
npm install @pplethai/cli
```

也可以使用：`pnpm add @pplethai/cli`、`yarn add @pplethai/cli`、`bun add @pplethai/cli`

## README

# pple CLI

Builder的终端工具：在一个apple ID和一个实时应用之间的三个命令， 以及Builder可以在控制台中执行的其他所有操作。

```bash
pple auth login                 # sign in with your PPLE ID (browser, no password in the terminal)
pple init                       # create an app (asks for App Name) and set up its code
pple init --name "Sign-up"      # same, without a prompt (for agents/scripts)
pple init brave-otter           # set up an app that already exists on the platform
pple deploy -m "Add the form"   # send the changes and put them live
pple upgrade                    # update pple itself from npm
pple help                       # every command; `pple <command> help` explains one
```

## Builder平价

Builder可以在控制台中查看或更改的任何内容都可以查看或更改 在这里([adr - 0020](https://npmcn.com/package/%40pplethai/docs/adr/0020-builder-parity-between-console-and-cli.md)）。 平台管理工作(审批队列，所有应用索引，直接编辑， 移动所有者，运行代码审查，管理员退休/清除/删除)留在 Console，并且CLI没有针对它的命令。

| 区域 | 命令 |
| --- | --- |
| 账户 | `auth login`， `auth logout`， `whoami`， `agreement` |
| 应用程序 | `apps`， `init`， `info`， `rename`， `retire`， `retry-setup` |
| 部署 | `deploy`， `redeploy`， `deploys [<id>]` （读取失败的部署日志） |
| 配置 | `env list`， `env set`， `env delete` |
| 出版 | `promote`， `invites [add|remove]`， `roles`， `request publish|change|limit|retire`， `requests` |
| 人 | `collaborators [add|remove]` |
| 笔记和回顾 | `notes [add]`， `reviews [<id>]` |

在一个应用程序上运行的每个命令都需要 `--app <slug>` 以及其他用途 应用程序所在文件夹的应用链接。读取命令 `--json` 和打印 平台自身的有效载荷；泰语文本是默认的。 `pple invites` 和 `pple collaborators` 打印完整的电话号码，就像控制台为一个 所有者。

CI测试保持了这一点。 `test/builder-parity.test.ts` 读取控制台的 `api` 对象(`console/web/console.ts`)，当一个方法不存在时，它就会失败 平台管理工作没有命名它的命令 `covers` （`src/registry.ts`)，也没有在测试中输入原因 `EXEMPT` 列表。 它证明了一个命令 _存在_，并不是说它的行为是一样的；权限保持 对齐是因为只有提供者执行它们。CLI CI无论何时运行 `console/web/console.ts` 的变化。合并后的命令只能在 命令行版本（ADR-0008），因此发布的命令行可以暂时滞后于控制台。

## 寻求帮助是安全的

`pple help`， `pple <command> help`， `pple <command> <subcommand> help`， `--help` 和 `-h` 解释一个命令，别无其他：它们永远不会到达网络， 更改任何东西，问一个问题，需要登录，或者运行每日更新检查。 `help` 只在命令本身的单词之后计数，所以 `pple info --app help` 还是指一个有子弹的应用 `pple env set API_URL help` 仍然设置值 `help`； `--help` 和 `-h` 赢得任何地方。代理探索 `--help`，所以这是检查每一个 命令在 `test/help.test.ts`.

## 重要的行为

在终端上，这些请求请求一个人，就像控制台那样。没有人在旁边跑 （代理、脚本、管道），除非给定特定的值，否则它们都会拒绝 被确认，所以目标会出现在建造者的记录中。有 没有通用的 `--yes`.

| 行动 | 无人看管的跑步必须通过 |
| --- | --- |
| `pple retire` | `--confirm <slug>` |
| `pple collaborators add <phone>` | 第二次运行时查找的令牌： `pple collaborators add --confirm <token>` |
| `pple request publish --address <name>` | `--confirm <name>` |
| `pple agreement` | 什么都不起作用：只有终端或控制台的人可以接受 |

该技能告诉代理人在通过任何这些之前获得建造者的OK。

Git是一个实现细节，GitHub也是。建造者被告知什么 发生在 _他们的应用程序_ -“发送您的更改…”，“志愿者注册是实时的。 在https://brave-otter.ppleth.ai”——从来没有一个分支发生过这样的事，从来没有 他们应该去某个地方开个账户。只有一个真正的 冲突暴露了下面的工具，甚至还有指令 而不是堆栈跟踪。

## 到达应用程序的代码

应用程序库是私有的，构建器的机器没有它们的凭证。 在每个涉及代码的命令之前，CLI会向提供程序请求一个 令牌作用域限定在一个仓库，将其保存在内存中，并将其交给 `git` 通过子进程的环境： `GIT_ASKPASS` 点 [`askpass/pple-askpass.mjs`](https://npmcn.com/package/%40pplethai/cli/askpass/pple-askpass.mjs)，它读取令牌 当git要求输入密码时，退出该环境。 `origin` 保持一个 plain URL，因此令牌永远不会通过 `ps`)， `.git/config`，或任何其他文件。提交作为构建器的PPLE进行编写 ID标识，由相同的响应提供——推动者是平台的 GitHub App，否则将是应用程序历史记录中的唯一名称。这个 推理是 [adr - 0005](https://npmcn.com/package/%40pplethai/docs/adr/0005-builders-never-hold-github-credentials.md).

## 命令是如何工作的

**`pple auth login`** 针对apple运行OAuth设备授权授予 ID: CLI打印一个代码，打开验证页面，轮询直到 建设者批准它。令牌进入 `$XDG_CONFIG_HOME/pple/credentials.json` (模式 `0600`) -从来没有在一个应用程序文件夹，这是一个回购平台 拥有。 `pple whoami` 通过刷新令牌静默地更新即将过期的令牌。

**`pple init`** 创建一个Builder应用程序（提示应用程序名称，或） `--name`)通过 同一提供方 `POST /apps` 控制台使用，等待，直到应用程序 准备好，然后搭建它——或者，给一个应用程序Slug，搭建一个应用程序 已经存在。无论哪种方式，它都会获取应用程序的代码，复制黄金路径 模板下的应用程序自己的名字，写道 `.pple/app.json` 链接文件夹 到应用程序，并安装技能和平台规则的构建器的AI编码 agent读取（ADR-0001, ADR-0019）。App Slug仍然是平台生成的； 裸露的 `pple init` 在一个已经有应用链接的文件夹中被拒绝。

**`pple deploy`** 把一切都记录在 在合作者的工作中，将它发送到应用程序的重新合并 然后观察平台构建它并报告实时URL， 或者解释为什么没有更改的构建输出。它不需要 参数：链接文件表示哪个app. Account-only命令 （`auth login` / `logout` / `whoami`)永远不要触及技能或平台规则。

**技能和平台规则** 不在这个包裹里。 `pple init`， `deploy`， `info` 和 `env`，在应用程序的文件夹中运行，向平台询问当前 对两者进行散列，只有当它与副本不同时才下载一个完整版本 在磁盘上，所以归并到 `main` 到达构建器的下一个命令，没有CLI 释放(adr - 0019)。每个代理编写一次副本，格式为所指定的格式 读取，并且每个路径都被忽略：

| 代理 | 技能 | 平台的规则 |
| --- | --- | --- |
| 克劳德代码 | `.claude/skills/pple-platform/` | `.claude/rules/pple-platform.md` |
| 光标 | `.agents/skills/pple-platform/` | `.cursor/rules/pple-platform.mdc` （`alwaysApply`） |
| 食典委 | `.agents/skills/pple-platform/` | `.pple/rules.md`，由一行指针插入 `AGENTS.md` |
| 双子座CLI | `.agents/skills/pple-platform/` | 无 |

哪个文件夹被刷新是一个命令运行，而不是应用程序 `--app` 名称;在应用程序文件夹之外什么都不会发生，也不会寻求帮助 刷新。只有当文件发生变化（第一次安装，第一次安装）时，刷新才有意义 位置放回，一个新版本)，并在stderr上说，所以 `--json` 输出 保持解析。刷新失败会发出警告，保留最后一个副本，然后永远不刷新 阻止命令；通过重命名完成的副本来替换每个位置 旧版本，所以下载到一半就没写完了。 兄弟技能、其他规则文件和 `AGENTS.md` 建造者写道，永远不会 触摸：指针只在文件缺失时创建。版本 平台发送的是不可信的-将离开其文件夹的文件路径拒绝 整个版本。

**`pple apps`， `rename`， `retire`， `retry-setup`， `redeploy`， `deploys`， `promote`， `invites`， `request`， `requests`， `roles`， `collaborators`， `notes`， `reviews`** 是来自终端的控制台按钮；每个呼叫相同 提供程序路由控制台所做的。 `request publish` 和 `request change` 从文件路径上载图标(`--icon`)的方式控制台的选择器， 并根据提供方的密钥或泰语标签命名角色 `GET /role-options` （`pple roles`) -控制台选择器显示的列表。

**`pple upgrade`** 询问NPM最新消息 `@pplethai/cli` 是和，当 这个拷贝是一个npm的全局根文件，安装它——这也是为什么 黄金路径模板向前移动(ADR-0007；技能不再 与CLI （ADR-0019）一起旅行。任何 其他安装通道在手册中被告知 `npm install -g @pplethai/cli` 行，而不是在第一个副本上安装第二个副本，因此 安装失败，携带npm自己的原因。CLI从不使用 `sudo`全球性的 Builder不能写入的文件夹是他们自己来修复的，而不是CLI强制的。

## 保持当前的

大约每天一次，在执行命令之前，CLI会询问npm 是否有更新 `pple`． 它运行 _之前_ 命令，因为 唯一免费升级的时刻是：没有什么是半途而废的，所以新版本 可以简单地交给相同的命令行。在一个终点站，建造者 如果是，命令行将安装新版本并重新运行原来的版本 这是命令。没有人在键盘上- AFK代理运行命令行是 构建服务-它打印关于新版本的一行，然后继续使用 命令;它从不问可能悬而未决的问题。

对命令的检查写为失败。一个不可能的注册表 Reached什么也没说，只需要一个请求，而不是一个命令： `update-check.json` 在CLI的config目录中记录了npm是 _问_，而不是它回答了什么。升级失败会打印出npm自己的原因和 手动行，然后提出继续使用当前的CLI(无人值守： 进行)。有两种方法可以关掉这一切：

```bash
PPLE_NO_UPDATE_CHECK=1 pple deploy          # this run, or exported in CI
echo '{ "updateCheck": false }' > ~/.config/pple/config.json   # this machine
```

## 布局

| 文件 | 它包含什么 |
| --- | --- |
| `src/registry.ts` | 命令表：每一个命令，用它的帮助声明一次，它涵盖了什么；解析命令行 |
| `src/command.ts` | 什么是命令，以及解析它的选项 |
| `src/help.ts` | 的文本 `pple help`，由桌子搭建而成 |
| `src/cli.ts` | 运行一个命令行：首先是帮助，然后是更新检查，然后是命令 |
| `src/target.ts` | 命令作用于哪个应用程序(`--app`，否则应用程序链接) |
| `src/commands/` | 指令，每个指令 `Deps` 以及它被赋予了什么 |
| `src/labels.ts`， `src/requests.ts` | Builder读取平台值和请求的Thai |
| `src/deps.ts` | 每个接缝：fetch， clock, subprocesses, output, template dir |
| `src/device-flow.ts` | 针对apple ID的RFC 8628 |
| `src/api.ts` | 提供程序API，也是唯一知道其错误代码的地方 |
| `src/git.ts` | Git，以及唯一命名它或保存回购令牌的地方 |
| `src/scaffold.ts` | 复制黄金路径模板 |
| `src/guidance.ts` | 将Skill和平台规则刷新到app文件夹中 |
| `src/npm.ts` | Npm：注册表的最新版本，以及安装通道 |
| `src/update.ts` | 每日更新检查，它的节奏状态，以及它的选择退出 |
| `askpass/pple-askpass.mjs` | git运行时会被告知应用程序的回购令牌 |

## 开发

```bash
npm install
npm test            # drives whole commands against a fake Provisioner and real git
npm run typecheck
npm run build       # bundles the template, then esbuild → dist/bin.js
```

测试运行真实的命令路径- real `git` 在临时目录中，一个假的 背后的平台 `Deps.fetch`，以及一个虚拟时钟，以便轮询循环结束 立即。 `test/support/harness.ts` 是入口点。

应用程序库在测试中由 `git http-backend` 基本原理背后 （`test/support/git-server.ts`)，只接受假平台的代币 铸造。本地路径可以让每个克隆和推送都在没有凭证的情况下成功 根本没有，没有什么能表明平台的令牌是打开一个 私人回购。

发布的包带有它自己的黄金路径模板副本 （`npm run build:template` 副本 `../template`）. 从结帐处跑下来 直接回到那个回购路径。技能不是捆绑的：测试服务于它 假平台。 `PPLE_TEMPLATE_DIR`， `PPLE_API_BASE`， `PPLE_SSO_BASE`， `PPLE_CLIENT_ID`， `PPLE_REPO_BASE`, `PPLE_REGISTRY_BASE` 覆盖暂存的默认值 工作。

## CLI释放

一个完整的第一阶段发射包括一个 **CLI释放**:海运 `@pplethai/cli` (本: `pple`)到NPM `latest` 区标签，也就是 构建器安装和自我更新。这是 **不** Cloudflare的一部分 Worker部署——Worker回滚永远不能发布或卸载CLI版本。

释放是通过 **CLI释放** 工作流 （`.github/workflows/cli-release.yml`)：任何拥有储存库的人都可以编写分派 在 `main`，它重新运行类型检查、测试和构建，询问发布闸门 版本是否 `package.json` 可以到达注册，发布，和 然后才标记提交 `cli-vX.Y.Z`． 唯一的例外是引导 Publish在npm上创建包，一个人只运行一次——参见 [文档/ deploy-phase1.md](https://npmcn.com/package/%40pplethai/docs/deploy-phase1.md) §3为两者。

这个版本来自 `package.json` 在 `main` -工作流不需要 版本输入，并拒绝发布NPM已经持有的版本。没有人 手动编辑该版本：PR更改该包所携带的内容 变更集(`npx changeset` 在回购根，或者a `skip-changeset` 给它贴上标签 版本包PR将这些变更集投入其中 `package.json` 和 `CHANGELOG.md`。所以 `main` 可能会在NPM之前-一个版本 这里是准备好的，不是发货的。看到 [`.changeset/README.md`](https://npmcn.com/package/%40pplethai/.changeset/README.md) 和 [adr - 0008](https://npmcn.com/package/%40pplethai/docs/adr/0008-cli-release-is-a-deliberate-act.md).

在创建包的引导发布之后，不支持任何方法 从笔记本电脑上释放。释放门是 `scripts/release-gate.mjs`, 它也回答本地问题：

```bash
node scripts/release-gate.mjs release   # may this version reach npm?
npm publish --access public --dry-run   # inspect the tarball, upload nothing
```

编译器安装 `npm install -g @pplethai/cli`.

## 常见问题

### @pplethai/cli 是什么？

Builder的终端工具：在ple ID和活动应用程序之间的三个命令，以及Builder可以在控制台中执行的所有其他操作。

### 如何安装 @pplethai/cli？

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

### @pplethai/cli 支持 TypeScript 吗？

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

### @pplethai/cli 支持 ESM 还是 CommonJS？

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

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

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

### @pplethai/cli 可以商用吗？

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

### @pplethai/cli 还在维护吗？

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