Document more mas-cli subcommands and standardise the format (#3988)

Added all the missing commands, and tried to standardise the formatting
across the various pages.

Author: sandhose

docs/SUMMARY.md

@@ -33,6 +33,7 @@
     - [`database`](./reference/cli/database.md)
     - [`manage`](./reference/cli/manage.md)
     - [`server`](./reference/cli/server.md)
+    - [`worker`](./reference/cli/worker.md)
     - [`templates`](./reference/cli/templates.md)
     - [`doctor`](./reference/cli/doctor.md)
 

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,10 +1,16 @@
 # `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.
 
 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

@@ -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
+```