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.
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'| Flag | Effect |
|---|---|
--json, -j | Print the API's data as JSON. Progress and success lines are left out. |
--quiet, -q | Leave 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 ends | What the CLI does | Exit code |
|---|---|---|
succeeded | Prints ✓ <operation> succeeded | 0 |
failed, timed_out or cancelled | Prints the status and the job's error | 2 |
| Still running after 15 minutes | Stops waiting with an error; the job keeps running in the panel | 2 |
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:
| Status | Hint |
|---|---|
401 | The token for this profile is not valid any more. Make a new one in the panel and run vaultpanel login. |
403 | The 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
| Code | Means |
|---|---|
0 | It worked. |
1 | The 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. |
2 | The panel refused the request, could not be reached, or a watched job did not succeed. |
3 | The 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