CLI overview
Install the vaultpanel command-line tool, sign in with an API token, manage profiles for several panels, and use it in CI.
vaultpanel does from a terminal what the panel does in a browser: list servers, create websites, deploy applications, run containers, take backups and follow jobs. It talks to the REST API with an API token, so it needs no access to the servers themselves and can never do more than the person whose token it carries.
The CLI is built on the JavaScript SDK and has no other dependencies.
Install
The CLI comes with every installed panel. On the panel's server, every vaultpanel command that is not one of the server commands goes to the CLI:
vaultpanel login --url https://panel.example.com
vaultpanel servers listOn any computer with Node.js 22 or newer, the CLI is packaged as @vaultpanel/cli:
npm install -g @vaultpanel/cli # then: vaultpanel --help
npx @vaultpanel/cli --help # or without installingSign in
The CLI signs in with an API token, never with your password.
Create a token
In the panel, open Users & Access > API Tokens and click New token. Give it a Name, tick what it may do under What it may do (the token's scopes) and choose when it Expires. Copy the token: it is shown once.
A token always acts as the person who made it, narrowed to its scopes. See API tokens for the scopes.
Log in
vaultpanel login --url https://panel.example.comAPI token: ****************
✓ Signed in to https://panel.example.com as you@example.com (token "Deploy script", profile "default")login asks for the token without showing it, checks it against the panel and only then saves it. Tokens start with vpt_; anything else is refused before any request.
Check who you are
vaultpanel whoamiIt shows the panel, the profile, your name and roles, the token's name and scopes, and how many permissions the token has.
The CLI checks the panel's HTTPS certificate like any Node.js program and has no option to skip that check. Use an address with a trusted certificate, such as a panel domain. With the self-signed certificate of a new install, point Node.js at a copy of that certificate (/etc/vaultpanel/tls/panel.crt on the panel's server) with the standard NODE_EXTRA_CA_CERTS environment variable.
Profiles
A profile is a panel address and an API token. login saves to the default profile unless you name another one, so you can work with several panels:
vaultpanel login --url https://staging.example.com --profile staging
vaultpanel servers list --profile staging
vaultpanel profiles # list saved profiles
vaultpanel profiles --use staging # make it the default
vaultpanel logout --profile staging # forget itlogout only removes the profile from the config file. The token stays valid until you revoke it in the panel.
The config file
Profiles are saved in ~/.config/vaultpanel/config.json, or $XDG_CONFIG_HOME/vaultpanel/config.json when XDG_CONFIG_HOME is set. The file is written with mode 0600 (its folder 0700) because it holds tokens. VAULTPANEL_CONFIG moves it anywhere else.
{
"profiles": {
"default": { "url": "https://panel.example.com", "token": "vpt_…" },
"staging": { "url": "https://staging.example.com", "token": "vpt_…" }
},
"defaultProfile": "default"
}How the CLI finds the panel and token
Each value comes from the first place that has it:
| Value | 1. Flag | 2. Environment | 3. Profile |
|---|---|---|---|
| Panel address | --url | VAULTPANEL_URL | the profile's url |
| API token | --token | VAULTPANEL_TOKEN | the profile's token |
| Profile | --profile | VAULTPANEL_PROFILE | defaultProfile in the config file, else default |
| Environment variable | What it does |
|---|---|
VAULTPANEL_URL | The panel's address. With or without /api/v1; https:// is assumed when no scheme is given. |
VAULTPANEL_TOKEN | An API token. |
VAULTPANEL_PROFILE | The profile to use. |
VAULTPANEL_CONFIG | The path of the config file. |
XDG_CONFIG_HOME | The base folder for the config file when VAULTPANEL_CONFIG is not set. |
NO_COLOR | Turns off colors in the output. |
In CI
Set VAULTPANEL_URL and VAULTPANEL_TOKEN and skip the config file entirely. Give the token only the scopes the job needs, such as Deploy for deployments:
#!/usr/bin/env bash
set -euo pipefail
export VAULTPANEL_URL=https://panel.example.com
export VAULTPANEL_TOKEN="$VAULTPANEL_DEPLOY_TOKEN" # scopes: deploy
vaultpanel apps deploy api --watch--watch follows the job and the command exits non-zero if it fails, so the pipeline fails with it.
Getting help
vaultpanel --help # every command group and the global flags
vaultpanel servers --help # the commands in one group
vaultpanel apps deploy --help # one command
vaultpanel --version # the CLI's version (the panel's version on the panel server)Short flags: -h is --help, -v is --version, -j is --json, -q is --quiet, -f is --force and -w is --watch.
The full list is in Commands.