# Command line

> Every command of the flexway and flexway-console binaries: options, exit codes, examples, from the binary or the published image.

Reference - Since version 0.1.0 - Flexway v1.7.1 - https://flexway.io/en/docs/reference-cli/

The `flexway` binary is both the service and its tools: with no argument it serves; followed by a
command it checks, converts or writes, **offline**, without starting a listener. The same commands
ship in every published image, whose entry point is the binary:

```bash
docker run --rm -v "$PWD:/etc/flexway:ro" ghcr.io/flexwiz/flexway:<version> validate
```

Options take one or two dashes (`-config` or `--config`). `-h` prints a command's help and exits `0`.

## Contents

| Command | Role | Exit codes | Since |
| --- | --- | --- | --- |
| [`flexway`](#flexway) | Serve | - | `0.1.0` |
| [`flexway validate`](#flexway-validate) | Validate a configuration and its contracts | `0`, `1`, `2` | `0.1.0` |
| [`flexway import krakend`](#flexway-import-krakend) | Take over a KrakenD configuration | `0`, `1`, `2`, `3` | `1.2.0` |
| [`flexway api-key`](#flexway-api-key) | Create an API key | `0`, `1` | `0.1.0` |
| [`flexway schema`](#flexway-schema) | Write the configuration's published schemas | `0`, `1`, `2` | `1.7.0` |
| [`flexway fragment digest`](#flexway-fragment-digest) | Compute the digest that pins a policy fragment | `0`, `1`, `2` | `1.7.0` |
| [`flexway version`](#flexway-version) | Say which version runs | `0` | `1.1.0` |
| [`flexway-console users`](#flexway-console-users) | Manage the console's local accounts | `0`, `1`, `2` | `1.0.0` |
| [`flexway-console version`](#flexway-console-version) | Say which console version runs | `0` | `1.1.0` |

## flexway

Serves the configuration the environment names. `SIGTERM` drains the requests in flight then stops,
`SIGHUP` reads the configuration again at once.

| Variable | Default | Role |
| --- | --- | --- |
| `FLEXWAY_CONFIG` | - (required; `/etc/flexway/flexway.yaml` in the image) | The `flexway.yaml` to serve |
| `FLEXWAY_ADDR` | `:8080` | Traffic listener |
| `FLEXWAY_ADMIN_ADDR` | `:9090` | Admin listener ([admin API](https://flexway.io/en/docs/reference-admin-api/)) |
| `FLEXWAY_TLS_ADDR` | `:8443` | TLS listener, when `server.tls` is set |

```bash
FLEXWAY_CONFIG=/etc/flexway/flexway.yaml flexway
```

## flexway validate

Loads the configuration and every contract it names with the start's loader - same checks, same
refusals - with no network and no cluster. A secret reference (`${VAR}`, `file:/...`) is checked for its
form, not resolved.

```sh
flexway validate [--config flexway.yaml] [--contract openapi.yaml] [-v]
```

| Option | Default | Role |
| --- | --- | --- |
| `--config` | `$FLEXWAY_CONFIG`, else `flexway.yaml` | The configuration to validate; the paths it holds are read from its directory |
| `--contract` | - | Another OpenAPI contract, validated in place of `contracts.openapi` |
| `-v` | no | Lists every resolved operation (method, template, upstream) and the full digest |

| Code | Meaning |
| --- | --- |
| `0` | Accepted: `valid: <n> operation(s) served from <n> contract(s), <n> upstream(s)` then `config_digest <digest>` |
| `1` | Refused: the field at fault and the reason |
| `2` | Misused command line |

```bash
docker run --rm -v "$PWD:/w:ro" ghcr.io/flexwiz/flexway:<version> validate --config /w/flexway.yaml --contract /w/next.yaml -v
```

The `config_digest` is the one `/config` publishes on a replica that serves this configuration.
Guide: [Serving your first API](https://flexway.io/en/docs/operations-first-api/).

## flexway import krakend

Converts a `krakend.json` once, offline: a `flexway.yaml`, the annotated contract, the same additions as
a JSON Patch (`contract.patch.json`) and a `coverage.md` report. The result passes the start's loader
before it is written.

```sh
flexway import krakend --config krakend.json --contract openapi.yaml --out <empty directory>
```

| Option | Default | Role |
| --- | --- | --- |
| `--config` | `krakend.json` | The KrakenD configuration (rendered, when it is flexible) |
| `--contract` | - (required) | The OpenAPI contract the endpoints are matched against |
| `--out` | - (required) | An empty or absent directory: the import never overwrites |

| Code | Meaning |
| --- | --- |
| `0` | Everything taken over |
| `1` | Refused, nothing written |
| `2` | Misused command line |
| `3` | Taken over, with elements without equivalent listed in `coverage.md` |

Guide: [Taking over an existing gateway](https://flexway.io/en/docs/operations-import/).

## flexway api-key

Creates an API key. The command **asks** for its id, its tenant, the operations it opens
(comma-separated `operationId`s) and its end (`90d`, `12w` or a `YYYY-MM-DD` date; `90d` by default),
then prints the key **once** and the entry to add to the key store - its SHA-256 digest, never the key.
No option: the inputs are interactive.

```bash
docker run --rm -it ghcr.io/flexwiz/flexway:<version> api-key
```

| Code | Meaning |
| --- | --- |
| `0` | Key created |
| `1` | Refused: malformed id (2 to 64 characters, lower-case, digits, `.`, `_`, `-`), no tenant or operation, a date in the past |

Guide: [API keys](https://flexway.io/en/docs/operations-api-keys/).

## flexway schema

Writes the configuration's published schemas (JSON Schema 2020-12) from the binary's model, offline:
`flexway.schema.json`, `contract-extensions.schema.json` and, since `1.7.0`,
`policy-fragment.schema.json` (policy fragments) and `architecture.schema.json` (the
`flexway.architecture.v1` model of the console's Architecture screen).

```sh
flexway schema [--out <directory>]
```

| Option | Default | Role |
| --- | --- | --- |
| `--out` | `.` | The directory the files are written to; each written path is printed |

| Code | Meaning |
| --- | --- |
| `0` | Written |
| `1` | Write failed |
| `2` | Misused command line |

```bash
docker run --rm -v "$PWD:/out" -u "$(id -u)" ghcr.io/flexwiz/flexway:<version> schema --out /out
```

Guide: [Validating in your editor](https://flexway.io/en/docs/operations-editor-validation/).

## flexway fragment digest

Reads a policy fragment file (`kind: PolicyFragment`) and prints the digest that pins it in
`policies.fragments.<import>.digest`: `sha256:` followed by the `sha256` of its bytes, what `sha256sum`
prints. A file no gateway would load (unknown key, a host, an import of another fragment, a literal
secret) is refused without a digest. Since `1.7.0`.

```sh
flexway fragment digest <fragment.yaml>
```

| Code | Meaning |
| --- | --- |
| `0` | The digest, alone on its line |
| `1` | File unreadable or refused: the reason |
| `2` | Misused command line |

```bash
make fragment-digest FILE=security-baseline.yaml
```

Guide: [Shared policy fragments](https://flexway.io/en/docs/operations-policy-fragments/).

## flexway version

Prints `flexway <version> (<commit>)`: the release tag, or `dev` for a build that is not a release. The
same value is in `build` of `/config` and at the foot of the console.

```bash
docker run --rm ghcr.io/flexwiz/flexway:<version> version
```

## flexway-console users

Manages the console's local accounts, from its container (`FLEXWAY_CONSOLE_STORE` must name the account
store). An invitation link is valid 72 h and printed once.

| Subcommand | Role |
| --- | --- |
| `list` | The local accounts: login, name, role, tenant, status, second factor, last sign-in |
| `add [login]` | A new account - asks for its name, its role (`viewer` or `admin`) and, for a viewer, its tenant; prints its invitation link |
| `reset <login>` | Invalidates the password and the sessions; prints a new invitation link |
| `mfa-reset <login>` | Turns the second factor off: the account enrols again at its next sign-in |
| `unlock <login>` | Ends every lockout of the account |
| `disable <login>` | Disables the account (never the last active admin) |

| Code | Meaning |
| --- | --- |
| `0` | Done |
| `1` | Refused (unknown account, last admin...) |
| `2` | Unknown or missing subcommand, store not configured |

```bash
kubectl exec deploy/<release>-flexway-console -- flexway-console users reset admin
```

Guide: [Console accounts](https://flexway.io/en/docs/operations-console-accounts/).

## flexway-console version

Prints `flexway-console <version> (<commit>)`.