CLI 0.2.5 command reference

Online purchasing is currently unavailable. Browse public products with catabricks catalog list or contact Catabricks. 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.

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.

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.

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

Copycli_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