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

# CLI

> Manage CloudBlast servers, backups, IPs, and security groups from the terminal

# CloudBlast CLI

The `cloudblast` CLI wraps the full CloudBlast API v2 — everything you can do in the console or via the API, you can do from your terminal or scripts. All output is JSON, so it composes with `jq` and works well in automation and cron jobs.

## Installation

```bash theme={null}
npm install -g @cloudblast/cli
```

Or run without installing:

```bash theme={null}
npx @cloudblast/cli servers list
```

## Authentication

Get an API token from [Account Settings](https://console.cloudblast.io/settings/api), then export it:

```bash theme={null}
export CLOUDBLAST_API_TOKEN=your-api-token
```

You can also pass `--token your-api-token` on any command.

| Variable               | Required | Description                                                    |
| ---------------------- | -------- | -------------------------------------------------------------- |
| `CLOUDBLAST_API_TOKEN` | Yes      | Your CloudBlast API token                                      |
| `CLOUDBLAST_API_URL`   | No       | API base URL (default: `https://console.cloudblast.io/api/v2`) |

## Quick Examples

```bash theme={null}
# List your servers
cloudblast servers list

# Create an Ubuntu 24.04 server
cloudblast servers create --plan 1 --location 2 --template ubuntu-24-04 --hostname web-01

# Restart a server
cloudblast servers power abc12345 restart

# Take a backup
cloudblast backups create abc12345 nightly --mode snapshot

# Open SSH on a security group
cloudblast security-groups add-rule 5 --type inbound --action ACCEPT --protocol tcp --destination-port 22
```

## Command Reference

### Account

| Command                                    | Description                                        |
| ------------------------------------------ | -------------------------------------------------- |
| `cloudblast account get`                   | Account info (name, email, credit balance, limits) |
| `cloudblast account usage`                 | Resource usage across all servers vs your limits   |
| `cloudblast account invoices [--page <n>]` | List invoices                                      |

### Plans & Locations

| Command                                        | Description                              |
| ---------------------------------------------- | ---------------------------------------- |
| `cloudblast plans list [--page <n>]`           | List server plans with pricing and specs |
| `cloudblast locations list`                    | List data center locations               |
| `cloudblast locations templates <location-id>` | List OS templates for a location         |

### SSH Keys

| Command                                            | Description                                    |
| -------------------------------------------------- | ---------------------------------------------- |
| `cloudblast ssh-keys list`                         | List SSH keys                                  |
| `cloudblast ssh-keys add <name> --key-file <path>` | Add a key from a file (or inline with `--key`) |
| `cloudblast ssh-keys delete <id>`                  | Remove an SSH key                              |

### Servers

| Command                                                                                       | Description                                            |
| --------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| `cloudblast servers list [--page <n>] [--status <status>]`                                    | List servers                                           |
| `cloudblast servers create --plan <id> --location <id> --template <slug> [--hostname <name>]` | Create a server                                        |
| `cloudblast servers get <server>`                                                             | Full server details                                    |
| `cloudblast servers credentials <server>`                                                     | Login credentials                                      |
| `cloudblast servers status <server>`                                                          | Real-time hypervisor status                            |
| `cloudblast servers power <server> <action>`                                                  | start, shutdown, restart, reset, kill, suspend, resume |
| `cloudblast servers rename <server> <name>`                                                   | Rename a server                                        |
| `cloudblast servers reinstall <server> --template <slug> [--password <pw>] --yes`             | Reinstall (all data lost)                              |
| `cloudblast servers delete <server> --yes`                                                    | Permanently delete a server                            |

### Server IPs

| Command                                                 | Description              |
| ------------------------------------------------------- | ------------------------ |
| `cloudblast ips list <server>`                          | List IPv4/IPv6 addresses |
| `cloudblast ips add <server> --count <n>`               | Allocate additional IPs  |
| `cloudblast ips remove <server> <address>`              | Remove a secondary IP    |
| `cloudblast ips set-rdns <server> <address> <hostname>` | Set reverse DNS (PTR)    |

### Backups

| Command                                                                            | Description           |
| ---------------------------------------------------------------------------------- | --------------------- |
| `cloudblast backups list <server> [--page <n>]`                                    | List backups          |
| `cloudblast backups create <server> <name> [--mode <mode>] [--compression <type>]` | Create a backup       |
| `cloudblast backups restore <server> <backup-uuid> --yes`                          | Restore from a backup |
| `cloudblast backups delete <server> <backup-uuid> --yes`                           | Delete a backup       |

### Security Groups (Firewall)

| Command                                                                                                  | Description                           |
| -------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| `cloudblast security-groups list`                                                                        | List security groups                  |
| `cloudblast security-groups create <name> [--description <text>]`                                        | Create a group                        |
| `cloudblast security-groups get <id>`                                                                    | Group with rules and attached servers |
| `cloudblast security-groups delete <id>`                                                                 | Delete a group                        |
| `cloudblast security-groups add-rule <group-id> --type <dir> --action <action> --protocol <proto> [...]` | Add a firewall rule                   |
| `cloudblast security-groups delete-rule <group-id> <rule-id>`                                            | Remove a rule                         |
| `cloudblast security-groups attach <group-id> <server>`                                                  | Attach a server                       |
| `cloudblast security-groups detach <group-id> <server>`                                                  | Detach a server                       |

## Destructive Operations

Commands that destroy data — `servers delete`, `servers reinstall`, `backups restore`, and `backups delete` — refuse to run without the `--yes` (`-y`) flag, so scripts must opt in explicitly.

## Scripting

Every command prints JSON and exits non-zero on failure:

```bash theme={null}
# Get the primary IP of each server
cloudblast servers list | jq -r '.data[].primary_ip'

# Nightly backup from cron
cloudblast backups create abc12345 "nightly-$(date +%F)" --mode snapshot
```