# CLI: rxctl

`rxctl` is a command-line tool for the RedSwitches API: list servers and offers, order, power, reverse DNS, SSH keys and cancellation from your terminal or scripts.

> **Note.** `rxctl` is not published yet. This page describes its commands so you can plan for it.

## Set up

`rxctl` reads the key from the environment:

```bash
export REDSWITCHES_API_KEY='rsw_live_XXXX…'
rxctl servers ls
```

Or save it once. `rxctl config set-key` asks for the key without showing it (or reads it from a pipe) and stores it in `~/.config/rxctl/config.json`, readable only by you. The environment variable wins when both are set. `rxctl config show` prints only the key's last four characters.

Every command prints a readable table by default. Add `--json` for the API's JSON, for scripts and `jq`. `rxctl <command> --help` lists a command's options.

## Commands

| Command | Does | Permission |
|---|---|---|
| `rxctl auth verify` | Show the key: label, permissions, expiry. | `read` |
| `rxctl account` | The account; the credit balance with `read_billing`. | `read` |
| `rxctl servers ls` | List servers. | `read` |
| `rxctl servers get srv_123` | One server in detail. | `read` |
| `rxctl servers traffic srv_123` | Data used and the allowance. | `read` |
| `rxctl servers label srv_123 web-1` | Rename a server (`""` clears the label). | `manage` |
| `rxctl offers ls` | Instant servers in stock. | `read` |
| `rxctl offers get ofr_12` | One offer with its prices and OS choices. | `read` |
| `rxctl orders create --offer ofr_12 --os os_31 [--ssh-key sshkey_7] [--label web-1] --dry-run` | Show the exact total. Orders nothing. | `order` |
| `rxctl orders create … --expected-total 15480 [--wait]` | Order; with `--wait`, follow it until ready. | `order` |
| `rxctl orders ls`, `rxctl orders get ord_456` | Your orders and their delivery state. | `read` |
| `rxctl invoices ls`, `rxctl invoices get inv_789` | Your invoices. | `read_billing` |
| `rxctl power reboot srv_123 [--wait]` | Power a server: `on`, `off` or `reboot`. With `--wait`, follow the action to the end. | `power` |
| `rxctl rdns set srv_123 203.0.113.10 mail.example.com` | Request a reverse DNS name. | `manage` |
| `rxctl rdns ls srv_123` | Open reverse DNS requests. | `read` |
| `rxctl ssh-keys ls` | List saved SSH keys. | `read` |
| `rxctl ssh-keys add --name laptop ~/.ssh/id_ed25519.pub` | Save a key. | `ssh_keys` |
| `rxctl ssh-keys rm sshkey_7` | Remove a saved key. | `ssh_keys` |
| `rxctl actions get act_42`, `rxctl actions wait act_42` | Show an action, or wait until it has finished. | `read` |
| `rxctl cancel request srv_123 [--reason "…"]` | Ask for cancellation at the end of the billing period. Beta. | `cancel` |
| `rxctl cancel status srv_123` | Show the cancellation state. Beta. | `read` |
| `rxctl cancel withdraw srv_123` | Ask staff to withdraw it. Beta. | `cancel` |
| `rxctl servers os srv_123` | OS images for a reinstall. Beta. | `read` |
| `rxctl reinstall srv_123 --os img_1042 --ssh-key sshkey_7 [--return-password] [--wait]` | Reinstall (wipes the disks). Beta, only where RedSwitches turned reinstall on. | `reinstall` |
| `rxctl rescue srv_123 [--return-password] [--wait]` | Boot into rescue mode. Beta. | `rescue` |
| `rxctl actions credentials act_44` | Read a password made with `--return-password`. Works once. Beta. | `read` |

`power`, `rdns`, `cancel`, `reinstall` and `rescue` also work under `servers`, for example `rxctl servers power reboot srv_123`.

## Examples

Order with a dry run first:

```bash
rxctl orders create --offer ofr_12 --os os_31 --ssh-key sshkey_7 --dry-run
# Total: 154.80 USD (15480)  Recurring: 129.00 USD  Paid from credit
rxctl orders create --offer ofr_12 --os os_31 --ssh-key sshkey_7 --label web-1 \
  --expected-total 15480 --wait
```

Reboot and wait:

```bash
rxctl power reboot srv_123 --wait
```

Get IPs for a script:

```bash
rxctl servers ls --json | jq -r '.data[] | [.id, .label, .primary_ip] | @tsv'
```

## Safety

- Commands that stop or change a server or spend money ask `[y/N]` first: `power off`, `reinstall`, `rescue`, `cancel request` and `orders create`. Add `--yes` (or `-y`) to skip the question in scripts. Without a terminal and without `--yes` they do nothing.
- `orders create` always runs a dry run first and shows the total before it asks. With `--yes` it also needs `--expected-total`, so a new price is never accepted unseen.
- Each write gets its own Idempotency-Key. Pass `--idempotency-key` to choose it, and use the same one to repeat a command whose answer you lost. `rxctl` retries only on network errors, `429`, `503` and `in_progress`, with the same key, so a retried command never orders or reboots twice.
- `--wait` honours `poll_after` from the API.
- Exit status is non-zero on any error, and the error code (for example `price_changed`) is printed with the request id. It is `1` for an API error or a `--wait` that did not end `done`, `2` for a mistyped command and `3` when you answered no.
- With `--return-password` and `--wait`, the password is printed once at the end. Store it then: the API does not return it again.