CLI 0.2.5 命令参考
目前不提供在线购买。请使用 catabricks catalog list 查看公开商品，或咨询数据使用。遇到 SALES_DISABLED 或 PAYMENT_NOT_CONFIGURED 时，请停止重试购买。提交咨询不会授予文件访问权限；已有订单的下载仍遵循其权限和期限。
以已安装的 catabricks --version、catabricks --help、catabricks COMMAND --help 为准。独立可执行文件安装请参阅安装指南。
| 命令 | 必需参数／主要选项 | 结果 |
|---|---|---|
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 服务器上，请显式选择文件存储，并在每个相关命令之前指定相同的全局选项。
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 下载链接。链接到期后，请重新点击原下载按钮或再次运行安装程序。
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