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
Code
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
Code