# Commands

URL: https://docs.vaultpanel.net/cli/commands

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

```text
vaultpanel <command> [subcommand] [arguments] [flags]
```

Each command works through the [REST API](https://docs.vaultpanel.net/api-reference) with the token of the current [profile](https://docs.vaultpanel.net/cli#profiles), so it can do only what that token allows. This page covers `@vaultpanel/cli` 0.1.2.

> **Note:**
CLI 0.1.1 and older send several commands in a form the panel refuses or ignores: `servers services` without `--restart`, `websites ssl` without `--renew`, `websites logs`, `apps logs`, setting variables with `apps env`, `apps rollback` without `--release`, `databases create --user`, and ports and environment variables in `containers deploy`. These work from CLI 0.1.2. `vaultpanel --version` shows which version you have.

## 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](https://docs.vaultpanel.net/cli/output-and-exit-codes#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.

```bash
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.

```bash
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.

```bash
vaultpanel whoami
```

### `profiles`

List saved profiles, or choose the default one.

```bash
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**.

```bash
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.

```bash
vaultpanel dashboard
```

## servers

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`

```bash
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`

```bash
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`

```bash
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](https://docs.vaultpanel.net/guides/servers/connecting-servers).

### `servers remove`

```bash
vaultpanel servers remove <server> --force
```

Removes the server from the panel and revokes its agent.

### `servers operations`

```bash
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.

```bash
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.

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

### `servers reboot`

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

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

### `servers groups`

```bash
vaultpanel servers groups
```

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

### `servers services`

```bash
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.

```bash
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.

| 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`

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

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

### `websites show`

```bash
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`

```bash
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.

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

### `websites ssl`

```bash
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.

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

### `websites enable` and `websites disable`

```bash
vaultpanel websites enable <website>
vaultpanel websites disable <website>
```

### `websites delete`

```bash
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`

```bash
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`

```bash
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`

```bash
vaultpanel apps show <app>
```

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

### `apps deploy`

```bash
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`

```bash
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`

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

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

### `apps deployments`

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

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

### `apps logs`

```bash
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`

```bash
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.

```bash
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.

| 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`

```bash
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`

```bash
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.

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

### `databases delete`

```bash
vaultpanel databases delete <database> --force
```

### `databases users`

```bash
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`

```bash
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`

```bash
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.

```bash
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`

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

### `containers logs`

```bash
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`

```bash
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`

```bash
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`

```bash
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).

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

### `backups restore`

```bash
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`

```bash
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](https://docs.vaultpanel.net/guides/backups-and-automation/backup-storage#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.

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

## cron

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

```bash
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. |

```bash
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. |

```bash
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.

```bash
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.

```bash
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](https://docs.vaultpanel.net/api-reference) lists every endpoint.
