Commands
Every vaultpanel CLI command, subcommand and flag, with examples, grouped by what they manage.
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.
| Flag | What 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, -j | Print what the API returned, as JSON, for scripts and jq. |
--quiet, -q | Only print what was asked for (no progress or success lines). |
--help, -h | Help for the CLI, a command group or one command. |
--version, -v | The 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:
| Alias | Command |
|---|---|
server | servers |
site, sites, website | websites |
app, applications | apps |
db, database | databases |
container, docker | containers |
backup | backups |
job | jobs |
alert | alerts |
token | tokens |
me | whoami |
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 whoamiprofiles
List saved profiles, or choose the default one.
vaultpanel profiles [--use name]| Flag | What 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]| Flag | What it does |
|---|---|
--all | Everyone's tokens, for people allowed to see them. |
--scopes | The 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 dashboardservers
Servers, their state and the operations their agents can run.
| Command | Does |
|---|---|
servers list | List servers. |
servers show <server> | One server in detail. |
servers add <name> | Add a server and print the agent install command. |
servers remove <server> --force | Remove a server from the panel. |
servers operations | The operation catalog agents can run. |
servers run <server> <OPERATION> | Run one operation from the catalog. |
servers reboot <server> --force | Reboot a server. |
servers groups | List 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]| Flag | What 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> --forceRemoves the server from the panel and revokes its agent.
servers operations
vaultpanel servers operationsLists 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]| Flag | What it does |
|---|---|
--params <json> | The operation's parameters, as JSON. |
--watch | Follow 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"}' --watchservers 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 groupsLists server groups with their number of servers and their ids.
servers services
vaultpanel servers services <server> [service] [--restart|--start|--stop] [--watch]| Form | What 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> --restart | Restarts the service. --start starts it instead. |
servers services <server> <service> --stop --force | Stops 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 --watchwebsites
Websites, their domains and certificates.
| Command | Does |
|---|---|
websites list | List 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> --force | Delete 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]| Flag | What 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. |
--watch | Follow 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 --watchwebsites 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.
| Flag | What it does |
|---|---|
--email <address> | The contact email Let's Encrypt needs. Defaults to the email of the account the token belongs to. |
--staging | Use Let's Encrypt's staging service, for testing. |
--wildcard | Ask for a wildcard certificate. |
--no-force-https | Do not redirect HTTP to HTTPS. By default, HTTP is redirected. |
--renew | Renew the existing certificate instead. |
--force | With --renew, renew even if the certificate is not due yet. |
--watch | Follow the job until it finishes. |
Certbot also renews certificates by itself.
vaultpanel websites ssl shop --email ops@example.com --watchwebsites 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.
| Command | Does |
|---|---|
apps list | List 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 deployments | Deployment 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:
| Flag | What it does |
|---|---|
--set KEY=value | Add a variable or change its value. Repeat it to set several. |
--unset KEY | Remove 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 --watchdatabases
MariaDB databases and their users.
| Command | Does |
|---|---|
databases list | List databases. |
databases create <name> --server <server> | Create a database and a user for it. |
databases delete <database> --force | Delete a database and its data. |
databases users | List 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.
| Flag | What it does |
|---|---|
--server <server> | The server to create it on. Required. |
--user <name> | Name the new user yourself. From CLI 0.1.2. |
--no-user | Create 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. |
--watch | Follow 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 --watchdatabases delete
vaultpanel databases delete <database> --forcedatabases users
vaultpanel databases users [--database <database>] [--server <server>] [--page-size 25]Every database user with its databases, server, hosts, access and status.
| Flag | What 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.
| Command | Does |
|---|---|
containers list | List 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> --force | Remove 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]| Flag | What 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=value | An 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. |
--watch | Follow 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 alwayscontainers 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.
| Command | Does |
|---|---|
backups list | List backups. |
backups create --type <type> --resource <name> | Back something up now. |
backups restore <backup id> --force | Restore 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
donebackups 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.
| Option | Meaning |
|---|---|
--key <file> | The key file the panel gave you. |
--out <file> | Where to write the backup. Default: the same name without .enc. |
--force | Replace 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 | headcron
Cron jobs.
| Command | Does |
|---|---|
cron list | List 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
| Command | Does |
|---|---|
alerts list | Alert 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.
| Command | Does |
|---|---|
jobs list | List 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 flag | What 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.