CLI & API Reference

Use the Agent API & CLI guide to connect an agent and run a first campaign. This reference covers the current CLI commands and public API. Fetch live protocol schemas for supported scientific configuration fields.

Installation Channels#

Node.js 20 or newer and npm are required. The npm channel installs a stable release:

npm install --global ariax-cli@latest

Alternatively, install from GitHub. The public installer downloads the latest GitHub main commit and uses npm to install it locally; this channel can contain changes not yet released to npm:

curl -fsSL https://raw.githubusercontent.com/cytokineking/ariax-cli/main/install.sh | sh

You can review the installer before running it.

Inspect the installed version, channel, and source revision with ariax --version --json. Updates follow the selected channel:

ariax upgrade --check
ariax upgrade
ariax upgrade --yes
ariax upgrade --channel npm
ariax upgrade --channel github

Switching channels replaces the CLI package and preserves login and project files. Switching to npm can select an older build than GitHub. Use the same Node.js installation and npm global prefix; type -a ariax helps identify a shadowing executable or alias. The installer supports an exact npm version through ARIAX_VERSION, or a full Git commit through ARIAX_REVISION.

Interactive update notices run at most once per day. They never install updates automatically and are skipped in CI, noninteractive commands, and JSON output. Set NO_UPDATE_NOTIFIER=1 to disable them.

Commands and Structured Output#

Run ariax help COMMAND for exact options. BindCraft2 uses --input-dir or a compatible single --input; other workflows use their protocol-specific input form. Use --json for agents and scripts: structured output goes to stdout and progress to stderr. Project operands accept UUIDs or exact unique names.

Input Validation and Uploads#

The CLI prepares and checks supported structures locally before direct upload to private object storage using short-lived URLs. API configuration validation does not parse uploaded structure bytes; raw API clients must check their own files, sequences, chains, and residue numbering. Compute-time preflight remains a separate check.

• BindCraft2: keep the prepared bundle intact. The first target is input.pdb or input.cif; additional targets and a custom scaffold use exact configured basenames. Hotspots/coldspots use native author numbering and can select an entire chosen chain, such as A.
• BoltzGen: provide --input for local validation and submission. mmCIF selections preserve absolute label_seq_id positions; do not substitute author numbering.
• PXDesign: retain full target sequences. Gapped PDBs whose sequence register would be lost by conversion are rejected; use compatible canonical mmCIF with matching selected-chain author/label identifiers.
• ESMFold2-pipeline: supported preparation can repair author atom IDs and normalize author chain IDs together with selectors. Preparing an RCSB structure saves an upload snapshot, avoiding a second fetch during compute.

Preparation writes copies and a provenance manifest without changing source files. Use the prepared job and input files together. Validation errors provide field paths and rule details in error.details.issues. Local checks, API acceptance, successful execution, and experimental success are separate kinds of evidence.

Compute Scope and GPU Policy#

Read the chosen protocol's bundled guide and fetch ariax pricing --json before recommending compute. Each row's hourly_rate is the current effective USD price for its complete gpu_id/gpu_count allocation. standard_hourly_rate supplies the comparison rate, and cli_hourly_rate supplies the current CLI rate for that same allocation. The response includes promotion status and the time of evaluation. Public previews do not reserve a rate; billing uses the rate recorded at the GPU allocation request. Recheck before a new launch or restart. If the preview fails, retry before estimating a launch. Include at least one protocol-compatible core GPU; supplemental classes alone are insufficient. Keep existing selections unless a change is authorized. RTX6000PRO is a distinct GPU class from RTX6000ADA and A6000.

allowed_gpus specifies alternatives, not a GPU count. Saving preferences replaces the saved policy for the next provisioning attempt; it does not change active instances or restart the project. Turbo supports 2, 4, or 8 GPUs when authorized and available. Allocation-hour prices already cover the complete allocation, so do not multiply them by GPU count again.

Design counts and trajectory limits bound work, not exact dollar spend. Forecast from representative observed work and recorded costs, including every job and allocation across attempts. Zero accepted designs does not establish a cost per accepted design. Read ariax skills --reference campaigns --read for review points and forecast limits.

Recover an Operation#

Submission and restart can start billable work. The CLI journals each spending request with the original request identity, account/origin, input hashes, and frozen prepared inputs. If the response is lost, reconcile that attempt:

ariax operations --json
ariax recover OPERATION_ID --wait

Recovery checks the actor-owned server record and replays the original request only when safe. An in-progress operation can remain recoverable before a project ID exists. Changes to existing source files, prepared bytes, account, or API origin block replay; deleted original files can be recovered from the frozen snapshot. A completed operation means the request completed, not the scientific campaign.

Ordinary upload intents expire after 15 minutes. Seven-day operation retention does not extend upload authorization. An expired unattached input can block recovery before backend execution: reconcile the original operation and project before arranging a new authorized upload or attempt. Follow the returned action; do not change request identity just to bypass an error.

Interrupting --wait leaves remote compute running. Use ariax status PROJECT_ID --wait to resume monitoring. A local timeout is not remote cancellation. Legacy resume-file commands remain available, but operation IDs are the preferred recovery path.

Only paused projects can be restarted. Failed, completed, and aborted projects cannot. recover does not restart failed compute. Scientific changes require a new project. For failures, inspect retained worker logs and contact support when there is no supported correction. Avoid repeatedly relaunching an exhausted pilot or retrying an unresolved provisioning problem.

Interpret Settings and Candidate Evidence#

ariax runs exposes best-effort recorded accepted settings; it does not prove what executed. ariax projects export exports public saved configuration, not the original inputs. Retain custom targets, MSA files, and scaffolds needed to reproduce a campaign; PXDesign regenerates its MSA.

Candidate tables describe current project output, not immutable historical run snapshots. Preserve engine-specific metric and filter meanings. Unknown ranking eligibility is distinct from false; --eligible is generally unsuitable as a BoltzGen or PXDesign shortlist filter. Use the matching bundled outputs guide.

BindCraft2 distinguishes attempted trajectories, saved predictions, refolds, ranked candidates, and accepted designs. Follow status's suggested action to choose final, all, or diagnostics. An attempt-limited campaign can complete with no accepted designs. Missing structures or scores are not evidence of a filter pass or failure.

New BindCraft2 campaigns default to saving terminal design predictions, failed trajectories/refolds, and binder monomers when available; explicit false settings are preserved. Accepted/ranked structures are always saved. Intermediate animations and relaxation are separate options. The candidates API supports view=diagnostics&structures_only=true to select rows with structures before pagination; older outputs may require inspecting CSVs and artifacts directly.

Candidate pages contain at most 50 rows. Sources are bounded to three CSVs, each at most 32 MiB/100,000 rows. Oversized sources return an explicit error with an artifact-download fallback. A cursor_stale response means the source changed: restart pagination. Use project.design_count_source before interpreting generic project counters, and prefer engine-specific evidence when those counters are unavailable.

Download Results and Inspect Logs#

ariax results PROJECT_ID --json
ariax results PROJECT_ID --path output/provenance.json --download ./results --details --json
ariax results PROJECT_ID --path output/Trajectory --download ./results --json
ariax logs JOB_ID --list
ariax logs JOB_ID --log-ref logs/design_workers/WORKER.log --tail 200

Use paths actually returned by discovery; the examples illustrate an exact file and a directory. --path matches an exact artifact or files beneath a directory, not globs or partial prefixes. Paths are preserved beneath the download directory.

Downloads refresh expired URLs and checkpoint completed files. Rerun the same download to verify completed files and resume; an interrupted individual file restarts from its beginning. Existing unrelated files are preserved unless --overwrite is requested. Available expected checksums are verified. Without an expected checksum, checksum_verified is false.

A missing archive manifest (404) does not block individual file downloads. --details reports archive verification as unavailable; malformed/mismatching metadata and integrity failures remain errors. Discovery includes supported scientific intermediates beyond the website's curated views, but excludes credentials and internal orchestration files.

ariax logs reads sanitized, bounded retained project compute logs. It does not expose platform or infrastructure logs. The default is a campaign summary; use --list to discover detailed worker logs and their actual references. A truncated response or worker exit code alone is not a complete diagnosis. Increase --tail up to 5000 when needed; a missing retained log is not a promise that one will appear later.

Feedback and Support#

With user authorization and a Full access key, record a project-related observation:

ariax feedback PROJECT_ID --category technical-support --message "Expected behavior, observed behavior, and actions tried" --job JOB_ID --json

--job is optional and must belong to the project. Categories are technical-support, feature-request, and other; messages are limited to 8 KiB of UTF-8 text. Exclude credentials, signed URLs, unnecessary scientific inputs, and bulk log dumps.

The response includes data.feedback_id. Feedback records a comment; it does not send email, open a support ticket, stop compute, or restart a job. For assistance, email [email protected] with the project ID and feedback ID, plus relevant CLI version, command, public error, and actions tried. An agent should send email only when asked.

Feedback submission is not automatically retried. A timeout leaves recording uncertain; a deliberate resubmission can create a duplicate. You can contact support with the project ID even without a feedback receipt.

REST API and Authentication#

The public contract is versioned under /api/v1. Use the live OpenAPI reference, protocol catalog, and API landing page for complete request/response schemas.

The pricing endpoint is public. Its channel query selects a preview; authenticated launch attribution determines eligibility. Using an API key alone does not qualify a raw API request for CLI pricing. See the pricing announcement for offer terms.

Protected requests use Authorization: Bearer $ARIAX_API_KEY. For noninteractive login, a secret-aware tool can provide a key through stdin with ariax login --with-token. Never pass a secret as a command-line argument.

Direct API clients must supply an Idempotency-Key for creation and restart; pause and abort accept one optionally. The CLI manages these identifiers itself. List endpoints return opaque cursors; pass them back unchanged. Respect Retry-After on temporary errors or rate limits. Public responses expose project-relevant settings, progress, allocation usage, and costs, not internal infrastructure details or credentials.