CLI basics

Cross-cutting CLI setup and day-to-day commands: install, login, aquin status, model loading, local command tracking, the aquin chat agent, session memory, and shared flags. GPU tools run against the model loaded with aquin load model, one model in VRAM at a time. Outputs are tracked under ~/.aquin/commands/. Account signup/login lives on aquin.app; compute and result cards live on your machine (CLI + desktop app).

Prerequisiteaquin login · aquin load model <model-id> · aquin status

21 commands

pip install aquin

Install the CLI from PyPI. Requires Python 3.10+ and a GPU accelerator (CUDA/ROCm or Apple Metal MPS) for model tools.

example

aquin login

Save your CLI token (aq-…) from aquin.app to ~/.aquin/config.json. After login/waitlist, generate or reveal the token on the access page, or under profile. Required for multi-account features and tools that need your account.

Flag	Description
--force	Replace the saved token even if one exists.

example

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.

example

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.

example

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.

example

aquin version

Print installed CLI version.

example

aquin update

Upgrade aquin to the latest PyPI release.

example

aquin help

Print command list filtered by current mode (LLM vs embedding). Shows only tools available for the loaded model.

example

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-id>*	Catalog slug or HuggingFace repo id.

example

Legacy shorthand: aquin load <model-id>.

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.

example

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.

example

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.

example

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

example

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.

example

aquin commands show

Print full JSON for one tracked record by id (prefix match allowed).

example

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

example

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.

example

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: discuss results on aquin.app and attach research materials as needed.

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 replay simulation or compare simulation.

example

Legacy alias: aquin list-runs. Full workflow: simulate → list simulation → replay simulation → compare simulation. Details: /docs/simulation/llm or /docs/simulation/embedding.

aquin replay simulation

agent tool: load_simulation_run

Reopen one saved simulation by run ID locally and emit a tracked result card. Run ID comes from aquin list simulation.

Flag	Description
--run_id*	Run ID from list simulation.

example

Legacy: aquin load simulation / 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.

example

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 (trace, steer, simulate, check layer, etc.) without agent orchestration. Same GPU path as chat. Each run is tracked locally. Add --check to save JSON + PNG artifacts for scripting; use --save for a custom JSON export path where supported.

Flag	Description
--check	Save JSON + PNG check artifacts in cwd.

example

Mode-filtered: aquin help shows verbs available for your loaded model. Legacy aliases still work: list-runs/load-run/compare-runs → list/replay/compare simulation; embed-* verbs in embedding mode (e.g. embed-retrieval → retrieval); benchmarks → benchmark. Removed: aquin mem, aquin run-code, aquin save-artifact, aquin pairs-generate, 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 dataset-generate (use simulate --topic or --dataset).

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

Shared flags

Available on GPU tool commands across inspection, simulation, and evals. The old --output json flag was removed; use --check for machine-readable JSON + PNG artifacts in the current directory.

--check	Save JSON + PNG check artifacts in the current directory (where supported).
--save <path>	Write a custom JSON export to the given path (where supported).
--dir <path>	Output directory for aquin activations capture.

Local command tracking

Every GPU tool you run writes a local record under ~/.aquin/commands/. List recent runs with aquin commands list, inspect full JSON with aquin commands show <id>, and clear old records when needed.

track a local run

Desktop app

Result cards and agent UI run in the Aquin desktop app on your machine. There is no web product surface at /app. Use aquin.app for waitlist/login and your CLI token; use the CLI for compute.