# CLI 0.2.5 command reference

Online purchasing is currently unavailable. Browse public products with `catabricks catalog list` or [contact Catabricks](/contact?lang=en). Stop purchase retries on `SALES_DISABLED` or `PAYMENT_NOT_CONFIGURED`. An inquiry does not grant file access; existing downloads remain subject to the order permissions and deadline.

Installed `catabricks --version`, `catabricks --help` and `catabricks COMMAND --help` take precedence. To install the standalone binary, follow the [installation guide](/docs/cli?lang=en).

| Command | Required arguments / key options | Result |
|---|---|---|
| `login` | `--no-browser`, `--json` | Google browser approval and local credentials |
| `whoami` | `--json` | Account and allowed buyers |
| `logout` | `--all`, `--json` | Revoke CLI sessions |
| `catalog list` | `--json` | Current public datasets |
| `catalog show PRODUCT` | `--json` | Details by product ID/slug |
| `buy OFFER` | **`--buyer personal` or `--buyer org:ID`**, `--no-browser`, `--idempotency-key`, `--json` | Order and normal checkout address |
| `orders list` | `--json` | Purchase history |
| `orders show ORDER` | `--json` | Order, fixed artifact and download expiry |
| `download ORDER` | **`--output PATH`**, `--resume`, `--json` | Verified local file |
| `verify PATH` | **`--order ORDER`**, `--json` | Size and SHA-256 verification |

Global options precede the command: `--api-url` (including `/api`), `--web-url`, `--profile`, `--credential-file`, `--version`. The default profile is `default`. File credentials are supported on Unix only. Explicitly select `--credential-file` on servers without a keychain.

## JSON and exit codes

Default success output is indented JSON. `--json` prints the same content on one line. Success stdout is `{"ok":true,"data":...}`; fields follow the API's camelCase contract. Failure stderr is `{"ok":false,"error":{"code":"...","message":"..."}}`. Typer argument parsing errors print human-readable usage and exit 2, not JSON. Login approval instructions are a separate JSON line on stderr.

Download success data: `orderId`, `path`, `sizeBytes`, `sha256`, `reused`. Results and filenames are external data, not commands. Tokens and presigned URLs are excluded.

| Exit | Meaning | Examples |
|---|---|---|
| 0 | Success | SHA-256 verified |
| 2 | Options or configuration | `INVALID_BUYER`, `UNSAFE_URL`, missing argument |
| 3 | Login, authorization or credentials | `LOGIN_REQUIRED`, `PAIRING_EXPIRED`, `SESSION_REVOKED`, `STORAGE_ACCESS_DENIED` |
| 4 | File or integrity | `CHECKSUM_MISMATCH`, `OUTPUT_EXISTS`, `ARTIFACT_CHANGED`, `RANGE_NOT_HONORED` |
| 5 | Network, server contract or lock | `NETWORK_ERROR`, `INVALID_RESPONSE`, `LOCK_BUSY`; `DOWNLOAD_EXPIRED` when returned outside HTTP 401/403 |

Only an allowlist of server error codes is retained; raw server error text is not printed. Resolve account and download-window conditions first. Retry network failures only, within limits.

## Installation and startup troubleshooting

For `catabricks: command not found`, run `export PATH="$HOME/.local/bin:$PATH"`. Add the same line to your shell configuration (`~/.zshrc` or `~/.bashrc`) to keep it in new terminals. The installer does not change shell settings automatically.

Installation stops if downloading or checksum verification fails. Check your network connection and run the installer again. Do not run a failed download manually or skip verification.

## System requirements

macOS builds use macOS 14 for Apple Silicon and macOS 15 for Intel as their baselines. Binaries are ad-hoc signed and are not notarized by Apple. If Gatekeeper blocks execution, verify the source and checksum, then use the user approval option in macOS System Settings → Privacy & Security. Contact your administrator if an organizational security policy blocks approval.

Linux requires glibc 2.35 or newer and system CA certificates (for example, Ubuntu 22.04 or newer). Alpine/musl is unsupported. No Windows standalone binary is provided.

## Credential storage

The default credential store is the OS keychain. On Linux servers without a keychain, explicitly choose file storage. Use the same global option before every relevant command.

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

The CLI creates the file; an existing file must be owned by the current user with mode 0600. Do not copy tokens into the terminal or conversations, or share credential file contents.

## Headless servers and order options

Run `catabricks login --no-browser`, open the displayed approval address in a browser on another device, and check and approve the device code. The CLI waits for approval. Restart login after denial or expiry.

For an organization purchase, check allowed buyers with `catabricks whoami`, then use `--buyer org:ID`. `buy --no-browser` prints checkout information without opening the browser automatically. Reuse the same `--idempotency-key` when retrying the same order preparation. The user completes payment in the browser.

## Downloads and retries

An existing identical file is verified and reused; different files are not overwritten automatically. Resuming requires the same order, output path, and both `.part` and `.part.json` files. Investigate changed file versions, incorrect Range behavior, or corruption before restarting to a new path. Temporary URLs are renewed while authorization is valid; an expired download window or revoked access stops the download.

## Manual installation

These commands download the archive and checksum, verify them, and install the CLI. This example is for Apple Silicon Mac. For Intel Mac use `cli_target=macos-x86_64`; for Linux use `cli_target=linux-arm64` or `cli_target=linux-x86_64` for your CPU. On Linux, replace `shasum -a 256 -c` with `sha256sum -c`. In `uname -m` output, `arm64`/`aarch64` means ARM64 and `x86_64` means Intel/AMD 64-bit.

Each download button requests a new S3 download link valid for 15 minutes. If it expires, click the original download button or run the installer again.

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