> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quadrillion.io/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Run the Qualia agent from your terminal — sign in and launch in one command.

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

<Tabs>
  <Tab title="macOS / Linux">
    ```bash theme={null}
    curl -fsSL https://quadrillion.io/install.sh | sh
    ```

    Installs `qualia` to `~/.local/bin`. If that directory isn't on your
    `PATH`, the script prints the line to add.
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    irm https://quadrillion.io/install.ps1 | iex
    ```

    Installs `qualia.exe` to `%LOCALAPPDATA%\Programs\qualia` and adds it to your
    user `PATH`. Restart your terminal afterward.
  </Tab>

  <Tab title="Homebrew">
    ```bash theme={null}
    brew install quadrillion-labs/tap/qualia
    ```
  </Tab>

  <Tab title="Direct download">
    Grab the archive for your platform and extract it:

    * macOS Apple Silicon: [`qualia-aarch64-apple-darwin.tar.gz`](https://quadrillion.io/download/qualia-aarch64-apple-darwin.tar.gz)
    * macOS Intel: [`qualia-x86_64-apple-darwin.tar.gz`](https://quadrillion.io/download/qualia-x86_64-apple-darwin.tar.gz)
    * Linux x86\_64: [`qualia-x86_64-unknown-linux-gnu.tar.gz`](https://quadrillion.io/download/qualia-x86_64-unknown-linux-gnu.tar.gz)
    * Windows x86\_64: [`qualia-x86_64-pc-windows-msvc.zip`](https://quadrillion.io/download/qualia-x86_64-pc-windows-msvc.zip)

    On macOS and Linux, move `qualia` somewhere on your `PATH`. On Windows,
    keep the extracted directory together and add that directory to `PATH`;
    `qualia.exe` needs the bundled DLLs and data beside it.
  </Tab>
</Tabs>

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.

<Tabs>
  <Tab title="Browser SSO">
    ```bash theme={null}
    qualia login
    ```

    Opens a browser on the same machine, signs you in, and stores a Quadrillion
    API key.
  </Tab>

  <Tab title="Headless / SSH">
    ```bash theme={null}
    qualia login --no-browser
    ```

    A box with no browser of its own cannot complete the normal sign-in: the
    page would deliver the key to `127.0.0.1` on whatever machine opened it.
    This prints a URL to open in a browser anywhere, shows the key it mints,
    and prompts you to paste it back. Qualia picks this flow automatically when
    it detects no browser, so plain `qualia login` also works over SSH.
  </Tab>

  <Tab title="Paste a key">
    ```bash theme={null}
    qualia login --key
    ```

    Prompts for an API key you already have, minting nothing — useful for CI,
    where the key comes from a secret store.
  </Tab>
</Tabs>

To drive a Quadrillion **cloud** workspace instead, sign in to the cloud
domain — via the browser, or with a session token for headless use:

```bash theme={null}
qualia login --cloud <env>.quadrillion.cloud
# headless:
qualia login --cloud <env>.quadrillion.cloud --session-token <token>
# or set QUALIA_CLOUD and QUALIA_SESSION_TOKEN in the environment
```

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:

```bash theme={null}
# Start a research turn
qualia -p "explore the dataset in sheet1.csv"

# Pick a model and independence level
qualia -p "fix the failing test" --model gpt-5.5:medium --independence high

# Continue an existing session
qualia -p "now add a chart" --resume session-<uuid>
```

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:

```bash theme={null}
qualia -p "explore the dataset" --cloud --workspace-id workspace-<uuid>
qualia --workspace-id workspace-<uuid> --tunnel session-<uuid>
qualia --workspace-id workspace-<uuid> ls
```

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

```bash theme={null}
qualia -p "train the model" \
  --post-run "python verify.py" \
  --post-run-output verdict.json \
  --post-run-timeout 1800
```

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:

```bash theme={null}
qualia -p "train the model" --cloud <env>.quadrillion.cloud \
  --artifacts out/model.pkl:./pulled logs:./logs \
  --chat-log ./transcript
```

`--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:

```bash theme={null}
qualia -p "explore the dataset" --provider kaggle --model google/gemini-3.5-flash
```

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:

```bash theme={null}
export OPENAI_COMPATIBLE_URL=https://proxy.example/openapi
export OPENAI_COMPATIBLE_API_KEY=proxy-key
export OPENAI_COMPATIBLE_ENABLED=true
export OPENAI_COMPATIBLE_MODELS=vendor/model-a,vendor/model-b

qualia -p "explore the dataset" --model vendor/model-a
```

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

```bash theme={null}
qualia ls        # list your cloud projects and sessions
qualia logout    # clear stored credentials
```

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