Getting started with Aquin CLI

Aquin is a CLI for mechanistic interpretability and model analysis on your own GPU. You install aquin on a CUDA machine, load a model, and run inspections, simulations, evals, or watch external training runs from the terminal. Each tracked result can appear in your web CLI inbox on aquin.app, where you attach outputs to the analyst chat and inspect interactive cards.

The CLI is not a hosted GPU service. Your machine runs forward passes locally. After each command, Aquin stores a local record under ~/.aquin/commands/ and, when logged in, auto-uploads it to your inbox (disable with AQUIN_AUTO_SEND=0). Use aquin chat for a multi-turn agent, or invoke any tool directly as a one-shot command.

Tool mode switches automatically when you load a model. Load an LLM (GPT-2, Pythia, Llama, Qwen) and you get inspection, eval, and simulation commands. Load an embedding encoder (GTE, MiniLM, BGE) and you get the embed analysis suite. Beyond catalog slugs, pass a HuggingFace repo id for supported families. See Supported models. No manual mode toggle; aquin help always shows what is available for your loaded model. Use aquin status anytime to see your account, CLI token, and loaded model (device, mode). Generate your CLI token under Profile → Account.

Feature-level tools need a sparse autoencoder pulled locally first (aquin load sae gpt2-small-l8). The sidebar groups every command by category (inspection, SAE inspection, simulation, SAE training, training watch, evals), split by LLM and embedding where applicable. Cross-cutting setup lives under CLI & web dashboard.

Web workflow

On aquin.app, create a session tab from the sidebar (New session). This is your analyst workspace, not a live CLI sync target. Run commands locally, then open the sidebar CLI inbox. Click one or more items to attach them to the chat. The right panel shows interactive cards (circuit graphs, attribution tables, and similar) for the attached output. Remove attachments with × on the chips in the chat input, or attach more items from the inbox.

Profile → Account is for identity and your CLI token. Generate or regenerate once, then paste it with aquin login. Each account has one active token; regenerating revokes the previous one. Teammates on a shared GPU use their own tokens and aquin switch.

First run

quick start

Command history & inbox

Every GPU tool writes a local record. List recent runs with aquin commands list, inspect full JSON with aquin commands show <id>, and manually upload with aquin commands send <id> if auto-upload is off.

tracked commands

Simulation run management

After aquin simulate, runs are saved locally. Use aquin list simulation to list IDs,aquin replay simulation --run_id … to reopen one, and aquin compare simulation --run_id_a … --run_id_b … to diff two forecasts. Legacy aliases list-runs, load-run, and compare-runs still work.

simulation runs

Shared CLI flags

GPU tools print formatted tables in the terminal by default. Add --check to also write JSON + PNG artifacts in the current directory (for scripting or CI). Use --save <path> when a command supports a custom JSON export, or --dir <path> for capture-activations. The legacy --output flag is no longer accepted.

trace with check artifacts