# swb releases

The signed-in tenant's releases, oldest first, or one release with its
channel moves.

## Synopsis

```
usage: swb releases [<id>] [--state s] [--limit n] [--json]
```

## Arguments and flags

| Argument or flag | Takes | Default |
|---|---|---|
| `<id>` | A release's **id**, as the list prints it. Prints that release and its moves instead of the list. | the list |
| `--state` | One of `assembling`, `testing`, `approved`, `closed` or `abandoned`. Narrows the list to releases in that state. Not taken with `<id>`. | every state |
| `--limit` | A positive integer: the page the API is asked for. | 50 |
| `--json` | Nothing. Prints what the API answered instead of the table or the summary. | off |
| `--help`, `-h` | Prints the command's help and exits. | off |

## What it prints

The list is an aligned table, one row per release, in the order the control
plane keeps them, oldest first. An empty value prints as `-`, and a time
prints as `2026-02-01 09:00`.

| Column | What it is |
|---|---|
| `NAME` | The name it was assembled under. |
| `ID` | Its id, which `swb releases <id>` and `swb approve-release` take. |
| `STATE` | `assembling` until it is approved, then `approved`; `abandoned` once a later release of the same app was assembled before it was approved. |
| `MOVES` | Each app it moves and the version it moves to. |
| `ASSEMBLED BY` | The person who assembled it, by the name the tenant's directory holds for them, else `Unnamed person`, followed by `via <app>` where they acted through an installed app. |
| `ASSEMBLED` | When it was assembled. |
| `APPROVED BY` | The person who approved it, named the same way; `-` before the approval. |

When the answer has more rows than the page, it adds
`(more; raise --limit to see them)`. With no releases it prints
`no releases`, or `no <state> releases` under `--state`.

Given an id, it prints the release and one line per move — the app, the
channel, the head the channel stood at when the release was assembled, and
the version it moves to:

```
Switchboard 9.9 (01JRELEASE): approved
assembled by Maria Ruiz at 2026-10-20 09:00; approved by Ana Ortiz at 2026-10-20 10:30
  switchboard stable 9.8.1 → 9.9.0
```

`--json` prints the release or the rows as the API answered them: `id`,
`name`, `owner`, `state`, `createdAt`, `approvedBy`, `approvedAt`, and
`moves`, each with its `app`, `channel`, `fromVersion` and `toVersion`.
`owner` and `approvedBy` are actors, each with its `kind`, `id`, `via` and
`name`; `approvedBy` is null before the approval.

## The operation and the permission

`Query.releases` for the list and `Query.release` for one release. The
caller needs `swb.apps.read` on the tenant.

## The same act in the console

Releases, under Deployments, and a release's own page, where the tenant has
turned releases on.

## Refusals and exit status

Exit status is 0 on success — an empty list included — and 1 on a refusal.

| Refusal | When |
|---|---|
| `not signed in or token expired — run swb login` | There is no usable credential. |
| `no release <id> in this tenant` | The tenant has no release with that id. |
| `--state takes assembling, testing, approved, closed, abandoned, not "<value>"` | `--state` was given something else. |
| `--limit takes a positive integer, not "<value>"` | `--limit` was given something else. |
| The API's own error text | The control plane refused the read — a caller without `swb.apps.read`, for example. |