# swb services

Every service the signed-in tenant may see — its own and other tenants' —
from the tenant's service directory.

## Synopsis

```
usage: swb services [--kind k] [--share s] [--json]
```

## Arguments and flags

| Argument or flag | Takes | Default |
|---|---|---|
| `--kind` | One of `app`, `api`, `dev-portal`, `site`, `agent` or `data`, in any case. Narrows the list to services of that kind. | every kind |
| `--share` | One of `tenant`, `org` or `portal`. Narrows the list to services shared at that level. The directory never holds a `hidden` service, so `hidden` is refused. | every level |
| `--json` | Nothing. Prints the services as the API answered them instead of the table. | off |
| `--help`, `-h` | Prints the command's help and exits. | off |

## What it prints

An aligned table, one row per service, in the order the control plane
answered them: grouped by the tenant that owns each. The command reads every
page of the directory before it prints, so the table is the whole directory.
An empty value prints as `-`.

| Column | What it is |
|---|---|
| `KIND` | The service's kind: `app`, `api`, `dev-portal`, `site`, `agent` or `data`. |
| `APP` | The app the service belongs to. |
| `ENV` | The environment it runs in. |
| `NAME` | Its name within that app and environment. |
| `URL` | Where it is reached. |
| `TENANT` | The tenant that owns it — the signed-in tenant's own, or another tenant's that shares it. |
| `SHARE` | The level it is shared at: `tenant` (the tenants its audience names), `org` (every tenant of the organization) or `portal` (listed in the developer portal as well). |

A service is in the directory when it is shared at `tenant`, `org` or
`portal` and its read audience is every tenant or names the signed-in tenant.
Sharing is visibility only: being listed here binds nothing and grants
nothing. With no such service it prints
`no service is shared with this tenant`.

`--json` prints every service as the API answered it: `app`, `env`, `kind`,
`name`, `url`, `tenant` and `share`, the enums in the API's own words
(`DEV_PORTAL`, `ORG`).

## The operation and the permission

`Query.services`, every page of it. The caller needs `swb.apps.read` on the
tenant. A product acting for a person through its install reads the same
directory, the same page the person is answered here.

## The same act in the console

The Services menu in the top bar lists the tenant's services from the same
directory, beside Willdan's apps.

## Refusals and exit status

Exit status is 0 on success — an empty directory included — and 1 on a
refusal.

| Refusal | When |
|---|---|
| `not signed in or token expired — run swb login` | There is no usable credential. |
| `--kind takes app, api, dev-portal, site, agent, data, not "<value>"` | `--kind` was given something else. |
| `--share takes tenant, org, portal, not "<value>"` | `--share` was given something else, `hidden` among it. Nothing is sent. |
| The API's own error text | The control plane refused the read — a caller without `swb.apps.read`, for example. |