# Output and exit codes

URL: https://docs.vaultpanel.net/cli/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.

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

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

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

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

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

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