popcorn-cli

Popcorn 官方命令行客户端。API Key 和 OAuth 均可查询模型、提交生图 / 生视频任务、管理素材与文件夹；适用于普通终端、Codex、Cursor、Claude Code、OpenClaw、Hermes Agent 及 WorkBuddy。

安装

需要 macOS、Linux 或 Windows 10/11，以及 Node.js 20 或更高版本；WorkBuddy 使用托管 Node 22。

npm install -g @baomihuatop/popcorn-cli

安装后确认命令可用：

popcorn-cli --version
popcorn-cli --help

查看版本

popcorn-cli --version

输出本地已安装的版本号（例如 0.3.0），退出码 0。版本号读取本地已安装包的 package.json，可与 popcorn-cli --help 一起用于确认安装结果。

本轮待发布版本为 0.3.1，包含 Windows 权限检查性能优化，以及状态检查的 --expected-origin 选项。发布前请从本地 tgz 安装验证，不能假设 npm 已有此版本。此前合入 0.3.0 的调试编号不代表已发布版本。

auth 命令自 0.2.0 起提供；浏览器 OAuth 与 v2 凭证存储需要 0.3.0 或更高版本：

npm install -g @baomihuatop/popcorn-cli@latest

登录与凭据管理

支持两种认证；相同 OS 用户及用户目录下的终端、Codex、Cursor、Claude Code、OpenClaw、Hermes 和 WorkBuddy 共用一组当前登录态，无 profile。容器、远端或其他 HOME/USERPROFILE 的凭证独立。新认证校验成功才替换旧态；切换会影响共享该目录的其他宿主。

| 首次认证场景 | 推荐方式 | | --- | --- | | Codex / Cursor / Claude Code 本地交互 | OAuth，执行 popcorn-cli auth login 自动打开本机浏览器，前台等待批准 | | OpenClaw / Hermes / 无人值守 Agent / CI / 定时任务 | API Key，由用户或部署人员在实际执行环境的私人终端或受保护配置步骤中绑定 | | WorkBuddy 连接器 | 现有 OAuth-only 连接流程，由宿主承接浏览器交互 |

推荐只用于首次认证；已有可用身份继续复用，用户可主动选择另一种受支持方式。--no-browser 用于无可用浏览器、用户要求手动打开链接或宿主接管打开动作，不作为本地交互默认。受限宿主中可由用户在同一 OS 用户和用户目录的本机终端完成 auth login 后复用。OAuth 出错不自动切换 Key；Key 不在聊天中传递或写入构建日志。

| 命令 | 行为 | | --- | --- | | auth login | 输出 HTTPS 链接并打开浏览器，复用爆米花原账号密码登录后确认授权 | | auth login --no-browser | 只输出链接，前台等待授权完成 | | auth login --no-browser --return-to-workbuddy | 连接器专用；换票、身份核对和凭证保存后唤起 WorkBuddy，失败提示手动返回 | | auth login --no-browser --adapter workbuddy | 本次源码新增的宿主适配器入口；旧回跳参数继续兼容 | | auth login --background --no-browser | 通用终端的短期后台等待；WorkBuddy client_id 下拒绝，防止宿主提前判成功 | | auth bind --api-key <API_KEY> | 只读验证新 Key 后绑定；config set-key 是兼容别名 | | auth status [--format <FORMAT>] | FORMAT 为 json 或 workbuddy；只读检查，不刷新、换票、迁移或写盘 | | auth ensure [--format <FORMAT>] | 任务/连接器前置检查；OAuth 到期前 30 秒内按需续期并核对远端身份；不启动后台 Worker | | auth status --format workbuddy --expected-origin https://baomihua.top | 一次只读检查生产地址与登录态；地址不符时退出 3，不访问远端、不刷新或改写凭证。ensure 也支持此选项 | | auth logout | Key 本地解绑；OAuth 本地退出并撤销远端授权 | | config show | 脱敏 JSON 配置 | | config set-url <HTTPS_ORIGIN> | 原子变更服务 origin；新地址不会接收旧凭证 |

popcorn-cli auth login
popcorn-cli auth bind --api-key <API_KEY>
popcorn-cli auth status
popcorn-cli auth logout

CLI 已接入 OAuth 业务请求。 模型、生成、任务、素材、目录使用当前 OAuth Bearer 或 API Key；每次请求发送前按需刷新，失败不回退 Key。实际权限、数据及计费仍由目标后端决定，不代表所有环境的 4.3/积分已验收。

• 浏览器会话 token 与 CLI OAuth access token 是两套凭证；CLI 不接触用户密码或网页 access/refresh。CLI OAuth 使用固定 popcorn-cli-access。
• 每个请求只携带一种认证头：OAuth Bearer 或 X-API-Key。服务端异常收到双头时仅 OAuth 生效，OAuth 失败不回退 Key。
• Key 的 bind/status/ensure 使用双认证身份接口；部署配套后端修复后，Key 检查不依赖 OAuth 开关或签发密钥配置。OAuth 不可用时仍明确失败，不降级为 Key。
• auth status 默认输出 JSON，verification=remote 表示本次身份 API 成功；verification=local, refresh_required=true 仅表示本地 refresh 尚可续期，不证明远端未撤销。
• WorkBuddy 连接器和专家任务前置改用 auth ensure（CLI ≥0.3.0），成功必须已核对远端身份；普通 status 仍只读。闲置时不定时刷新，下一次 ensure 恢复；刷新响应不确定时停止重放旧 refresh，不自动回退 Key。
• 服务端 access 默认有效期调整为两小时；以服务端返回期限为准，旧 token 不追溯延期。若部署仍显式配置 CLI_OAUTH_ACCESS_TTL=900，需改为 7200 并重启后端。
• 若仍出现 BUSINESS_OAUTH_NOT_READY，检查 WorkBuddy 实际调用路径与 CLI 版本；旧调试包保留了本地门禁，需要更新。401/403 直接失败，不改用 Key；提交或上传响应丢失不自动重发。
• status 的退出码：0 当前状态可用/本地可续期；3 未登录、凭证拒绝、方式不匹配；1 网络、服务、存储或不确定结果。网络故障不会清凭证。
• WorkBuddy 格式成功只输出 Logged in，失败不会包含该成功词。POPCORN_REQUIRED_AUTH_METHOD=oauth 下 Key 不算已连接，logout 也不会误清已有 Key；申请客户端由 POPCORN_OAUTH_CLIENT_ID=popcorn-workbuddy 标识。
• auth logout 离线也清本地，但远端撤销未确认时退出 1 并明确提示，可到网页“CLI 授权管理”补撤销。
• 升级不覆盖凭证；卸载 npm 包不会自动注销。需要退出时先执行 logout。

存储、并发和平台

当前实现使用设计中的受限文件后备：~/.popcorn-cli 目录 0700，当前记录、秘密文件、pending/intent 为 0600。config.json v2 只含当前身份与秘密引用，原 Key/CLI tokens 位于 secrets/<随机UUID>.json，仍属于应严格保护的本机秘密，不应提交或共享。此版本不接入可能弹交互对话框的系统凭证库。

原 v1 config.apiKey 可只读兼容；第一次认证写操作原子迁移到 v2。status/config show 不迁移。none 墓碑阻止旧 Key 复活；旧版 CLI 不理解 v2，勿降级并混用旧写入器。

支持 macOS/Linux/Windows 10、11 + Node ≥20。跨进程锁采用 fs-native-extensions 的原生 advisory lock，npm 含平台预编译包，不需要系统 Python/flock；进程退出自动释放锁，不按 TTL 偷锁。刷新结果不确定时保留 intent 并要求重新登录，不盲重发旧 refresh。auth ensure 和业务请求共用刷新协调，普通 auth status 始终只读。

2026-11-03 在 Windows 10 x64、PowerShell 5.1、WorkBuddy 托管 Node 22.22.2 上完成完整 unit/e2e 回归：131 项，126 通过、0 失败、5 项按平台条件跳过；包含真实 ACL、junction、后台登录、双进程续期、短 keep-alive 和 PowerShell JSON 文件提交。此前已在 macOS 验证；Linux、Windows 11、ARM64 和非管理员账号仍需对应环境验证。WorkBuddy 使用 authDeviceFlow + authWaitForExit=true 和前台 auth login --no-browser；WorkBuddy client_id 下 --background 会在任何状态变更或网络请求前拒绝。本仓库不维护连接器包或 cli.json。

2026-10-26 已通过 QA + macOS WorkBuddy 5.9.0 的真实桌面验证：无确认码卡片、自动跳转、人工批准后保存/连接成功、拒绝及取消。使用当时标为 0.3.1 的本地未发布调试包和隔离 HOME（相关能力现并入 0.3.0）；测试授权已清理、原市场配置已恢复。该结果不代表正式 npm 安装、Linux、已授权状态下宿主重启或业务 OAuth 已验收。

取消清理失败时只提示用 status 核实，不自动注销；凭证已经发布后的取消不保证回滚旧态。宿主可能记录完整短期确认 URI，配置不能替宿主保证脱敏。

开发测试

宿主差异集中在 src/adapters/：WorkBuddy 的前台限制、固定回跳和文本状态格式由其适配器负责。通用认证模块不硬编码生态客户端名单；默认 client 为 popcorn-cli，独立 client 必须先在服务端登记，并通过绑定身份校验。--adapter workbuddy 是本次源码新增能力，发布前已有连接器可继续使用兼容的 --return-to-workbuddy；不要只凭旧包的版本号推断它含新入口。

通用 Skill 位于 agents/skills/popcorn-cli/。首次配置宿主时按需读取其 references/coding-agents.md、references/openclaw.md、references/hermes.md 或 references/workbuddy.md；业务调用共用一套命令和 JSON。容器或远端 HOME 需要独立、可写且持久化的凭证目录。

Codex、Cursor、Claude Code 可直接安装 npm 包自带的完整 Skill。在目标项目根目录三选一执行；加 --scope user 安装到当前 OS 用户目录：

popcorn-cli skill install --agent codex
popcorn-cli skill install --agent cursor
popcorn-cli skill install --agent claude-code

项目目录分别为 .agents/skills/popcorn-cli、.cursor/skills/popcorn-cli、.claude/skills/popcorn-cli；用户目录是在用户 HOME 下的相同路径。默认项目目录为 CWD，也支持 --project-dir "/path with spaces"。Windows 使用 popcorn-cli.cmd。安装返回 JSON，包含 path 和 changed；相同内容幂等，冲突保留旧文件并返回非零退出码。升级时先将旧目录移出 skills 发现目录备份，再重装。Cursor 兼容另外两种发现目录，同一项目可复用而无需安装第三份。

安装后重新打开宿主会话，Codex 用 $popcorn-cli，Cursor/Claude Code 用 /popcorn-cli。三者保留 API Key/OAuth 双认证和通用 JSON；不配置 WorkBuddy 专属环境或适配器。详情见 宿主说明。skill install 是本次源码新增入口，发布前先从本地 tgz 安装，不能假定 npm 同版本旧包已包含它。Skill 安装不迁移 CLI、凭证或云端权限；云端支持需在实际宿主执行环境单独验证。

本机装有 WorkBuddy 时另运行 npm run test:workbuddy（可用 WORKBUDDY_APP_ASAR 指定归档位置）。该探针使用 POSIX Shell/进程语义，Windows 下明确跳过，不将 Mac 应用归档当作 Windows 验收。它读取安装包中原始 CliRuntime 的指定方法，运行真实 CLI + 本地 HTTPS 替身，验证前台等待、最终退出、拒绝、到期及取消发布边界。浏览器/日志及进程树辅助适配被隔离，不能代替桌面 UI、真实账号、托管运行时或 Linux E2E；归档不存在或方法布局变更时明确失败。

使用 Node.js ≥20，安装依赖后执行：

npm ci
npm test
npm run test:unit
npm run test:e2e
npm run test:coverage

测试使用 Node 内置的 node:test，无需额外测试框架。单元测试覆盖协议校验、请求头互斥、凭证权限与迁移、认证切换、轮询、刷新和故障恢复。e2e 启动真实 CLI 子进程与本机 HTTPS 测试服务，验证前后台登录、SIGINT、跨进程锁、Key 业务兼容及退出码。

test/e2e/coding-agents.test.js 额外覆盖 Codex/Cursor/Claude Code 的项目/用户 Skill 安装、完整引用、冲突保留、空凭证可发现以及双认证模型请求。npm run test:agents 使用本机实际安装的 Codex app-server 和 Claude Code 初始化事件，分别验证项目和用户 Skill 的真实发现；无模型回合，隔离用户配置，Claude 仅使用合成 Key 与本机 HTTP 替身。可通过 POPCORN_CODEX_BIN、POPCORN_CLAUDE_BIN 指定可执行文件（Windows 指向原生 .exe）；未安装时明确 skip。该可选探针不装宿主、不消耗真实模型账号，不纳入未安装宿主的 CI 默认测试。

2026-10-28 macOS：Codex 0.165.0 和 Claude Code 2.1.308 的项目/用户发现探针均通过。npm 本地 tgz 安装后的三宿主 × 两 scope 安装及幂等检查通过。Cursor 已按其官方发现目录、标准 Skill 格式和真实 CLI 子进程覆盖；尚未执行 Cursor IDE 的 Skill 选择器与模型调用 UI 验收。上述结果不代替三宿主云端或 Windows/Linux 原生 Agent 验收。

scripts/run-tests.js 用参数数组传入测试文件，不依赖 Shell 展开通配符。.github/workflows/test.yml 配置 Node 20/22 × Linux/macOS/Windows 回归；Windows 运行原生 ACL 及 .cmd 安装检查。新增 CI 配置尚需提交后在对应 runner 上执行，本机分支模拟不等于原生平台已通过。

e2e 需要 PATH 中的 OpenSSL（支持 req -addext），运行时生成临时 localhost 证书，通过 NODE_EXTRA_CA_CERTS 信任该证书，保留 TLS 校验。每例使用临时 HOME，测试结束清理凭证和子进程；不需要真实账号，不连接生产服务。测试支持 macOS/Linux/Windows；Windows 使用 USERPROFILE 与 HOME 双重隔离，SIGINT 用例仅在 POSIX 执行，Windows 强制终止另有独立用例；本机 HTTPS 测试不替代真实 WorkBuddy 和生产后端联调。

查询可用模型

提交任务前，先查询当前认证身份可用的模型和参数 schema。

popcorn-cli image models
popcorn-cli video models
popcorn-cli video models --detail <MODEL_ID>

models 默认返回模型清单、model_limit、计费配置、公共调用建议和提交任务所需的参数结构。使用 --detail <MODEL_ID> 查看单个模型完整信息。

提交任务

生图任务：

popcorn-cli image submit -n "demo image" -d "cat test" -p '{"model":"sd-xl-v1","prompt":"a cat"}'

生视频任务：

popcorn-cli video submit -n "demo video" -d "cinematic cat test" -p '{"model":"video-model-id","prompt":"a cinematic cat"}'

关联会话 ID：

popcorn-cli image submit -s <SESSION_ID> -n "demo image" -d "cat test" -p '{"model":"sd-xl-v1","prompt":"a cat"}'

指定 AI 产物文件夹（仅支持 cli_generate）：

popcorn-cli folder list -t cli_generate
popcorn-cli image submit -f <FOLDER_ID> -n "demo image" -d "cat test" -p '{"model":"sd-xl-v1","prompt":"a cat"}'

-n, --name 和 -d, --description 必填；-p, --params 与 --params-file 必须二选一，内容必须是 JSON 对象。具体字段以 image models / video models 返回的 params_schema 为准。

上传资源

上传本地图片、视频或音频资源：

popcorn-cli resource upload ./demo.png --name "demo image" --description "reference image"

指定上传资源文件夹：

popcorn-cli resource upload ./demo.mp4 --folder-id 123 --name "demo video" --description "reference video"

--name 和 --description 必填。资源类型由后端按文件扩展名 / Content-Type 推断，CLI 不再提供 --type。--folder-id 不传则不归属目录；传入时必须是当前用户的 cli_upload 目录 ID，并由后端校验权限。

查询上传资源：

popcorn-cli resource list --name demo --created-from 2026-08-01 --created-to 2026-08-06 --page 1 --page-size 20

返回内容包含 name、description、file_url、created_at，并附带 total/page/page_size 分页信息。

查询任务

按任务 ID 查询单个任务：

popcorn-cli task list -t <TASK_ID>

按会话 ID 查询该会话下的任务：

popcorn-cli task list -s <SESSION_ID>

文件夹

按类型查询文件夹：

popcorn-cli folder list -t cli_generate
popcorn-cli folder list -t cli_upload

创建文件夹：

popcorn-cli folder create -n "角色参考" -t cli_upload
popcorn-cli folder create -n "主角" -t cli_upload -p <PARENT_ID>

type 支持 cli_generate（CLI 生成产物）与 cli_upload（CLI 上传资源）。

常用命令

| 命令 | 说明 | |------|------| | popcorn-cli --version | 显示本地已安装的版本号 | | popcorn-cli skill install --agent <codex\|cursor\|claude-code> [--scope project\|user] | 安装完整 Skill 到宿主发现目录；默认项目级 | | popcorn-cli auth login [--no-browser] [--background] | OAuth 浏览器授权，后台退出 0 仅表示已就绪 | | popcorn-cli auth status | 只读状态；不可用退出 3，无法判断退出 1 | | popcorn-cli auth bind --api-key <apiKey> | 使用 API Key 绑定登录 | | popcorn-cli auth logout | Key 本地解绑；OAuth 远端撤销和本地退出 | | popcorn-cli config set-key <apiKey> | 设置 API Key（等同于 auth bind） | | popcorn-cli config set-url <baseUrl> | 设置后端服务地址 | | popcorn-cli config show | 查看当前配置 | | popcorn-cli image models | 查询可用生图模型 | | popcorn-cli image models --detail <MODEL_ID> | 查看单个生图模型完整信息 | | popcorn-cli image submit -n <NAME> -d <DESCRIPTION> -p <JSON> | 提交生图任务 | | popcorn-cli video models | 查询可用生视频模型 | | popcorn-cli video models --detail <MODEL_ID> | 查看单个生视频模型完整信息 | | popcorn-cli video submit -n <NAME> -d <DESCRIPTION> -p <JSON> | 提交生视频任务 | | popcorn-cli resource upload <file> -n <NAME> -d <DESCRIPTION> | 上传图片、视频或音频资源 | | popcorn-cli resource list --name <KEYWORD> --page <PAGE> | 查询上传资源 | | popcorn-cli task list -t <TASK_ID> | 按任务 ID 查询任务 | | popcorn-cli task list -s <SESSION_ID> | 按会话 ID 查询任务 | | popcorn-cli folder list -t <TYPE> | 按类型查询文件夹 | | popcorn-cli folder create -n <NAME> -t <TYPE> | 创建文件夹 |

所有命令都支持 --help：

popcorn-cli --help
popcorn-cli auth --help
popcorn-cli auth bind --help
popcorn-cli image --help
popcorn-cli folder --help
popcorn-cli folder create --help
popcorn-cli resource upload --help

升级

npm install -g @baomihuatop/popcorn-cli@latest

卸载

npm uninstall -g @baomihuatop/popcorn-cli

常见问题

popcorn-cli: command not found

确认 npm 全局安装目录已加入 PATH，或重新打开终端后再试。

未设置 API Key

先执行：

popcorn-cli auth bind --api-key <YOUR_API_KEY>

认证失败 / 不确定凭据是否有效

执行 popcorn-cli auth status 定位原因：

• AUTH_NO_CREDENTIALS（退出码 3）→ 本地还没绑定凭据，按上一条执行 auth bind。
• AUTH_CREDENTIALS_INVALID（退出码 3）→ 凭据被服务端拒绝，到爆米花后台确认或重新生成 API Key 后重新绑定。
• AUTH_CHECK_FAILED（退出码 1）→ 网络或服务异常，用 popcorn-cli config show 确认 baseUrl 是否正确后重试。

params 不是合法的 JSON

-p 参数必须传入合法 JSON 对象字符串，建议用单引号包裹完整 JSON。

2026-10-26 补测完成：账号密码登录后恢复授权、A→B 切换并重新确认、凭证保存后返回 WorkBuddy。修复 statusMatch 未兼容 CLI 行尾而误报断连，以及 macOS 深链接只导航未稳定激活窗口的问题；最终用户确认自动返回，宿主绿色连接，CLI 远端身份为 B。CLI 53 单元 + 18 E2E、连接器 12 项、原始宿主运行时 6 项、前端授权页 18 项通过。仍不代表正式 npm 分发或 Linux 验收，详细证据见连接器设计 11.7。

Windows 使用与验证

PowerShell 5.1 调用 .cmd 时不要直接照搬 Bash 的单引号 JSON。图片和视频提交使用 UTF-8 参数文件；支持 PowerShell 的 UTF-8 BOM，且不受命令行内联 JSON 长度限制：

$params = @{ model = '<MODEL_ID>'; prompt = '中文 "提示词"' }
$params | ConvertTo-Json -Depth 20 | Set-Content -LiteralPath .\params.json -Encoding UTF8
popcorn-cli.cmd image submit -n demo -d reference --params-file .\params.json
# video submit 同样支持 --params-file；不要同时传 --params。

连接器只读 status 仍使用 8 秒检查预算；Windows 任务前置 ensure 使用 30 秒预算，以等待原生权限校验、并发刷新锁和远端身份核对。Windows 通用后台登录的 worker 就绪另有 25 秒预算；WorkBuddy 仍只使用前台登录。

Windows 修复随 CLI 0.3.1 交付，WorkBuddy 配套连接器最低 CLI 版本为 0.3.1。发布前可从源码 npm pack 后安装本地 tgz，不能假定 npm 上已经存在该版本。

npm.cmd install -g @baomihuatop/[email protected]
popcorn-cli.cmd --version
popcorn-cli.cmd auth login
popcorn-cli.cmd auth status

上述固定版本命令供版本正式发布后使用。通过 WorkBuddy 使用时，每次 Agent Shell 调用增加：

$env:POPCORN_REQUIRED_AUTH_METHOD = 'oauth'
$env:POPCORN_OAUTH_CLIENT_ID = 'popcorn-workbuddy'
popcorn-cli.cmd auth ensure

Windows 凭证目录为 %USERPROFILE%\.popcorn-cli，使用 NTFS ACL 保护。第一次写入前停止继承父目录规则，仅授予当前用户、SYSTEM、本机 Administrators 完全控制；后续按读取或锁内事务重新验证目录和子文件。拒绝外部用户访问、junction/symlink 和不安全旧目录，不以 chmod 模拟 POSIX 权限。Windows PowerShell 5.1 或 ACL 不可用时明确失败，不放宽权限或回退 Key。

临时文件先 flush，再在同一卷原子替换，不执行 Windows 不支持的目录 fd/fsync。Windows 通过系统协议处理器打开浏览器和固定 workbuddy://connectors。强制终止不能保证执行清理；OS 自动释放进程锁，下一次检查核实当前态，不自动注销原有授权。

Windows 开发机或 CI 可运行：

.\scripts\test-windows.ps1

脚本运行完整测试，再打包并安装到临时 npm prefix，验证真实 .cmd shim 与 Windows 凭证目录。原生测试会放宽临时文件的 Everyone ACL 验证拒绝行为、检查 junction、测试强制退出后的恢复；只使用合成凭证与隔离用户目录。CI 的 Windows runner 需 Node 22、npm、Windows PowerShell 5.1 和 PATH 中支持 req -addext 的 OpenSSL。macOS 上的分支模拟回归不能代替这些原生 Windows 用例或 WorkBuddy 桌面验收。