# Install the rack4 command-line tool

> Download rack4 for Linux, macOS or Windows, check it against SHA256SUMS, log in with an API token, and run your first commands.

Source: https://rack4.io/help/install-the-rack4-cli · Updated: 2026-11-01

`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](https://rack4.io/help/api-quickstart) 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](https://rack4.io/help/rack4-cli-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](https://rack4.io/help/api-tokens): 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`:

```bash
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:

```bash
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](https://rack4.io/help/api-quickstart) and the panel do everything the CLI does. There's one file per system:

| System | File |
| --- | --- |
| Linux on Intel or AMD | `rack4-linux-amd64` |
| Linux on ARM (Graviton, Ampere, Raspberry Pi 4 and later with a 64-bit OS) | `rack4-linux-arm64` |
| macOS on Apple silicon | `rack4-darwin-arm64` |
| macOS on Intel | `rack4-darwin-amd64` |
| Windows | `rack4-windows-amd64.exe` |
| Windows on ARM | `rack4-windows-arm64.exe` |

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

```bash
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`:

```bash
sha256sum --ignore-missing -c SHA256SUMS
```

On macOS, print both and compare them by eye:

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

On Windows, in PowerShell:

```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:

```bash
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](https://rack4.io/help/api-tokens)). 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`:

```bash
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:

```bash
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

```bash
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](https://rack4.io/help/teams).

## 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.

```bash
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

```bash
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](https://rack4.io/help/snapshots) 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`:

```bash
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](https://rack4.io/help/one-click-apps), extra packages or a [first-boot script](https://rack4.io/help/setup-scripts), add `--app`, `--package` (once per package) and `--setup-script`:

```bash
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
# 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](https://rack4.io/status): 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`:

```bash
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](https://rack4.io/tutorials/script-rack4-with-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](#put-it-on-your-path): allow it in **Privacy & Security** or remove the quarantine flag.

## Next steps

- [rack4 CLI cheat sheet](https://rack4.io/help/rack4-cli-cheat-sheet): every command by task.
- [Automate snapshots before risky changes with the CLI](https://rack4.io/tutorials/automate-snapshots-before-risky-changes-cli).
- [API tokens for CI and automation](https://rack4.io/help/api-tokens-for-automation), for rack4 in a pipeline.
- The [plans](https://rack4.io/plans) you can order with `rack4 servers create`.