CLI & web dashboard
The terminal and the web dashboard are two halves of one workflow. This page covers both: the cross-cutting CLI commands (install, login, aquin status, model loading, local command tracking, CLI inbox upload, the aquin chat agent, session memory, and code execution) and the aquin.app dashboard where you attach tracked outputs, inspect interactive cards, and plan research with the analyst chat. GPU tools run against the model loaded with aquin load --model, one model in VRAM at a time. Tracked outputs auto-upload to your web inbox when logged in.
25 commands
pip install aquin
Install the CLI from PyPI. Requires Python 3.10+ and a CUDA-capable GPU for model tools.
aquin login
Save your CLI token (aq-…) from aquin.app to ~/.aquin/config.json. Generate under Profile → Account → CLI token; copy again anytime with your account password, or regenerate to rotate. Required before inbox upload and multi-account features.
| Flag | Description |
|---|---|
| --force | Replace the saved token even if one exists. |
aquin status
Show logged-in account, saved CLI token, and engine state: loaded model, tool mode (LLM vs embedding), device, GPU, and location. Replaces the old aquin whoami, aquin api-key, and aquin session status commands. Use --api-key to print the token only for scripts.
| Flag | Description |
|---|---|
| --api-key | Print CLI token only (e.g. curl: Bearer $(aquin status --api-key)). |
| -k | Short form of --api-key. |
When no model is loaded: Model: (none). Run: aquin load --model <id>
aquin switch
Switch between Aquin accounts saved on this machine (each account has its own CLI token). Use aquin switch --add to paste a second token. On shared GPUs, teammates each log in with their own token and switch locally.
| Flag | Description |
|---|---|
| [account-email] | Switch to a saved account by email or id. |
| --add | Paste a CLI token for another account and switch to it. |
aquin logout
Remove saved CLI token(s) from this machine. Does not revoke the token on the server.
| Flag | Description |
|---|---|
| [account-email] | Log out one saved account; omit to clear the active account. |
aquin version
Print installed CLI version.
aquin update
Upgrade aquin to the latest PyPI release.
aquin help
Print command list filtered by current mode (LLM vs embedding). Shows only tools available for the loaded model.
aquin load --model
Load one model onto the GPU for all subsequent GPU tools. Catalog slugs (gpt2-small, gte-small, llama-3.2-1b) and supported HuggingFace repo ids work. Mode (LLM vs embedding) is inferred from the model. Run again to switch models. Gated Hugging Face models (e.g. Llama) use the HF token from the Aquin server after aquin login; no huggingface-cli login required.
| Flag | Description |
|---|---|
| --model* | Catalog slug or HuggingFace repo id. |
Shorthand: aquin load <model-id> without --model.
aquin load sae
Download or activate a sparse autoencoder for feature-level tools. Catalog: aquin load sae <model-l{n}> pulls public weights. User-trained: aquin load sae --user <name> [--layer N] after aquin sae train, or --path <file.pt>. Binding is stored in ~/.aquin/active_user_sae.json.
| Flag | Description |
|---|---|
| <model-l{n}> | Catalog SAE slug from aquin list sae. |
| --user | Activate a user-trained SAE by run name (loaded model must match). |
| --path | Activate from an explicit .pt path. |
| --layer | SAE layer (required if run has multiple layers). |
| --model | Model slug when using --path without .meta.json. |
aquin list model
List catalog models (with public SAEs where available) and supported model families. Pass any family example HuggingFace repo id to aquin load --model. Use --families for full notes.
| Flag | Description |
|---|---|
| --families | Print extended family help and SAE notes. |
https://aquin.app/docs/models
aquin list sae
List public SAE checkpoints (catalog). Add --user to list locally trained SAEs under ~/.aquin/sae/user/.
| Flag | Description |
|---|---|
| --user | List user-trained SAEs (from aquin sae train). |
| --model | Filter by model slug. |
aquin info sae
Show metadata for one SAE: layer, dictionary size, architecture, interpretability score.
| Flag | Description |
|---|---|
| <model-l{n}>* | SAE slug from aquin list sae (model id + layer). |
aquin commands list
List locally tracked CLI runs under ~/.aquin/commands/. Every GPU tool and one-shot command writes a record with id, timestamp, category, command, summary, args, result, and optional card payload.
| Flag | Description |
|---|---|
| --last | Show only the last N records. |
| --since | Filter by age (e.g. 2h, 7d). |
| --category | Filter by category (inspection, simulation, sae, …). |
| --model | Filter by model id. |
| --command | Filter by command verb. |
aquin commands show
Print full JSON for one tracked record by id (prefix match allowed).
aquin commands send
Upload one or more tracked records to your web CLI inbox on aquin.app. Auto-upload runs after each tracked command by default (AQUIN_AUTO_SEND=0 to disable). Requires aquin login.
On the web: sidebar CLI inbox → click items to attach to the analyst chat. Multiple sendables per session tab are supported.
aquin commands clear
Delete local tracked records. Use --before to keep recent history.
| Flag | Description |
|---|---|
| --before | Clear records older than duration (e.g. 7d, 30d). |
aquin chat
Multi-turn terminal agent. Requires aquin login and a loaded model (aquin load --model). Cloud orchestrator picks tools from the engine registry; GPU executes locally. Tool results are tracked locally and auto-upload to your CLI inbox when logged in.
Optional: aquin load sae <model>-l<n> before inspection tools. Example prompts: Run full inspection on "…" · find deception features · simulate training on topic flowers. Web analyst chat is separate: attach inbox outputs on aquin.app to discuss results.
aquin list simulation
agent tool: list_simulation_runs
List saved simulation runs on local disk (~/.aquin/runs/). Works in both LLM and embedding mode; run IDs come from aquin simulate. Use before load simulation or compare simulation.
| Flag | Description |
|---|---|
| --output json | Raw JSON stdout. |
Legacy alias: aquin list-runs. Full workflow: simulate → list simulation → load simulation → compare simulation. Details: /docs/simulation/llm or /docs/simulation/embedding.
aquin load simulation
agent tool: load_simulation_run
Reload one saved simulation by run ID locally and emit a tracked result card. Run ID comes from aquin list simulation. Uploads to CLI inbox when logged in.
| Flag | Description |
|---|---|
| --run_id* | Run ID from list simulation. |
| --output json | Raw JSON stdout. |
Legacy alias: aquin load-run.
aquin compare simulation
agent tool: compare_simulations
Side-by-side diff of two saved simulation runs. LLM: predicted loss delta, SAE feature shifts, LiSSA influence changes, attack-surface metrics (consistency, suppression, robustness). Embedding: loss trajectory, geometry metrics, triplet margin satisfaction. Both runs must be the same kind (LLM vs LLM or embed vs embed).
| Flag | Description |
|---|---|
| --run_id_a* | First run (before / baseline). |
| --run_id_b* | Second run (after / variant). |
| --label_a / --label_b | Display labels in the comparison table. |
| --output json | Raw JSON stdout. |
Legacy alias: aquin compare-runs. Typical use: compare two simulate configs (dataset cleanup, LR tweak, rank change). See /docs/simulation/llm or /docs/simulation/embedding.
aquin <tool-verb>
One-shot basic CLI: any tool verb from the registry (inspect, steer, simulate, layer-drift, etc.) without agent orchestration. Same GPU path as chat. Each run is tracked locally and auto-uploads to your CLI inbox when logged in. Use --output json for scripting.
| Flag | Description |
|---|---|
| --output json | Raw JSON stdout. |
Mode-filtered: aquin help shows verbs available for your loaded model. Legacy aliases still work: mem-write/mem-read → aquin mem; list-runs/load-run/compare-runs → list/load/compare simulation; embed-* verbs in embedding mode (e.g. embed-retrieval → retrieval); benchmarks → benchmark. Removed: aquin connect, aquin engine start, aquin session (use aquin load --model), aquin whoami/api-key/session status (use status), aquin pull sae (use load sae).
aquin run-code
agent tool: write_and_run_code
Execute Python on the engine GPU context for custom scoring, activation analysis, or bespoke probes. Prefer aquin chat for iterative scripts; use this for one-shot automation. Same tool the agent calls as write_and_run_code.
| Flag | Description |
|---|---|
| --code* | Python source to execute. |
| --kernel_mode | server (default) or browser. |
| --label | Optional label for the run card. |
| --output json | Raw JSON stdout. |
aquin save-artifact
agent tool: save_code_artifact
Save a named Python script as a local code artifact for the agent loop. Typically used after run-code produces a working scorer or experiment script.
| Flag | Description |
|---|---|
| --name* | Artifact name. |
| --description* | Short description. |
| --code* | Python source to persist. |
| --attach_as | eval_scorer, experiment_metric, or standalone. |
| --output json | Raw JSON stdout. |
aquin mem
Read or write local session memory keys visible to aquin chat and the web analyst panel when attached.
| Flag | Description |
|---|---|
| --write | Write mode (requires --key and --value). |
| --read | Read mode (requires --key). |
| --key* | Memory key. |
| --value | Value to store (--write only). |
Legacy mem-write and mem-read redirect to aquin mem --write / --read.
Configuration
Local paths and environment variables the CLI reads between runs.
| ~/.aquin/config.json | Saved CLI tokens (multi-account via aquin switch). |
| ~/.aquin/engine.json | base_url, active_model_id, device, gpu_info after aquin load --model. |
| ~/.aquin/active_model.txt | Model currently loaded in VRAM; determines LLM vs embedding tool mode. |
| ~/.aquin/commands/ | Tracked CLI outputs (index.json + per-run JSON). |
| ~/.aquin/runs/<id>/ | Saved simulation runs on local disk. |
| ~/.aquin/watch/<run_id>/ | Training watch manifest + events.jsonl. |
| ~/.aquin/sae/user/<model>/<name>/ | Temp SAE weights from aquin sae train. |
| AQUIN_API_KEY | Environment override for CLI token. |
| AQUIN_BASE_URL | API base URL override (default https://api.aquin.app). |
| AQUIN_AUTO_SEND | Set to 0, false, or off to disable auto-upload to web CLI inbox after tracked commands. |
Shared flags
Available on every GPU tool command across inspection, simulation, and evals.
| --output json | Print raw JSON instead of formatted terminal output. |
| --check | Save check JSON + PNG artifacts in the current directory (where supported). |
The web dashboard
The dashboard at aquin.app/app is your analyst workspace. It is where the outputs you produce on your GPU with the CLI turn into something you can read, interrogate, and plan around. You do not run forward passes here. You attach tracked command outputs, inspect interactive cards, and talk to an analyst that knows the CLI end to end. Everything is organized into session tabs, each with its own analyst chat and set of attached results.
CLI and dashboard, side by side
The two halves have distinct jobs. The CLI does everything that needs your GPU; the dashboard is where the results become readable and actionable.
| Concern | CLI (your machine) | Dashboard (aquin.app) |
|---|---|---|
| Compute | Runs forward passes, training, and analysis on your GPU | None; reads results only |
| Outputs | Writes local records and auto-uploads them | Lists them in the CLI inbox |
| Reasoning | One-shot tools or the aquin chat agent | Analyst chat that plans and interprets |
| Artifacts | JSON and PNG on disk | Interactive cards and attached research files |
Sessions and tabs
A session is a single analyst workspace. Create one with a single click on New session in the sidebar. A new tab opens immediately, titled New chat, ready for you to start typing or attach results. There is no naming step to get in the way.
Titles are editable. Hover a tab and click the pencil to rename it whenever you like. If you never rename it, the first message you send is used to generate a short, descriptive title automatically, so tabs stay readable without any effort. Renaming yourself always takes priority over the automatic title.
Delete a session from the same hover controls. Deletion removes the tab and its chat from your workspace. It does not touch the local command records under ~/.aquin/commands/ on your machine.
The CLI inbox
Every GPU tool you run writes a local record and, when you are logged in, auto-uploads it to your inbox. The inbox lives at the bottom of the sidebar and lists your recent command outputs across every tool: inspections, simulations, evals, checkpoint diffs, and more. If auto-upload is disabled with AQUIN_AUTO_SEND=0, push a specific run manually with aquin commands send <id>.
Click any inbox item to attach it to the current session. You can attach more than one output to a single chat, which is how you get the analyst to reason across, say, an inspection and a simulation together. Attached items show as a counter in the chat input; click the counter to open a popover listing everything attached, and detach anything you no longer need.
Interactive cards
When you attach an output, the right panel renders it as an interactive card rather than raw JSON. Depending on the tool that produced it you get circuit graphs, attribution tables, feature lists, logit-lens views, UMAP explorers, training charts, and similar. These are the same numbers the analyst sees, so you can read the visual and ask about it in the same place.
The analyst chat
The chat is the core of the dashboard. It is a mechanistic-interpretability collaborator that knows the Aquin CLI in depth: which command produces which result, what the flags do, which models are supported, and how the pieces fit into a research workflow. Ask it to plan an investigation and it will propose concrete commands to run locally; attach the results and it will interpret them and suggest the next step.
As a conversation develops, the chat maintains a short objective line beneath the input that reflects what you are currently working toward. It updates on its own as the direction of the chat shifts, so you always have a one-line summary of the thread without writing it yourself.
Attaching research materials
Beyond CLI outputs, use the + button on the left of the chat input to attach your own files. Text documents and PDFs are read and their contents made available to the analyst, so you can bring a paper, a hypothesis, or a set of notes into the conversation and have the analyst design experiments around them. Images can be attached for visual context as well. This is what lets you take an outside idea and turn it into a concrete plan of CLI commands.