# Ligne de commande

> Chaque commande des binaires flexway et flexway-console : options, codes de sortie, exemples, depuis le binaire ou l'image publiée.

Référence - Depuis la version 0.1.0 - Flexway v1.7.1 - https://flexway.io/docs/reference-cli/

Le binaire `flexway` est à la fois le service et ses outils : sans argument, il sert ; suivi d'une
commande, il vérifie, convertit ou écrit, **hors ligne**, sans démarrer d'écouteur. Les mêmes commandes
sont dans chaque image publiée, dont le point d'entrée est le binaire :

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

Les options s'écrivent avec un ou deux tirets (`-config` ou `--config`). `-h` affiche l'aide d'une
commande et sort en `0`.

## Sommaire

| Commande | Rôle | Codes de sortie | Depuis |
| --- | --- | --- | --- |
| [`flexway`](#flexway) | Servir | - | `0.1.0` |
| [`flexway validate`](#flexway-validate) | Valider une configuration et ses contrats | `0`, `1`, `2` | `0.1.0` |
| [`flexway import krakend`](#flexway-import-krakend) | Reprendre une configuration KrakenD | `0`, `1`, `2`, `3` | `1.2.0` |
| [`flexway api-key`](#flexway-api-key) | Créer une clé d'API | `0`, `1` | `0.1.0` |
| [`flexway schema`](#flexway-schema) | Écrire les schémas publiés de la configuration | `0`, `1`, `2` | `1.7.0` |
| [`flexway fragment digest`](#flexway-fragment-digest) | Calculer l'empreinte qui épingle un fragment de politique | `0`, `1`, `2` | `1.7.0` |
| [`flexway version`](#flexway-version) | Dire quelle version tourne | `0` | `1.1.0` |
| [`flexway-console users`](#flexway-console-users) | Gérer les comptes locaux de la console | `0`, `1`, `2` | `1.0.0` |
| [`flexway-console version`](#flexway-console-version) | Dire quelle version de la console tourne | `0` | `1.1.0` |

## flexway

Sert la configuration nommée par l'environnement. `SIGTERM` draine les requêtes en cours puis arrête,
`SIGHUP` relit la configuration tout de suite.

| Variable | Défaut | Rôle |
| --- | --- | --- |
| `FLEXWAY_CONFIG` | - (obligatoire ; `/etc/flexway/flexway.yaml` dans l'image) | Le `flexway.yaml` à servir |
| `FLEXWAY_ADDR` | `:8080` | Écouteur de trafic |
| `FLEXWAY_ADMIN_ADDR` | `:9090` | Écouteur d'administration ([API d'administration](https://flexway.io/docs/reference-admin-api/)) |
| `FLEXWAY_TLS_ADDR` | `:8443` | Écouteur TLS, quand `server.tls` est posé |

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

## flexway validate

Charge la configuration et chaque contrat qu'elle nomme avec le chargeur du démarrage - mêmes
contrôles, mêmes refus - sans réseau ni grappe. Une référence de secret (`${VAR}`, `file:/...`) est
vérifiée dans sa forme, pas résolue.

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

| Option | Défaut | Rôle |
| --- | --- | --- |
| `--config` | `$FLEXWAY_CONFIG`, sinon `flexway.yaml` | La configuration à valider ; les chemins qu'elle contient se lisent depuis son dossier |
| `--contract` | - | Un autre contrat OpenAPI, validé à la place de `contracts.openapi` |
| `-v` | non | Liste chaque opération résolue (méthode, gabarit, amont) et l'empreinte complète |

| Code | Sens |
| --- | --- |
| `0` | Acceptée : `valid: <n> operation(s) served from <n> contract(s), <n> upstream(s)` puis `config_digest <empreinte>` |
| `1` | Refusée : le champ fautif et la raison |
| `2` | Ligne de commande mal formée |

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

L'empreinte `config_digest` est celle que publie `/config` d'une réplique qui sert cette configuration.
Guide : [Servir sa première API](https://flexway.io/docs/operations-first-api/).

## flexway import krakend

Convertit une fois, hors ligne, un `krakend.json` : un `flexway.yaml`, le contrat annoté, le même ajout
en JSON Patch (`contract.patch.json`) et un rapport `coverage.md`. Le résultat passe le chargeur du
démarrage avant d'être écrit.

```sh
flexway import krakend --config krakend.json --contract openapi.yaml --out <dossier vide>
```

| Option | Défaut | Rôle |
| --- | --- | --- |
| `--config` | `krakend.json` | La configuration KrakenD (rendue, si elle est flexible) |
| `--contract` | - (obligatoire) | Le contrat OpenAPI auquel les endpoints sont rapportés |
| `--out` | - (obligatoire) | Un dossier vide ou absent : l'import n'écrase jamais |

| Code | Sens |
| --- | --- |
| `0` | Tout est repris |
| `1` | Refus, rien n'est écrit |
| `2` | Ligne de commande mal formée |
| `3` | Repris, avec des éléments sans équivalent listés dans `coverage.md` |

Guide : [Reprendre une passerelle existante](https://flexway.io/docs/operations-import/).

## flexway api-key

Crée une clé d'API. La commande **demande** son identifiant, son tenant, les opérations qu'elle ouvre
(`operationId` séparés par des virgules) et sa fin (`90d`, `12w` ou une date `AAAA-MM-JJ` ; `90d` par
défaut), puis affiche la clé **une seule fois** et l'entrée à ajouter au magasin de clés - son
empreinte SHA-256, jamais la clé. Aucune option : les saisies sont interactives.

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

| Code | Sens |
| --- | --- |
| `0` | Clé créée |
| `1` | Refus : identifiant mal formé (2 à 64 caractères, minuscules, chiffres, `.`, `_`, `-`), tenant ou opérations absents, date passée |

Guide : [Clés d'API](https://flexway.io/docs/operations-api-keys/).

## flexway schema

Écrit les schémas publiés de la configuration (JSON Schema 2020-12) depuis le modèle du binaire, hors
ligne : `flexway.schema.json`, `contract-extensions.schema.json` et, depuis `1.7.0`,
`policy-fragment.schema.json` (fragments de politique) et `architecture.schema.json` (modèle
`flexway.architecture.v1` de l'écran Architecture de la console).

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

| Option | Défaut | Rôle |
| --- | --- | --- |
| `--out` | `.` | Le dossier où les fichiers sont écrits ; chaque chemin écrit est affiché |

| Code | Sens |
| --- | --- |
| `0` | Écrits |
| `1` | Échec d'écriture |
| `2` | Ligne de commande mal formée |

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

Guide : [Valider dans son éditeur](https://flexway.io/docs/operations-editor-validation/).

## flexway fragment digest

Lit un fichier de fragment de politique (`kind: PolicyFragment`) et affiche l'empreinte qui l'épingle
dans `policies.fragments.<import>.digest` : `sha256:` suivi du `sha256` de ses octets, la valeur de
`sha256sum`. Un fichier qu'aucune passerelle ne chargerait (clé inconnue, hôte, import d'un autre
fragment, secret en clair) est refusé sans empreinte. Depuis `1.7.0`.

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

| Code | Sens |
| --- | --- |
| `0` | L'empreinte, seule sur sa ligne |
| `1` | Fichier illisible ou refusé : la raison |
| `2` | Ligne de commande mal formée |

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

Guide : [Fragments de politique partagés](https://flexway.io/docs/operations-policy-fragments/).

## flexway version

Affiche `flexway <version> (<commit>)` : le tag de la release, ou `dev` pour un build qui n'en est pas
une. La même valeur est dans `build` de `/config` et au pied de la console.

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

## flexway-console users

Gère les comptes locaux de la console, depuis son conteneur (`FLEXWAY_CONSOLE_STORE` doit désigner le
magasin des comptes). Un lien d'invitation est valable 72 h et affiché une seule fois.

| Sous-commande | Rôle |
| --- | --- |
| `list` | Les comptes locaux : identifiant, nom, rôle, tenant, statut, second facteur, dernière connexion |
| `add [login]` | Un nouveau compte - demande son nom, son rôle (`viewer` ou `admin`) et, pour un lecteur, son tenant ; affiche son lien d'invitation |
| `reset <login>` | Invalide le mot de passe et les sessions ; affiche un nouveau lien d'invitation |
| `mfa-reset <login>` | Désactive le second facteur : le compte s'enrôle à nouveau à sa prochaine connexion |
| `unlock <login>` | Lève tous les verrouillages du compte |
| `disable <login>` | Désactive le compte (jamais le dernier admin actif) |

| Code | Sens |
| --- | --- |
| `0` | Fait |
| `1` | Refus (compte inconnu, dernier admin...) |
| `2` | Sous-commande inconnue ou absente, magasin non configuré |

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

Guide : [Comptes de la console](https://flexway.io/docs/operations-console-accounts/).

## flexway-console version

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