docs: Rename the "usage" section to "reference"

docs/reference/cli/README.md

@@ -0,0 +1,36 @@
+# Command line tool
+
+The command line interface provides subcommands that helps running the service.
+
+## Logging
+
+The overall log level of the CLI can be changed via the `RUST_LOG` environment variable.
+Default log level is `info`.
+Valid levels from least to most verbose are `error`, `warn`, `info`, `debug` and `trace`.
+
+## Global flags
+
+### `--config`
+
+Sets the configuration file to load.
+It can be repeated multiple times to merge multiple files together.
+
+---
+
+```
+Usage: mas-cli [OPTIONS] [COMMAND]
+
+Commands:
+  config     Configuration-related commands
+  database   Manage the database
+  server     Runs the web server
+  worker     Run the worker
+  manage     Manage the instance
+  templates  Templates-related commands
+  doctor     Run diagnostics on the deployment
+  help       Print this message or the help of the given subcommand(s)
+
+Options:
+  -c, --config <CONFIG>  Path to the configuration file
+  -h, --help             Print help
+```

docs/reference/cli/config.md

@@ -0,0 +1,51 @@
+# `config`
+
+Helps to deal with the configuration
+
+## `config check`
+
+Check the validity of configuration files.
+
+```console
+$ mas-cli config check --config=config.yaml
+INFO mas_cli::config: Configuration file looks good path=["config.yaml"]
+```
+
+## `config dump`
+
+Dump the merged configuration tree.
+
+```console
+$ mas-cli config dump --config=first.yaml --config=second.yaml
+---
+clients:
+  # ...
+```
+
+## `config generate`
+
+Generate a sample configuration file.
+It generates random signing keys (`.secrets.keys`) and the cookie encryption secret (`.secrets.encryption`).
+
+```console
+$ mas-cli config generate > config.yaml
+INFO generate: mas_config::oauth2: Generating keys...
+INFO generate:rsa: mas_config::oauth2: Done generating RSA key
+INFO generate:ecdsa: mas_config::oauth2: Done generating ECDSA key
+```
+
+## `config sync [--prune] [--dry-run]`
+
+Synchronize the configuration with the database.
+This will synchronize the `clients` and `upstream_oauth` sections of the configuration with the database.
+By default, it does not delete clients and upstreams that are not in the configuration anymore. Use the `--prune` option to do so.
+The `--dry-run` option will log the changes that would be made, without actually making them.
+
+```console
+$ mas-cli config sync --prune --config=config.yaml
+INFO cli.config.sync: Syncing providers and clients defined in config to database prune=true dry_run=false
+INFO cli.config.sync: Updating provider provider.id=01H3FDH2XZJS8ADKRGWM84PZTY
+INFO cli.config.sync: Adding provider provider.id=01H3FDH2XZJS8ADKRGWM84PZTF
+INFO cli.config.sync: Deleting client client.id=01GFWRB9MYE0QYK60NZP2YF905
+INFO cli.config.sync: Updating client client.id=01GFWRB9MYE0QYK60NZP2YF904
+```

docs/reference/cli/database.md

@@ -0,0 +1,11 @@
+# `database`
+
+Run database-related operations
+
+## `database migrate`
+
+Run the pending database migrations
+
+```
+$ mas-cli database migrate
+```

docs/reference/cli/doctor.md

@@ -0,0 +1,10 @@
+# `doctor`
+
+Run diagnostics on the live deployment.
+This tool should help diagnose common issues with the service configuration and deployment.
+
+When running this tool, make sure it runs from the same point-of-view as the service, with the same configuration file and environment variables.
+
+```
+$ mas-cli doctor
+```

docs/reference/cli/manage.md

@@ -0,0 +1,7 @@
+# `manage`
+
+Includes admin-related subcommands.
+
+## `manage verify-email <username> <email>`
+
+Mark a user email address as verified

docs/reference/cli/server.md

@@ -0,0 +1,10 @@
+# `server`
+
+Runs the authentication service.
+
+```
+$ mas-cli server
+INFO mas_cli::server: Starting task scheduler
+INFO mas_core::templates: Loading builtin templates
+INFO mas_cli::server: Listening on http://0.0.0.0:8080
+```

docs/reference/cli/templates.md

@@ -0,0 +1,37 @@
+# `templates`
+
+Helps customizing templates.
+
+## `templates save <path>`
+
+Save the builtin template in the specified folder.
+
+```console
+$ mas-cli templates save ./templates
+INFO mas_core::templates: Wrote template path="./templates/login.html"
+INFO mas_core::templates: Wrote template path="./templates/register.html"
+INFO mas_core::templates: Wrote template path="./templates/index.html"
+INFO mas_core::templates: Wrote template path="./templates/reauth.html"
+INFO mas_core::templates: Wrote template path="./templates/form_post.html"
+INFO mas_core::templates: Wrote template path="./templates/error.html"
+INFO mas_core::templates: Wrote template path="./templates/base.html"
+```
+
+By default this command won't overwrite existing files, but this behavior can be changed by adding the `--overwrite` flag.
+
+## `templates check <path>`
+
+Check the validity of the templates in the specified folder.
+It compiles the templates and then renders them with different contexts.
+
+```console
+$ mas-cli templates check ./templates
+INFO mas_core::templates: Loading builtin templates
+INFO mas_core::templates: Loading templates from filesystem path=./templates/**/*.{html,txt}
+INFO mas_core::templates::check: Rendering template name="login.html" context={"csrf_token":"fake_csrf_token","form":{"fields_errors":{},"form_errors":[],"has_errors":false}}
+INFO mas_core::templates::check: Rendering template name="register.html" context={"__UNUSED":null,"csrf_token":"fake_csrf_token"}
+INFO mas_core::templates::check: Rendering template name="index.html" context={"csrf_token":"fake_csrf_token","current_session":{"active":true,"created_at":"2021-09-24T13:26:52.962135085Z","id":1,"last_authd_at":"2021-09-24T13:26:52.962135316Z","user_id":2,"username":"john"},"discovery_url":"https://example.com/.well-known/openid-configuration"}
+...
+```
+
+Builtin templates are still loaded by default when running this command, but this can be skipped by adding the `--skip-builtin` flag.