# swb listing

An app's listing — its entry in the marketplace: who sees its product page,
which tenants besides its owner may install their own copy, and which have.
[`swb list`](/command-line/list) sets it.

## Synopsis

```
usage: swb listing <app> [--json]
```

## Arguments and flags

| Argument or flag | Takes | Default |
|---|---|---|
| `<app>` | The app's **id**. Required. | — |
| `--json` | Nothing. Prints the app's catalog entry as the API answered it instead of the table. | off |
| `--help`, `-h` | Prints the command's help and exits. | off |

## What it prints

A one-row table:

| Column | What it is |
|---|---|
| `APP` | The app's id. |
| `OWNER` | The tenant that owns the app and lists it. |
| `LEVEL` | Who sees the product page: `PRIVATE` (the owner's people), `ORG` (everyone signed in) or `LISTED` (the marketplace). |
| `AUDIENCE` | The tenants besides the owner that may install their own copy, or `owner only`. |
| `INSTALLED BY` | Every tenant that has installed the listed app, the owner among them where it has. |

An app never listed prints `<app> is not listed; its owner is <tenant>`, or
`no tenant owns it yet` where the catalog records no owner.

`--json` prints the catalog entry as the API answered it: `id`, `owner`, and
`listing` — null for an app never listed — with its `level`,
`installAudience` and `installedBy`.

## The operation and the permission

`Query.app`. The caller needs `swb.apps.read` on the tenant: the catalog
entry is the platform's, read by every tenant that installs the app.
`swb listing` also reads `Query.me` once for the tenant.

## The same act in the console

An app's page → **Settings** → *Listing*: the level, the install audience and
who has installed it.

## Refusals and exit status

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

| Refusal | When |
|---|---|
| `swb listing takes <app>` | The app is missing. |
| `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. |
| The API's own error text | The control plane refused the read — a caller without `swb.apps.read`, for example. |

## Example

```console
$ swb listing data-automation
APP              OWNER          LEVEL  AUDIENCE     INSTALLED BY
data-automation  willdan-group  ORG    weidt-group  willdan-group, weidt-group
```