subotiz-cli

subotiz-cli 是基于 Go + Cobra 的 Subotiz API 命令行客户端。MVP 同时面向 人工操作和自动化 Agent：命令把稳定、可机器解析的数据写到 stdout，把告警、 错误和调试信息写到 stderr。

当前运行时已经包含配置/环境管理、raw API 调用、输出格式化、请求 dry-run 预览，以及基于 OpenAPI 的服务命令生成器。生成的服务命令依赖真实的上游 subotiz-openapi 规格；如果该规格无法同步或构建，生成命令树可能仍是占位 实现。

英文文档见 README.md。

安装

使用 npm 安装

npm 包发布在公网 npm registry，内嵌 darwin 和 linux 的 x64 / arm64 预编译二进制，安装时不需要配置 Go 私有模块，也不下载 release 资产。

推荐使用带可见安装引导的一条命令：

npx @subotiz/cli@latest install

安装引导会用彩色小标题展示进度，同步包内 skills，创建 Claude Code skills 软链， 初始化本地配置，可选交互式设置 API Key，并在结束时展示脱敏后的配置。直接回车 可以跳过 API Key 设置。环境选择提供 sandbox / prod / skip 预置选项，支持上下键切换、空格键选定、回车键确认。

如果需要全局安装后长期使用：

npm install -g @subotiz/cli
subotiz-cli install
subotiz-cli version

安装时会自动把 npm 包内的 Subotiz skills 同步到 ~/.agents/skills/。如果需要跳过 本地 skill 同步，可以设置：

SUBOTIZ_SKIP_SKILL_INSTALL=1 npm install -g @subotiz/cli

如果你的 Agent 使用其他 skill 目录，可以指定目标路径：

SUBOTIZ_SKILLS_DIR="$HOME/.agents/skills" npm install -g @subotiz/cli

如果安装时使用了 --ignore-scripts，或之后想手动重新同步，可以运行：

subotiz-cli install
subotiz-cli skill install
subotiz-cli skill install --dir "$HOME/.agents/skills"

从源码构建或安装

仅当你从源码构建，或通过 go install 安装私有 GitLab 模块时，才需要配置 Go 私有模块访问：

go env -w GOPRIVATE=gitlab.shoplazza.site

本地构建：

make build
./bin/subotiz-cli version

从当前 checkout 安装：

make install
subotiz-cli version

使用 go install 安装：

go install gitlab.shoplazza.site/shoplaza/financial/pgs/subotiz-cli@latest
subotiz-cli version

从当前 checkout 构建并安装 npm 包用于本地发布验证：

make npm-build
npm install -g .
subotiz-cli version

npm 发布、包内容和 postinstall 脚本说明集中维护在 npm/README.md。

开发与发布命令

同步 OpenAPI 规格

从同级 ../subotiz-openapi 仓库同步 OpenAPI 规格到 api-spec/：

make sync-spec

如果 subotiz-openapi 不在默认路径，可以直接调用脚本并传入路径：

bash scripts/sync-openapi.sh /path/to/subotiz-openapi

生成命令代码

根据已同步的 OpenAPI 规格生成 gen/services/*_gen.go 和 cmd/service/register_gen.go：

make generate

本地编译

编译当前平台二进制到 bin/subotiz-cli：

make build
./bin/subotiz-cli version

修改发布版本并重建 npm 二进制

一键修改 package.json.version，并用同一个版本重建 npm 内嵌二进制：

npm run version:set -- 0.1.3

该命令会执行 make npm-build，并验证 subotiz-cli version 输出的 CLI 版本与 npm 发布版本一致。

预览版本修改但不写文件：

npm run version:set -- 0.1.3 --dry-run

只更新 package.json.version，不编译：

npm run version:set -- 0.1.3 --no-build

单独构建 npm 发布产物

如果版本号已经正确，只需要重新构建 npm 包内嵌二进制：

make npm-build

构建结果位于 npm/bin/，支持 darwin / linux 的 amd64 / arm64。

检查 npm 包内容

发布前检查 npm tarball 会包含哪些文件：

npm pack --dry-run

应确认包含 npm/scripts/*.js、npm/bin/subotiz-cli-*、skills/*/SKILL.md 和 skills/*/references/**。

发布到 npm

公开发布 scoped package：

npm publish --access public

推荐完整发布流程：

make sync-spec
make generate
npm run version:set -- 0.1.3
npm pack --dry-run
npm publish --access public

快速开始

初始化配置

subotiz-cli config init

默认配置文件写入 ~/.subotiz/config.yaml。如果设置了 XDG_CONFIG_HOME，则写入 $XDG_CONFIG_HOME/subotiz/config.yaml。

默认配置包含 sandbox 和 prod 环境。可以通过环境变量或显式 配置更新 API key：

export SUBOTIZ_API_KEY="replace-with-your-own-key"
subotiz-cli env add sandbox \
  --base-url https://api.sandbox.subotiz.com \
  --api-key "$SUBOTIZ_API_KEY"

不要把真实 API key 写进文档、Issue、Prompt 或共享日志。

切换环境

subotiz-cli env list
subotiz-cli env use sandbox
subotiz-cli config show

一次性执行时，可以用 flag 和环境变量覆盖配置：

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_API_KEY | 未提供 --api-key 时使用的 API key。 | | SUBOTIZ_ENV | 未提供 --env 时使用的环境名称。 | | SUBOTIZ_BASE_URL | 未提供 --base-url 时使用的 API Base URL。 |

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

查询产品列表

同步真实 OpenAPI 规格并重新生成命令后，预期可以使用生成的产品列表命令：

make sync-spec
make generate
make build

./bin/subotiz-cli product list \
  --base-url https://api.sandbox.subotiz.com \
  --api-key "$SUBOTIZ_API_KEY" \
  --dry-run

如果 subotiz-openapi 不可用，生成文件可能仍是占位实现，此时 product list 可能尚未注册。可以改用下面的 raw API 命令。

Raw API 示例

提供 --base-url 和 --api-key 时，raw 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

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

--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

全局 Flags

| Flag | 默认值 | 说明 | | --- | --- | --- | | --env <name> | 空 | 环境名称。API 调用时覆盖 SUBOTIZ_ENV 和配置里的默认环境。 | | --api-key <key> | 空 | API key。覆盖 SUBOTIZ_API_KEY 和配置/凭证读取。 | | --base-url <url> | 空 | API Base URL。覆盖 SUBOTIZ_BASE_URL 和配置环境里的 Base URL。 | | --format <json|ndjson|csv> | json | API 响应输出格式。 | | --jq <expr> | 空 | 用于过滤 JSON 输出的 jq 表达式。 | | --dry-run | false | 打印脱敏后的请求预览，不发送请求。 | | --debug, -v | false | 开启 stderr 调试日志。 | | --timeout <duration> | 30s | 请求超时时间，例如 10s 或 1m。 | | --config <path> | 空 | 配置文件路径。为空时使用默认配置路径。 |

输出契约

subotiz-cli 严格区分 stdout 和 stderr：

• stdout 用于可机器解析的命令输出：JSON、NDJSON、CSV，或 dry-run JSON 预览。
• stderr 用于面向人的错误、告警、调试日志、request ID、trace ID 和排障提示。

自动化脚本应只解析 stdout。调试和错误输出的形态可能比 stdout 载荷更自由。

安全说明

• 默认配置目录权限强制为 0700；显式 --config 路径不会 chmod 已存在的父目录， 但配置文件权限仍强制为 0600。
• 配置路径和配置文件不能是符号链接。
• config show、dry-run 输出、调试输出和错误输出会对 API key、Bearer token、 secret、password、cookie、session 等敏感值做脱敏。
• 对 prod 或 https://api.subotiz.com 发起写请求（POST、PUT、PATCH、 DELETE）时，会向 stderr 打印生产写操作告警。
• 优先使用 SUBOTIZ_API_KEY 或 ${env:...} 占位符，不要把密钥提交到配置文件。

尚未覆盖

当前仍未覆盖 OS keychain 集成、自动分页、Shortcut 命令、单元测试、E2E 测试、 CI/CD、self-update，也不承诺在真实 OpenAPI 规格不可用时提供完整的生产级生成命令覆盖。