Agentic & Basic CLI

Cross-cutting commands: installation, authentication, aquin status (logged-in account, CLI token, and active session/engine state), model loading, the aquin chat agent loop, one-shot basic CLI invocation, session memory, Python code execution on the engine, and legacy packaging. These apply regardless of LLM vs embedding mode unless noted. All GPU and sync commands run against the active session — switch sessions with aquin session switch, not per-command flags. Each session locks to one model at start (use aquin session start --model, not per-command --model). On the web, Profile → Account holds your CLI token (generate/regenerate); Profile → CLI shows connected engines and 14-day usage charts.

Prerequisiteaquin login · aquin session start --id <id> --model <model-id> · aquin status · aquin list session

26 commands

pip install aquin

Install the CLI from PyPI. Requires Python 3.10+ and a CUDA-capable GPU for model tools.

example

aquin login

Save your CLI token (aq-…) from aquin.app to ~/.aquin/config.json. Generate or regenerate the token under Profile → Account → CLI token (one active token per account). Required before any other command. If already logged in, prints your account and exits — use aquin switch for another account or aquin login --force to replace.

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

example

aquin status

Show logged-in account, saved CLI token, and engine/session state: device, session name, locked model, tool mode (LLM vs embedding), 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 not connected: Session: Not connected. Run: aquin session start --id <session> --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 session start

Register this machine as an engine, create or resume a session by id (web tab title = that id), and load one model onto the GPU (locked for the life of the session). Device label, GPU, and location are detected automatically. Resuming an existing session reloads its locked model — omit --model in that case. All GPU commands sync to the active session.

Flag	Description
--id*	Session id for web sync (browser tab title). Reuses existing session if id already exists.
--model*	Model to load and lock: gpt2-small, pythia-70m, llama-3.2-1b, gte-small, all-minilm-l6, bge-small-en, etc. Required for new sessions.

example

aquin session switch

Switch active session by id and reload its locked model into VRAM. All subsequent commands sync to that session.

example

aquin session delete

Delete a session by id from the cloud and local CLI registry. Clears active session if it was deleted. Web sidebar delete uses the same path.

example

aquin session leave

Mark engine offline and clear local session state. Stops pushing sync events.

example

aquin load

Load assets for the active session. Models are loaded at aquin session start --model (one per session); the legacy aquin load --model still works but prints a note to prefer session start. Use aquin load sae to download public SAE weights before feature-level inspection. 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
sae <model-l{n}>*	SAE slug from aquin list sae (e.g. gpt2-small-l8).

example

aquin list model

List catalog models (with public SAEs where available) and supported model families. Pass any family example HuggingFace repo id to session start --model. Use --families for full notes.

Flag	Description
--families	Print extended family help and SAE notes.

example

https://aquin.app/docs/models

aquin list session

List sessions (local registry + cloud). Drops local entries deleted on web. Active session marked with *.

example

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 load sae

Load an SAE 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 (session 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 chat

Multi-turn terminal agent. Cloud orchestrator picks tools from the registry; GPU executes locally. Every message and tool result syncs to the web orchestrator panel. Preferred workflow for exploratory work: describe what you want in natural language.

example

Example prompts: Run full inspection on "…" · Simulate training on topic flowers · Run embed layer drift on "…"

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 from aquin simulate. Use before load simulation or compare simulation.

Flag	Description
--output json	Raw JSON stdout.

example

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 and push the full result card to the web orchestrator. Run ID comes from aquin list simulation.

Flag	Description
--run_id*	Run ID from list simulation.
--output json	Raw JSON stdout.

example

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.

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 (inspect, steer, simulate, layer-drift, etc.) without agent orchestration. Same GPU path and web sync as chat. Use --output json for scripting.

Flag	Description
--output json	Raw JSON stdout.

example

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; aquin engine start → session start. Removed: aquin connect (use session start), 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.

example

aquin save-artifact

agent tool: save_code_artifact

Save a named Python script as a session code artifact (visible on the web orchestrator). 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.

example

aquin mem

Read or write session memory keys visible to aquin chat and the web analyst panel.

Flag	Description
--write	Write mode (requires --key and --value).
--read	Read mode (requires --key).
--key*	Memory key.
--value	Value to store (--write only).

example

Legacy mem-write and mem-read redirect to aquin mem --write / --read.

Configuration

Local paths and environment variables the CLI reads between sessions.

~/.aquin/config.json	Saved CLI tokens (multi-account via aquin switch).
~/.aquin/sessions.json	Local session name registry (pruned on aquin list session).
~/.aquin/engine.json	active_session_name, engine_id, base_url, active_model_id after session start.
~/.aquin/active_model.txt	Model locked to the active session; determines LLM vs embedding tool mode.
~/.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 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).