Skip to main content
The Qualia CLI runs the agent straight from your terminal. It installs as a single binary — no Python required — and by default runs the agent locally on your machine, using Quadrillion’s hosted models after a quick sign-in. It can also drive a Quadrillion cloud workspace with --cloud.

​
Install

Installs qualia to ~/.local/bin. If that directory isn’t on your PATH, the script prints the line to add.
The Linux binary requires glibc 2.28 or newer (Debian 10+, Ubuntu 20.04+, RHEL 8+, or equivalent). Linux ARM64 and musl-based distributions are not currently supported.

​
Sign in

For local runs, sign in once to mint a Quadrillion API key. The key unlocks the hosted models, so you never handle raw provider keys.
Opens a browser on the same machine, signs you in, and stores a Quadrillion API key.
To drive a Quadrillion cloud workspace instead, sign in to the cloud domain — via the browser, or with a session token for headless use:
Without --session-token, a headless cloud login prints the sign-in URL and prompts for the session_token cookie from the browser you used, instead of waiting on a callback that cannot arrive.

​
Run

By default the agent runs locally, in your current directory:
On the first local run, Qualia detects an existing Python/Jupyter kernel or offers to install a managed one. The standalone CLI does not require a preinstalled Python runtime. Add --cloud <env>.quadrillion.cloud (or set QUALIA_CLOUD) to run the same commands against your initial Quadrillion cloud workspace. Pass --workspace-id workspace-<uuid> to run, resume, list, or tunnel within another workspace:

​
Verify a run in its own environment

--post-run runs a command after the turn finishes, in the same environment the turn ran in and with the working directory set to the workspace root. In cloud mode that is the box that produced the artifacts, so verification reads a checkpoint in place instead of dragging it across the network — only the verdict comes back.
The command should print its verdict as a single JSON object on stdout; other output is ignored, so it can log progress freely. It also receives QUALIA_WORKSPACE, QUALIA_SESSION_ID, and QUALIA_PROJECT_ID. Qualia distinguishes a verdict from a broken verifier. A command that exits 0 with {"ok": false} is an authoritative negative result. A command that exits non-zero, times out, or prints nothing parseable produces a null verdict with a failure reason instead — score the first, and mask the second rather than treating it as a zero.

​
Copy artifacts and transcripts back

In cloud mode, --artifacts REMOTE:LOCAL copies workspace paths back to this machine after the turn, before compute is torn down. Files and directories both work, and the flag is repeatable:
--chat-log DIR materializes the session transcript into DIR as a raw SQLite chat store — chatlog.sqlite3 plus per-session sessions/<id>/actions.sqlite3, with original IDs preserved — so any SQLite tooling can read it. The raw row export is written alongside as export.qualia.json. Exports never fail the turn or strand compute, but they do change the exit code: if any requested path could not be pulled, qualia exits 74 (EX_IOERR) instead of 0. That is deliberately distinct from 1 — 1 means the turn itself failed and is worth rerunning, while 74 means the turn was fine and only its export is incomplete. A pipeline that scores these files should treat 74 as “do not score,” since a partial export is indistinguishable from a complete one once the files are on disk.

​
Pin the compute a cloud run uses

Three flags shape the kernels a cloud run starts. --compute-provider {modal,gcp,aws,sail} pins every kernel to one provider — the run refuses loudly, before the turn starts, if that provider is not enabled on the target cloud. --gpu TYPE[xCOUNT] (e.g. --gpu h100x8, --gpu a10g) requests GPU hardware, and --cpu N requests a core count. Which GPU types and counts a deployment can serve is provider-specific; unavailable demands fail at configure time or at kernel start, never silently downgrade. The provider/GPU demand is recorded immutably and verified after the run against the hardware the kernel actually reported. A run that contradicts the demand exits 1 — wrong compute invalidates the run outright, so it outranks the export-incomplete exit 74. A run that merely could not be observed well enough to prove the demand exits 69, the same code a lost event stream reports: its outcome is unknown, not wrong. Agent tools that adjust compute_traits mid-run inherit the pinned demand and error if they contradict it.

​
Use a custom model endpoint

For a local run, you can route Qualia to an OpenAI-compatible endpoint. This capability must be enabled for your account. Known endpoints are selected by name with --provider, which reads the endpoint’s own environment variables and applies the right settings — no manual exports needed. For the Kaggle model proxy:
Selecting the Kaggle provider obtains proxy credentials automatically by running kaggle benchmarks auth, and refreshes them mid-run when they expire (about every 30 minutes) — just keep the kaggle CLI installed and logged in. For other OpenAI-compatible endpoints, configure the connection explicitly:
The API key is optional for keyless servers. List the endpoint’s exact model IDs in OPENAI_COMPATIBLE_MODELS when it does not provide a /models API. Otherwise, Qualia discovers its models automatically. Either way the list only seeds the model picker — --model and model settings like DEFAULT_MODEL accept any ID, with a warning for ones Qualia does not recognize. If the endpoint requires Gemini-compatible function schemas, set OPENAI_COMPATIBLE_TOOL_SCHEMA=gemini; it defaults to openai. These variables also override individual values from an active --provider profile.

​
Manage sessions

For local runs, Ctrl+C interrupts generation and shuts down local kernels. For cloud runs, it stops the server-side turn and tears down associated compute unless you pass --keep-alive.