Install the rack4 command-line tool

rack4 does from a terminal most of what the panel does in a browser. It lists and controls your servers, opens SSH, edits the firewall, takes snapshots, sets reverse DNS and shows invoices. It's one file with nothing else to install, and it uses the same API you can call with curl.

To install it, run the install script (Linux and macOS) or download the file for your system and check it against SHA256SUMS, then log in with an API token using rack4 init or rack4 login. The steps for each system are below, and the cheat sheet lists every command once you're set up.

What you need#

• Linux or macOS on Intel/AMD or ARM, or Windows 10 or later. An OpenSSH client for rack4 ssh (all three include one).
• An API token: read and write to change things, read only to look.

Install with one command (Linux and macOS)#

Once the downloads are published, this downloads the right file for your system, checks it against SHA256SUMS, and asks before it puts rack4 in ~/.local/bin:

curl -fsSL https://rack4.io/cli/install.sh | sh

Add options after sh -s --: --yes installs without asking, --system installs to /usr/local/bin (with sudo unless you're root), and --dir DIR picks another folder. For example:

curl -fsSL https://rack4.io/cli/install.sh | sh -s -- --yes --system

If the checksum doesn't match, or SHA256SUMS has no line for the file, it stops and installs nothing. The checksum file comes from the same place as the download, so it catches a broken or swapped file on the way, not a compromised download site. Until the downloads are published, the script only says so and installs nothing. You can read it before you run it: curl -fsSL https://rack4.io/cli/install.sh | less. On Windows, follow the steps below.

Download it#

The downloads go at https://rack4.io/downloads/vps9/; they aren't published yet, and until they are, the API and the panel do everything the CLI does. There's one file per system:

Next to them is SHA256SUMS, with a checksum for each file. Download that as well. On Linux, for example:

curl -LO https://rack4.io/downloads/vps9/rack4-linux-amd64
curl -LO https://rack4.io/downloads/vps9/SHA256SUMS

Check the download#

Your file's checksum has to match its line in SHA256SUMS. On Linux, sha256sum checks it for you and prints OK:

sha256sum --ignore-missing -c SHA256SUMS

On macOS, print both and compare them by eye:

shasum -a 256 rack4-darwin-arm64
grep rack4-darwin-arm64 SHA256SUMS

On Windows, in PowerShell:

(Get-FileHash .\rack4-windows-amd64.exe -Algorithm SHA256).Hash.ToLower()
Select-String rack4-windows-amd64.exe .\SHA256SUMS

If the two don't match, delete the file and download it again.

Put it on your PATH#

On Linux and macOS:

chmod +x rack4-linux-amd64
sudo mv rack4-linux-amd64 /usr/local/bin/rack4
rack4 version

macOS may refuse to run it the first time, because it was downloaded from the internet. Allow it under System Settings > Privacy & Security, or remove the quarantine flag with xattr -d com.apple.quarantine /usr/local/bin/rack4.

On Windows, rename the file to rack4.exe and move it to a folder that's on your PATH, or run it from where it is.

Log in#

Make a token under tokens in the panel (how). Choose read and write if you want to change things. read only is enough for looking.

Save the token in a file only you can read, then hand that file to rack4 login:

rack4 login < ~/.rack4-token

In PowerShell, pipe it in instead: Get-Content ~\.rack4-token | rack4 login.

You can also run plain rack4 login and paste the token at the prompt. It shows on screen as you paste, though, so the file is the better habit.

Either way, rack4 checks the token with the API. Then it prints the account the token belongs to and where it saved it, in your user's config folder:

• Linux: ~/.config/rack4/config.json
• macOS: ~/Library/Application Support/rack4/config.json
• Windows: %AppData%\rack4\config.json

On Linux and macOS the file is readable only by you.

For a script, or a machine you share, skip the saved login and set the token in the environment. It takes priority over a saved one:

export RACK4_TOKEN="$(cat ~/.rack4-token)"

rack4 logout deletes the saved token from your machine. The token itself still works until you revoke it in the panel, so do that too if it may have leaked.

Check it worked#

rack4 whoami
rack4 servers

The first prints the email of the account the token belongs to; the second, a table of your servers with their id, hostname, state, IPv4 and plan. rack4 --json whoami shows the account and your role on it if you're on a team.

Or set it up in one go#

rack4 init walks you through the first run: it asks for a token (or reads it from --token-file), checks and saves it the way rack4 login does, then offers to add your SSH public key to your account so new servers can use it.

rack4 init --token-file ~/.rack4-token

It looks for ~/.ssh/id_ed25519.pub, then id_ecdsa.pub, then id_rsa.pub, shows the key's fingerprint and asks before adding it. If a key with the same fingerprint is already on your account, it says so and adds nothing. Point it at another file with --key ~/.ssh/work.pub, or skip the key with --no-key. With --yes it adds the key without asking. If you have no key yet, it tells you how to make one with ssh-keygen -t ed25519.

First commands#

rack4 servers                               # your servers
rack4 servers show web-1                    # details and recent events
rack4 ssh web-1                             # runs your own ssh client as root@ the server's IPv4
rack4 servers reboot web-1
rack4 firewall web-1                        # the inbound rules
rack4 snapshots web-1 create before-upgrade
rack4 rdns web-1                            # reverse DNS for each address
rack4 invoices

Name a server by its hostname or by its id (srv_…). rack4 ssh needs an OpenSSH client on your machine, which macOS, Linux and current Windows all include. To log in as someone other than root, put --user before the server: rack4 ssh --user deploy web-1. Anything after -- goes to ssh as it is, as in rack4 ssh web-1 -- -L 8080:localhost:80.

A snapshot shuts a running server down while it's taken and starts it again afterwards, so pick a quiet moment.

Commands that destroy something ask you to type the server's hostname first: servers delete, servers reinstall, snapshots revert and snapshots rm. keys rm asks for the key's name. Add --yes to skip the question in a script.

rack4 help lists every command.

Scripts and JSON#

Add --json to get JSON instead of a table. For lists, that's just the array. It works well with jq:

rack4 servers --json | jq -r '.[] | select(.state == "running") | .ipv4'

Every command takes --json, including login, logout, version, status, open and init, which print a small JSON object of their own (never the token). ssh is the one exception: it hands over to your ssh client.

rack4 exits with 0 when the command worked, 1 when it failed and 2 when the command line itself was wrong. Errors go to stderr with the API's own message.

To order a server with a one-click app, extra packages or a first-boot script, add --app, --package (once per package) and --setup-script:

rack4 servers create --plan standard --image ubuntu-24.04 --hostname web-1 --key key_… \
  --app docker --package htop --package git --setup-script ./setup.sh

rack4 servers create sends an Idempotency-Key with every order, so a retry can't place a second one. If the answer gets lost on the way back, rack4 prints the key and the command to repeat with --idempotency-key. The order makes an invoice to pay, and the server is built once it's paid, straight away if your account credit covers it.

The API address is https://my.rack4.io unless you set --api or RACK4_API. rack4 only talks to it over https, except on localhost, and never follows a redirect.

Tab completion#

rack4 completion prints a completion script for bash, zsh, fish or PowerShell. It completes commands and subcommands, and your servers' hostnames where a command takes a server. Load it from your shell's startup file:

# bash, in ~/.bashrc
source <(rack4 completion bash)
# zsh, in ~/.zshrc after compinit
source <(rack4 completion zsh)
# fish, once
rack4 completion fish > ~/.config/fish/completions/rack4.fish

In PowerShell, add rack4 completion powershell | Out-String | Invoke-Expression to your $PROFILE.

Hostnames come from the API using your saved login or RACK4_TOKEN, with a three-second limit per Tab press. Without a login, only the commands complete; nothing is printed on errors.

Open the panel#

rack4 open opens the panel in your browser, and rack4 open web-1 opens that server's page. On a machine without a browser, such as over SSH, add --print to get the address instead. It only ever opens http and https addresses on the panel's own host.

Service status#

rack4 status shows the same summary as the status page: each part of the service, its uptime over 90 days, open incidents and planned maintenance. It needs no login. rack4 --json status prints the API's answer as it is, so a script can check .status.level:

rack4 --json status | jq -r .status.level     # operational, maintenance, degraded, partial_outage or major_outage

Troubleshooting#

rack4: command not found after the install script. ~/.local/bin isn't on your PATH yet. Add export PATH="$HOME/.local/bin:$PATH" to ~/.bashrc or ~/.zshrc and open a new terminal, or install with --system instead.

rack4: not logged in: run rack4 login (or set RACK4_TOKEN). No token is saved and RACK4_TOKEN is empty. Run rack4 login < ~/.rack4-token.

rack4: Send a valid API token: Authorization: Bearer vps9_… The token was revoked, expired or pasted with extra characters. Make a new one and log in again.

rack4: the API address must look like https://my.rack4.io. RACK4_API or --api ends in /api/v1. The CLI wants the panel's address, https://my.rack4.io, without the path. The TypeScript SDK takes that form too, so one RACK4_API=https://my.rack4.io works for both. Unless you're pointing at a test copy of the API, leave it unset.

macOS says the developer can't be verified. See Put it on your PATH: allow it in Privacy & Security or remove the quarantine flag.

Next steps#

• rack4 CLI cheat sheet: every command by task.
• Automate snapshots before risky changes with the CLI.
• API tokens for CI and automation, for rack4 in a pipeline.
• The plans you can order with rack4 servers create.