> ## Documentation Index
> Fetch the complete documentation index at: https://docs.subotiz.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Subotiz CLI

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

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

## 一条命令快速安装

首次使用推荐直接运行：

```bash theme={null}
npx @subotiz/cli@latest install
```

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

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

<Frame>
  <img src="https://mintcdn.com/shoplazza-92a3a725/kRg57qaFxQCCAN8Z/images/94262c1b-286c04aebf5da1865a67054181ce48a5ff599b435413ed6d01e7553d-e78cdf42-f247-4f19-b53a-d9c762f1b1bc.png?fit=max&auto=format&n=kRg57qaFxQCCAN8Z&q=85&s=7ff9d740b11c08bd979d3f4b5717b5d7" width="1158" height="1770" data-path="images/94262c1b-286c04aebf5da1865a67054181ce48a5ff599b435413ed6d01e7553d-e78cdf42-f247-4f19-b53a-d9c762f1b1bc.png" />
</Frame>

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

```bash theme={null}
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拷贝过去

<Frame>
  <img src="https://mintcdn.com/shoplazza-92a3a725/kRg57qaFxQCCAN8Z/images/d6cec4f1-58fbfbd562f15b2aed2cb2f67d6162a5498c44c0f19d00a0b5e5bbaa-6cfb7f7d-a19b-40f7-8b78-8457afb4f597.png?fit=max&auto=format&n=kRg57qaFxQCCAN8Z&q=85&s=ebbc25fccfd523ec3723c0699a8ee09b" width="1076" height="1878" data-path="images/d6cec4f1-58fbfbd562f15b2aed2cb2f67d6162a5498c44c0f19d00a0b5e5bbaa-6cfb7f7d-a19b-40f7-8b78-8457afb4f597.png" />
</Frame>

## 关键指令

### 查看版本

```bash theme={null}
subotiz-cli version
```

### 查看当前配置

```bash theme={null}
subotiz-cli config show
```

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

### 查看环境列表

```bash theme={null}
subotiz-cli env list
```

### 切换默认环境

```bash theme={null}
subotiz-cli env use sandbox
```

### 新增或更新环境

```bash theme={null}
subotiz-cli env add sandbox \
  --base-url https://api.sandbox.subotiz.com \
  --api-key "$SUBOTIZ_API_KEY"
```

### 预览 API 请求

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

```bash theme={null}
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 请求

```bash theme={null}
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`：

```bash theme={null}
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 环境中，推荐使用环境变量传递运行参数：

```bash theme={null}
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 请求时的环境解析，不会改变 `env list`、`env use`、`env add`、`env remove` 对配置文件的展示或修改语义。

## 常用全局参数

| 参数                             | 说明                                             |
| ------------------------------ | ---------------------------------------------- |
| `--env <name>`                 | 指定环境名称，覆盖 `SUBOTIZ_ENV` 和配置中的默认环境。             |
| `--api-key <key>`              | 指定 API Key，覆盖 `SUBOTIZ_API_KEY` 和配置中的密钥。       |
| `--base-url <url>`             | 指定 API Base URL，覆盖 `SUBOTIZ_BASE_URL` 和配置中的地址。 |
| `--format <json\|ndjson\|csv>` | 指定 API 响应输出格式，默认 `json`。                       |
| `--jq <expr>`                  | 使用 jq 表达式过滤 JSON 输出。                           |
| `--dry-run`                    | 输出脱敏后的请求预览，不发送请求。                              |
| `--debug` 或 `-v`               | 开启 stderr 调试日志。                                |
| `--timeout <duration>`         | 设置请求超时时间，例如 `10s` 或 `1m`。                      |
| `--config <path>`              | 指定配置文件路径。为空时使用默认配置路径。                          |

## 输出约定

`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 等敏感值做脱敏处理。