# swb environments

The tenant's environments, each with the AWS account it deploys into and its
class — or, with `--create`, one more.

An environment is a name one of the tenant's AWS connections declares: a
connection's archetype list names the environments each archetype serves, and
creating the environment binds it to the one connection whose list names it.
The environment takes that connection's account and its first region, and the
class of the control plane that serves it — never one read off the name, so an
environment called `production` in a dev class is a dev environment. Nothing is
created in the account: an install into the environment deploys there later.

## Synopsis

```
usage: swb environments [--create <name>] [--json]
```

## Arguments and flags

| Argument or flag | Takes | Default |
|---|---|---|
| `--create` | An environment **name**, one an AWS connection of the tenant lists. The name goes as typed. | — |
| `--json` | Nothing. Prints the API's answer as given instead of the table. | off |
| `--help`, `-h` | Prints the command's help and exits. | off |

With no `--create` the command lists; with one it creates.

## What it prints

One row per environment: its name, the AWS account it deploys into, and its
class — `dev`, `staging` or `production`. A tenant with none prints one line
saying so. After a create, the one environment the API answered, in the same
columns.

`--json` prints the environments as `Query.tenant` answered them on a list, and
the environment `Mutation.createEnvironment` answered on a create.

## The operation and the permission

`Mutation.createEnvironment` to create one, which needs `swb.apps.install` —
the tenant administrator's, the same as installing an app. The list is
`Query.tenant`'s environments, which any member of the tenant reads. `swb
environments` also reads `Query.me` once for the tenant.

## The same act in the console

**Environments** → *Create environment*. Its name field suggests the names the
tenant's connections declare and no environment of the tenant holds.

## Refusals and exit status

Exit status is 0 on success — an empty list included — and 1 on every refusal
below.

| Refusal | When |
|---|---|
| `<name> cannot be created: an environment stands on a connected AWS account, …` | The tenant has connected no AWS account. |
| `no AWS connection of this tenant declares <name>: …` | No connection's archetype list names it. Add it to one on **AWS connections**. |
| `<name> is declared by the connections for accounts … and an environment deploys into one account: …` | Two or more connections list it. |
| `this tenant already holds the environment <name>` | The tenant has an environment of that name; it is left as it was. |
| `not signed in or token expired — run swb login` | There is no usable credential. |
| The API's own error text | Any other refusal — a caller without `swb.apps.install`, for example. |

## Example

```console
$ swb environments --create qa1001
NAME    ACCOUNT       CLASS
qa1001  111122223333  dev
```