Agent API & CLI

Ariax is a shared workspace for scientists and AI agents. Prepare, run, and review protein-design campaigns on the website, through the ariax CLI, or with scripts using the public REST API. All three work with the same account and projects.

Bring your agent into a new campaign or an ongoing or completed project. You set the scientific direction and compute scope; the agent can prepare inputs, follow progress, and inspect the evidence with you. Ariax handles GPU provisioning and workflow execution.

Install the latest stable CLI to use the workflow described here. For command details, installation channels, recovery, and REST endpoints, see the CLI & API reference.

Install the CLI#

Both installation channels require Node.js 20 or newer and npm. Choose one:

npm — stable release

npm install --global ariax-cli@latest

GitHub — latest source from main

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

The GitHub channel downloads the CLI source from GitHub and uses npm to install it locally. It may include changes not yet published in a stable npm release. You can review the installer before running it.

Check your installation and its channel:

ariax --version --json
ariax help

To check for updates or upgrade your installation:

ariax upgrade --check
ariax upgrade

The CLI does not update itself automatically. Updates follow your installed channel. The reference explains how to pin a release or revision and switch channels.

Connect Your Account#

Create a key in Settings → API keys. Full access lets an agent upload inputs, create and manage projects, and record project feedback. View access is enough to validate configurations, inspect authorized projects, and download results.

ariax login
ariax me

Paste the key into the hidden terminal prompt. The CLI verifies it and saves it in the operating system's credential store when available. If that store is unavailable, it asks before using a user-only credential file.

Keep keys out of agent conversations, job files, URLs, and command-line arguments. When an agent needs authentication, run ariax login yourself and tell it to continue. For automation, inject ARIAX_API_KEY from a secret manager; it takes precedence over a saved login.

ariax logout removes the local credential. Revoke a key on the API Keys page to invalidate it. If Ariax rejects a rotated or revoked key, replace the saved login or environment secret and rerun the failed command; the CLI does not replay it automatically.

Work with Your Agent#

Codex, Claude Code, Cursor, and other terminal-capable agents can use the CLI. Its shared workflow, protocol guides, and output references are bundled with the package. No separate skill installation or hosted MCP server is required.

Start with a scientific goal or an existing project URL, then give your agent this instruction:

Use the Ariax CLI for this project. Check ariax --version and
ariax upgrade --check --json; tell me if an update is available.
Run ariax skills --read --json and read data.content. Read the matching
protocol guide with ariax skills <protocol> --read --json and its output
guide with ariax skills <protocol> --reference outputs --read --json.
Use the live schema to prepare and validate inputs. Show me the target,
binder format, scientific settings, and compute scope before launching.
Carry forward any authorization I have already given; ask before material
changes outside it. Review progress, candidates, and observed costs before
recommending the next step. If login is needed, ask me to run ariax login
in my terminal. Never ask for an API key in this chat.

The placeholder <protocol> means one of the IDs below. ariax skills --json lists all guides and reference identifiers. --read --json returns Markdown in data.content; --read --no-json prints it directly.

Choose a Workflow#

Choose a workflow based on the scientific goal, binder format, available inputs, design mechanism, and evaluation policy. Preserve an explicitly chosen engine when it fits the experiment; the workflow comparison describes the options.

Ariax's BindCraft / bindcraft-v1.5 workflow runs the FreeBindCraft repository, kept current with upstream BindCraft and extended with an optional PyRosetta bypass. Both scoring paths use this repository.

The CLI alias bindcraft still means v1.5, not BindCraft2. BindCraft2's scFv workflow designs two variable-domain chains; it does not design a connecting linker. Compare scientific methods and licensing on the Workflows page.

ariax protocols
ariax schema bindcraft2 --raw -o bindcraft2-schema.json
ariax skills bindcraft2 --read --no-json
ariax skills --reference campaigns --read --no-json

The live schema defines supported fields and defaults. Normal JSON schema output contains the schema at data.json_schema; --raw writes the standalone schema.

Prepare a BindCraft2 Campaign#

Start from the bundled bindcraft2-pilot.json example, found under the examples directory reported by ariax skills --json, and edit it for your target and scientific goal. Examples illustrate syntax; they are not ready-to-run biological experiments.

Put all configured target and custom scaffold files in one directory. The first target must be a structure named input.pdb or input.cif; secondary targets may use supported PDB, mmCIF, or FASTA inputs. Filenames in the job must match the exact bundle basenames.

ariax inputs inspect --input-dir ./bc2-inputs -f bc2-job.json --json
ariax inputs prepare --input-dir ./bc2-inputs -f bc2-job.json --output ./bc2-prepared --json
ariax validate -f ./bc2-prepared/job.json --input-dir ./bc2-prepared --json

Inspection and preparation need no account. They check supported structure information, selected chains, residue selectors, and file roles. Preparation writes the normalized job.json, required files, and an input manifest recording hashes and provenance. Keep that bundle together. Use --full for complete sequences and residue maps, or --details for additional preparation diagnostics.

--input-dir is specific to BindCraft2 and cannot be combined with --input. For a BindCraft2 configuration requiring only one input.pdb or input.cif, --input is also supported. For other structure-based workflows, use the appropriate single-file input and read the matching protocol guide. BoltzGen validation and submission require --input for local structure checks.

Local preparation checks the supplied structure; API validation checks the configuration. Neither establishes remote execution success or experimental binding. Resolve validation errors before proceeding.

Review and Launch#

Review the target construct and site, binder format, accepted-design goal, attempt limit, GPU policy, and expected review point. The bundled campaign guide suggests a BindCraft2 pilot of 2 accepted designs with up to 20 trajectories when a bounded pilot is appropriate; retain explicit user choices and smaller tests.

ariax pricing --json

Use each row's hourly_rate as the current effective price for the complete allocation specified by gpu_id and gpu_count. standard_hourly_rate provides the comparison rate. Turbo totals already include every GPU in the allocation. Fetch a fresh preview before launching or restarting; if pricing is unavailable, retry before estimating the cost.

The GPU allocation request locks the rate. Queued jobs, replacements, and explicit restarts use the policy in effect at their own allocation. You can review a running CLI project on the website while retaining its saved rate. The pricing update covers permanent Turbo fee removal and the October 2026 CLI/Agent offer, including eligibility and the offer window. Use the current CLI so requests carry the required launch attribution.

Select compatible GPUs within the authorized memory and hourly-price limits, including at least one protocol-compatible core GPU. Choosing several compatible alternatives can improve availability. Turbo allows multiple GPUs when authorized; it increases concurrent spend and does not combine their memory for a single design.

A trajectory cap bounds attempts, not exact dollar spend. Use observed runtime, costs, and useful candidate yield to evaluate further work. Do not promise a fixed campaign cost from design counts alone.

The following command starts billable compute. Run it after the campaign is authorized:

ariax submit -f ./bc2-prepared/job.json --input-dir ./bc2-prepared --name bc2-pilot --wait --json

Record the returned project and operation IDs. Interrupting --wait stops local monitoring; the remote project continues. Resume monitoring with ariax status PROJECT_ID --wait. If the submission outcome is uncertain, reconcile the original operation using the recovery guide before making another submission.

Collaborate on an Existing Project#

Give your agent the website project URL or its ID. The agent can extract the UUID from the URL; CLI project operands accept a UUID or exact unique project name, rather than the full URL. A link alone does not grant access: the connected account and key must be authorized.

ariax status PROJECT_ID --json
ariax runs PROJECT_ID --json
ariax candidates PROJECT_ID --view final --json
ariax results PROJECT_ID --download ./ariax-results --json

For BindCraft2, follow the action suggested by status to choose the relevant candidate view. Accepted designs appear in final; refolds and earlier trajectories provide different evidence. A completed pilot with zero accepted designs can be a scientific outcome rather than an execution failure.

Review structures on the website while your agent analyzes downloaded tables and files. Compare candidates within their engine's scientific context; scores from different engines are not a common quality scale. Ask the agent to distinguish computational filter passes, plausible poses, and evidence that still needs experimental testing.

ariax projects export PROJECT_ID --output job.json exports saved public settings. It does not download the original inputs or create a new project. Scientific changes require preparing and submitting a new campaign within your authorization; restarting a paused project preserves its configuration.

Keep the Work Moving#

• Read the CLI & API reference for downloads, retained logs, recovery, feedback, and automation.
• Use the BindCraft2 setup guide for scientific controls and output interpretation.
• Compare all five engines on Workflows.
• Read bundled campaign and interpretation guidance with ariax skills --reference campaigns --read and ariax skills --reference interpretation --read.