# swb service

One of the signed-in tenant's own services: where it is reached, how it is
shared, and who may bind it.

## Synopsis

```
usage: swb service <app> <env> <kind> <name> [--json]
```

## Arguments and flags

| Argument or flag | Takes | Default |
|---|---|---|
| `<app>` | The app the service belongs to. Required. | — |
| `<env>` | The environment it runs in. Required. | — |
| `<kind>` | One of `app`, `api`, `dev-portal`, `site`, `agent` or `data`, in any case. Required. | — |
| `<name>` | Its name within that app and environment. Required. | — |
| `--json` | Nothing. Prints the service as the API answered it instead of the summary. | off |
| `--help`, `-h` | Prints the command's help and exits. | off |

## What it prints

The service's four parts, then one line each for what it reads:

```
atlas/prod/data/ia
url          https://data.atlas.example/ia
share        org
approval     owner
fingerprint  sha256:3f9a
tenant       weidt-group
read         every tenant
maintain     weidt-group
```

| Line | What it is |
|---|---|
| `url` | Where the service is reached. |
| `share` | The level it is shared at: `hidden`, `tenant`, `org` or `portal`. |
| `approval` | Who signs for a first bind: `owner`, or `none` where a bind needs no one's word. |
| `fingerprint` | The digest of what a binding depends on; it changes when the service does. |
| `tenant` | The tenant that owns it, the signed-in tenant. |
| `read` | The tenants that may bind it to read, or `every tenant`. |
| `maintain` | The tenants that may bind it to maintain, or `no tenant`. |

Only the signed-in tenant's own services are read by name: another tenant's
service, shared or not, is not, and `swb services` is where the services
other tenants share are listed.

`--json` prints the service as the API answered it: `app`, `env`, `kind`,
`name`, `url`, `tenant`, `share`, `approval`, `fingerprint`, and `audience`
with its `read` and `maintain`, a read audience of every tenant answered as
`["org"]`.

## The operation and the permission

`Query.service`. The caller needs `swb.apps.read` on the tenant.

## The same act in the console

An app's page → **Sharing** lists each of its services with its level, its
audience and its approval, and the service's **Edit sharing…** changes them,
as [`swb share`](/command-line/share) does.

## Refusals and exit status

Exit status is 0 on success and 1 on a refusal.

| Refusal | When |
|---|---|
| `not signed in or token expired — run swb login` | There is no usable credential. |
| `takes a service's <app> <env> <kind> <name>` | Fewer than the four parts were given. |
| `<kind> takes app, api, dev-portal, site, agent, data, not "<value>"` | The kind is none of those. |
| `the tenant holds no service <app>/<env>/<kind>/<name>` | The signed-in tenant holds no such service. |
| The API's own error text | The control plane refused the read — a caller without `swb.apps.read`, or a service row it cannot read whole, for example. |