# swb deploys

The deploys of one environment, newest first within each app.

## Synopsis

```
usage: swb deploys --env <env> [--status <status>] [--limit n] [--json]
```

## 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`](/command-line/approve-deploy) or [`swb reject-deploy`](/command-line/reject-deploy)), `UPDATE_AVAILABLE` (a version offered to the environment, which nothing deploys until someone runs it with [`swb run-deploy`](/command-line/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

```console
$ swb deploys --env prod --status FAILED --limit 2
ID        APP             KIND  VERSION  STATUS  TRIGGER  BY            STARTED           FINISHED          ERROR
dep-91c4  direct-install  APP   1.8.0    FAILED  console  chuck@…       2026-01-31 11:22  2026-01-31 11:31  CREATE_FAILED: SiteBucket
dep-8f02  cortex          APP   4.2.1    FAILED  ci       github-actions  2026-01-29 08:03  2026-01-29 08:07  Deploy role assumption denied
```