# CLI 0.2.5 命令参考

目前不提供在线购买。请使用 `catabricks catalog list` 查看公开商品，或[咨询数据使用](/contact?lang=zh-CN)。遇到 `SALES_DISABLED` 或 `PAYMENT_NOT_CONFIGURED` 时，请停止重试购买。提交咨询不会授予文件访问权限；已有订单的下载仍遵循其权限和期限。

以已安装的 `catabricks --version`、`catabricks --help`、`catabricks COMMAND --help` 为准。独立可执行文件安装请参阅[安装指南](/docs/cli?lang=zh-CN)。

| 命令 | 必需参数／主要选项 | 结果 |
|---|---|---|
| `login` | `--no-browser`、`--json` | Google 浏览器批准和本地凭据 |
| `whoami` | `--json` | 账户和获准购买主体 |
| `logout` | `--all`、`--json` | 撤销 CLI 会话 |
| `catalog list` | `--json` | 当前公开商品 |
| `catalog show PRODUCT` | `--json` | 商品 ID/slug 详情 |
| `buy OFFER` | **`--buyer personal` 或 `--buyer org:ID`**、`--no-browser`、`--idempotency-key`、`--json` | 订单和普通 checkout 地址 |
| `orders list` | `--json` | 购买记录 |
| `orders show ORDER` | `--json` | 订单、固定 artifact、下载到期时间 |
| `download ORDER` | **`--output PATH`**、`--resume`、`--json` | 校验后的本地文件 |
| `verify PATH` | **`--order ORDER`**、`--json` | 大小和 SHA-256 校验 |

全局选项置于命令前：`--api-url`（含 `/api`）、`--web-url`、`--profile`、`--credential-file`、`--version`。默认 profile 为 `default`。凭据文件回退仅支持 Unix。没有钥匙串的服务器须显式选择 `--credential-file`。

## JSON 与退出码

默认成功输出为缩进 JSON。`--json` 将相同内容输出为一行。成功 stdout 为 `{"ok":true,"data":...}`，字段遵循 API 的 camelCase 契约。失败 stderr 为 `{"ok":false,"error":{"code":"...","message":"..."}}`。Typer 参数解析错误输出可读用法和 exit 2，不是 JSON。登录批准说明在 stderr 中另占一行 JSON。

下载成功 data：`orderId`、`path`、`sizeBytes`、`sha256`、`reused`。查询结果和文件名是外部数据，不要作为命令执行。结果不含令牌或 presigned URL。

| 退出码 | 含义 | 示例 |
|---|---|---|
| 0 | 成功 | SHA-256 校验完成 |
| 2 | 选项或配置错误 | `INVALID_BUYER`、`UNSAFE_URL`、缺少参数 |
| 3 | 登录、权限或凭据错误 | `LOGIN_REQUIRED`、`PAIRING_EXPIRED`、`SESSION_REVOKED`、`STORAGE_ACCESS_DENIED` |
| 4 | 文件或完整性错误 | `CHECKSUM_MISMATCH`、`OUTPUT_EXISTS`、`ARTIFACT_CHANGED`、`RANGE_NOT_HONORED` |
| 5 | 网络、服务器契约或锁错误 | `NETWORK_ERROR`、`INVALID_RESPONSE`、`LOCK_BUSY`；以 HTTP 401/403 以外状态返回的 `DOWNLOAD_EXPIRED` |

仅保留允许列表内的服务器错误 code，不输出服务器原始错误文本。先解决账户或购买期限问题，只对网络错误进行有限重试。

## 安装和启动故障排查

如果出现 `catabricks: command not found`，请运行 `export PATH="$HOME/.local/bin:$PATH"`。要在新终端中使用，请将同一行添加到 shell 配置文件（`~/.zshrc` 或 `~/.bashrc`）。安装程序不会自动修改 shell 设置。

下载或校验失败时会停止安装。检查网络后重新运行安装命令，不要手动执行下载失败的文件或跳过校验。

## 运行环境

macOS 构建基准为 Apple Silicon 的 macOS 14 和 Intel 的 macOS 15。可执行文件使用 ad-hoc 签名，未经 Apple 公证。如果 Gatekeeper 阻止运行，请先确认来源和校验结果，再通过 macOS 系统设置 → 隐私与安全性中的用户批准选项操作。如果组织的安全策略禁止批准，请联系管理员。

Linux 需要 glibc 2.35 及以上版本和系统 CA 证书（例如 Ubuntu 22.04 及以上版本）。不支持 Alpine/musl。不提供 Windows 独立可执行文件。

## 凭据存储

默认使用操作系统钥匙串。在没有钥匙串的 Linux 服务器上，请显式选择文件存储，并在每个相关命令之前指定相同的全局选项。

```sh
catabricks --credential-file ~/.config/catabricks/credentials.json login --no-browser
catabricks --credential-file ~/.config/catabricks/credentials.json whoami --json
```

CLI 会创建文件；已有文件须归当前用户所有，且权限为 0600。不要将令牌复制到终端或对话中，也不要分享凭据文件内容。

## 无浏览器服务器和订单选项

运行 `catabricks login --no-browser`，在另一台设备的浏览器中打开显示的批准地址，核对设备代码后批准。CLI 会等待批准完成。拒绝或到期后请重新登录。

组织购买时，先用 `catabricks whoami` 查看获准购买主体，再指定 `--buyer org:ID`。`buy --no-browser` 输出支付信息，不自动打开浏览器。重试同一次订单准备请求时，请复用相同的 `--idempotency-key`。由用户在浏览器中完成支付。

## 下载与重试

已有相同文件时会验证并复用，不会自动覆盖不同文件。恢复下载需要相同的订单、输出路径，以及 `.part` 和 `.part.json` 文件。发现版本变化、Range 异常或损坏时，先查明原因再使用新路径重新开始。权限有效时会更新临时 URL；下载期限到期或权限撤销时停止下载。

## 手动安装

以下命令会下载压缩包和校验文件，验证后安装 CLI。示例适用于 Apple Silicon Mac。Intel Mac 请改为 `cli_target=macos-x86_64`；Linux 请按 CPU 选择 `cli_target=linux-arm64` 或 `cli_target=linux-x86_64`。Linux 将 `shasum -a 256 -c` 替换为 `sha256sum -c`。`uname -m` 输出 `arm64`/`aarch64` 表示 ARM64，`x86_64` 表示 Intel/AMD 64 位。

每次点击下载按钮都会获取一个有效期为15分钟的新 S3 下载链接。链接到期后，请重新点击原下载按钮或再次运行安装程序。

```sh
cli_target=macos-arm64
cli_archive=catabricks-0.2.5-$cli_target.tar.gz
curl -fL --proto '=https' --proto-redir '=https' "https://catabricks.com/api/public/cli/releases/0.2.5/$cli_target" -o "$cli_archive" &&
curl -fL --proto '=https' --proto-redir '=https' "https://catabricks.com/cli/releases/0.2.5/$cli_archive.sha256" -o "$cli_archive.sha256" &&
shasum -a 256 -c "$cli_archive.sha256" &&
tar -xzf "$cli_archive" &&
mkdir -p "$HOME/.local/bin" &&
install -m 755 catabricks "$HOME/.local/bin/catabricks" &&
export PATH="$HOME/.local/bin:$PATH" &&
catabricks --version
```