boltz-api-cli

README

Boltz CLI

The official CLI for the Boltz REST API.

It is generated with Stainless.

Installation

Install or update

The recommended installer downloads the latest release for your platform from Boltz's install CDN. Rerun the same command to update an existing installation.

macOS and Linux:

curl -fsSL https://install.boltz.bio/boltz-api/install.sh | sh

Windows PowerShell:

irm https://install.boltz.bio/boltz-api/install.ps1 | iex

By default, the installer updates an existing boltz-api on PATH. If no existing binary is found, it installs to $HOME/.local/bin on macOS/Linux and %LOCALAPPDATA%\Programs\Boltz\bin on Windows. Set BOLTZ_API_INSTALL_DIR to choose a different install directory.

The installer uses https://install.boltz.bio/boltz-api for release metadata and binary downloads. Set BOLTZ_API_INSTALL_BASE_URL to use a mirror. Set BOLTZ_API_RELEASE_RETRIES or BOLTZ_API_RELEASE_RETRY_DELAY to override the default retry count and delay.

For reproducible installs, pin a version:

curl -fsSL https://install.boltz.bio/boltz-api/install.sh | BOLTZ_API_VERSION=0.15.3 sh

$env:BOLTZ_API_VERSION = "0.15.3"; irm https://install.boltz.bio/boltz-api/install.ps1 | iex

Installing with Go

To build from source, you need Go version 1.25 or later installed.

go install 'github.com/boltz-bio/boltz-api-cli/cmd/boltz-api@latest'

Once you have run go install, the binary is placed in your Go bin directory:

• Default location: $HOME/go/bin (or $GOPATH/bin if GOPATH is set)
• Check your path: Run go env GOPATH to see the base directory

If commands aren't found after installation, add the Go bin directory to your PATH:

# Add to your shell profile (.zshrc, .bashrc, etc.)
export PATH="$PATH:$(go env GOPATH)/bin"

Running Locally

After cloning the git repository for this project, you can use the scripts/run script to run the tool locally:

./scripts/run args...

Customization Model

Custom CLI extensions should follow one path:

• add commands, global flags, and command-tree rewrites through pkg/cmd/custom_apply.go
• keep Boltz-specific hand-written command code in pkg/cmd/custom_*.go
• avoid editing generated resource command files

Cross-cutting generated behavior is intentionally limited to three temporary seam files: pkg/cmd/cmd.go, pkg/cmd/cmdutil.go, and cmd/boltz-api/main.go. Everything else in pkg/cmd should be either generated from Stainless or part of the small non-generated runtime allowlist already in the repo. New custom behavior should follow the custom_*.go pattern rather than add logic to generated commands directly.

Usage

The CLI follows a resource-based command structure:

boltz-api [resource] <command> [flags...]

boltz-api predictions:structure-and-binding start \
  --api-key 'My API Key' \
  --input '{entities: [{chain_ids: [string], type: protein, value: value}]}' \
  --model boltz-2.1

For details about specific commands, use the --help flag.

Environment variables

Environment variable	Required	Default value
BOLTZ_API_KEY	no	null

OAuth mode can also be configured with:

• BOLTZ_COMPUTE_AUTH_ISSUER_URL
• BOLTZ_COMPUTE_AUTH_CLIENT_ID
• BOLTZ_COMPUTE_AUTH_SCOPE (comma-separated)
• BOLTZ_COMPUTE_AUTH_AUDIENCE
• BOLTZ_COMPUTE_AUTH_AUTHORIZATION_URL
• BOLTZ_COMPUTE_AUTH_TOKEN_URL
• BOLTZ_COMPUTE_AUTH_USERINFO_URL
• BOLTZ_COMPUTE_AUTH_REVOCATION_URL
• BOLTZ_COMPUTE_ORG
• BOLTZ_COMPUTE_LISTEN_PORT

Global flags

• --api-key (can also be set with BOLTZ_API_KEY env var)
• --help - Show command line usage
• --debug - Enable debug logging (includes HTTP request/response details)
• --version, -v - Show the CLI version
• --base-url - Use a custom API backend URL
• --format - Change the output format (auto, explore, json, jsonl, pretty, raw, yaml)
• --format-error - Change the output format for errors (auto, explore, json, jsonl, pretty, raw, yaml)
• --transform - Transform the data output using GJSON syntax. On paginated or streamed list commands, the transform runs on each item unless you use --format raw.
• --transform-error - Transform the error output using GJSON syntax
• --auth-issuer-url - OIDC issuer URL used for OAuth login and bearer-token refresh
• --auth-client-id - OAuth client ID for public-client login
• --auth-scope - OAuth scope to request (repeatable)
• --auth-audience - OAuth audience/resource to request for compute access
• --auth-authorization-url - Override the discovered authorization endpoint
• --auth-token-url - Override the discovered token endpoint
• --auth-userinfo-url - Override the discovered userinfo endpoint
• --auth-revocation-url - Override the discovered revocation endpoint
• --org - Persist or override the local selected organization
• --listen-port - Bind the OAuth loopback listener to a specific port

OAuth authentication

The CLI supports API-key mode and OAuth bearer-token mode. When --api-key or BOLTZ_COMPUTE_API_KEY is present, API-key mode wins. Otherwise the CLI uses a stored OAuth session if one matches the configured issuer, client ID, audience, and scopes.

Use API-key mode for CI and agent automation. The stored OAuth session is a human login flow with local state, refresh, and browser/loopback behavior.

Start a login flow with:

boltz-api auth login

For agent or MCP subprocess usage where a localhost callback is not practical, use OAuth device authorization:

boltz-api auth login --device-code

Machine callers can request newline-delimited JSON events and surface the auth_url event to the user:

boltz-api auth login --device-code --json-events

By default, OAuth login uses Boltz's first-party OAuth configuration:

• issuer: https://lab.boltz.bio
• client ID: boltz-cli
• scopes: openid offline_access profile email compute:run
• audience/resource: boltz-compute-api
• loopback callback: http://127.0.0.1:8421/oauth/callback

For local development against a locally running Lab backend, override the issuer:

BOLTZ_COMPUTE_AUTH_ISSUER_URL='http://localhost:3000' boltz-api auth login

Available auth commands:

• boltz-api auth login
• boltz-api auth logout
• boltz-api auth whoami
• boltz-api auth status
• boltz-api auth validate
• boltz-api auth orgs
• boltz-api auth wait
• boltz-api auth switch-org <org>
• boltz-api config show
• boltz-api config reset

Command roles:

• auth whoami - concise local identity and current mode
• auth status - stable machine-readable auth diagnostics without refreshing
• auth validate - local auth check that may refresh an expired OAuth access token
• auth orgs - list organization IDs available to the current OAuth session or API key
• auth switch-org - store the OAuth organization ID to send with compute API requests
• auth wait - wait for usable local auth to appear, returning structured success or waiting status
• config show - show the path and contents of the local non-secret config file
• config reset - remove the local non-secret config file

auth status, auth validate, auth orgs, and auth wait return structured output. They exit with code 1 when no usable auth mode is available. auth status remains read-only; auth validate may refresh an expired OAuth access token using the stored refresh token; auth wait stays read-only and polls local auth state until usable auth appears or the timeout expires. In API-key mode, auth validate confirms that an API key is configured locally; it does not make a server round-trip.

For machine callers that need to wait for a browser-based login to finish:

boltz-api --format json auth wait --timeout 60s --poll-interval 2s

auth status includes the local config path and warns when the resolved OAuth issuer or client ID looks like a placeholder. The CLI stores non-secret auth configuration in:

• macOS: ~/Library/Application Support/boltz-compute/config.yaml
• Linux: ~/.config/boltz-compute/config.yaml
• Windows: %APPDATA%\boltz-compute\config.yaml
• ~/.cache/boltz-compute/session.json

Refresh tokens are stored in the OS keychain when available, with a fallback to:

• ~/.config/boltz-compute/credentials.json

Local download helpers

download-results creates or resumes a local run directory under boltz-experiments/ and checkpoints progress in .boltz-run.json. It also writes a sanitized run.json for the remote run. Pipeline downloads include results/<result-id>/metadata.json for each result and a results/index.jsonl manifest with one result per line plus local artifact paths.

Structure prediction run IDs now use the sab_pred prefix. Historical pred_ IDs are still supported.

Examples:

boltz-api download-results --id sab_pred_123 --name example-run
boltz-api download-results --name example-run
boltz-api download-results --id pred_123 --name legacy-run
boltz-api download-results --id prot_des_123 --name batch-run
boltz-api download-results --id sab_pred_123 --name human-run --progress-format text --verbose

Use download-status to read the local checkpoint without making API calls:

boltz-api --format json download-status --name example-run

By default, download-results emits machine-readable JSON Lines progress events on stderr while stdout still prints the final run directory. Use --progress-format text --verbose for human-readable progress logs instead.

Passing files as arguments

To inline file contents into request values, you can use the @myfile.ext syntax:

boltz-api <command> --arg @abe.jpg

Files can also be passed inside JSON or YAML blobs:

boltz-api <command> --arg '{image: "@abe.jpg"}'
# Equivalent:
boltz-api <command> <<YAML
arg:
  image: "@abe.jpg"
YAML

To parse a file as structured JSON or YAML and inject the parsed object or array, use @json://... or @yaml://...:

boltz-api predictions:structure-and-binding start \
  --input @json:///tmp/input.json

boltz-api predictions:structure-and-binding start <<'YAML'
input:
  entities: "@yaml:///tmp/entities.yaml"
model: boltz-2.1
YAML

If you need to pass a string literal that begins with an @ sign, you can escape the @ sign to avoid accidentally passing a file.

boltz-api <command> --username '\@abe'

Explicit encoding

For JSON endpoints, the CLI tool does filetype sniffing to determine whether the file contents should be sent as a string literal (for plain text files) or as a base64-encoded string literal (for binary files). If you need to explicitly send the file as either plain text or base64-encoded data, you can use @file://myfile.txt (for string encoding) or @data://myfile.dat (for base64-encoding). Use @json://... or @yaml://... only when you want the CLI to parse the referenced file and inject structured data. Note that absolute paths will begin with @file://, @data://, @json://, or @yaml://, followed by a third / (for example, @file:///tmp/file.txt).

boltz-api <command> --arg @data://file.txt

Structured input for design and screen commands

For small-molecule/protein design and library-screen create or estimate commands, prefer a single top-level --input value. The CLI merges that object into the request body, so idempotency_key and workspace_id can still stay as their own top-level flags:

boltz-api small-molecule:library-screen start \
  --input @json:///tmp/input.json \
  --idempotency-key req_123 \
  --workspace-id ws_123

boltz-api protein:design start \
  --input @json:///tmp/input.json \
  --idempotency-key req_123

Legacy per-field flags still work and can override fields from --input when you want to tweak part of a payload:

boltz-api small-molecule:library-screen start \
  --input @json:///tmp/input.json \
  --target @json:///tmp/target-override.json

boltz-api small-molecule:library-screen start \
  --molecule '{smiles: CCO}' \
  --molecule '{smiles: CCN}' \
  --target @json:///tmp/target.json

boltz-api protein:library-screen start \
  --protein @json:///tmp/protein-a.json \
  --protein @json:///tmp/protein-b.json \
  --target @json:///tmp/target.json

When piping JSON or YAML on stdin, the CLI merges that data onto the HTTP request body, so you must use API body field names, not singular legacy CLI flag names:

boltz-api small-molecule:library-screen start <<'YAML'
molecules:
  - smiles: CCO
  - smiles: CCN
target: {}
YAML

boltz-api protein:library-screen start <<'YAML'
proteins:
  - {}
  - {}
target: {}
YAML

Use --help on a specific command to see the repeatable flag names it accepts.

Transform behavior

--transform applies to the whole response for single-object commands. On paginated or streamed list commands, it applies to each emitted item unless you use --format raw, in which case it runs on the full response page.

Examples:

# Per-item extraction on list output
boltz-api small-molecule:library-screen list-results \
  --id sm_scr_123 \
  --transform 'input_molecule.id'

# Whole-list reshaping or aggregation is better handled with jq
boltz-api small-molecule:library-screen list-results \
  --id sm_scr_123 \
  --format raw | jq '.data[] | {id, binding_confidence: .metrics.binding_confidence}'

Array-root expressions such as #.{...} are not the right tool in streamed per-item mode.

Linking different Go SDK versions

You can link the CLI against a different version of the Boltz Go SDK for development purposes using the ./scripts/link script.

To link to a specific version from a repository (version can be a branch, git tag, or commit hash):

./scripts/link github.com/org/repo@version

To link to a local copy of the SDK:

./scripts/link ../path/to/boltzapi-go

If you run the link script without any arguments, it will default to ../boltzapi-go.