lium provider
Provider-side CLI for Bittensor Subnet 51. The lium provider namespace covers everything the provider portal frontend at lium.io/portal does — portal authentication, node lifecycle, central-miner-server configuration, batch sync, and read-only billing / machine-request queries — so an AI agent (or any automation) can run a Lium provider account end-to-end without a browser.
Distinct from lium mine, which is the renter-side bootstrap for installing the node binary on a host. Hotkey registration on SN51 itself is performed directly with btcli subnet register; everything after that is lium provider ….
lium provider [OPTIONS] SUBCOMMAND [SUBCOMMAND-OPTIONS]
Group-level options
Set once on the lium provider group; every subcommand inherits them. CLI flags beat env vars beat ~/.lium/config.ini.
| Flag | Env var | Config key | Effect |
|---|---|---|---|
-w, --coldkey NAME | LIUM_PROVIDER_COLDKEY | provider.coldkey | Bittensor coldkey (wallet) name |
-k, --hotkey NAME | LIUM_PROVIDER_HOTKEY | provider.hotkey | Bittensor hotkey on the coldkey |
--portal-url URL | LIUM_PORTAL_URL | provider.portal_url | Override portal base URL (default: production) |
--json | — | — | Emit one machine-readable JSON envelope per command |
--debug | — | — | Verbose logging; include error context on stderr |
-y, --yes | LIUM_PROVIDER_ACK=1 | — | Auto-confirm the persona gate for spend-affecting subcommands |
--dry-run | — | — | Skip irreversible subprocess calls (e.g. ssh) and report intent only |
Persist hotkey/coldkey across sessions instead of repeating flags:
lium config set provider.coldkey miner-prod
lium config set provider.hotkey miner-1
After that, every lium provider … invocation auto-resolves the wallet identity from ~/.lium/config.ini.
Subcommand map
| Group | Purpose | Spend-affecting? |
|---|---|---|
portal | JWT session against the provider portal | no |
status | Aggregated provider snapshot | no |
node | GPU node lifecycle on the portal | most subcommands yes |
config | Portal-account & central-miner-server settings | mutating subcommands yes |
sync | Batch sync between portal and central miner server | yes |
billing | Paginated billing history | no |
machine-request | Pending tenant machine requests | no |
machine | GPU machine catalogue + reward estimates | no |
Spend-affecting subcommands run a persona gate that prompts unless --yes is set or LIUM_PROVIDER_ACK=1 is exported.
lium provider portal
Manage the cached JWT used to authenticate against the provider portal. The token is keyed by hotkey ss58 and stored under ~/.lium/provider/.
lium provider portal login [--force] # Exchange a hotkey signature for a JWT
lium provider portal logout # Drop the cached JWT for this hotkey
lium provider portal whoami # Call /auth/me with the cached token
Flag (on login) | Effect |
|---|---|
--force | Bypass the local token cache and re-authenticate |
login requires --hotkey (or LIUM_PROVIDER_HOTKEY, or provider.hotkey in config). logout and whoami do too.
lium provider status
One-shot health snapshot composed from the subtensor metagraph, portal /auth/me, the node list, and validator weights. Sources that fail are skipped and surfaced as warnings in the JSON envelope.
lium provider status [--netuid 51]
| Flag | Effect |
|---|---|
--netuid INT | Subnet to query (default: 51) |
lium provider node
Node lifecycle on the portal. Mutating subcommands (add, rm, update-*, min-gpu set/unset, notice-period set/unset, notify-added) run the persona gate.
lium provider node list [--miner-hotkey HK] [--page N] [--limit N]
lium provider node get <NODE_ID>
lium provider node add --gpu-type TYPE --ip IP [--port 8080] [--price USD] --gpu-count N
lium provider node rm <NODE_ID>
lium provider node update-price <NODE_ID> --price USD
lium provider node update-gpu <NODE_ID> --gpu-type TYPE --gpu-count N
lium provider node min-gpu set <NODE_ID> <COUNT>
lium provider node min-gpu unset <NODE_ID>
lium provider node pods <NODE_ID>
lium provider node machine-requests <NODE_ID>
lium provider node notice-period set <NODE_ID>
lium provider node notice-period unset <NODE_ID>
lium provider node notify-added <NODE_ID> --request-id REQ
| Subcommand | Args / flags | Purpose |
|---|---|---|
list | --miner-hotkey HK, --page N, --limit N | Paginated node listing for the active provider |
get | NODE_ID | Fetch a single node record |
add | --gpu-type, --ip, --port (default 8080), --price (optional; auto-filled from public shared-config when omitted), --gpu-count (default 1) | Queue a new node addition (POST /executors). Persona-gated |
rm | NODE_ID | Delete the node. Persona-gated |
update-price | NODE_ID --price USD | Set price-per-GPU/hour. Persona-gated |
update-gpu | NODE_ID --gpu-type TYPE --gpu-count N | Change GPU type/count. Persona-gated |
min-gpu set | NODE_ID COUNT | Minimum GPU count required for rental matchmaking. Persona-gated |
min-gpu unset | NODE_ID | Clear the minimum-GPU rule. Persona-gated |
pods | NODE_ID | List pods currently rented on this node |
machine-requests | NODE_ID | List pending tenant requests targeting this node |
notice-period set | NODE_ID | Open a notice period before maintenance / decommission. Persona-gated |
notice-period unset | NODE_ID | Cancel an open notice period. Persona-gated |
notify-added | NODE_ID --request-id REQ | Mark a tenant machine request fulfilled (POST /machine-added). Persona-gated |
The portal still exposes these routes under /executors/...; the CLI verb is node because that is the user-facing terminology after the 2026 Provider rename.
Default prices & shared-config
lium provider node add accepts --price as optional. When omitted, the CLI fetches the public, unauthenticated GET /v1/shared-config snapshot from https://lium.io/api (the same data the provider portal frontend uses to populate its Add-Node modal) and looks up the base USD/GPU/hour for --gpu-type. The chosen price is printed to stderr so you can confirm before the call hits the portal.
If the GPU type isn't in the public price table, the CLI exits 1 with ARG_INVALID and lists known types — pass --price explicitly or correct the spelling. To browse all known GPU types interactively, use lium provider machine list.
Override the snapshot URL with the LIUM_SHARED_CONFIG_URL environment variable (useful when pointing at staging or a self-hosted backend).
lium provider config
Portal-account state held server-side — distinct from lium config (CLI-side ~/.lium/config.ini) and lium provider portal (JWT/session). Mutating subcommands run the persona gate.
lium provider config show
lium provider config opt-in # use lium.io's central miner server
lium provider config opt-out # run your own central miner server
lium provider config set-email <EMAIL>
lium provider config set-subscriptions [--gpu TYPE]... # repeat --gpu, or pass none to clear
| Subcommand | Effect |
|---|---|
show | Full GET /auth/me profile |
opt-in / opt-out | Toggle the lium.io central miner server. Persona-gated |
set-email | Update the contact email. Persona-gated |
set-subscriptions | Set machine-request notification subscriptions by GPU type (repeat --gpu); pass none to clear. Persona-gated |
lium provider sync
Batch sync between the portal and the central miner server — the same buttons the portal frontend exposes as "Sync From Miner Server" and "Sync Into Miner Server". Both subcommands are persona-gated.
lium provider sync from-miner-server # pull node state from the central miner server
lium provider sync to-miner-server # push node state to the central miner server
lium provider billing
lium provider billing list [--miner-hotkey HK] [--page N] [--limit N]
Paginated billing-history entries for the active provider, filtered by hotkey if provided.
lium provider machine-request
lium provider machine-request list # all pending tenant requests
lium provider machine-request get <REQ_ID> # single tenant machine request
lium provider machine
lium provider machine list
lium provider machine estimate --gpu-type TYPE --gpu-count N [--gpu-price USD]
| Subcommand | Args | Purpose |
|---|---|---|
list | — | Available GPU machine catalogue |
estimate | --gpu-type, --gpu-count, optional --gpu-price | Estimated rewards for a given GPU configuration |
End-to-end examples
# One-time setup: persist wallet identity so flags aren't needed on every call
lium config set provider.coldkey miner-prod
lium config set provider.hotkey miner-1
# Authenticate against the provider portal
lium provider portal login
lium provider portal whoami
# Health snapshot (registration, portal session, node count, validator weights)
lium provider status
lium provider --json status # JSON envelope for scripts / agents
# Provision: opt in to the lium.io central miner server, then add a node
lium provider config opt-in --yes
# Explicit price (override):
lium provider node add \
--gpu-type "NVIDIA H200 NVL" \
--gpu-count 8 \
--ip 203.0.113.42 \
--port 8080 \
--price 1.85 \
--yes
# Or omit --price to auto-fill from the public shared-config baseline:
lium provider node add \
--gpu-type "NVIDIA H200 NVL" \
--gpu-count 8 \
--ip 203.0.113.42 \
--yes
# Inspect & manage the node
lium provider node list --limit 50
lium provider node get <NODE_ID>
lium provider node pods <NODE_ID>
lium provider node update-price <NODE_ID> --price 2.10 --yes
# Reward forecasting and tenant requests
lium provider machine estimate --gpu-type "NVIDIA H200 NVL" --gpu-count 8
lium provider machine-request list
lium provider node machine-requests <NODE_ID>
lium provider node notify-added <NODE_ID> --request-id <REQ_ID> --yes
# Schedule maintenance, then close out
lium provider node notice-period set <NODE_ID> --yes
# ... maintenance happens ...
lium provider node notice-period unset <NODE_ID> --yes
# Sync state between portal and central miner server
lium provider sync from-miner-server --yes
lium provider sync to-miner-server --yes
# Billing & history
lium provider billing list --page 1 --limit 50
# Drop the token when rotating hotkeys
lium provider portal logout
Add --json to any command for a machine-readable envelope (scripted automation, CI runs, AI-agent loops). Pair with --yes (or LIUM_PROVIDER_ACK=1) to skip the persona prompt on spend-affecting calls.
Exit codes & errors
lium provider … exits with the same codes documented in the CLI reference index. Every subcommand maps a ProviderError to one of:
| Code class | Meaning |
|---|---|
ARG_INVALID | Required flag or argument missing (e.g. --hotkey) |
PORTAL_AUTH_INVALID | JWT missing/expired — run lium provider portal login --force |
PORTAL_CONTRACT | Portal returned an unexpected envelope shape |
PORTAL_SERVER | Portal 5xx — retry with --debug for context |
See also
lium mine— install and start the node binary on the hostlium gpu-splitting— prepare Docker storage for multi-tenant rental- Provider Portal — Overview
- Provider Portal — Managing Nodes
- Provider Portal — Machine Requests
- AI Agents integration guide