AquinLabs

CLI reference

Binary: aq. Train / eval / fleet. Agent chat is axi (separate package). After TypeScript changes in a checkout: cd aq && npm run build.

Prerequisiteaq installed · cwd is usually a train folder

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.

FlagDescription
[dir] Train directory (default cwd).
example
$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.

FlagDescription
[name] Probe name. Omit to run all.
--ckpt <name> Named checkpoint instead of last.
example
$aq eval
example
$aq eval holdout --ckpt last

aq checkpoint [--keep name]

List checkpoints, or name a copy of last under artifacts/checkpoints/.

FlagDescription
--keep <name> Save a named copy of last.
example
$aq checkpoint --keep best

aq serve [prompt]

Generate from a checkpoint (methods that implement generate). Writes artifacts/serve.json.

FlagDescription
--ckpt <name> Checkpoint to serve.
--max-tokens n Max new tokens.
--temperature t Sampling temperature.
example
$aq serve "hello" --max-tokens 32
example
cat artifacts/serve.json

aq diff [<a> <b>]

List run records under artifacts/runs/, or diff two run records.

example
$aq diff <run-a> <run-b>

aq help

Short Unix-style help for the aq CLI.

example
$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.

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

example
$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.

FlagDescription
--on <place|pool>Target place or pool.
--port NSSH -L tunnel (also sets AQ_PORT on remote).
--no-setupSkip remote aq setup.
example
$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.

SubcommandDescription
run|train|eval|serveStart work (--on, --nodes, --gpu, --devices, --port, --tag, --manage, --json).
sweepFan-out --shard N and/or --grid k=a,b; placeholders {i} {n} {shard} {gridKey}.
list|status|logs|pull|downInspect / fetch / cancel.
recoverRestart same id (--same|--next|--on).
watch|manageManaged auto-recover loop / policy.
submitAlias → aq queue push.
example
$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.

example
$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.

example
$aq port 8000 --on temp --bg
$aq tag place temp team=ml
$aq tag job <id> exp=baseline