Agent & raw CLI

Cross-cutting commands: installation, authentication, engine connection, model loading, the aquin chat agent loop, one-shot raw CLI invocation, session memory, and legacy packaging. These apply regardless of LLM vs embedding mode unless noted.

23 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 Aquin API key (aq-…) from aquin.app to ~/.aquin/config.json. Required before any other command.

example

aquin api-key

Print the saved API key. Useful for curl: Authorization: Bearer $(aquin api-key).

example

aquin whoami

Show the account associated with the saved API key.

example

aquin switch

Replace the saved API key with a new one.

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 connect

Register this machine as an engine on api.aquin.app, create a session, and write session_id to ~/.aquin/engine.json. Required for web sync. Every GPU command after connect pushes SyncEvents to the session.

Flag	Description
--device*	Human-readable machine label.
--api-key	Override saved key.

example

Open https://aquin.app/app/session/<session_id> to watch live.

aquin disconnect

Mark engine offline. Stops pushing sync events.

example

aquin engine status

Show connection state, session_id, engine_id, active model, and tool mode (LLM / embedding).

example

aquin load

Load a model onto local GPU and set tool mode automatically. LLMs activate inspection/eval/simulation tools. Embedding models activate embed-* tools. No reconnect needed when switching model types.

Flag	Description
--model*	Model ID: gpt2-small, pythia-70m, llama-3.2-1b, gte-small, all-minilm-l6, bge-small-en, etc.

example

aquin list models

List available model IDs from the registry.

example

aquin list saes

List public SAE checkpoints (model-layer pairs).

example

aquin info sae

Show metadata for one SAE: layer, dictionary size, training corpus.

Flag	Description
<model-l{n}>*	SAE slug, e.g. gpt2-small-l8.

example

aquin pull sae

Download SAE weights to local cache. Required before feature-level inspection tools.

Flag	Description
<model-l{n}>*	SAE slug.

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.

Flag	Description
--session	Attach to existing session ID.

example

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

aquin <tool-verb>

One-shot raw CLI: any tool verb from the registry (inspect, steer, simulate, embed-layer-drift, etc.) without agent orchestration. Same GPU path and web sync as chat. Use --output json for scripting.

Flag	Description
--session	Session to sync to.
--output json	Raw JSON stdout.

example

Mode-filtered: aquin help shows verbs available for your loaded model.

aquin mem-write

agent tool: write_session_memory

Write a key-value pair to session memory. Visible to aquin chat agent and web analyst panel.

Flag	Description
--key*	Memory key.
--value*	Memory value (string).

example

aquin mem-read

agent tool: read_session_memory

Read a value from session memory by key.

Flag	Description
--key*	Memory key.

example

aquin run-code

agent tool: write_and_run_code

Write and execute Python on the local engine. Coming soon.

Flag	Description
--code*	Python source.

example

Not yet implemented.

aquin save-artifact

agent tool: save_code_artifact

Save a named code artifact to the session. Coming soon.

Flag	Description
--name*	Artifact name.
--description	Description.
--code*	Source code.

example

Not yet implemented.

aquin package / aquin push

Legacy training upload flow: package a recorded training run and push to cloud for post-hoc inspection. Separate from the sync CLI workflow.

example

Legacy. New workflows use aquin connect + aquin chat + simulation tools.

Configuration

Local paths and environment variables the CLI reads between sessions.

~/.aquin/config.json	Saved API key.
~/.aquin/engine.json	session_id, engine_id, base_url after connect.
~/.aquin/active_model.txt	Last loaded model; determines LLM vs embedding tool mode.
~/.aquin/runs/<id>/	Saved simulation runs on local disk.
AQUIN_API_KEY	Environment override for API key.
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.

--session <id>	Attach to a specific session (default: active session from ~/.aquin/engine.json).
--output json	Print raw JSON instead of formatted terminal output.
--model <id>	Override the active model for this command only.