CLI Reference

CLI overview

Install the vaultpanel command-line tool, sign in with an API token, manage profiles for several panels, and use it in CI.

Last updated

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 list

On 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 installing

Sign 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.com
API 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 whoami

It 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 it

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

~/.config/vaultpanel/config.json
{
  "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:

Value1. Flag2. Environment3. Profile
Panel address--urlVAULTPANEL_URLthe profile's url
API token--tokenVAULTPANEL_TOKENthe profile's token
Profile--profileVAULTPANEL_PROFILEdefaultProfile in the config file, else default
Environment variableWhat it does
VAULTPANEL_URLThe panel's address. With or without /api/v1; https:// is assumed when no scheme is given.
VAULTPANEL_TOKENAn API token.
VAULTPANEL_PROFILEThe profile to use.
VAULTPANEL_CONFIGThe path of the config file.
XDG_CONFIG_HOMEThe base folder for the config file when VAULTPANEL_CONFIG is not set.
NO_COLORTurns 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:

deploy.sh
#!/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.