Install the vps9 command-line tool

vps9 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 vps9 init or vps9 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 vps9 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 vps9 in ~/.local/bin:

curl -fsSL https://vpsnine.com/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://vpsnine.com/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. Before launch, the script only says the downloads aren't published yet. You can read it before you run it: curl -fsSL https://vpsnine.com/cli/install.sh | less. On Windows, follow the steps below.

Download it#

Downloads open at launch, at https://vpsnine.com/downloads/vps9/. 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://vpsnine.com/downloads/vps9/vps9-linux-amd64
curl -LO https://vpsnine.com/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 vps9-darwin-arm64
grep vps9-darwin-arm64 SHA256SUMS

On Windows, in PowerShell:

(Get-FileHash .\vps9-windows-amd64.exe -Algorithm SHA256).Hash.ToLower()
Select-String vps9-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 vps9-linux-amd64
sudo mv vps9-linux-amd64 /usr/local/bin/vps9
vps9 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/vps9.

On Windows, rename the file to vps9.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 vps9 login:

vps9 login < ~/.vps9-token

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

You can also run plain vps9 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, vps9 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/vps9/config.json
• macOS: ~/Library/Application Support/vps9/config.json
• Windows: %AppData%\vps9\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 VPS9_TOKEN="$(cat ~/.vps9-token)"

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

vps9 whoami
vps9 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. vps9 --json whoami shows the account and your role on it if you're on a team.

Or set it up in one go#

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

vps9 init --token-file ~/.vps9-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#

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

Name a server by its hostname or by its id (srv_…). vps9 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: vps9 ssh --user deploy web-1. Anything after -- goes to ssh as it is, as in vps9 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.

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

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

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

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

vps9 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, vps9 prints the key and the command to repeat with --idempotency-key. Orders open at launch; until then the API refuses them.

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

Tab completion#

vps9 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 <(vps9 completion bash)
# zsh, in ~/.zshrc after compinit
source <(vps9 completion zsh)
# fish, once
vps9 completion fish > ~/.config/fish/completions/vps9.fish

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

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

Open the panel#

vps9 open opens the panel in your browser, and vps9 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#

vps9 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. vps9 --json status prints the API's answer as it is, so a script can check .status.level:

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

Troubleshooting#

vps9: 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.

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

vps9: 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.

vps9: the API address must look like https://my.vpsnine.com. VPS9_API or --api ends in /api/v1. The CLI wants the panel's address, https://my.vpsnine.com, without the path. The TypeScript SDK takes that form too, so one VPS9_API=https://my.vpsnine.com 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#

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