# CLI overview

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

> 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](https://docs.vaultpanel.net/api-reference) 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](https://docs.vaultpanel.net/developers/sdk) and has no other dependencies.

## Install

**On the panel server**

The CLI comes with every installed panel. On the panel's server, every `vaultpanel` command that is not one of the [server commands](https://docs.vaultpanel.net/cli/server-command) goes to the CLI:

```bash
vaultpanel login --url https://panel.example.com
vaultpanel servers list
```

**Another computer**

On any computer with Node.js 22 or newer, the CLI is packaged as `@vaultpanel/cli`:

```bash
npm install -g @vaultpanel/cli   # then: vaultpanel --help
npx @vaultpanel/cli --help       # or without installing
```

> **Note:**
On the panel's server, `vaultpanel help` and `vaultpanel version` are server commands: they show the server command's help and the installed panel version. Use `vaultpanel <command> --help` for the CLI's own help.

## 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](https://docs.vaultpanel.net/api-reference/api-tokens) for the scopes.

### Log in

```bash
vaultpanel login --url https://panel.example.com
```

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

```bash
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](https://docs.vaultpanel.net/getting-started/panel-https-and-domain#put-the-panel-on-a-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:

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

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

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

```bash
#!/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](https://docs.vaultpanel.net/cli/output-and-exit-codes#exit-codes) if it fails, so the pipeline fails with it.

## Getting help

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