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.

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.

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'

login, logout, ssh and version don't print JSON.

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.

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.