# swb history

What happened to an app in your tenant, newest first: every registration,
build, channel move, install, deploy, settings change, grant, listing change
and removal, with when it happened, who did it and what it concerns.

## Synopsis

```
usage: swb history <app> [--since <time>] [--kind <kind>]... [--limit <n>] [--json]
```

## Arguments and flags

| Argument or flag | Takes | Default |
|---|---|---|
| `<app>` | The app's **id**. Required. | — |
| `--since` | A time, ISO-8601 (`2026-10-01` or `2026-10-01T09:00:00Z`). Keeps the entries at or after it. | every entry |
| `--kind` | One kind of entry. Give it again for more; an entry of any of them is kept. | every kind |
| `--limit` | A positive integer. Stops after that many entries. | every entry, every page followed |
| `--json` | Nothing. Prints the entries and the token that reads on as the API answered them instead of the table. | off |
| `--help`, `-h` | Prints the command's help and exits. | off |

The kinds are `created`, `installed`, `removed`, `build-recorded`,
`build-failed`, `channel-moved`, `deploy-requested`, `deploy-landed`,
`deploy-failed`, `deploy-cancelled`, `settings-changed`, `access-changed`, `share-changed`,
`listing-changed`, `customer-changed`, `hold-set`, `hold-released` and
`channel-followed`, and one no act records yet: `release-approved`.

## What it prints

One row per entry, newest first:

| Column | What it is |
|---|---|
| `AT` | When it happened, `YYYY-MM-DD HH:MM`. |
| `KIND` | What kind of act it was. |
| `ACTOR` | Who did it: the platform's own act by the name its writer recorded (`switchboard`, `repository-scan`), a person by the name their sign-in account carries, as Switchboard last read it, or `Unnamed person` where it carries none, and `a workload` or `an API key` otherwise, with `via <app>` where a person acted through a product's install. A person's sign-in id is never printed. |
| `ENV` | The environment, where the act had one. |
| `REF` | What it concerns: the deploy, the build run, the version a channel moved to or a hold names, the channel an install was made to follow, the grant, or the settings version. |

An app nothing has happened to in your tenant prints `no history for <app>`.
With `--limit`, a history that has more prints `(more; raise --limit to see
them)` under the table.

`--json` prints `items`, each entry with `at`, `kind`, `actor` (`kind`, `id`,
`via`, `name`), `env`, `ref` and `detail` — the part of the act's payload a reader
shows, as JSON text, such as the keys a settings change wrote — and
`nextToken`, null once every page was read.

## The operation and the permission

`Query.app` and its `history` field (`App.history`), one call per page. The
caller needs `swb.apps.read` on the tenant, and reads only the tenant's own
entries: a deploy another tenant made of the same app is in that tenant's
history, not yours. `swb history` also reads `Query.me` once for the tenant.

## The same act in the console

None: the console does not show an app's history. A product built on
Switchboard reads the same entries through its install, for the apps it
provides.

## Refusals and exit status

Exit status is 0 on success and 1 on every refusal below.

| Refusal | When |
|---|---|
| `swb history takes <app>` | The app is missing. |
| `--limit takes a positive integer, not "<n>"` | `--limit` is not a positive integer. |
| `the catalog carries no app named <app>` | No app has that id. |
| `not signed in or token expired — run swb login` | There is no usable credential. |
| `ValidationFailed: <the API's message>` | A `--kind` the history does not name. |
| `<error type>: <the API's message>` | The control plane refused the read — a caller without `swb.apps.read`, for example, is `NotAuthorized`. |

## Example

```console
$ swb history crew-signout --kind deploy-requested --kind deploy-landed
AT                KIND              ACTOR                      ENV   REF
2026-10-07 13:00  deploy-landed     switchboard                test  01J9Q4DEPLOY0000000000002
2026-10-07 12:58  deploy-requested  Maria Ruiz via breadboard  test  01J9Q4DEPLOY0000000000002
```