# swb builds

The builds the control plane recorded for the signed-in tenant, newest first
by when each run started.

## Synopsis

```
usage: swb builds [--repo owner/name] [--limit n] [--json]
```

## Arguments and flags

| Flag | Takes | Default |
|---|---|---|
| `--repo` | A repository as `owner/name`. Narrows the list to that repository. | every repository of the tenant |
| `--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 |

## What it prints

An aligned table, one row per build, in these columns. An empty value prints
as `-`, and a time prints as `2026-02-01 09:00`.

| Column | What it is |
|---|---|
| `ID` | The build's id. |
| `REPO` | The repository it was built from, `owner/name`; `-` for an upload, which no repository built. |
| `APP` | The app the build belongs to. |
| `VERSION` | The version it published. |
| `CHANNEL` | The channel the version advanced on. |
| `BRANCH` | The branch the commit is on; `-` for an upload. |
| `COMMIT/NOTE` | The commit, first seven characters; for an upload a product made for a person, the note it carries in its place. |
| `STATUS` | `RUNNING` while the run goes on; then `RECORDED` when it published a version, `FAILED` when the fleet reports it ended other than succeeded, or `NO_RELEASE` when it succeeded and released nothing. |
| `STARTED` | When the build started. |

When the answer has more rows than the page, it adds
`(more; raise --limit to see them)`. With no builds it prints `no builds`, or
`no builds for <owner/name>` under `--repo`.

`--json` prints the rows as the API answered them: `id`, `source`
(`REPOSITORY` or `UPLOAD`), `repo`, `appId`, `version`, `commit` (in full),
`branch`, `note`, `actor` — its `kind`, `id` and the product it acted `via` —
`channel`, `status`, `artifactKey`, `startedAt`, and `resolvedSchemaSets` —
each with its `set`, `channel` and `version`. An upload's `repo`, `commit` and
`branch` are null.

## The operation and the permission

`Query.builds`, asked by repository with `--repo` and by tenant without it.
The caller needs `swb.apps.read` on the tenant. `swb builds` also reads
`Query.me` once, to learn the tenant, and caches it in the credential file.

## The same act in the console

An app's page, Builds tab — the same rows, for one app at a time.

## 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. |
| `--limit takes a positive integer, not "<value>"` | `--limit` was given something else. |
| `Unknown option '--<name>'` | A flag the command does not take. |
| The API's own error text | The control plane refused the read — a caller without `swb.apps.read`, for example. |

## Example

```console
$ swb builds --repo lime-energy/direct-install --limit 3
ID        REPO                        APP             VERSION  CHANNEL  BRANCH  COMMIT/NOTE  STATUS    STARTED
bld-3f1a  lime-energy/direct-install  direct-install  1.8.2    beta     main    9c41e0a      RECORDED  2026-02-01 09:12
bld-3e77  lime-energy/direct-install  direct-install  1.8.1    beta     main    41bd9a2      RECORDED  2026-01-31 16:40
bld-3e42  lime-energy/direct-install  direct-install  1.8.0    beta     main    7de0c15      FAILED    2026-01-31 11:05
```