# swb list

Lists an app in the marketplace: who sees its product page, and which
tenants besides its owner may install their own copy — the act of an app's
**Settings** tab under *Listing*. [`swb listing`](/command-line/listing)
shows the listing without changing it.

## Synopsis

```
usage: swb list <app> [--level <level>] [--to <tenant,...>] [--json]
```

## Arguments and flags

| Argument or flag | Takes | Default |
|---|---|---|
| `<app>` | The app's **id**. Required. | — |
| `--level` | `private`, `org` or `listed`, in any case — who sees the product page: the owner's people, everyone signed in, or every tenant in the marketplace. | the listing's level |
| `--to` | Tenant **ids**, comma-separated: the tenants besides the owner that may install their own copy. `--to ""` names none, which leaves the owner alone. | the listing's audience |
| `--json` | Nothing. Prints the listing as the API answered it instead of the table. | off |
| `--help`, `-h` | Prints the command's help and exits. | off |

At least one of `--level` and `--to` is required; whichever is left out is
kept from the standing listing. An app never listed has no level to keep, so
its first listing names `--level`.

## What it does

Reads the app's catalog entry with `Query.app`, then calls
`Mutation.setListing` with the level and the audience. A listing is the
catalog's and nothing else's: it writes no access to anything, and a tenant
it names installs its own copy, in its own account, through the install
wizard, and a tenant it leaves out is refused that install, naming the
listing.

## What it prints

The listing the control plane recorded, in the table
[`swb listing`](/command-line/listing) prints: `APP`, `OWNER`, `LEVEL`,
`AUDIENCE` and `INSTALLED BY`. `--json` prints the listing as the API
answered it: `level`, `installAudience` and `installedBy`.

## The operation and the permission

`Mutation.setListing`. The caller needs `swb.publishing.write`, and only the
tenant that owns the app may list it. `swb list` also reads `Query.me` once
for the tenant and `Query.app` for the listing it keeps.

## The same act in the console

An app's page → **Settings** → *Listing* → **Save listing**, with the install
audience picked from the organization's tenants.

## Refusals and exit status

Exit status is 0 once the listing is recorded, and 1 on every refusal below.

| Refusal | When |
|---|---|
| `swb list takes <app>` | The app is missing. |
| `swb list needs --level, --to or both; swb listing shows the listing` | Neither flag was given. |
| `--level takes one of private, org, listed, not "<value>"` | `--level` was given something else. |
| `the catalog carries no app named <app>` | No app has that id. |
| `<app> is not listed yet, so there is no level to keep; give --level` | `--to` alone on an app never listed. |
| `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 write — a caller without `swb.publishing.write`, a tenant that does not own the app, or an audience naming a tenant that does not exist. |

## Example

```console
$ swb list data-automation --level org --to weidt-group
APP              OWNER          LEVEL  AUDIENCE     INSTALLED BY
data-automation  willdan-group  ORG    weidt-group  willdan-group
```