In one paragraph: rarecloud is the official command-line client for RareCloud. It is a thin wrapper over the public API at https://api.rarecloud.io/v1, so anything it does you could also do with curl, and it works on cloud VMs, managed Kubernetes clusters, classic VPS, volumes, networks, load balancers, Object Storage, domains, billing and tickets. Two short aliases, rcloud and rare, are installed with it. This page covers version 0.3.0. Releases are on GitHub.
Install
macOS and Linux, with Homebrew
brew install rarecloudio/tap/rarecloud
macOS and Linux, with the install script
curl -fsSL https://raw.githubusercontent.com/RareCloudio/rarecloud-cli/main/install.sh | sh
Debian, Ubuntu, RHEL, Fedora
Download the .deb or .rpm for your architecture (amd64 or arm64) from the latest release and install it:
sudo dpkg -i rarecloud_0.3.0_linux_amd64.deb # Debian, Ubuntu
sudo rpm -i rarecloud_0.3.0_linux_amd64.rpm # RHEL, Fedora
Windows
Download rarecloud_0.3.0_windows_amd64.zip from the latest release, unzip it and put rarecloud.exe somewhere on your PATH.
Check it
rarecloud --version # rarecloud version 0.3.0
rarecloud upgrade --check
rarecloud upgrade replaces the binary with the newest release. Homebrew and package installs can also update the usual way.
Authenticate
Create a token in the console under Account, then API tokens. Pick the scopes the CLI needs: services:read and services:write for servers and cloud resources (Object Storage included), billing:read for balance and invoices, domains:read / domains:write for domains, tickets:read / tickets:write for support, account:read for the profile. Scopes match exactly, so :write does not include :read. A token can also carry an expiry date and a rate limit of 1 to 600 requests a minute.
Then either save it:
rarecloud auth login # paste the token, or: echo "$TOKEN" | rarecloud auth login
rarecloud auth whoami
or set it for the current shell:
export RARECLOUD_TOKEN=rc_pat_...
The saved token lives in config.toml in your user config folder: ~/.config/rarecloud/ on Linux, ~/Library/Application Support/rarecloud/ on macOS, %AppData%\rarecloud\ on Windows. The file is readable only by you (mode 0600). The token you paste is shown on screen, so pipe it in on a shared or recorded terminal. Every command also accepts --token to override it for one call.
Global flags
| Flag | What it does |
|---|---|
-o, --output table|json | Table for people (default), JSON for scripts and jq |
--token | API token for this call only |
--api | API base URL, default https://api.rarecloud.io |
--idempotency-key | The key a create command sends. By default each create makes a fresh one; pass the key a failed create printed to retry it without creating a duplicate (see Safe retries) |
-h, --help | Help for any command, for example rarecloud server create --help |
Every command, by area
Generated from the 0.3.0 release binary. <id> values come from the matching list command.
Authentication
| Command | What it does |
|---|---|
rarecloud auth login | Save an API token to your config file (paste it or pipe it in) |
rarecloud auth logout | Clear the locally-saved API token |
rarecloud auth whoami | Print the email of the current API token's owner |
Catalog
| Command | What it does |
|---|---|
rarecloud catalog details <product-sku> | Show live product details (region availability, pricing, config options) |
rarecloud catalog images | List available OS images |
rarecloud catalog plans <product-sku> | Show plans (sizes + prices) for a product |
rarecloud catalog products | List all orderable products. Flags: --backend, --category, --kind |
rarecloud catalog regions | List available regions (datacenter slugs) |
Servers
| Command | What it does |
|---|---|
rarecloud server backup create <server-id> | Create a new backup (classic VPS) |
rarecloud server backup list <server-id> | List backups for a server (classic VPS) |
rarecloud server check | Ask whether a server create with the same flags would be accepted, without creating anything. Exit code 0 accepted, 2 refused, 1 error. Flags: --image, --name, --plan, --region, --ssh-key, --tag |
rarecloud server console <server-id> | Get the web console (noVNC) URL for a server |
rarecloud server create | Provision a new server. Flags: --image, --name, --plan, --region, --ssh-key, --tag |
rarecloud server destroy <server-id> | Permanently destroy a server (irreversible; refuses without --yes). Aliases delete, rm. Flags: --yes |
rarecloud server get <server-id> | Show details for a single server |
rarecloud server list | List your servers |
rarecloud server metrics <server-id> | Resource usage for a server; cloud VMs return CPU, memory, disk and network time series. Flags: --json, --range |
rarecloud server rdns delete <server-id> | Remove the PTR record for a cloud VM's primary IPv4 |
rarecloud server rdns get <server-id> | Read the PTR record for a cloud VM's primary IPv4 |
rarecloud server rdns set <server-id> | Set the PTR record for a cloud VM's primary IPv4. Flags: --hostname |
rarecloud server reboot <server-id> | Soft-reboot a server |
rarecloud server reinstall <server-id> | Reinstall (destructively rebuild) a cloud VM from a chosen image. Flags: --image, --password, --ssh-key |
rarecloud server reset-password <server-id> | Reset the root password on a running cloud VM (live, non-destructive). Flags: --generate, --password |
rarecloud server resize <server-id> | Resize a cloud VM to a different plan (async). Flags: --flavor |
rarecloud server start <server-id> | Power on a server |
rarecloud server stop <server-id> | Power off a server |
rarecloud server tag set <server-id> <tag>... | Replace a cloud VM's tags with the given ones |
rarecloud server tag clear <server-id> | Remove every tag from a cloud VM |
Managed Kubernetes
| Command | What it does |
|---|---|
rarecloud server kubeconfig <cluster-id> | Fetch a short-lived admin kubeconfig for a managed Kubernetes cluster. Flags: --output-file |
rarecloud server kubeconfigs create <cluster-id> | Create a long-lived kubeconfig credential (revocable any time). Flags: --name, --output-file, --role, --ttl |
rarecloud server kubeconfigs download <cluster-id> <credential-id> | Re-download the kubeconfig for an active credential. Flags: --output-file |
rarecloud server kubeconfigs list <cluster-id> | List long-lived kubeconfig credentials for a cluster |
rarecloud server kubeconfigs revoke <cluster-id> <credential-id> | Revoke a credential (immediate: its kubeconfig stops working) |
rarecloud server scale <cluster-id> | Show or set worker min/max for a managed Kubernetes cluster. Flags: --max, --min |
Volumes, networks and load balancers
| Command | What it does |
|---|---|
rarecloud firewall attach <id> | Attach a firewall to a cloud VM. Flags: --server |
rarecloud firewall create | Create a new firewall. Flags: --name |
rarecloud firewall delete <id> | Delete a firewall |
rarecloud firewall detach <id> | Detach a firewall from a cloud VM. Flags: --server |
rarecloud firewall get <id> | Show a firewall and its rules |
rarecloud firewall list | List your firewalls |
rarecloud firewall rule add <firewall-id> | Add a rule to a firewall. Flags: --description, --direction, --port, --protocol, --source |
rarecloud firewall rule rm <firewall-id> <rule-id> | Remove a rule from a firewall |
rarecloud load-balancer add-member <lb-id> | Add a cloud VM as a member. Flags: --port, --server |
rarecloud load-balancer create | Create an L4 load balancer. It answers at once and finishes setting up in the background; --wait blocks until it is active. Flags: --member, --name, --port, --wait, --wait-timeout |
rarecloud load-balancer delete <id> | Delete a load balancer (alias rm); --wait blocks until it is gone. Flags: --wait, --wait-timeout |
rarecloud load-balancer get <id> | Show one load balancer (incl. members) |
rarecloud load-balancer list | List your load balancers |
rarecloud load-balancer remove-member <lb-id> <member-id> | Remove a member from the load balancer |
rarecloud network attach-vm <network-id> | Attach a cloud VM to this network. Flags: --vm |
rarecloud network create | Create a private network. Flags: --name |
rarecloud network delete <id> | Delete a network (must have no attached VMs) |
rarecloud network get <id> | Show one network |
rarecloud network list | List your private networks |
rarecloud reserved-ip attach <id> | Attach a reserved IP to a cloud VM. Flags: --server |
rarecloud reserved-ip create | Reserve a new public IP (billed while reserved). Flags: --server |
rarecloud reserved-ip detach <id> | Detach a reserved IP from its VM (stays reserved + billed) |
rarecloud reserved-ip list | List your reserved IPs |
rarecloud reserved-ip release <id> | Release a reserved IP (stops billing, IP returns to the pool) |
rarecloud volume attach <id> | Attach a volume to a cloud VM. Flags: --server |
rarecloud volume create | Create a block volume (billed per GB while it exists). Flags: --name, --size |
rarecloud volume delete <id> | Delete a volume (stops billing; must be detached) |
rarecloud volume detach <id> | Detach a volume from its VM. Flags: --server |
rarecloud volume get <id> | Show one volume |
rarecloud volume list | List your volumes |
Object Storage
| Command | What it does |
|---|---|
rarecloud object-storage regions | List the regions a bucket can be created in |
rarecloud object-storage enable | Enable Object Storage (starts the monthly base fee). Optional: the first bucket enables it too |
rarecloud object-storage status | Status, usage, this month's charge and the price card (alias get) |
rarecloud object-storage usage | Daily usage for the whole account (stored, egress, CDN). Flags: --days |
rarecloud object-storage disable | Delete the Object Storage account for good; refused while any bucket or active key exists. Flags: --yes |
rarecloud bucket create <name> | Create a bucket named <handle>-<name>; --handle is required on your first bucket and never changes. Flags: --handle, --region, --versioning |
rarecloud bucket list | List your buckets |
rarecloud bucket get <id> | Show one bucket |
rarecloud bucket update <id> | Turn versioning on or off. Public delivery is not available yet, so --public on is refused. Flags: --versioning |
rarecloud bucket usage <id> | Daily usage for one bucket (stored, CDN). Flags: --days |
rarecloud bucket rm <id> | Delete a bucket; a bucket with objects needs --purge (alias delete). Flags: --purge, --yes |
rarecloud object-storage key create | Create an S3 access key for every bucket or a list of bucket ids, read or readwrite. The secret is shown once. Flags: --access, --buckets, --name |
rarecloud object-storage key list | List access keys (never shows a secret) |
rarecloud object-storage key rm <id> | Revoke an access key (aliases revoke, delete). Flags: --yes |
Billing and orders
| Command | What it does |
|---|---|
rarecloud credit balance | Show current credit balance |
rarecloud credit state | Show cloud billing state: any open cloud invoice, the dated suspension schedule, and the runway |
rarecloud invoice list | List invoices for the current account |
rarecloud order get <id> | Show one order (incl. the service line items it created) |
rarecloud order list | List your orders (newest first) |
rarecloud payment-method add | Add a payment method (backend may not support stored instruments). Flags: --name, --type |
rarecloud payment-method list | List available payment methods |
rarecloud payment-method remove <id> | Remove a payment method |
Account and security
| Command | What it does |
|---|---|
rarecloud account show | Show the current account profile |
rarecloud ssh-key add | Register a new SSH public key. Flags: --file, --key, --name |
rarecloud ssh-key list | List your registered SSH keys |
rarecloud ssh-key remove <key-id> | Unregister an SSH key (does NOT touch authorized_keys on existing servers) |
rarecloud token create | Create a new API token (token shown ONCE, not retrievable later). Flags: --expires, --label, --rate-limit-rpm, --scopes |
rarecloud token list | List your API tokens |
rarecloud token revoke <token-id> | Revoke an API token (immediate, no propagation delay) |
rarecloud 2fa disable | Disable 2FA. Flags: --code |
rarecloud 2fa enable | Enable 2FA with a code from your authenticator (returns one-time backup codes). Flags: --code |
rarecloud 2fa setup | Begin 2FA setup (returns the secret + otpauth URL to add to your authenticator) |
rarecloud 2fa status | Show 2FA status |
Domains
| Command | What it does |
|---|---|
rarecloud domain available <domain> | Check whether a domain is available to register |
rarecloud domain contacts get <id> | Show a domain's registrant contact |
rarecloud domain contacts update <id> | Update a domain's registrant contact (only the flags you pass change). Flags: --address1, --address2, --city, --country, --email, --first-name, --last-name, --organisation, --phone, --postcode, --state |
rarecloud domain dns get <id> | Show a domain's DNS host records |
rarecloud domain dns update <id> | Replace a domain's DNS records from a JSON file ([{hostname,type,address,priority?}]). Flags: --records-file |
rarecloud domain get <id> | Show details for one domain |
rarecloud domain list | List your domains |
rarecloud domain nameservers get <id> | Show a domain's nameservers |
rarecloud domain nameservers update <id> | Replace a domain's nameservers (2-5 required). Flags: --nameserver |
rarecloud domain register <domain> | Register a new domain (places an order + invoice; fulfils on payment). Flags: --dns-management, --id-protection, --nameserver, --years |
rarecloud domain renew <id> | Renew a domain (optionally toggle auto-renew). Flags: --auto-renew, --no-auto-renew, --years |
rarecloud domain tld-pricing | Show register / transfer / renew prices per TLD |
rarecloud domain transfer <domain> | Transfer a domain in (places an order; needs the EPP/auth code). Flags: --epp, --id-protection, --nameserver, --years |
Support tickets
| Command | What it does |
|---|---|
rarecloud ticket close <id> | Close a ticket |
rarecloud ticket create | Open a new support ticket. Flags: --attach, --body, --department, --priority, --subject |
rarecloud ticket departments | List support departments (ids for ticket create --department) |
rarecloud ticket get <id> | Show one ticket (incl. messages) |
rarecloud ticket list | List your support tickets. Flags: --status |
rarecloud ticket reply <id> | Reply to a ticket. Flags: --body |
Keeping the CLI current
| Command | What it does |
|---|---|
rarecloud upgrade | Replace the binary with the newest GitHub release (--check only looks). Flags: --check |
A note on two groups: rarecloud token commands call the token endpoints, which the API only allows from a signed-in console session, so with an API token they return a permission error. Create and revoke tokens in the console. rarecloud payment-method add depends on the payment backend and may not store an instrument. |
Recipes
Deploy a Cloud VM
rarecloud catalog plans g-2vcpu-8gb # sizes and prices
rarecloud ssh-key add --name laptop --file ~/.ssh/id_ed25519.pub
rarecloud ssh-key list # note the key id
rarecloud server check --plan g-2vcpu-8gb --image ubuntu-24.04 \
--region bucharest-ro --name web-01 --ssh-key <key-id> # would it be accepted?
rarecloud server create --plan g-2vcpu-8gb --image ubuntu-24.04 \
--region bucharest-ro --name web-01 --ssh-key <key-id>
rarecloud server list
rarecloud server tag set <server-id> web prod # optional labels
server check takes the same flags as server create and creates, holds and charges nothing. It prints the verdict, and when the order would be refused it says why and links to the add-funds or pay-invoice page. Its exit code (0 accepted, 2 refused, 1 error) lets a script stop before the real order. Tags are optional: set them at create with --tag (repeatable) or later with server tag set.
Add a volume
rarecloud volume create --name web-01-data --size 50
rarecloud volume attach <volume-id> --server <server-id>
Volumes are billed per GB while they exist. Format and mount the disk inside the VM.
Put a load balancer in front
rarecloud load-balancer create --name web --port 443 \
--member <server-id> --member <server-id> --wait
rarecloud load-balancer get <lb-id>
The load balancer exists as soon as the command answers; its listener, members and public IP are then set up in the background, which takes a few minutes. --wait blocks until it is active (15 minutes at most by default, change it with --wait-timeout). Without --wait, check load-balancer get instead of creating it again.
Store files in Object Storage
rarecloud object-storage regions # pick a region id
rarecloud bucket create photos --region eu-central-1 --handle acme # becomes acme-photos
rarecloud object-storage key create --name ci --access readwrite --buckets "*"
rarecloud bucket list
The first bucket chooses your handle for good and starts the monthly base fee. The key's secret is printed once, so store it right away. Any S3 tool works with it, using the endpoint that object-storage regions lists for the bucket's region.
Work with a Kubernetes cluster
Create the cluster in the console or through the MCP server; the CLI then handles access and scaling:
rarecloud server kubeconfig <cluster-id> -f kubeconfig.yaml # short-lived admin
rarecloud server kubeconfigs create <cluster-id> --name ci \
--role view --ttl 90d -f ci-kubeconfig.yaml # long-lived, revocable
rarecloud server scale <cluster-id> --min 2 --max 4
KUBECONFIG=kubeconfig.yaml kubectl get nodes
Check balance and invoices
rarecloud credit balance
rarecloud credit state # open cloud invoice, dated suspension schedule, runway
rarecloud invoice list
rarecloud credit balance -o json | jq .
Destroy
rarecloud volume detach <volume-id> --server <server-id>
rarecloud volume delete <volume-id>
rarecloud server destroy <server-id> --yes # refuses to run without --yes
server destroy, bucket rm, object-storage key rm and object-storage disable refuse to run without --yes. volume delete, reserved-ip release, network delete, firewall delete and load-balancer delete act at once, so double-check the id.
Safe retries
Every create command (server, volume, network, firewall, load balancer, reserved IP, bucket, access key, domain, ticket and the like) sends an Idempotency-Key. If the answer is lost to a dropped connection or a timeout, the CLI retries up to 2 times with the same key and the API runs the create only once. If it still fails, the error prints the key:
rarecloud server create --plan g-2vcpu-8gb --image ubuntu-24.04 --region bucharest-ro \
--name web-01 --ssh-key <key-id> --idempotency-key 5f0c6c1e-8a43-4b8e-9f2a-0d4a2f6e9b17
Run the same command with that key and you get the original result back instead of a second server. A one-time secret, such as a console password, is shown only in the first answer.
Troubleshooting
| What you see | What it means |
|---|---|
token cannot be empty or a rejected token on login | Paste the whole token; it starts with rc_pat_. |
| A permission error | The token lacks a scope for that command. Add it on a new token; :write does not include :read. |
Too many requests (HTTP 429) | The token hit its requests-per-minute limit. Wait for the Retry-After seconds or use a token with a higher limit. |
server create refuses the order | Run server check with the same flags: it says why. Check the plan, image and region with catalog plans, catalog images and catalog regions; for cloud VMs the region is bucharest-ro. Your account limits and balance also apply. |
| A create failed mid-way | Retry the same command with the --idempotency-key the error printed. You get the original result, not a duplicate. |
RESOURCE_PROTECTED | API access is switched off for that resource in the console, so tokens can read it but not change it. Turn it back on in the console if the change is wanted. server get, volume get, network get, load-balancer get and domain get print the resource's API access on stderr. |
BACKEND_UNAVAILABLE (HTTP 503) | The API is briefly busy. Wait the Retry-After seconds and run it again; for a create, reuse the same --idempotency-key. |
| Output is hard to script | Add -o json. |
Links
- Releases: github.com/RareCloudio/rarecloud-cli
- API reference: console.rarecloud.io/docs/api
- Step-by-step tutorial: Automate your VPS with the RareCloud CLI
- The same API for agents and as code: MCP docs and Terraform docs