gpunz CLI

The gpunz command line talks to the same REST API as the console. Search offers, rent servers, connect over SSH and read logs from Linux, macOS, WSL or Windows PowerShell.

Install

The script downloads the build for your platform from gpu.nz, checks its SHA-256 sum and installs gpunz. Running it again updates the file in place.

curl -fsSL https://gpu.nz/install.sh | sh

Installs to ~/.local/bin (to /usr/local/bin as root). Set GPUNZ_INSTALL_DIR for another folder.

Then run gpunz login.

Check the install:

gpunz version

Release files and checksums are published at https://gpu.nz/cli/latest/

Sign in and keys

By default, gpunz login shows a short code, opens the confirmation page in your browser and waits for approval. The key is then stored locally.

Run gpunz login. The CLI prints a code such as ABCD-EFGH and a link.
The sign-in page opens by itself. Enter the code there. If you are not signed in to gpu.nz, sign in first.
Approve the sign-in. The CLI receives the key and saves it to the config file.

On a server without a browser, run gpunz login --no-browser and open the link on another device.

Existing key

Create a key in the console (API keys) and run gpunz login --key gpz_… or set GPUNZ_API_KEY. Keys created in the console can be limited by scope and expiry.

gpunz login --key gpz_…

gpunz logout removes the key from this machine. The key stays active until you revoke it in the console.

gpunz logout

Commands

Global flags

--json: Print JSON instead of tables
--api-url URL: API base URL (for development)
--api-key KEY: API key for this run only

gpunz login [--key KEY] [--no-browser]

--key KEY: Store an existing key instead of signing in through the browser
--no-browser: Don't open a browser; only print the code and link

gpunz login

gpunz login --key gpz_xxxxxxxxxxxxxxxx

gpunz logout

Remove the saved key

gpunz logout

gpunz whoami

The account in use

gpunz whoami --json

gpunz balance

Balance, available funds, hourly burn and runway

gpunz balance

gpunz gpus

GPU models, free units and starting prices

gpunz gpus

gpunz search [flags]

Search offers with filters and sorting

--gpu SLUG: Model slug(s), comma-separated: rtx-4090,a100
--num-gpus N: GPUs per machine: 1, 2, 4 or 8
--type TYPE: on_demand (default) or interruptible
--max-price RUB: Maximum on-demand price, rubles per hour
--country CC: ISO-2 country codes, comma-separated
--min-reliability R: Reliability, 0–1 or percent (0.99 or 99)
--verified: Verified machines only
--min-vram GB: Minimum VRAM per GPU, GB
--min-cuda VER: Minimum CUDA version, e.g. 12.4
--min-disk GB: Minimum disk, GB
--min-down MBPS: Minimum download speed, Mbps
--order FIELD: price (default), -price, dlperf, dlperf_per_price, reliability, vram, inet_down
--limit N: Rows to show, 1–200

gpunz search --gpu rtx-4090 --max-price 40 --verified

gpunz search --gpu a100 --num-gpus 4 --order -price --limit 10

gpunz templates

Launch templates: image, ports, disk size

gpunz templates

gpunz ssh-keys [ls | add [PATH] [--name NAME] | rm ID]

Account SSH keys: list, add, remove

--name NAME: SSH key name (default: the comment in the key file)

gpunz ssh-keys add

gpunz ssh-keys add ~/.ssh/work.pub --name work

gpunz ssh-keys rm 2f9c4a1e

gpunz create OFFER_ID --template SLUG [--disk GB] [flags]

Rent an offer

--template SLUG: Template slug (required)
--disk GB: Disk size, GB (default: the template's recommended size)
--name NAME: Server name
--type TYPE: on_demand (default) or interruptible
--ssh-key ID: SSH key ID; repeat the flag (default: all your keys)
--env KEY=VALUE: Environment variable KEY=VALUE; repeatable
--onstart CMD: Script run when the server starts

An Idempotency-Key header is set automatically, so retrying a create does not rent a second server

gpunz create 8f2c91d0 --template pytorch --disk 80 --name train

gpunz create 8f2c91d0 --template pytorch --type interruptible

gpunz instances [--all] (alias: ls)

Your servers (alias: ls)

--all: Include destroyed servers

gpunz instances

gpunz ls --all

gpunz show ID

Details of one server, including the SSH command

gpunz show 2f9c4a1e

gpunz start ID

Start a stopped server

gpunz start 2f9c4a1e

gpunz stop ID

Stop a server; its disk is kept

gpunz stop 2f9c4a1e

gpunz destroy ID [-y]

Delete a server and its disk

-y, --yes: Skip the confirmation prompt

gpunz destroy 2f9c4a1e

gpunz destroy 2f9c4a1e -y

gpunz ssh ID [ssh args…]

Open an SSH session with the system ssh client

gpunz ssh 2f9c4a1e

gpunz ssh 2f9c4a1e -L 8888:localhost:8888

gpunz logs ID [--tail N]

The last lines of a server's logs

--tail N: Lines from the end, 1–1000

gpunz logs 2f9c4a1e --tail 100

gpunz api-keys [ls | create --name NAME | rm ID]

API keys: list, create, delete

--name NAME: SSH key name (default: the comment in the key file)
--scopes LIST: Comma-separated scopes (default: all)
--expires-in-days N: Expire after N days (0 = never)

gpunz api-keys create --name ci --scopes instances:read,instances:write

gpunz api-keys ls

gpunz version

The CLI version

gpunz version

gpunz update [--force]

Update the CLI to the latest release

--force: Reinstall even if the version is current

gpunz update

gpunz completion bash|zsh|fish|powershell

Shell completion script for bash, zsh, fish or PowerShell

eval "$(gpunz completion bash)"

gpunz completion powershell | Out-String | Invoke-Expression

Output formats

Commands print aligned tables by default. Colours appear only in a terminal and are turned off by NO_COLOR or when output goes to a file.

With --json the command prints the API response as is, which suits scripts and jq.

gpunz instances --json | jq '.data[].id'

Money is in rubles: 25,40 ₽/ч in the Russian locale, ₽25.40/h in English.

Messages follow LC_ALL, then LANG: anything starting with ru is Russian. API errors come back in the language of the request.

Errors print as “error: message (code)”. With --json the error is a JSON object on stderr.

Variables and config

Precedence: command-line flag, then environment variable, then the config file.

Variable	Meaning
GPUNZ_API_KEY	API key, e.g. gpz_…
GPUNZ_API_URL	API base URL, default https://gpu.nz/api/v1
NO_COLOR	Turn colours off
LC_ALL, LANG	Message language: ru… or en
GPUNZ_INSTALL_DIR	Install folder for install.sh and install.ps1

Config: ~/.config/gpunz/config.json (Linux, macOS), %APPDATA%\gpunz\config.json (Windows). It holds api_key and api_url and is written with mode 0600.

{
  "api_key": "gpz_…",
  "api_url": "https://gpu.nz/api/v1"
}

Exit codes

0	Success
1	Other error, including network failures and an unreachable API
2	Bad arguments or flags
3	Not signed in, invalid key, or missing scope
4	Server, offer or template not found
5	Insufficient balance

Troubleshooting

gpunz is not found after installing

Open a new terminal. On Linux and macOS, add the install folder to PATH (install.sh prints the line for ~/.profile).

“not signed in” (exit code 3)

Run gpunz login. If GPUNZ_API_KEY is set, check that the key is not revoked or expired.

The browser does not open

Open the link gpunz prints and enter the code. You can also use gpunz login --no-browser.

gpunz ssh cannot find ssh

On Windows, enable the OpenSSH Client optional feature. Without an ssh client, gpunz prints the command for manual use.

checksum mismatch during install or update

The file does not match SHA256SUMS, so nothing was installed. Try again later and check your network or proxy.

update on Windows does not replace gpunz.exe

The running binary is renamed aside and the new one takes its place. If the folder is write-protected, run the terminal as administrator.