CLI Reference

Commands

Every vaultpanel CLI command, subcommand and flag, with examples, grouped by what they manage.

Last updated
vaultpanel <command> [subcommand] [arguments] [flags]

Each command works through the REST API with the token of the current profile, so it can do only what that token allows. This page covers @vaultpanel/cli 0.1.2.

Global flags

These work with every command.

FlagWhat it does
--url <url>The panel's address. Overrides VAULTPANEL_URL and the profile.
--token <token>An API token. Overrides VAULTPANEL_TOKEN and the profile.
--profile <name>Which saved profile to use.
--json, -jPrint what the API returned, as JSON, for scripts and jq.
--quiet, -qOnly print what was asked for (no progress or success lines).
--help, -hHelp for the CLI, a command group or one command.
--version, -vThe CLI's version.

How arguments work

Names, not ids. Commands take the name of a server, website, app, database, container or cron job: vaultpanel apps deploy api finds the app called api. An id (a UUID) is used as it is. A name is matched exactly first (ignoring case), then as part of a name. A name that matches more than one thing is an error, never a guess. The lookup reads the first 100 items of the list.

Destructive commands need --force. Anything that deletes, removes, restores, reboots or stops a service refuses to run without it, so a typo in a script does not take a site down.

Long operations are jobs. Creating websites, deployments, certificates, backups and container changes run in the panel's job queue. These commands print the job id; --watch (-w) follows the job, prints its log and exits non-zero if it does not succeed. See jobs and waiting.

Flag values. Write --name value or --name=value. A value that starts with - needs the --name=value form. -- ends the flags; everything after it is an argument.

Repeated flags. From CLI 0.1.2, --set, --unset, --env, --query, --port and --ports can be given more than once, and every value is used: --set A=1 --set B=2. Any other flag holds one value: when it is repeated, the last one wins.

Aliases. Some groups answer to other names too:

AliasCommand
serverservers
site, sites, websitewebsites
app, applicationsapps
db, databasedatabases
container, dockercontainers
backupbackups
jobjobs
alertalerts
tokentokens
mewhoami

A command group run without a subcommand, such as vaultpanel servers, prints the group's commands.

Account and tokens

login

Save a panel address and API token as a profile.

vaultpanel login [--url https://panel.example.com] [--token vpt_...] [--profile name]

Without --token, it asks for the token without showing it. The token is checked against the panel before it is saved. Without --url, it reuses the profile's saved address. The profile is --profile, else VAULTPANEL_PROFILE, else default.

logout

Forget a saved profile. The token stays valid until you revoke it in the panel.

vaultpanel logout [--profile name]

whoami

Who the token belongs to and what it may do: the panel, the profile, your name, email and roles, the token's name and scopes, and the number of permissions it has.

vaultpanel whoami

profiles

List saved profiles, or choose the default one.

vaultpanel profiles [--use name]
FlagWhat it does
--use <name>Make this profile the default.

tokens

List your API tokens: name, prefix, owner, scopes, last use and state (active, revoked or expired). Create and revoke tokens in the panel under Users & Access > API Tokens.

vaultpanel tokens [--all] [--scopes]
FlagWhat it does
--allEveryone's tokens, for people allowed to see them.
--scopesThe scopes this panel offers and what each allows, instead of tokens.

dashboard

The dashboard numbers: how many servers are online and offline, websites (with how many certificates are expiring), applications, databases and firing alerts.

vaultpanel dashboard

servers

Servers, their state and the operations their agents can run.

CommandDoes
servers listList servers.
servers show <server>One server in detail.
servers add <name>Add a server and print the agent install command.
servers remove <server> --forceRemove a server from the panel.
servers operationsThe operation catalog agents can run.
servers run <server> <OPERATION>Run one operation from the catalog.
servers reboot <server> --forceReboot a server.
servers groupsList server groups.
servers services <server> [service]List services, check one, or restart, start or stop it.

servers list

vaultpanel servers list [--search text] [--status online] [--page-size 25]
FlagWhat it does
--search <text>Match the name, host name or public IP address.
--status <status>Only servers in this state: pending, online, offline or disabled.
--page-size <n>How many to list, up to 100.

Shows the name, status, agent version, CPU, memory, when the server was last seen and its id.

servers show

vaultpanel servers show <server>

The name, id, status, agent version, operating system, host name, addresses, CPU and memory, whether a newer agent is available, and when it was last seen.

servers add

vaultpanel servers add <name>

Adds the server to the panel and prints the command to run on it, as root, to install the agent. The command carries a one-time enrollment token. See connecting servers.

servers remove

vaultpanel servers remove <server> --force

Removes the server from the panel and revokes its agent.

servers operations

vaultpanel servers operations

Lists the operations available on this panel, such as SERVICE_RESTART or SERVER_REBOOT, with what each one does and whether it changes the server. Nothing outside this catalog can run on a server: the agent has no shell.

servers run

Run one operation from the catalog on a server.

vaultpanel servers run <server> <OPERATION> [--params '{"service":"nginx"}'] [--watch]
FlagWhat it does
--params <json>The operation's parameters, as JSON.
--watchFollow the job until it finishes.

The operation name is case-insensitive. The panel checks your permission for the operation and its parameters before queuing it.

vaultpanel servers run web-1 SERVICE_STATUS --params '{"service":"nginx"}' --watch

servers reboot

vaultpanel servers reboot <server> --force [--watch]

Queues SERVER_REBOOT. The agent reports success, then reboots the server a few seconds later.

servers groups

vaultpanel servers groups

Lists server groups with their number of servers and their ids.

servers services

vaultpanel servers services <server> [service] [--restart|--start|--stop] [--watch]
FormWhat it does
servers services <server>Lists the services the agent last reported, with their state.
servers services <server> <service>Asks the agent for the service's state now.
servers services <server> <service> --restartRestarts the service. --start starts it instead.
servers services <server> <service> --stop --forceStops the service. --stop needs --force.

A restart, start or stop prints the job, or follows it with --watch. These forms work from CLI 0.1.2. The older form, --restart nginx, still works.

vaultpanel servers services web-1
vaultpanel servers services web-1 nginx
vaultpanel servers services web-1 nginx --restart --watch

websites

Websites, their domains and certificates.

CommandDoes
websites listList websites.
websites show <website>One website in detail.
websites create <name>Create a website.
websites ssl <website>Get or renew its Let's Encrypt certificate.
websites enable <website>Turn a website on.
websites disable <website>Turn a website off.
websites delete <website> --forceDelete a website.
websites logs <website>A website's access or error log.

websites list

vaultpanel websites list [--server <server>] [--search text] [--page-size 25]

Shows each website's name, type, domains, server, status and certificate state.

websites show

vaultpanel websites show <website>

The name, id, type, server, domains, document root, PHP version or proxy port, status, certificate (with its expiry date) and the last error, if any.

websites create

vaultpanel websites create <name> --server <server> --domains a.example.com,b.example.com \
  [--type static|php|proxy] [--php 8.3] [--proxy-port 3000] [--root public] [--watch]
FlagWhat it does
--server <server>The server to create it on. Required.
--domains <list>Comma-separated domains; the first is the primary one. Required.
--type <type>static (the default), php or proxy.
--php <version>The PHP version, for a PHP site.
--proxy-port <port>The local port of the app, for a reverse proxy. From CLI 0.1.2.
--root <path>The document root. From CLI 0.1.2.
--watchFollow the job until the site is set up.

<name> is also the site's Linux user and folder name, and cannot be changed later.

vaultpanel websites create shop --server web-1 --domains shop.example.com,www.shop.example.com --type php --php 8.3 --watch

websites ssl

vaultpanel websites ssl <website> [--email you@example.com] [--staging] [--wildcard] [--no-force-https] [--watch]
vaultpanel websites ssl <website> --renew [--force] [--watch]

Without --renew, gets a Let's Encrypt certificate for the website's domains. Issuing works from CLI 0.1.2.

FlagWhat it does
--email <address>The contact email Let's Encrypt needs. Defaults to the email of the account the token belongs to.
--stagingUse Let's Encrypt's staging service, for testing.
--wildcardAsk for a wildcard certificate.
--no-force-httpsDo not redirect HTTP to HTTPS. By default, HTTP is redirected.
--renewRenew the existing certificate instead.
--forceWith --renew, renew even if the certificate is not due yet.
--watchFollow the job until it finishes.

Certbot also renews certificates by itself.

vaultpanel websites ssl shop --email ops@example.com --watch

websites enable and websites disable

vaultpanel websites enable <website>
vaultpanel websites disable <website>

websites delete

vaultpanel websites delete <website> --force [--remove-files]

Removes the website's NGINX and PHP configuration and its certificate. The site's files and Linux user are kept unless you add --remove-files (from CLI 0.1.2).

websites logs

vaultpanel websites logs <website> [--log error|access] [--lines 200]

Reads the last lines of the website's error log (the default) or access log through the agent and prints them. --lines defaults to 200; the panel accepts 10 to 2000. --kind is still accepted in place of --log. Works from CLI 0.1.2.

apps

Applications: deploy, roll back, restart and read their history.

CommandDoes
apps listList applications.
apps show <app>One application in detail.
apps deploy <app>Deploy the current branch.
apps rollback <app>Go back to the previous release, or a named one.
apps restart <app>Restart, start or stop an application.
apps deploymentsDeployment history.
apps logs <app>An application's output or error log.
apps env <app>Read or set environment variables.

apps list

vaultpanel apps list [--server <server>] [--search text] [--page-size 25]

Shows each app's name, runtime, server, process state, branch, when it was last deployed and its port.

apps show

vaultpanel apps show <app>

The name, id, server, runtime, repository, branch, port, process state with its restart count, and the last deployment.

apps deploy

vaultpanel apps deploy <app> [--watch]

Deploys the app's branch into a new release. With --watch, the command follows the deployment and fails if it fails, which is what a CI pipeline wants.

apps rollback

vaultpanel apps rollback <app> [--release <deployment id>] [--watch]

Points the app back at the release of an earlier deployment and restarts it.

Without --release, the CLI picks the newest successful deployment before the live one whose release is still on the server, and prints which one it chose (from CLI 0.1.2). If no earlier release is left on the server, it stops with an error; deploy an older commit instead.

--release takes a deployment id. Find them with vaultpanel apps deployments --app <app>.

apps restart

vaultpanel apps restart <app> [--stop] [--start] [--watch]

Restarts the app. --stop stops it and --start starts it instead.

apps deployments

vaultpanel apps deployments [--app <app>] [--page-size 25]

When each deployment ran, the app, status, commit, what triggered it and its id.

apps logs

vaultpanel apps logs <app> [--log output|error] [--lines 200]

Reads the last lines of the app's output log (the default) or error log through the agent and prints them. --lines defaults to 200; the panel accepts 10 to 2000. The older --kind out|error is still accepted. Works from CLI 0.1.2.

apps env

vaultpanel apps env <app> [--set KEY=value --set OTHER=value] [--unset KEY]

Without --set or --unset, lists the app's environment variables as Variable and Value rows. Setting and removing work from CLI 0.1.2:

FlagWhat it does
--set KEY=valueAdd a variable or change its value. Repeat it to set several.
--unset KEYRemove a variable. Repeat it to remove several.

Only the variables you name change; the rest stay as they are. The app uses new values after its next deploy or apply.

vaultpanel apps env api --set LOG_LEVEL=debug --set FEATURE_X=1 --unset OLD_FLAG
vaultpanel apps deploy api --watch

databases

MariaDB databases and their users.

CommandDoes
databases listList databases.
databases create <name> --server <server>Create a database and a user for it.
databases delete <database> --forceDelete a database and its data.
databases usersList database users.

databases list

vaultpanel databases list [--server <server>] [--search text] [--page-size 25]

The name, server, status, size, its users and the website or app that uses it.

databases create

vaultpanel databases create <name> --server <server> [--user name | --no-user] [--privileges all|readonly] [--watch]

Creates the database and, by default, a user named like it with a generated password.

FlagWhat it does
--server <server>The server to create it on. Required.
--user <name>Name the new user yourself. From CLI 0.1.2.
--no-userCreate the database without a user. From CLI 0.1.2.
--privileges <level>The user's access: all (the default) or readonly. From CLI 0.1.2.
--watchFollow the job until it finishes.

The user's password is printed once, before the job is followed, so you see it even with --watch. It is never shown again. With --json, it is the password field of the reply.

vaultpanel databases create shopdb --server web-1 --user shopuser --watch

databases delete

vaultpanel databases delete <database> --force

databases users

vaultpanel databases users [--database <database>] [--server <server>] [--page-size 25]

Every database user with its databases, server, hosts, access and status.

FlagWhat it does
--database <database>Only users of this database. The CLI filters the list itself, from the first 100 users (or --page-size). From CLI 0.1.2.
--server <server>Only users on this server. From CLI 0.1.2.
--page-size <n>How many to list, up to 100.

containers

Docker containers VaultPanel deploys.

CommandDoes
containers listList containers.
containers deploy <name>Deploy a container from a public image.
containers restart <container>Restart, start or stop a container.
containers logs <container>A container's output.
containers remove <container> --forceRemove a container.

containers list

vaultpanel containers list [--server <server>] [--page-size 25]
vaultpanel containers list --all --server <server>

Lists the containers VaultPanel deployed: name, image, server, state, ports and when they were updated. --all asks the agent on one server (--server is required) for every container there, including ones VaultPanel did not deploy, and prints them as a table: name, image, state, status, ports and whether VaultPanel deployed it.

containers deploy

vaultpanel containers deploy <name> --server <server> --image redis:7 \
  [--port 6379:6379] [--port 0.0.0.0:8080:80/tcp] [--env KEY=value] \
  [--memory 512] [--cpu 50] [--restart unless-stopped] [--watch]
FlagWhat it does
--server <server>The server to run it on. Required.
--image <image>A public image, such as redis:7. Required.
--port <port>Publish a port, as [address:]host[:container][/protocol], where the protocol is tcp or udp. Repeat it for several ports. From CLI 0.1.2.
--env KEY=valueAn environment variable. Repeat it for several. From CLI 0.1.2.
--memory <mb>Memory limit in MB.
--cpu <percent>CPU limit, in percent.
--restart <policy>unless-stopped (the default), always, on-failure or no. From CLI 0.1.2.
--watchFollow the deployment.

A port without an address binds to 127.0.0.1, so it is reachable from the server only. Give 0.0.0.0 to make it public. Without a container port, it is the same as the host port; without a protocol, it is tcp. --ports is accepted as another name for --port, and either takes a comma-separated list.

vaultpanel containers deploy cache --server web-1 --image redis:7 --port 6379 --memory 256 --watch
vaultpanel containers deploy web --server web-1 --image nginx:1.27 \
  --port 0.0.0.0:8080:80 --env TZ=UTC --env MODE=prod --restart always

containers restart

vaultpanel containers restart <container> [--start] [--stop] [--watch]

containers logs

vaultpanel containers logs <container> [--lines 200]

Reads the container's last lines through the agent and prints them. --lines defaults to 200; the panel accepts 10 to 2000.

containers remove

vaultpanel containers remove <container> --force [--remove-volumes] [--watch]

Removes the container. Its volumes are kept unless you add --remove-volumes (from CLI 0.1.2). --delete-volumes is still accepted as another name for it.

backups

Backups and restores of websites, apps and databases.

CommandDoes
backups listList backups.
backups create --type <type> --resource <name>Back something up now.
backups restore <backup id> --forceRestore a backup.
backups decrypt <file.enc> --key <key file>Decrypt a copy taken from storage, with no panel.

backups list

vaultpanel backups list [--server <server>] [--status completed] [--type website|application|database] [--page-size 25]

--status is creating, completed, failed, deleting or missing. --type lists only backups of websites, applications or databases (from CLI 0.1.2). Shows when each backup was made, what it holds, status, size, trigger and id.

backups create

vaultpanel backups create --type website|application|database --resource <name or id> [--storage <storage id>] [--watch]

Backs up one website, app or database now. --storage sends the backup to a particular backup storage, by its id (from CLI 0.1.2).

for site in $(vaultpanel websites list --json | jq -r '.[].name'); do
  vaultpanel backups create --type website --resource "$site" --watch
done

backups restore

vaultpanel backups restore <backup id> --force [--no-safety-backup] [--watch]

Restores the backup in place. By default, the panel first backs up the current state as a safety backup, so the restore can be undone. --no-safety-backup skips it (from CLI 0.1.2).

backups decrypt

vaultpanel backups decrypt <file.enc> --key <key file> [--out <file>] [--force]

Decrypts a copy of a backup you downloaded from a bucket or backup server, with the storage's key file (Backups > Storage > Key in the panel; see Save the backup key). It needs no panel and no token, so it works even when the panel is gone. From CLI 0.1.3.

OptionMeaning
--key <file>The key file the panel gave you.
--out <file>Where to write the backup. Default: the same name without .enc.
--forceReplace the output file if it exists.

It prints the backup's SHA-256, which matches the checksum shown in the panel when the copy is intact. A wrong key, or a copy that was changed or cut short, is refused and writes nothing.

vaultpanel backups decrypt 7f3c….tar.gz.enc --key vaultpanel-backup-key-offsite.txt
tar -tzf 7f3c….tar.gz | head

cron

Cron jobs.

CommandDoes
cron listList cron jobs.
cron run <cron job>Run a cron job now.
cron runs <cron job>Its run history.
vaultpanel cron list [--server <server>] [--page-size 25]
vaultpanel cron run <cron job> [--watch]
vaultpanel cron runs <cron job>

cron list shows each job's name, schedule, server, state, last run and result. cron runs shows when each run started, its status, exit code and how long it took.

alerts

CommandDoes
alerts listAlert events, firing ones by default.
alerts acknowledge <alert id>Acknowledge a firing alert.
vaultpanel alerts list [--status firing|open|resolved]
vaultpanel alerts acknowledge <alert id>

--status is firing (the default), open (pending and firing together) or resolved. The list shows when each alert started, the alert, server, status, value and id.

jobs

Background jobs: deployments, website changes, backups and operations.

CommandDoes
jobs listList jobs.
jobs show <job id>One job with its log.
jobs watch <job id>Follow a job until it finishes.
jobs cancel <job id>Cancel a job that is still queued.
vaultpanel jobs list [--status running] [--server <server>] [--type DEPLOY_APPLICATION] [--all] [--page-size 25]
vaultpanel jobs show <job id>
vaultpanel jobs watch <job id>
vaultpanel jobs cancel <job id>

--status is queued, dispatched, running, succeeded, failed, timed_out or cancelled. --type lists only jobs of one operation type (case-insensitive). jobs list leaves out routine lookups, such as file listings and log reads; --all includes them. --type and --all work from CLI 0.1.2. jobs watch exits non-zero when the job does not succeed. Only queued jobs can be cancelled; the panel answers 409 JOB_NOT_CANCELLABLE for any other.

api

Call any API endpoint directly, for anything the commands above do not cover.

vaultpanel api <METHOD> <path> [--data '{"name":"x"}'] [--data-file file.json] [--query key=value]
Argument or flagWhat it does
<METHOD>GET, POST, PATCH, PUT or DELETE.
<path>Relative to /api/v1: vaultpanel api GET /servers calls /api/v1/servers.
--data <json>The request body, as JSON.
--data-file <file>Read the request body from a JSON file instead.
--query <key=value>A query parameter. Repeat it for several (from CLI 0.1.2).

It prints the whole reply envelope (success, data, message, requestId), whatever --json says.

vaultpanel api GET /websites --query serverId=<server id> --query pageSize=100 | jq '.data.items | length'

With CLI 0.1.1 or older, only the last --query is sent; put several query parameters in the path itself instead: "/websites?serverId=<server id>&pageSize=100".

The API reference lists every endpoint.