pple CLI

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

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）。 平台管理工作(审批队列，所有应用索引，直接编辑， 移动所有者，运行代码审查，管理员退休/清除/删除)留在 Console，并且CLI没有针对它的命令。

在一个应用程序上运行的每个命令都需要 --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.

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

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

到达应用程序的代码

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

命令是如何工作的

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)。每个代理编写一次副本，格式为所指定的格式 读取，并且每个路径都被忽略：

哪个文件夹被刷新是一个命令运行，而不是应用程序 --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(无人值守： 进行)。有两种方法可以关掉这一切：

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

布局

开发

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 §3为两者。

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

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

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.