swb deploys
The deploys of one environment, newest first within each app.
Synopsis
Code
Arguments and flags
| Flag | Takes | Default |
|---|---|---|
--env | An environment's name or id; a name is matched first. Required. | — |
--status | One of QUEUED, AWAITING_GATE, UPDATE_AVAILABLE, RUNNING, DONE, PREVIEWED, FAILED, SUPERSEDED, CANCELLED, in any case. The API answers only the rows in that state; DONE is a deploy that landed. | every state |
--limit | A positive integer: the page the API is asked for. | 50 |
--json | Nothing. Prints the rows as the API answered them instead of the table. | off |
--help, -h | Prints the command's help and exits. | off |
The API applies --status before it answers, and counts --limit before
it filters, so a narrow --limit can come back short, or empty, with more
rows in that state still to read: the command then says there are more.
What it prints
An aligned table, one row per deploy, in these columns. An empty value prints
as -, and a time prints as 2026-02-01 09:00.
| Column | What it is |
|---|---|
ID | The deploy's id. |
APP | The app deployed. |
KIND | APP or CONFIG. |
VERSION | The version deployed. |
STATUS | QUEUED, AWAITING_GATE (waiting for an approver, who decides it with swb approve-deploy or swb reject-deploy), UPDATE_AVAILABLE (a version offered to the environment, which nothing deploys until someone runs it with swb run-deploy), RUNNING, DONE (it landed), PREVIEWED, FAILED, SUPERSEDED (replaced by a newer version before it ran) or CANCELLED. |
TRIGGER | What started it. |
BY | Who requested it, by email or name — a workload or an API key by its own id — as the console names them; Unnamed person where the deploy records neither, and - for a deploy nobody asked for. |
STARTED | When it started. |
FINISHED | When it ended, - while it runs. |
ERROR | Why it failed, - otherwise. |
With nothing to show it prints no deploys in <environment>, or
no FAILED deploys in <environment> under --status. When the API has more
rows to read than the page held, it adds (more; raise --limit to see them),
after the table or after that line.
--json prints the rows as the API answered them — the same fields plus
installId, environmentId, channel, preview, triggerDetail and
githubCheckUrl.
The operation and the permission
Query.deploys, narrowed by environment and, under --status, by status;
the tenant is the caller's, never an argument. The caller needs
swb.apps.read on the tenant. swb deploys also reads Query.me once for
the tenant, and Query.tenant to turn the --env name into an id.
The same act in the console
An app's page, Deploys tab — the same rows, scoped by app rather than by environment.
Refusals and exit status
Exit status is 0 on success — an empty list included — and 1 on a refusal.
| Refusal | When |
|---|---|
swb deploys needs --env <env> | --env was not given. |
no environment named "<env>" in tenant <tenant> (have: dev, staging, prod) | No environment of the tenant has that name or id. |
--status takes one of QUEUED, AWAITING_GATE, UPDATE_AVAILABLE, RUNNING, DONE, PREVIEWED, FAILED, SUPERSEDED, CANCELLED, not "<value>" | --status was given something else, succeeded among them. Nothing is sent. |
--limit takes a positive integer, not "<value>" | --limit was given something else. |
not signed in or token expired — run swb login | There is no usable credential. |
Example
Code