---
sidebar_position: 62
description: Reference for the `lium provider` CLI namespace — portal session, node lifecycle, central-miner-server config, sync, billing, and machine-request queries. Mirrors every action the provider portal frontend exposes.
keywords:
  - lium provider
  - lium provider portal
  - lium provider node
  - lium provider config
  - lium provider sync
  - lium provider billing
  - lium provider machine-request
  - lium provider machine
  - lium provider status
  - subnet 51 provider cli
  - miner portal automation
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lium.io/llms.txt
> Use this file to discover all available pages before exploring further.

# `lium provider`

Provider-side CLI for Bittensor Subnet 51. The `lium provider` namespace covers everything the provider portal frontend at [lium.io/portal](https://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`](./mine.md), 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 …`.

```bash
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:

```bash
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`](#lium-provider-portal) | JWT session against the provider portal | no |
| [`status`](#lium-provider-status) | Aggregated provider snapshot | no |
| [`node`](#lium-provider-node) | GPU node lifecycle on the portal | most subcommands yes |
| [`config`](#lium-provider-config) | Portal-account & central-miner-server settings | mutating subcommands yes |
| [`sync`](#lium-provider-sync) | Batch sync between portal and central miner server | yes |
| [`billing`](#lium-provider-billing) | Paginated billing history | no |
| [`machine-request`](#lium-provider-machine-request) | Pending tenant machine requests | no |
| [`machine`](#lium-provider-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/`.

```bash
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 executor list, and validator weights. Sources that fail are skipped and surfaced as `warnings` in the JSON envelope.

```bash
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.

```bash
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](#default-prices--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`](#lium-provider-machine).

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.

```bash
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.

```bash
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`

```bash
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`

```bash
lium provider machine-request list           # all pending tenant requests
lium provider machine-request get <REQ_ID>   # single tenant machine request
```

## `lium provider machine`

```bash
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

```bash
# 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](./index.md#exit-codes). 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`](./mine.md) — install and start the node binary on the host
- [`lium gpu-splitting`](./gpu-splitting.md) — prepare Docker storage for multi-tenant rental
- [Provider Portal — Overview](/providers/portal/overview)
- [Provider Portal — Managing Nodes](/providers/portal/managing-nodes)
- [Provider Portal — Machine Requests](/providers/portal/machine-requests)
- [AI Agents integration guide](../../agents.md)