Command Reference

This page covers every aq command. If you just want the fastest path to a running box, start with the Quickstart instead, come back here for the rest of the surface.

All commands

Every command also accepts -h/--help for its own flag list.

Marketplace

gpus

aq gpus [flags]

Bare, aq gpus prints a market-summary table - one row per GPU model, cheapest per-GPU rate first, with how many providers and offers back it - so you can see at a glance which model is cheapest and how contested it is. This is the one aq command that needs no account, no API key, and no aq login - it just reads the same public marketplace endpoint.

$ aq gpus
GPU               VRAM   FROM $/GPU-HR  CHEAPEST AT   REGION        PROVIDERS  OFFERS
RTX3070           8      0.0500         simplepod     CA            2          12
A16               2GB    0.0590         vultr         New Jersey    1          19
V100              16     0.0700         simplepod     US            3          46
...
H100              80GB   2.5250         hyperstack    CANADA-1      4          60
H200              141GB  3.6200         massecompute  us-east-1     3          38
B200              -      6.0600         hyperstack    CANADA-1      2          9
B300              288GB  7.8900         runpod        EU-NL-1       1          12
585 offers across 41 GPU models. `aq gpus --gpu <model>` lists every offer, `--limit 0` the whole feed
ready to rent one? `aq login` pairs an account, then `aq up --gpu <model>` deploys.

Any flag - a filter, --limit, or --json - switches it to the per-offer table instead, listing every individual offer that matches:

$ aq gpus --gpu H100 --limit 5
GPU   GPUS  VRAM  PROVIDER      REGION        AVAIL  $/GPU-HR  $/HR TOTAL
H100  1     80GB  massecompute  us-central-3  1      2.4500    2.4500
H100  2     80GB  massecompute  us-central-3  2      2.4500    4.9000
H100  1     80GB  hyperstack    CANADA-1      1      2.5250    2.5250
H100  1     80GB  hyperstack    CANADA-1      1      2.5250    2.5250
H100  1     94GB  runpod        unknown       1      2.5900    2.5900
showing 5 of 77 offers; use --limit 0 for all
ready to rent one? `aq login` pairs an account, then `aq up --gpu <model>` deploys.

--json emits the raw offer fields from the marketplace feed plus a derived pricePerGpuHour, so scripts can sort or filter without re-deriving the per-GPU math themselves.

Authentication

login

aq login

Device-pairing flow: prints a URL and a confirmation code, optionally opens your browser to it, and waits for you to approve the pairing in the console. See the Quickstart for a full example.

logout

aq logout

Removes the stored CLI credential from your machine.

whoami

aq whoami

Shows the current login state.

version

aq version

Prints the installed aq version.

help

aq help

Shows the built-in command list.

Deploy & connect

up

aq up [flags]

Rents the cheapest matching GPU and provisions the box: a bare box by default, or with an app installed via --comfyui/--jupyter. See Quickstart for a walkthrough.

import

aq import [flags]
aq import --resume <volume-id>

Run this ON a box you rent somewhere else. It surveys the box, shows you exactly what it will and will not capture, and (once you agree) captures /workspace into a new Aquanode Volume you can attach to any pod. See aq import for the full walkthrough.

The survey prints three groups: what is being captured, what is being skipped (with sizes, so you can add it with --include), and what could not be read at all. The third group matters most: a directory listed there is not in the capture, and the usual fix is to re-run under sudo. Directories below a size floor are not listed individually; the survey says so when it applies one.

A non-interactive shell without --yes refuses rather than guessing. Package manifests (dpkg/rpm/pip) are recorded for reference and are never replayed on restore.

ssh

aq ssh                     # your only live deployment
aq ssh <name|id>           # a deployment by --name or id
aq ssh <name> -- <cmd…>    # run a command instead of opening a shell

aq manages ~/.ssh/aquanode.config (included from your ~/.ssh/config) with one aq-<name> alias per live box, so ssh, scp, rsync, and VSCode Remote-SSH all work with that alias with no aq involved. If you have no SSH key at all, aq generates a passphrase-less one at ~/.ssh/aquanode_ed25519. See the Quickstart for more examples.

push

aq push [name|id] [flags]

Sends your working directory to a box you already rented, over the same managed ssh alias aq ssh uses. It is a plain directory copy, not a new protocol, so anything you could do with scp/rsync by hand keeps working alongside it.

run

aq run [name|id] [flags] -- <command...>

Pushes the working directory, then runs a command on the box with the terminal attached. It is aq push followed by aq ssh -- cd <dir> && <cmd>, folded into one command.

With --detach, aq run prints a run id to stdout and returns immediately. Read its output with aq logs.

logs

aq logs [name|id] [flags]

Reads a detached run's output (the other half of aq run --detach). Defaults to the most recent run on the box.

ls

aq ls [--all]

Lists your machines: what is running right now and what it costs (id, name, status, GPU, provider, hourly rate, age). Live boxes only by default; pass --all to include closed and failed ones too. This is different from aq pods, which lists what you own whether or not it is currently running a box.

status

aq status <name|id>

Re-checks a provisioning or running pod: state, HTTPS URL, and credentials (add --show-secrets to print the password).

down

aq down <name|id>

Tears the pod down and stops billing.

Environment & Volume

env keep

aq env keep <name|id> <environment-name>

Names the pod's current environment (a fresh capture on a running pod, the working environment as-is on a stopped one) as the next version, and files it under Yours in the environment picker. Mints nothing if you keep the same environment twice with no change in between.

env share

aq env share <name|id> [--version <id>]
aq env share --from-environment <name|id> --version <id>

Prints a link to one Environment version, e.g. aq env share my-box. Without --version this shares the latest, taking a fresh capture first if the pod is running. --from-environment shares a version of an already-Kept or -Shared environment directly, not necessarily attached to any pod right now; --version is required with it, since a standalone environment has no single pod to default the latest version from. It prints Preparing link... and polls until the link is ready before printing it, since the share is a server-side copy job, not instant.

env ls

aq env ls
aq env ls <name|id>

Bare, lists the environments you can pick from: Built-in, Yours (kept or previously shared), and Shared with you. With a pod or environment name/id, lists that one's version history instead (id, version, created, what's included/left out).

env rm

aq env rm <id>

Deletes a kept or shared environment. Breaks nothing already running; existing share links to it stop working.

volume ls

aq volume ls
aq volume ls <id>

Bare, lists the volumes you own: name, size, and status (in use by a running pod, idle, or never saved). With an id, shows that one volume's detail and full point history instead.

volume dup

aq volume dup <id> <new-name>

Duplicates a volume into an independent copy, seeded from the source's current head. Writes on one never flow to the other.

volume restore

aq volume restore <id> <point-id>

Moves a volume's head to an earlier history point. Only allowed while the volume is not attached to a running pod.

volume rm

aq volume rm <id>

Deletes a volume and its whole history. Refused only while the volume is in use by a running pod; a stopped pod pointed at it is detached and starts with an empty /workspace next time.

Pod lifecycle

stop

aq stop <name|id>

Captures the pod's environment and volume, then releases its machine. aq up takes no pod argument and always starts a fresh, empty box, so it is not how you pick this back up. Restore it with aq start.

start

aq start <name|id>

Restores a stopped pod's environment and volume onto a fresh machine. You choose the card it comes back on with the same --gpu, --gpus, --max-price, and --provider flags that aq up takes.

move

aq move <name|id> [flags]

Stops the pod, then starts it on a different GPU. Takes the same --gpu, --gpus, --max-price, and --provider flags as aq start. The machine is released only after both captures are confirmed, so a failed start on the new GPU leaves the pod stopped with its data intact.

autostop

aq autostop <name|id> on|off

Turns this pod's auto-stop on or off, using the platform's default idle thresholds. This is not the same as idle: idle policy is a per-deployment threshold config that always outranks this, and autostop carries no thresholds of its own. Use aq idle set to change when idle counts as idle, and autostop to turn stopping on pods on/off at all.

pods

aq pods

Lists the pods you own: name, whether it's running (yes/no, or stopping while a Stop or the first half of a Move is in flight), its current Environment (name vN, or bare name before it has a minted version), and its Volume's size.

pods create

aq pods create <name> --env <name|id> [flags]

The terminal equivalent of the console's New pod screen: pick an Environment, pick or skip a Volume, pick a machine, and launch, in one command. This is the only way to start a brand new pod from a kept or shared Environment; aq up only ever starts a bare box or a built-in app.

With neither --volume nor --no-volume, a fresh empty volume is created for the pod, the same default the console's New pod screen uses.

Idle policy

idle

A per-deployment auto-stop policy (warn/stop thresholds, GPU idle %). It always outranks a pod's own aq autostop preference above.

aq idle status <name|id>   # show the policy and its current live verdict
                            # (ACTIVE / IDLE / UNKNOWN)
aq idle set <name|id>       # update the policy (only the flags you pass change)

See also Stop, start, and move for how this behaves across the console and API.

Jobs

job

Everything about jobs is a subcommand of aq job. It is a group rather than top-level verbs because aq run already means "push this directory to a box and run a command on it" and aq logs already tails a box, and aq run mybox and aq run myjob are the same string.

aq job run <pod> <version> -- <argv...>
aq job run --image <ref> -- <argv...>
aq job ls
aq job logs <job> [-f] [--attempt <n>]
aq job cancel <job>
aq job pull <job> [dest]
aq job rerun <job>
aq job rm <job>

A job is one execution: aq job run creates the job and starts it in one call, either a pod version you saved (<pod> <version> positionals) or a container image you already have (--image). There is no create, no point, and no per-job runs list, because a job has exactly one execution. To run the same command again, use rerun, which makes a new job.

job run

--on only applies to a version-source job: a box you attach already carries a saved version, so it has nothing an --image job could match against. See aq job run --help for the checkpoint flags.

Without --detach, aq job run streams the log until the run ends, exiting non-zero unless it succeeded. An image-source job states its entrypoint after a bare --.

job ls

Lists your jobs: name, status, GPU, duration and cost. UNSERVABLE means Aquanode could not get the run a machine at all: it does not mean your own code failed.

job logs

A job that moved between machines has several attempts. The default is the latest rather than all of them concatenated, which would put the timestamps out of order in the middle with nothing marking the seam.

If the machine cannot be reached, aq says so on stderr rather than printing nothing: an empty log and an unreadable one are different facts.

job cancel

Stops the job's run. Billing stops when the machine started only for it is released.

job pull

Downloads the job's run's landed artifacts (its log object and every declared output) into dest (default: ./<job>-<runId>/), one file per artifact key. Re-running skips a file already downloaded at the same size, so an interrupted pull picks up where it left off.

job rerun

Makes a new job that reruns this one's spec (same source, hardware, secrets) and starts it immediately. Prints the new job's id; watch it with aq job logs.

job rm

Removes the job record.

Environment variables