CLI reference
Binary: aq. Train / eval / fleet. Agent chat is axi (separate package). After TypeScript changes in a checkout: cd aq && npm run build.
aq train
Fit the recipe. Writes checkpoints under artifacts/checkpoints/, appends artifacts/metrics.jsonl, and records a run. Live steps stream on stderr. Kernel IPC: artifacts/request.json → result.json.
| Flag | Description |
|---|---|
| [dir] | Train directory (default cwd). |
$aq train
aq eval [name]
Score probes in evals/. Humans own the gate. When recipe.eval.min_score is set, results are pass/fail; otherwise scores are reported without inventing a verdict. Writes artifacts/eval.json.
| Flag | Description |
|---|---|
| [name] | Probe name. Omit to run all. |
| --ckpt <name> | Named checkpoint instead of last. |
$aq eval
$aq eval holdout --ckpt last
aq checkpoint [--keep name]
List checkpoints, or name a copy of last under artifacts/checkpoints/.
| Flag | Description |
|---|---|
| --keep <name> | Save a named copy of last. |
$aq checkpoint --keep best
aq serve [prompt]
Generate from a checkpoint (methods that implement generate). Writes artifacts/serve.json.
| Flag | Description |
|---|---|
| --ckpt <name> | Checkpoint to serve. |
| --max-tokens n | Max new tokens. |
| --temperature t | Sampling temperature. |
$aq serve "hello" --max-tokens 32
cat artifacts/serve.json
aq diff [<a> <b>]
List run records under artifacts/runs/, or diff two run records.
$aq diff <run-a> <run-b>
aq help
Short Unix-style help for the aq CLI.
$aq help
SSH fleet
Places, launch, remote jobs, pools. Walkthrough: SSH fleet.
aq add ssh [name] [--host H …]
Register an SSH place. Interactive prompts by default. Non-interactive (agent/scripts): --host required, plus optional --user, --port, --key. Probes cpu/ram/gpu into ~/.aquin/places.json.
$aq add ssh temp
$aq add ssh lab --host 1.2.3.4 --user ubuntu --key ~/.ssh/id_ed25519
aq add pool [name] [members…]
Pool of SSH places. --on <pool> picks a free member (reachable + capacity + lowest live-job load).
$aq add pool gpus box1 box2
aq places [--tag k=v] [--probe]
List places with live load (CPU/mem/disk/GPU). --probe refreshes capacity. --tag filters by label.
aq launch [dir] --on <place> [--port N] [-- <cmd>]
Sync folder → place, setup aq on remote, open SSH (or run -- <cmd>). Skip profile prompts with lean/minimal when asked.
| Flag | Description |
|---|---|
| --on <place|pool> | Target place or pool. |
| --port N | SSH -L tunnel (also sets AQ_PORT on remote). |
| --no-setup | Skip remote aq setup. |
$aq launch --on temp
$aq go temp
$aq sync --on temp
$aq shutdown [--wipe]
aq jobs …
Background jobs on a place. Remote source of truth: <remoteDir>/jobs/<id>/. train|eval|serve wrap run -- aq …. See Jobs.
| Subcommand | Description |
|---|---|
| run|train|eval|serve | Start work (--on, --nodes, --gpu, --devices, --port, --tag, --manage, --json). |
| sweep | Fan-out --shard N and/or --grid k=a,b; placeholders {i} {n} {shard} {gridKey}. |
| list|status|logs|pull|down | Inspect / fetch / cancel. |
| recover | Restart same id (--same|--next|--on). |
| watch|manage | Managed auto-recover loop / policy. |
| submit | Alias → aq queue push. |
$aq jobs train --on temp
$aq jobs train --on gpus --nodes 2
$aq jobs sweep --shard 8 --on gpus -- aq train --shard {i}/{n}
$aq jobs recover <id> --next
$aq jobs watch
aq queue add|push|worker|drain|move
Pending work → SSH claim (priority). Bind a queue to a place or pool with add --on.
$aq queue add gpus --on gpus
$aq queue push gpus --priority 10 -- aq train
$aq queue worker gpus --once
aq port · aq tag
aq port <N> [--on p] [--bg] opens an SSH -L tunnel. aq tag place|job sets labels; filter with places/jobs --tag k=v.
$aq port 8000 --on temp --bg
$aq tag place temp team=ml
$aq tag job <id> exp=baseline