# swb apps

The apps the signed-in tenant owns, in id order, each with the version at the
head of each of its channels and the environments it is installed in. A
retired app is left out.

## Synopsis

```
usage: swb apps [--kind <kind>] [--json]
```

## Arguments and flags

| Flag | Takes | Default |
|---|---|---|
| `--kind` | An app's kind: `cfn`, `pilet`, `configset`, `content` or `schema-set`, in any case. Keeps the apps of that kind. | every kind |
| `--json` | Nothing. Prints the apps as the API answered them instead of the table. | off |
| `--help`, `-h` | Prints the command's help and exits. | off |

Every page the API answers is followed to the end, so the list is the whole
catalog the tenant owns, however many pages it takes.

## What it prints

An aligned table, one row per app, in the order the API answered them. An
empty value prints as `-`.

| Column | What it is |
|---|---|
| `APP` | The app's id. |
| `NAME` | The name people see, as the app was registered with it; `—` for an app its repository's scan registered, which records none. |
| `HEADS` | The version at the head of each channel the app has, ascending by channel: `beta 1.4.0, stable 1.3.0`. |
| `INSTALLED IN` | The environments of the tenant the app is installed in, as the API answered them; a pull request's environment is not among them. |

A tenant that owns no app prints `the tenant owns no apps`, or `the tenant
owns no <kind> apps` under `--kind`, and no table.

`--json` prints every page's apps as the API answered them: each app's `id`,
`name`, `channels` — each with its `channel` and `version` — and
`environments` — each with its `env`.

## The operation and the permission

`Query.apps`, with `kind` where `--kind` is given, read through every
`nextToken`; it reads each app's `id`, `name`, `channels { channel version }`
and `environments { env }`. The caller needs `swb.apps.read` on the tenant.
`swb apps` also reads `Query.me` once, to learn the tenant, and caches it in
the credential file.

## The same act in the console

Deployments, Apps — the tenant's own apps and the repositories behind them.

## 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. |
| `--kind takes cfn, pilet, configset, content, schema-set, not "<value>"` | `--kind` was given something else; nothing is sent. |
| `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 apps
APP           NAME         HEADS                     INSTALLED IN
alpha         Alpha        beta 1.4.0                test, live
crew-board    Crew board   beta 2.0.0, stable 1.9.1  live
portal        —            -                         -
```