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.

Set up

rxctl reads the key from the environment:

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:

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:

rxctl power reboot srv_123 --wait

Get IPs for a script:

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.