CLI Client

Overview

The gg CLI runs on your local machine (macOS, Linux, Windows) and is a complete GPUniq control surface:

• Rent and replace GPUs with an interactive 2D picker, filters, and a full-width marketplace table
• SSH into instances (always through the ssh.gpuniq.com proxy, never a bare provider IP)
• LLM chat — one-shot commands or an interactive REPL
• Image generation — gg image "a red cat astronaut" -o cat.png
• Volume, SSH-key, and billing management

Everything is billed from the same USD balance on your account.

Installation

pip install -U gpuniq

Python 3.8+. After installation the gg command is available in your terminal.

Authentication

Paste your API key once. Get one from the CLI page in your dashboard (or from LLM API Keys — they're the same keys).

gg login                       # hidden prompt
gg login gpuniq_your_key       # non-interactive
gg login --api-url https://dev-api.gpuniq.com/v1   # point at staging

The key is stored in ~/.gpuniq/config.json. Run gg status any time to see whether you're logged in.

Commands

gg rent — interactive GPU rental

gg rent

Opens a full-width flow:

1. Filter wizard — GPU model (2D picker by generation: Datacenter / 50XX / 40XX / 30XX / 20XX / 1660 with arrow-key navigation), minimum GPU count, max price / hour, verified-only, sort order.
2. Marketplace table — paginated, adapts columns to your terminal width. Wide terminals show #, GPU, CNT, VRAM, RAM, DISK, CPU, NET ↓/↑, LOCATION, RELIA, AVAIL, HOSTING, PRICE, VER. Use [n] / [p] to page, [f] to re-open filters, [s] to resort.
3. Billing plan — week (default), month, or minute.
4. Template — PyTorch, ComfyUI, vLLM, Ubuntu VM, or a custom Docker image.
5. Volume — pick an existing one, create a new one inline, or skip.
6. Confirm. If the offer was snapped up by someone else between listing and ordering (HTTP 410), the picker loops back so you don't lose plan / volume choices.

Flags to skip any prompt:

gg rent --gpu "RTX 4090" --count 1 --pricing week \
        --disk 100 --max-price 1.50 --verified

gg replace — swap the GPU on a running instance

gg replace             # pick the target instance interactively
gg replace 142         # replace this specific instance

Flow:

1. Pick the running instance to replace (auto-selected if you only have one).
2. Browse for a new GPU using the same picker as gg rent.
3. Review the summary (old vs. new, plan, volume, image).
4. On confirm, the old instance is destroyed (DELETE — terminates the provider machine, releases the SSH proxy port, soft-deletes the task) and a new order is placed with the same billing plan and volume. The Docker image defaults to the old instance's image so your on-disk data stays usable.

If the first replacement offer is taken between browse and order (410), the picker loops without losing the plan/volume; the old instance is only destroyed once a replacement is committed.

Same flags as gg rent — plus a positional <instance_id>.

gg open — SSH into an instance

gg open                # auto-select or arrow-key menu
gg open 142            # connect to a specific instance

Before connecting, the CLI:

1. Scans ~/.ssh/*.pub and offers to attach a matching key that already exists in your account (so password prompts go away).
2. Calls POST /v1/instances/{id}/ssh-proxy/ensure so you connect through ssh.gpuniq.com:<port> even on older orders whose proxy allocation failed at order time.

If the backend endpoint can't allocate a proxy, the CLI falls back to the direct host silently.

gg orders — list active instances

gg orders

ID      GPU                       STATUS       PRICE/HR    SSH COMMAND
----------------------------------------------------------------------
142     RTX 4090 x2               running      $0.45       ssh root@ssh.gpuniq.com -p 20142
143     A100 80GB                 running      $1.20       ssh root@ssh.gpuniq.com -p 20143

Shows only active instances (running, starting, provisioning).

gg stop — stop a running instance

gg stop                # interactive
gg stop 142            # explicit

Pauses the instance but keeps the task record around. For a permanent destroy (free up the SSH proxy port, etc.) use gg replace or delete via the dashboard / SDK.

gg llm — chat with a text model

gg llm "Explain CUDA streams in one sentence"     # one-shot, prints answer
gg llm                                            # interactive REPL
gg llm --list-models                              # list available text models
gg llm -m claude-haiku-4-5 --temperature 0.3 "rewrite X..."

In REPL mode:

• /exit or Ctrl-D to quit
• /clear to reset chat history

After each reply, the CLI prints tokens used, USD cost, and remaining balance (suppress with -q / --quiet).

gg image — generate images

gg image "a red cat astronaut on Mars"                        # auto-named PNG in cwd
gg image "variations" -n 4 -o ./renders/                      # directory target
gg image "edit me" --input cat.png --model nano-banana-pro --size 2048x2048 -o cat_v2.png

For Nano Banana slugs the CLI automatically uses the async-poll surface so you never hit a proxy's ~100s idle-read timeout. It streams job status updates (pending → processing → completed) to stderr so you can see progress.

gg balance — show USD balance

gg balance

Prints your current balance in the account currency (USD / RUB / EUR depending on your profile). This balance pays for GPU rentals, LLM chat, and image generation.

gg status — login + session info

gg status

CLI Login (gg login)
  Status:     connected
  API URL:    https://api.gpuniq.com/v1
  API key:    gpuniq…Abc4
  Instances:  3 total (1 running on this page)

Works whether you're logged in as a client (gg login) or initialised on a GPU (gg init). On a GPU it additionally shows the checkpoint summary.

gg ssh-keys — manage account SSH keys

gg ssh-keys list          # or just: gg ssh-keys
gg ssh-keys add           # uploads ~/.ssh/id_*.pub (interactive pick if multiple)

gg volumes — manage persistent storage

gg volumes                                             # list
gg volumes create my-data --size 50 --description "training data"
gg volumes delete 7

Volume data is S3-backed and auto-syncs between /workspace, /root on the GPU and the cloud via rclone. Survives gg replace so you can swap GPUs without losing state.

gg help

gg help                  # same as gg --help

Unknown commands now print a clear Error: unknown command '<x>'. plus full help — they no longer masquerade as the (confusing) "gg not initialized" message.

Typical workflow

# 1. Install, authenticate, add SSH key, create volume
pip install -U gpuniq
gg login
gg ssh-keys add
gg volumes create training-data --size 50

# 2. Rent a GPU interactively
gg rent --gpu "RTX 4090" --pricing week

# 3. Check, connect, work
gg orders
gg open

# 4. Between training runs, chat and generate images
gg llm "summarise the last paper on Gaussian splatting"
gg image "dashboard hero illustration, vector style" -o hero.png

# 5. Upgrade to a bigger GPU without losing volume data
gg replace 142 --gpu A100

# 6. When done, stop
gg stop 142

Configuration

Client config lives at ~/.gpuniq/config.json:

{
  "version": 1,
  "api_key": "gpuniq_...",
  "api_base_url": "https://api.gpuniq.com/v1"
}

To switch endpoints (e.g. staging):

gg login --api-url https://dev-api.gpuniq.com/v1

GPU-side mode

When gg runs on a GPU instance (after gg init <token>, usually done automatically on deploy), it becomes a command-checkpointing and persistent-service runner. See the CLI GPU-side guide for those commands (gg <command>, gg list, gg logs, gg services, gg restart, gg replay).