Add documentation to account for all cli mas options and standardise format

docs/reference/cli/README.md

@@ -15,6 +15,14 @@ Valid levels from least to most verbose are `error`, `warn`, `info`, `debug` and
 Sets the configuration file to load.
 It can be repeated multiple times to merge multiple files together.
 
+### `--help`
+
+Print out help instructions.
+
+### `--version` 
+
+Print the mas cli version.
+
 ---
 
 ```
@@ -33,4 +41,5 @@ Commands:
 Options:
   -c, --config <CONFIG>  Path to the configuration file
   -h, --help             Print help
+  -V, --version          Print version
 ```

docs/reference/cli/config.md

@@ -2,6 +2,10 @@
 
 Helps to deal with the configuration
 
+Global options:
+- `--config <config>`: Path to the configuration file.
+- `--help`: Print help.
+
 ## `config check`
 
 Check the validity of configuration files.

docs/reference/cli/database.md

@@ -2,10 +2,14 @@
 
 Run database-related operations
 
+Global options:
+- `--config <config>`: Path to the configuration file.
+- `--help`: Print help.
+
 ## `database migrate`
 
-Run the pending database migrations
+Run the pending database migrations.
 
 ```
 $ mas-cli database migrate
-```
+```

docs/reference/cli/doctor.md

@@ -1,5 +1,11 @@
 # `doctor`
 
+Global options:
+- `--config <config>`: Path to the configuration file.
+- `--help`: Print help.
+
+## `doctor`
+
 Run diagnostics on the live deployment.
 This tool should help diagnose common issues with the service configuration and deployment.
 
@@ -7,4 +13,4 @@ When running this tool, make sure it runs from the same point-of-view as the ser
 
 ```
 $ mas-cli doctor
-```
+```

docs/reference/cli/manage.md

@@ -1,7 +1,104 @@
 # `manage`
 
-Includes admin-related subcommands.
 
-## `manage verify-email <username> <email>`
+The MAS CLI provides several subcommands for managing users and configurations
 
-Mark a user email address as verified
+Global options:
+- `--config <config>`: Path to the configuration file.
+- `--help`: Print help.
+
+## `manage add-email`
+
+Add an email address to the specified user.
+
+```
+$ mas-cli manage add-email <username> <email>
+```
+
+## `manage verify-email`
+
+[DEPRECATED] Mark an email address as verified.
+
+```
+$ mas-cli manage verify-email <username> <email>
+```
+
+## `manage set-password`
+
+Set a user password.
+
+Options:
+- `--ignore-complexity`: Don't enforce that the password provided is above the minimum configured complexity.
+
+```
+$ mas-cli manage set-password <username> <password> --ignore-complexity
+```
+
+## `manage issue-compatibility-token`
+
+Issue a compatibility token for a user.
+
+Options:
+- `--device-id <device_id>`: Device ID to set in the token. If not specified, a random device ID will be generated.
+- `--yes-i-want-to-grant-synapse-admin-privileges`: Whether the token should be given admin privileges.
+
+```
+$ mas-cli manage issue-compatibility-token <username> --device-id <device_id> --yes-i-want-to-grant-synapse-admin-privileges
+```
+
+## `manage provision-all-users`
+
+Trigger a provisioning job for all users.
+
+```
+$ mas-cli manage provision-all-users
+```
+
+## `manage kill-sessions`
+
+Kill all sessions for a user.
+
+Options:
+- `--dry-run`: Do a dry run, ie see which sessions would be killed.
+
+```
+$ mas-cli manage kill-sessions <username> --dry-run
+```
+
+## `manage lock-user`
+
+Lock a user.
+
+Options:
+- `--deactivate`: Whether to deactivate the user.
+
+```
+$ mas-cli manage lock-user <username> --deactivate
+```
+
+## `manage unlock-user`
+
+Unlock a user.
+
+```
+$ mas-cli manage unlock-user <username>
+```
+
+## `manage register-user`
+
+Register a user. This will interactively prompt for the user's attributes unless the `--yes` flag is set. It bypasses any policy check on the password, email, etc.
+
+Options:
+- `--username <username>`: Username to register.
+- `--password <password>`: Password to set.
+- `--email <email>`: Email to add. Can be specified multiple times.
+- `--upstream-provider-mapping <UPSTREAM_PROVIDER_ID:SUBJECT>`: Upstream OAuth 2.0 provider mapping. Can be specified multiple times.
+- `--admin`: Make the user an admin.
+- `--no-admin`: Make the user not an admin.
+- `--yes`: Don't ask questions, just do it.
+- `--display-name <display_name>`: Set the user's display name.
+- `--ignore-password-complexity`: Don't enforce that the password provided is above the minimum configured complexity.
+
+```
+$ mas-cli manage register-user
+```

docs/reference/cli/server.md

@@ -1,7 +1,18 @@
 # `server`
 
+Global options:
+- `--config <config>`: Path to the configuration file.
+- `--help`: Print help.
+
+## `server`
+
 Runs the authentication service.
 
+Options:
+- `--no-migrate`: Do not apply pending database migrations on start.
+- `--no-worker`: Do not start the task worker.
+- `--no-sync`: Do not sync the configuration with the database.
+
 ```
 $ mas-cli server
 INFO mas_cli::server: Starting task scheduler

docs/reference/cli/templates.md

@@ -1,5 +1,9 @@
 # `templates`
 
+Global options:
+- `--config <config>`: Path to the configuration file.
+- `--help`: Print help.
+
 ## `templates check`
 
 Check the validity of the templates loaded by the config.

docs/reference/cli/worker.md

@@ -0,0 +1,13 @@
+# `worker`
+
+Global options:
+- `--config <config>`: Path to the configuration file.
+- `--help`: Print help.
+
+## `worker`
+
+Runs the authentication service worker.
+
+```
+$ mas-cli worker
+```