CLI Reference

Output and exit codes

How the vaultpanel CLI prints tables and JSON, follows jobs, reports errors, retries requests, and which exit code each outcome returns.

Last updated

The CLI is meant for people and for scripts. People get tables; scripts get JSON, stable exit codes and errors on standard error.

Output formats

By default, lists print as tables and single items as Field: value lines. Times are relative ("3 minutes ago") and sizes are human-readable.

NAME   STATUS  AGENT   CPU  MEMORY          LAST SEEN       ID
web-1  online  0.41.0  12%  1.2 GB / 3.8 GB  10 seconds ago  2f6c…

--json (-j) prints what the API returned instead, for jq:

vaultpanel servers list --json | jq -r '.[] | select(.status != "online") | .name'
FlagEffect
--json, -jPrint the API's data as JSON. Progress and success lines are left out.
--quiet, -qLeave out informational and success lines, but keep tables, results and job log lines.

For a list, --json prints the array of items. vaultpanel api always prints the whole reply envelope, with success, data, message and requestId.

Colors are used only when the output is a terminal, and never when NO_COLOR is set. Errors and warnings go to standard error, so they never end up in piped JSON.

Jobs and waiting

Long operations run as jobs in the panel's queue. Commands that start one print the job id and return:

Deploying api: job 2f6c8a1e-…

Add --watch (-w) to follow it instead. The CLI checks the job every 2 seconds, prints each new log line and its status changes, and ends when the job finishes:

vaultpanel apps deploy api --watch
vaultpanel jobs watch 2f6c8a1e-…
How the job endsWhat the CLI doesExit code
succeededPrints ✓ <operation> succeeded0
failed, timed_out or cancelledPrints the status and the job's error2
Still running after 15 minutesStops waiting with an error; the job keeps running in the panel2

With --json, a watched command prints the finished job and its log lines as one JSON object.

Errors

When the panel refuses a request, the CLI prints its message, and for validation errors each field that failed:

✗ Some fields are invalid
✗   domains: Add at least one domain
Request id 7d1c9e2a-… (quote it when reporting a problem).

It adds a hint for the two errors you can fix yourself:

StatusHint
401The token for this profile is not valid any more. Make a new one in the panel and run vaultpanel login.
403The token's scopes do not cover this. Make one with wider scopes, or ask an owner.

Quote the request id when you report a problem: it identifies the request in the panel's logs.

Retries and timeouts

Each request times out after 30 seconds. GET requests are retried up to twice when the panel answers 429, 502, 503 or 504, or when the network fails. Requests that change something are never retried, so a deploy is never started twice.

Exit codes

CodeMeans
0It worked.
1The command was used wrongly (a missing argument, an unknown command, --force left out, invalid JSON), there is no panel address or token, or something local failed.
2The panel refused the request, could not be reached, or a watched job did not succeed.
3The token is not valid any more (401), or its scopes do not cover this (403).

A script can branch on them:

status=0
vaultpanel apps deploy api --watch || status=$?
case $status in
  0) echo "Deployed" ;;
  3) echo "Fix the token: vaultpanel login"; exit 1 ;;
  *) echo "The deploy failed ($status)"; exit 1 ;;
esac