helldweller · Oct 26, 2026 · Oct 26, 2026
@@ -6,7 +6,7 @@ description: Overview of the Dispatch CLI.
 
 Dispatch ships with a robust CLI, providing configuration, server, scheduler, plugin, database, and shell commands. Here we'll give a partial overview; if you'd like a complete list of Dispatch commands available via the CLI, please use the command `dispatch --help` once you have installed the application.
 
-## Server
+## Server {#server}
 
 The server sub-command contains all Dispatch server-related commands.
 
@@ -27,7 +27,7 @@ Commands:
   start
 ```
 
-### Config
+### Config {#config}
 
 The `config` command helps debug as it shows the configuration variables seen by the server \(combining envvars, defaults, and the .env file\).
 
@@ -42,15 +42,15 @@ METRIC_PROVIDERS                          spectator-metric
 ...
 ```
 
-### Develop
+### Develop {#develop}
 
 The `develop` command starts the development server. This server will continually watch for file changes and reload the server accordingly. You'll find it useful to combine this with a `DEBUG` log level, as below.
 
 ```bash
 > dispatch server develop --log-level debug
 ```
 
-### Routes
+### Routes {#routes}
 
 The `routes` command is useful for development. This command shows which endpoints the server is currently listening on, the HTTP verb methods are accepted, and whether authentication is enabled.
 
@@ -65,15 +65,15 @@ Path                                  Authenticated    Methods
 ...
 ```
 
-### Shell
+### Shell {#shell}
 
 The `shell` command is useful for development. It drops you into an interactive python shell with the same context as the server itself.
 
 ```bash
 > dispatch server shell
 ```
 
-### Start
+### Start {#start}
 
 The `start` command starts a production-grade Dispatch web server. It's an alias to the [uvicorn](https://www.uvicorn.org/) web server, so it contains all of the options and flags available with that server.
 
@@ -99,7 +99,7 @@ To start Dispatch, you will need to tell the start command where to find the `di
 > dispatch server start dispatch.main:app --workers 6 --host 127.0.0.1 --port 8000 --proxy-headers
 ```
 
-## Scheduler
+## Scheduler {#scheduler}
 
 The `scheduler` command contains all of the Dispatch scheduler logic.
 
@@ -117,7 +117,7 @@ Commands:
   start  Starts the scheduler.
 ```
 
-### List
+### List {#list}
 
 The `list` command lists all tasks registered with the scheduler. Today the scheduler periods are hardcoded and cannot be adjusted.
 
@@ -145,7 +145,7 @@ case-triage-reminder             1 day, 0:00:00  18:00:00
 case-stable-reminder             1 day, 0:00:00  18:00:00
 ```
 
-### Start
+### Start {#start-1}
 
 The `start` command starts the scheduler and allows tasks to be executed based on the defined period.
 
@@ -160,7 +160,7 @@ Often it's helpful to run a particular task immediately:
 > dispatch scheduler start incident-status-report-reminder --eager
 ```
 
-## Database
+## Database {#database}
 
 The `database` command contains all of the Dispatch database logic.
 
@@ -191,15 +191,15 @@ Commands:
 Note: The database command is a combination of custom commands and `alembic` commands. For more information about alembic database migrations, see [here](https://alembic.sqlalchemy.org/en/latest/).
 :::
 
-### Init
+### Init {#init}
 
 The `init` command takes a fresh database and creates the necessary tables and values for Dispatch to operate.
 
 ```bash
 > dispatch database init
 ```
 
-### Revision
+### Revision {#revision}
 
 The `revision` command is an `alembic` command that creates a new database schema revision based on the application's models.
 
@@ -209,25 +209,25 @@ Commonly used in conjunction with the `--autogenerate` flag:
 > dispatch database revision --autogenerate
 ```
 
-### Upgrade/Downgrade
+### Upgrade/Downgrade {#upgradedowngrade}
 
 The `upgrade` and `downgrade` commands manage how `alembic` database migrations are deployed, allowing you to move the database forward and backward through revisions. You'll often need to run the `upgrade` command after installing a new version of Dispatch.
 
 ```bash
 > dispatch database upgrade
 ```
 
-### Restore/Dump
+### Restore/Dump {#restoredump}
 
 The `restore` and `dump` commands allow you to quickly backup and restore the Dispatch database. It can also be used to load our [example](https://github.com/helldweller/dispatch/blob/main/data/dispatch-sample-data.dump) data set into your Dispatch installation.
 
 Today, the `.dump` file must be located in `$CWD` and must be named `dispatch-backup.dump`.
 
-## Plugins
+## Plugins {#plugins}
 
 The `plugin` command contains all of the logic for dealing with Dispatch's plugins.
 
-### List
+### List {#list-1}
 
 The `list` command lists all currently available plugins. This command is useful in determining which plugins are available to be used via configuration variables.
 
@@ -242,7 +242,7 @@ Google Group - Participant Group  google-group-participant-group  0.1.0       pa
 ...
 ```
 
-### Install
+### Install {#install}
 
 The `install` command will try installing all available plugins.
 

@@ -0,0 +1 @@
+{ "label": "Plugins", "key": "contributing-plugins" }
@@ -1,6 +1,6 @@
 # FAQ
 
-## Running ‘dispatch database upgrade’ seems stuck.
+## Running ‘dispatch database upgrade’ seems stuck. {#running-dispatch-database-upgrade-seems-stuck}
 
 The upgrade is most likely stuck because an existing query on the database is holding onto a lock that the migration needs.
 

@@ -8,15 +8,15 @@ tags:
 
 Dispatch relies on multiple services to work, which are all orchestrated by `Docker Compose`.
 
-### Requirements
+### Requirements {#requirements}
 
 - [Docker](https://www.docker.com/) 17.05.0+
 - [Docker Compose](https://docs.docker.com/compose/) 1.19.0+
 - A dedicated \(sub\)domain to host Dispatch on \(for example, dispatch.yourcompany.com\).
 - At least 2400MB memory
 - 2 CPU Cores
 
-## Installing Dispatch Server
+## Installing Dispatch Server {#installing-dispatch-server}
 
 We strongly recommend using Docker for installing Dispatch and all its services. If you need to do something custom, you can use this repository as the basis of your setup. If you do not wish to use the Docker images we provide, you can still find Dispatch on PyPI; however, we don't recommend that method. You'll need to work your way back from the main Dispatch image. It is not too hard, but you are likely to spend a lot more time and hit some bumps.
 
@@ -46,7 +46,7 @@ To start, run the install script:
 Note: The `core` Docker service is not needed once the `web` and `schedule` services, which depend on it, are built.
 :::
 
-### The "first" user problem
+### The "first" user problem {#the-first-user-problem}
 
 For any new Dispatch installation, new users are expected to register themselves via the `/auth/register` endpoint in the Dispatch UI. By default, users registering via this method are granted regular "user" permissions within Dispatch. There is no direct way through the UI to allow a user to obtain an "Owner" role (as no other Owners exist to grant them access).
 
@@ -61,11 +61,11 @@ The default organization name in the sample data file is "default".
 
 After one owner user has been established, they can grant this role to others via the UI.
 
-## Going to Production
+## Going to Production {#going-to-production}
 
 Before you deploy Dispatch to production, there are a few considerations and steps that should be taken.
 
-### Basics
+### Basics {#basics}
 
 Because of the sensitivity of the information stored and maintained by Dispatch. You must follow standard host hardening practices:
 
@@ -74,21 +74,21 @@ Because of the sensitivity of the information stored and maintained by Dispatch.
 - Enable remote logging
 - Restrict access to the host
 
-### Credential Management
+### Credential Management {#credential-management}
 
 Dispatch plugins require API tokens to communicate with third-party resources. These tokens are stored in either an environment variable or in the Dispatch `.env` file.
 
 By default, these strings are in plain text, but Dispatch does provide hooks that allow for these credentials to be decrypted on server start. See the [Secret Provider](./settings/server.mdx#general) configuration option.
 
-### Authentication
+### Authentication {#authentication}
 
 Dispatch provides a "Basic" authentication provider that controls access via a username and password combination to get going quickly. By default, this provider allows for **open registration**, which means that anyone will be able to create a Dispatch account if they have network access to your server.
 
 Dispatch provides a "PKCE" authentication method to integrate existing and more robust SSO solutions for more robust authentication. See the [Authentication Provider](./settings/server.mdx#authentication)
 
-### TLS/SSL
+### TLS/SSL {#tlsssl}
 
-#### Nginx
+#### Nginx {#nginx}
 
 Nginx is a popular choice to serve a Python project:
 

@@ -24,7 +24,7 @@ no allow list. The tenant boundary *is* the authorization boundary, which is why
 See [Who can sign in](#who-can-sign-in).
 :::
 
-## Create the app registration
+## Create the app registration {#create-the-app-registration}
 
 In the [Microsoft Entra admin center](https://entra.microsoft.com), go to
 **Identity → Applications → App registrations → New registration**.
@@ -38,15 +38,15 @@ In the [Microsoft Entra admin center](https://entra.microsoft.com), go to
 Record the **Application (client) ID** and the **Directory (tenant) ID** from the
 registration's Overview page.
 
-### Supported account types
+### Supported account types {#supported-account-types}
 
 Choose **single tenant**. Dispatch has no per-user approval step, so a multitenant
 registration means any Microsoft work, school, or personal account in the world
 can sign in and be provisioned. Only pick multitenant if you genuinely intend to
 admit guests from other directories, and pair it with a separate authorization
 control — the issuer setting below can only pin one tenant.
 
-### Redirect URI
+### Redirect URI {#redirect-uri}
 
 The redirect URI must be registered under the **Single-page application**
 platform, not **Web**. That is what makes Entra:
@@ -64,15 +64,15 @@ this one URI needs registering however many routes the app has. Add
 `http://localhost:8080/implicit/callback` as a second URI if you want the local
 dev server to sign in against the same registration.
 
-### Client secret
+### Client secret {#client-secret}
 
 **Do not create one.** A single-page application is a public client; Microsoft
 documents that SPAs must not use secrets or certificates when redeeming an
 authorization code, and Entra refuses client credentials on any request carrying
 an `Origin` header. Dispatch never sends one and has nowhere to put one that the
 browser could not read. PKCE, not a secret, is what binds the code to this client.
 
-### Scopes and permissions
+### Scopes and permissions {#scopes-and-permissions}
 
 `openid`, `profile` and `email` — the three OpenID Connect scopes the frontend
 already requests. Nothing else. These are delegated permissions that need no
@@ -82,7 +82,7 @@ the user's identity out of the ID token and never calls Graph.
 Leave **API permissions** at the `User.Read` default Entra adds, or remove it.
 Dispatch does not use it.
 
-### Token claims
+### Token claims {#token-claims}
 
 Dispatch needs exactly one claim: an email address to key the user on. By default
 it reads `email`, but Entra emits `email` for a managed user only if you add it as
@@ -101,7 +101,7 @@ addresses — Dispatch also uses this value to match people to incidents and to
 address notifications — add `email` under **Token configuration → Add optional
 claim → ID → email** and leave `DISPATCH_JWT_EMAIL_OVERRIDE` unset instead.
 
-## Configure Dispatch
+## Configure Dispatch {#configure-dispatch}
 
 With `<tenant-id>` and `<client-id>` from the registration:
 
@@ -136,7 +136,7 @@ Notes on the less obvious ones:
 * Settings prefixed `VITE_` are read when the frontend bundle is **built**, not
   when the server starts — see [Frontend build](#frontend-build).
 
-### Restricting sign-in to your tenant
+### Restricting sign-in to your tenant {#restricting-sign-in-to-your-tenant}
 
 Two things do this, and both matter:
 
@@ -155,7 +155,7 @@ with Dispatch's: set **Enterprise applications → Dispatch → Properties →
 Assignment required** to **Yes** and assign the groups that should have access.
 Dispatch has no equivalent.
 
-### Frontend build
+### Frontend build {#frontend-build}
 
 The three `VITE_`-prefixed values are compiled into the JavaScript bundle, so
 changing them means rebuilding the frontend, not restarting the server. When
@@ -174,7 +174,7 @@ The backend settings are ordinary environment variables and take effect on
 restart. None of them is a secret, so they are safe in a Compose file or an image
 build log — there is no client secret anywhere in this configuration.
 
-## Who can sign in
+## Who can sign in {#who-can-sign-in}
 
 Dispatch provisions on first sight. The first request carrying an ID token it
 accepts creates a `DispatchUser` with the `Member` role in the organization being
@@ -189,7 +189,7 @@ Consequently:
   **Settings → Users**, or with
   `dispatch user update --role owner --organization <org> <email>`.
 
-### Existing Dispatch users
+### Existing Dispatch users {#existing-dispatch-users}
 
 Users are keyed by email address, and that does not change when you enable Entra.
 An account that already exists — created by basic auth self-registration, by an
@@ -212,14 +212,14 @@ resolved back to an address anyway. The tenant restriction, not the claim's
 immutability, is what makes the address trustworthy.
 :::
 
-## Verifying it works
+## Verifying it works {#verifying-it-works}
 
 1. Restart the server (and rebuild the frontend) with the settings above.
 2. Open Dispatch. You should be redirected to `login.microsoftonline.com` and back.
 3. Check the server log at startup. The PKCE provider warns about anything it
    needs and does not have — a missing JWKS URL, issuer, or audience.
 
-### Troubleshooting
+### Troubleshooting {#troubleshooting}
 
 | Symptom | Cause |
 | --- | --- |
@@ -231,7 +231,7 @@ immutability, is what makes the address trustworthy.
 | 401 with *Token carries no 'email' claim* | Set `DISPATCH_JWT_EMAIL_OVERRIDE=preferred_username`, or add the `email` optional claim. |
 | `AADSTS50011`, redirect URI mismatch | The registered URI must be the deployment origin plus `/implicit/callback`, exactly. |
 
-## Reverting to another provider
+## Reverting to another provider {#reverting-to-another-provider}
 
 There is nothing to undo in the database — Entra sign-in creates ordinary
 Dispatch users. To go back to basic authentication, set

@@ -16,6 +16,6 @@ It's common for incident response teams to maintain a list of contacts and run b
 
 **Company:** Company associated with the individual.
 
-#### Engagement
+#### Engagement {#engagement}
 
 In addition to fields about the individual, Dispatch allows you to associate the individual with other Dispatch primitives. For instance, if you would like to involve an individual for all incidents of a given priority, associate that priority with the individual.
@@ -18,6 +18,6 @@ Like `Teams`, there are often groups of individuals (teams) responsible for an a
 
 **Enabled:** Flag that determines if this particular service is active.
 
-#### Engagement
+#### Engagement {#engagement}
 
 In addition to the service fields, Dispatch allows you to associate the service with other Dispatch primitives. For instance, if you would like to involve a service for all incidents of a given priority, associate that priority with the service.
@@ -14,6 +14,6 @@ Like `Individuals`, there are often groups of individuals (teams) that need to b
 
 **Company:** Company associated with the team.
 
-#### Engagement
+#### Engagement {#engagement}
 
 In addition to fields about the team, Dispatch allows you to associate a team with other Dispatch primitives. For instance, if you would like to involve an entire team for all incidents of a given priority, associate that priority with the team.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		{ "label": "Plugins", "key": "contributing-plugins" }