Subotiz CLI

subotiz-cli` 是 Subotiz API 的命令行客户端，适合开发者、运维人员和自动化 Agent 在本地或 CI 环境中快速调用 Subotiz API。

它提供配置管理、环境切换、Raw API 调用、请求预览、输出格式化等能力。命令输出遵循自动化友好的约定：可解析结果写入 stdout，调试、告警和错误信息写入 stderr，方便脚本和 Agent 稳定消费。

一条命令快速安装

首次使用推荐直接运行：

npx @subotiz/cli@latest install

这条命令会完成安装、初始化和基础配置引导：

• 同步内置 Subotiz skills。
• 初始化本地配置文件。
• 可选交互式设置 API Key。
• 展示脱敏后的配置结果，便于确认当前环境和配置路径。

完成后可以立即检查版本：

subotiz-cli version

当前 npm 包支持 macOS 和 Linux 的 x64、arm64 平台，内置预编译二进制，安装时不需要配置 Go 私有模块，也不需要额外下载 release 资产。

适用场景

• 快速完成 Subotiz API 的本地调试和请求预览。
• 在 CI、脚本或 Agent 环境中调用支付、订阅、商品、价格等 API。
• 管理 sandbox 和 prod 等多环境配置。
• 通过 --dry-run 预览请求，降低误操作风险。
• 使用 JSON、NDJSON、CSV 或 jq 表达式处理 API 响应。

在Agent中使用

cursor、claude code等编码agent的skills已经默认支持，若您的agent需要使用自定义的skills目录，请将~/.agents/skills/目录下对应skills拷贝过去

关键指令

查看版本

subotiz-cli version

查看当前配置

subotiz-cli config show

config show 会对 API Key 等敏感字段做脱敏处理。

查看环境列表

subotiz-cli env list

切换默认环境

subotiz-cli env use sandbox

新增或更新环境

subotiz-cli env add sandbox \
  --base-url https://api.sandbox.subotiz.com \
  --api-key "$SUBOTIZ_API_KEY"

预览 API 请求

使用 --dry-run 可以只输出脱敏后的请求预览，不会真正发送请求：

subotiz-cli api GET /api/v1/products \
  --base-url https://api.sandbox.subotiz.com \
  --api-key "$SUBOTIZ_API_KEY" \
  --query '{"limit":20,"status":"active"}' \
  --dry-run

发送 POST 请求

subotiz-cli api POST /api/v1/products \
  --base-url https://api.sandbox.subotiz.com \
  --api-key "$SUBOTIZ_API_KEY" \
  --data '{"name":"demo-product","active":true}' \
  --dry-run

确认请求无误后，再移除 --dry-run 发送真实请求。

从文件读取请求体

--data 支持内联 JSON，也支持 @file：

subotiz-cli api PATCH /api/v1/products/prod_demo \
  --base-url https://api.sandbox.subotiz.com \
  --api-key "$SUBOTIZ_API_KEY" \
  --data @payload.json \
  --dry-run

环境变量

在 CI、脚本或 Agent 环境中，推荐使用环境变量传递运行参数：

SUBOTIZ_BASE_URL=https://api.sandbox.subotiz.com \
SUBOTIZ_API_KEY="replace-with-your-own-key" \
SUBOTIZ_ENV=sandbox \
subotiz-cli api GET /api/v1/products --dry-run

SUBOTIZ_ENV 主要影响 API 请求时的环境解析，不会改变 env list、env use、env add、env remove 对配置文件的展示或修改语义。

常用全局参数

输出约定

subotiz-cli 将机器可读输出和面向人的诊断信息分开：

• stdout：JSON、NDJSON、CSV 或 dry-run JSON 预览。
• stderr：错误、告警、调试日志、request ID、trace ID 和排障提示。

自动化脚本应只解析 stdout。stderr 的内容用于排障，不建议作为稳定协议依赖。

安全建议

• 不要在文档、Issue、Prompt、命令历史或共享日志中粘贴真实 API Key。
• 优先使用 SUBOTIZ_API_KEY、CI Secret 或配置占位符管理密钥。
• 调用生产环境写请求前，先使用 --dry-run 预览请求。
• 对 prod 或 https://api.subotiz.com 发起 POST、PUT、PATCH、DELETE 请求时，CLI 会向 stderr 输出生产写操作告警。
• config show、dry-run 输出、调试输出和错误输出会对 API Key、Bearer Token、secret、password、cookie、session 等敏感值做脱敏处理。