Command Reference

This page covers all 24 aq commands. 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.

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 brings up a working setup. See Quickstart for a walkthrough.

deploy

aq deploy --snapshot <id> [flags]

Rents a fresh GPU and restores a save onto it — moving an environment to a different (or cheaper) box, optionally on a different provider than the one it came from.

--comfyui is the default if you pass neither app flag; pass --no-app for a restore with no app relaunched.

import

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

Run this ON a GPU box you rent somewhere else. It surveys the box, shows you exactly what it will and will not capture, and — once you agree — captures the environment into a new Aquanode setup you can launch on any provider we support. 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.

status

aq status <name|id>

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

down

aq down <name|id> [--save]

Tears the setup down and stops billing. --save saves first; termination is skipped if the save fails.

Save, share & fork

save

aq save <name|id> [--name <lineage>] [--path <dir>]

Saves the setup's current state into its named save lineage. The first save on a setup asks for a lineage name once (Enter accepts the default, which is the setup's own name; a non-interactive shell just uses the default). Every later save reuses that lineage silently and increments its version (v1, v2, v3, ...).

share

aq share <name|id> <ver>

Prints a link to one immutable saved version, e.g. aq share comfyui 3. The link always points at that exact version, never at whatever the lineage's head becomes later.

fork

aq fork <token|link> [--name <name>]

Turns a link from aq share — someone else's, or your own team's share of a team you've since left — into a brand new setup in your own library. Registers ownership only; it does not itself boot any hardware. --name defaults to a name derived from the source.

edit-version

aq edit-version <name|id> <ver> [--label <text>] [--description <text>] [--visibility private|team|public]

Edits a saved version's label, description, and/or visibility. Only the flags you pass change; there is currently no way to clear a label/description back to empty.

Setup lifecycle

pause

aq pause <name|id>

Saves the setup, then releases its machine. Pick it back up any time with aq up.

autopause

aq autopause <name|id> on|off

Turns this setup's stop-when-idle preference 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 autopause carries no thresholds of its own — use aq idle set to change when idle counts as idle, and autopause to turn stopping on setups on/off at all.

force-detach

aq force-detach <name|id> --yes

Breaks the setup's lease even mid-sync — for when a deployment died holding it and it needs freeing before anything else can attach. --yes acknowledges work since the last completed sync may be lost; there is no silent form of this command.

sync-now

aq sync-now <name|id>

Forces a sync tick right now instead of waiting for the setup's own schedule — e.g. right before aq share/aq fork so the link reflects your latest work. Requires the setup to be attached to a running deployment.

setups

aq setups

Lists the setups you own: name, whether it's running, latest saved version, and size.

Idle policy

idle

A per-deployment auto-pause policy (warn/stop thresholds, GPU idle %). It always outranks a setup's own aq autopause 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 Auto-pause for how this behaves across the console and API.

Endpoints

endpoint

aq endpoint create <setup> <version> --max-instances <n> --spend-cap-cents <n> [--name <name>]
aq endpoint point <name> <version>
aq endpoint rm <name>

create makes a setup version callable. --max-instances and --spend-cap-cents are required — an endpoint hands out a GPU budget, so neither ever defaults to unbounded. --name defaults to the setup's own name.

point repoints an endpoint at a different version in its lineage — also how you roll back.

rm removes an endpoint.

call

aq call <endpoint> [--input file]

Makes a call against an endpoint and prints its call id. --input is a JSON file of the declared params; with no --input, the call is made with no inputs.

calls

aq calls <endpoint>

Lists an endpoint's recent calls: id, status, phase, and reason. "unservable" means Aquanode could not get the call a box at all — not that the call's own code failed.

Environment variables