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
The server sub-command contains all Dispatch server-related commands.
> dispatch server --help develop ⬇ ◼
Usage: dispatch server [OPTIONS] COMMAND [ARGS]...
Container for all dispatch server commands.
Options:
--help Show this message and exit.
Commands:
config Prints the current config as dispatch sees it.
develop Runs a simple server for development.
routes Prints all available routes.
shell Starts an ipython shell importing our app.
start
Config
The config command helps debug as it shows the configuration variables seen by the server (combining envvars, defaults, and the .env file).
> dispatch server config
>
Key Value
---------------------------------------- -----------------------
DISPATCH_DOMAIN example.com
STATIC_DIR
METRIC_PROVIDERS spectator-metric
...
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.
> dispatch server develop --log-level debug
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.
> dispatch server routes
Path Authenticated Methods
------------------------------------ --------------- ---------
/healthcheck False GET
/documents/ True GET
/documents/{document_id} True GET
/documents/ True POST
...
Shell
The shell command is useful for development. It drops you into an interactive python shell with the same context as the server itself.
> dispatch server shell
Start
The start command starts a production-grade Dispatch web server. It's an alias to the uvicorn web server, so it contains all of the options and flags available with that server.
> dispatch server start --help
Usage: dispatch server start [OPTIONS] APP
Options:
--host TEXT Bind socket to this host. [default:
127.0.0.1]
--port INTEGER Bind socket to this port. [default: 8000]
--uds TEXT Bind to a UNIX domain socket.
--fd INTEGER Bind to socket from this file descriptor.
--reload Enable auto-reload.
--reload-dir TEXT Set reload directories explicitly, instead
of using the current working directory.
...
To start Dispatch, you will need to tell the start command where to find the dispatch ASGI application. For example, a common set of flags might be:
> dispatch server start dispatch.main:app --workers 6 --host 127.0.0.1 --port 8000 --proxy-headers
Scheduler
The scheduler command contains all of the Dispatch scheduler logic.
> dispatch scheduler --help
Usage: dispatch scheduler [OPTIONS] COMMAND [ARGS]...
Container for all dispatch scheduler commands.
Options:
--help Show this message and exit.
Commands:
list Prints and runs all currently configured periodic tasks, in...
start Starts the scheduler.
List
The list command lists all tasks registered with the scheduler. Today the scheduler periods are hardcoded and cannot be adjusted.
> dispatch scheduler list
Task Name Period At Time
------------------------------- -------------- ---------
incident-status-report-reminder 1:00:00
incident-daily-summary 1 day, 0:00:00 18:00:00
calculate-incident-cost 0:05:00
incident-task-reminders 1:00:00
incident-task-sync 0:00:30
term-sync 1:00:00
document-term-sync 1 day, 0:00:00
application-sync 1:00:00
Start
The start command starts the scheduler and allows tasks to be executed based on the defined period.
> dispatch scheduler start
Starting scheduler...
Often it's helpful to run a particular task immediately:
> dispatch scheduler start incident-status-report-reminder --eager
Database
The database command contains all of the Dispatch database logic.
> dispatch database --help
Usage: dispatch database [OPTIONS] COMMAND [ARGS]...
Container for all dispatch database commands.
Options:
--help Show this message and exit.
Commands:
downgrade Downgrades database schema to the next newest version.
drop Drops all data in database.
heads Shows the heads of the database.
history Shows the history of the database.
init Initializes a new database.
populate Populates database with default values.
revision Create new database revision.
sync-triggers Ensures that all database triggers have been installed.
upgrade Upgrades database schema to newest version.
Note: The database command is a combination of custom commands and alembic commands. For more information about alembic database migrations, see here.
Init
The init command takes a fresh database and creates the necessary tables and values for Dispatch to operate.
> dispatch database init
Revision
The revision command is an alembic command that creates a new database schema revision based on the application's models.
Commonly used in conjunction with the --autogenerate flag:
> dispatch database revision --autogenerate
Upgrade/Downgrade
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.
> dispatch database upgrade
Restore/Dump
The restore and dump commands allow you to quickly backup and restore the Dispatch database. It can also be used to load our example data set into your Dispatch installation.
Today, the .dump file must be located in $CWD and must be named dispatch-backup.dump.
Plugins
The plugin command contains all of the logic for dealing with Dispatch's plugins.
List
The list command lists all currently available plugins. This command is useful in determining which plugins are available to be used via configuration variables.
> dispatch plugins list
Title Slug Version Type Author Description
-------------------------------- ------------------------------ ---------- ----------------- ------------- ---------------------------------------------------------
Dispatch - Document Resolver dispatch-document-resolver 0.1.0 document-resolver Kevin Glisson Uses dispatch itself to resolve incident documents.
Dispatch - Participants dispatch-participants 0.1.0 participant Kevin Glisson Uses dispatch itself to determine participants.
Google Docs - Document google-docs-document 0.1.0 document Kevin Glisson Uses google docs to manage document contents.
Google Group - Participant Group google-group-participant-group 0.1.0 participant_group Kevin Glisson Uses Google Groups to help manage participant membership.
...
Install
The install command will try installing all available plugins.
> dispatch plugins install
INFO:dispatch.common.utils.cli:Attempting to load plugin: dispatch_basic_auth
INFO:dispatch.common.utils.cli:Successfully loaded plugin: dispatch_basic_auth
INFO:dispatch.common.utils.cli:Attempting to load plugin: dispatch_contact
INFO:dispatch.common.utils.cli:Successfully loaded plugin: dispatch_contact
INFO:dispatch.common.utils.cli:Attempting to load plugin: dispatch_document_resolver
...
Keep in mind that this will only make plugins available. To enable them create and configure the plugin instance