CLI Reference

Complete reference for every lium command, grouped by what you're trying to do. Each command has its own page with arguments, options, and runnable examples.

If you're new, start at the Quickstart and circle back here once you know which command you need.

Global Options

Available on every command:

Flag	Effect
`--help`	Show help for the command
`--version`	Print CLI version (on the root `lium` command)

Pods

Day-to-day pod lifecycle, access, and observation.

Command	Purpose
`lium ls`	List available GPU nodes
`lium up`	Create a new pod
`lium ps`	List your active pods
`lium describe`	Show one pod in full: ports, GPU, template, billing
`lium ssh`	Open an SSH session
`lium exec`	Run a command on a pod
`lium scp`	Copy files to/from a pod
`lium rsync`	Sync directories to a pod
`lium rm`	Stop / remove pods
`lium reboot`	Reboot one or more pods
`lium logs`	Stream or tail pod logs
`lium update`	Update a running pod (e.g. install Jupyter)
`lium port-forward`	Forward a pod port to your local machine
`lium schedules`	List / cancel auto-termination schedules

Storage

Persistent volumes and pod backups.

Command	Purpose
`lium volumes`	Manage persistent volumes (`list` / `new` / `rm`)
`lium bk`	Pod backups: create, schedule, restore, list, delete

Templates

Command	Purpose
`lium templates`	List and search Docker templates and images

Account & Config

Command	Purpose
`lium signup`	Create an account from the terminal and store its API key
`lium init`	First-time setup for an existing account (API key + SSH key)
`lium config`	Read / write CLI configuration
`lium theme`	Change CLI color theme
`lium balance`	Show your current account balance
`lium fund`	Fund your account with TAO or free Subnet 51 alpha from a Bittensor wallet
`lium topup`	Top up your balance with a stablecoin (agent self-funding)
`lium ssh-keys`	List / sync SSH keys on your account

Providers

Commands for users running provider nodes on Subnet 51. See also the Providers section for setup and architecture.

Command	Purpose
`lium mine`	Bootstrap a provider node end-to-end
`lium gpu-splitting`	Prepare Docker storage for multi-tenant rental
`lium provider`	Full provider-portal automation: portal session, node lifecycle, central-miner-server config, sync, billing, and machine-request queries

Patterns That Work Across Commands

Pod selectors

Most pod-targeting commands (ssh, exec, scp, rsync, rm, reboot) accept any of:

A pod name: lium ssh my-pod
An index from lium ps: lium ssh 1
A comma-separated list: lium exec 1,2,3 "uptime"
The keyword all: lium scp all ./config.json

A named target that matches no pod exits 5 — a typo must not read like work that happened. Asking for everything is the opposite case: lium rm --all and lium reboot --all on an account with no pods leave the asked-for state already true, so they warn and exit 0.

Output formats

Listing commands accept --format (table or json):

lium ls --format json | jq '.[] | .gpu_type'
lium ps --format json > pods.json

Environment variables

Override config without editing files:

LIUM_API_KEY=xyz lium ls

For provider commands, LIUM_PROVIDER_COLDKEY and LIUM_PROVIDER_HOTKEY set the wallet identity (or persist them via lium config set provider.coldkey ... / lium config set provider.hotkey ...). LIUM_PORTAL_URL overrides the portal base URL, and LIUM_PROVIDER_ACK=1 auto-confirms the persona gate on spend-affecting lium provider … subcommands. See lium provider for the full surface.

Exit codes

Code	Meaning
`0`	Success
`1`	General error
`2`	Configuration error — bad arguments, unreadable script, missing configuration
`3`	API error — the API refused or failed the call
`4`	SSH error
`5`	Pod not found
`6`	Permission denied — the account is not allowed to do this

Two exceptions:

lium exec exits with the remote command's exit code, so lium exec my-pod "cmd" && next-step chains the way you expect.
lium provider … has its own exit-code map — the same numbers carry different meanings there (2 is auth, 3 a portal error, 5 an SSH error, 6 missing configuration), and it also emits 7, which this table does not list.

Global Options​

Pods​

Storage​

Templates​

Account & Config​

Providers​

Patterns That Work Across Commands​

Pod selectors​

Output formats​

Environment variables​

Exit codes​

See also​