popcorn-op-cli

Popcorn 官方经营命令行客户端。通过本地配置的后管 CLI API Key 调用经营报表接口，用于查询平台总览、组织目录、租户与模型汇总，以及单租户下钻明细。所有报表命令均为只读。

安装

需要 Node.js 18 或更高版本。

首次安装请按 爆米花运营 CLI 安装与使用指南 操作；该指南包含环境准备、API Key 配置、首个报表和故障排查。

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

安装后确认命令可用：

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

配置

安装后需先配置后端地址和 CLI API Key（由运维提供）：

popcorn-op-cli config set-url <YOUR_ADMIN_BACKEND_URL>
popcorn-op-cli config set-api-key <YOUR_CLI_API_KEY>

baseUrl 是后端根地址，不要加 /admin 或 /api 后缀。

# 查看当前环境
popcorn-op-cli config show

配置会保存在本机：~/.popcorn-op-cli/config.json。

经营报表

报表固定按北京时间（Asia/Shanghai）统计，不提供 --timezone 参数。日期使用 YYYY-MM-DD；传入时 --start-date 和 --end-date 必须同时提供。不传日期时由后端默认本月 1 日至当前日。

平台总览：

popcorn-op-cli report overview \
  --start-date 2026-08-01 \
  --end-date 2026-08-31

组织目录及配置模型（平台运营权限）：

popcorn-op-cli report organizations

租户与模型列表：

popcorn-op-cli report tenants
popcorn-op-cli report models

单租户汇总，以及按账户或模型下钻：

popcorn-op-cli report tenant 1001
popcorn-op-cli report tenant 1001 --breakdown accounts
popcorn-op-cli report tenant 1001 --breakdown models

当前命令输出后端原始 { data, meta } JSON，便于脚本和二次处理。

积分流水明细导出

detail 用于导出租户在指定时间范围内的积分流水，会自动请求全部分页并写入文件。日期按北京时间解释。

# 仅导出积分分配流水（credit_type=allocate）
popcorn-op-cli detail allocation \
  --tenant-id 123 \
  --start-date 2026-08-01 \
  --end-date 2026-08-10 \
  --output ./tenant-123-allocation.csv

# 导出该租户的全部积分变更明细
popcorn-op-cli detail changes \
  --tenant-id 123 \
  --start-date 2026-08-01 \
  --end-date 2026-08-10 \
  --output ./tenant-123-changes.json

默认按输出文件扩展名选择格式：.csv 为 CSV，.json 为 JSON；也可以显式传入 --format csv 或 --format json。

| 指标 | 说明 | |------|------| | pool_consumed_credits | 租户积分池下发/扣减；用于余额经营 | | task_consumed_credits | 任务净消耗：预扣减去失败和结算返还 | | closing_balance_credits | 查询截止日的可用积分余额 | | task_count | 任务主记录数量，不重复计算重试 |

常用命令

| 命令 | 说明 | |------|------| | popcorn-op-cli config set-url <url> | 设置后管地址 | | popcorn-op-cli config set-api-key <key> | 设置 CLI API Key | | popcorn-op-cli config show | 查看当前配置 | | popcorn-op-cli report overview | 查看全局经营总览 | | popcorn-op-cli report organizations | 查看组织目录和配置模型 | | popcorn-op-cli report tenants | 查看租户汇总列表 | | popcorn-op-cli report models | 查看模型汇总列表 | | popcorn-op-cli report tenant <id> | 查看单租户汇总或下钻明细 | | popcorn-op-cli detail allocation ... | 导出指定租户的积分分配流水 | | popcorn-op-cli detail changes ... | 导出指定租户的全部积分变更明细 |

所有命令都支持 --help：

popcorn-op-cli --help
popcorn-op-cli report --help
popcorn-op-cli report overview --help
popcorn-op-cli detail --help
popcorn-op-cli config --help

升级

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

卸载

npm uninstall -g @baomihuatop/popcorn-op-cli

常见问题

popcorn-op-cli: command not found

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

未配置 API Key

先执行：

popcorn-op-cli config set-api-key <YOUR_CLI_API_KEY>

401 / 403

API Key 缺失、过期、错误，或没有报表权限 / 请求范围越权。请重新配置有效的后管 CLI API Key。

--start-date 和 --end-date 必须同时提供

日期参数必须成对传入，例如：

popcorn-op-cli report overview --start-date 2026-08-01 --end-date 2026-08-31