NodeRings CLI

Install, authenticate, and automate agent registration with the nr command-line tool

The nr CLI is the automation path for NodeRings providers. Use it to authenticate, manage service accounts and agents, and register a provider VM as a peered agent cluster (k3s, Calico, Liqo, and the optional hypervisor operator stack).

If you prefer a guided install from the dashboard, see Agents. Both paths reach the same end state.

Who this is for

You are…	Start here
Registering your first agent from a terminal	Tutorial: Register your first agent
Automating install in CI or on a headless host	How to: Automate with CI
Looking up a flag, env var, or exit code	Reference
Deciding CLI vs UI, or understanding phases	Explanation

Prerequisites (high level)

A verified provider organization (marketplace review approved) — login can succeed while agent APIs still return a pending-review error
A dedicated Ubuntu 22.04+ VM for the agent (2 vCPU / 4 GB RAM minimum; see Agents)
Outbound HTTPS to the NodeRings API and to download install tooling
sudo / root on the agent VM for k3s installation
A hypervisor API token when you install the operator: Get started (Proxmox), Get started (VirtFusion), or Get started (SolusVM 2)

Documentation map

These pages follow the Diátaxis structure:

Tutorials

Learning-oriented. Step-by-step first success with nr.

How-to guides

Task-oriented. Solve a specific job with the CLI.

Reference

Information-oriented. Commands, flags, config, exit codes.

Explanation

Understanding-oriented. How registration, auth, and local state work.

Quick orientation

nr version
export NR_API_TOKEN='<service-account-token>'
echo $NR_API_TOKEN
nr cluster register \
  --name edge-ams-01 \
  --agent-ip 203.0.113.10 \
  --gateway-region AMS01 \
  --org-id <org-uuid>
nr cluster verify --name edge-ams-01 --org-id <org-uuid>

Diagnostic messages go to stderr. Use --output=json on supported commands when you need machine-readable stdout.

Get started (Proxmox) — Proxmox marketplace onboarding
Get started (VirtFusion) — VirtFusion marketplace onboarding
Get started (SolusVM 2) — SolusVM 2 marketplace onboarding
Agents — what the agent stack installs
Access control — roles and service accounts
Provider API — REST equivalents for many CLI actions