# Usage
## Main Command
```
BES tooling: Alert daemon
The daemon watches for changes to alert definition files and automatically
reloads when changes are detected. You can also send SIGHUP to manually trigger
a reload.
On Windows, the daemon can be installed as a native Windows service using the
'install' subcommand. See 'bestool-alertd install --help' for details.
Usage: bestool-alertd [OPTIONS] <COMMAND>
Commands:
run Run the alert daemon
reload Send reload signal to running daemon
loaded-alerts List currently loaded alert files
pause-alert Temporarily pause an alert
validate Validate an alert definition file
help Print this message or the help of the given subcommand(s)
Options:
--color <MODE>
When to use terminal colours.
You can also set the `NO_COLOR` environment variable to disable
colours, or the `CLICOLOR_FORCE` environment variable to force
colours. Defaults to `auto`, which checks whether the output is a
terminal to decide.
Possible values:
- auto: Automatically detect whether to use colours
- always: Always use colours, even if the terminal does not support
them
- never: Never use colours
[default: auto]
-v, --verbose...
Set diagnostic log level.
This enables diagnostic logging, which is useful for investigating
bugs. Use multiple times to increase verbosity.
You may want to use with `--log-file` to avoid polluting your
terminal.
--log-file [<PATH>]
Write diagnostic logs to a file.
This writes diagnostic logs to a file, instead of the terminal, in
JSON format.
If the path provided is a directory, a file will be created in that
directory. The file name will be the current date and time, in the
format `programname.YYYY-MM-DDTHH-MM-SSZ.log`.
--log-timeless
Omit timestamps in logs.
This can be useful when running under service managers that capture
logs, to avoid having two timestamps. When run under systemd, this is
automatically enabled.
This option is ignored if the log file is set, or when using
`RUST_LOG` or equivalent (as logging is initialized before arguments
are parsed in that case); you may want to use `LOG_TIMELESS` instead
in the latter case.
-h, --help
Print help (see a summary with '-h')
```
## Subcommands
### `run`
```
Run the alert daemon
Starts the daemon which monitors alert definition files and executes alerts
based on their configured schedules. The daemon will watch for file changes and
automatically reload when definitions are modified.
Usage: bestool-alertd run [OPTIONS]
Options:
--database-url <DATABASE_URL>
Database connection URL
PostgreSQL connection URL, e.g.,
postgresql://user:pass@localhost/dbname
[env: DATABASE_URL=]
--glob <GLOB>
Glob patterns for alert definitions
Patterns can match directories (which will be read recursively) or
individual files. Can be provided multiple times. Examples:
/etc/tamanu/alerts, /opt/*/alerts, /etc/tamanu/alerts/**/*.yml
--email-from <EMAIL_FROM>
Email sender address
[env: EMAIL_FROM=]
--mailgun-api-key <MAILGUN_API_KEY>
Mailgun API key
[env: MAILGUN_API_KEY=]
--mailgun-domain <MAILGUN_DOMAIN>
Mailgun domain
[env: MAILGUN_DOMAIN=]
--dry-run
Execute all alerts once and quit (ignoring intervals)
--no-server
Disable the HTTP server
--server-addr <SERVER_ADDR>
HTTP server bind address(es)
Can be provided multiple times. The server will attempt to bind to
each address in order until one succeeds. Defaults to [::1]:8271 and
127.0.0.1:8271
-h, --help
Print help (see a summary with '-h')
```
### `reload`
```
Send reload signal to running daemon
Connects to the running daemon's HTTP API and triggers a reload. This is an
alternative to SIGHUP that works on all platforms including Windows.
Usage: bestool-alertd reload [OPTIONS]
Options:
--server-addr <SERVER_ADDR>
HTTP server address(es) to try
Can be provided multiple times. Will attempt to connect to each
address in order until one succeeds. Defaults to [::1]:8271 and
127.0.0.1:8271
-h, --help
Print help (see a summary with '-h')
```
### `loaded-alerts`
```
List currently loaded alert files
Connects to the running daemon's HTTP API and retrieves the list of currently
loaded alert definition files.
Usage: bestool-alertd loaded-alerts [OPTIONS]
Options:
--server-addr <SERVER_ADDR>
HTTP server address(es) to try
Can be provided multiple times. Will attempt to connect to each
address in order until one succeeds. Defaults to [::1]:8271 and
127.0.0.1:8271
--detail
Show detailed state information for each alert
-h, --help
Print help (see a summary with '-h')
```
### `pause-alert`
```
Temporarily pause an alert
Pauses an alert until the specified time. The alert will not execute during this
period. The pause is lost when the daemon restarts.
Usage: bestool-alertd pause-alert [OPTIONS] <ALERT>
Arguments:
<ALERT>
Alert file path to pause
Options:
--until <UNTIL>
Time until which to pause the alert (fuzzy time format)
Examples: "1 hour", "2 days", "next monday", "2024-12-25T10:00:00Z"
Defaults to 1 week from now if not specified.
--server-addr <SERVER_ADDR>
HTTP server address(es) to try
Can be provided multiple times. Will attempt to connect to each
address in order until one succeeds. Defaults to [::1]:8271 and
127.0.0.1:8271
-h, --help
Print help (see a summary with '-h')
```
### `validate`
```
Validate an alert definition file
Parses an alert definition file and reports any syntax or validation errors.
Uses pretty error reporting to pinpoint the exact location of problems. Requires
the daemon to be running.
Usage: bestool-alertd validate [OPTIONS] <FILE>
Arguments:
<FILE>
Path to the alert definition file to validate
Options:
--server-addr <SERVER_ADDR>
HTTP server address(es) to try
Can be provided multiple times. Will attempt to connect to each
address in order until one succeeds. Defaults to [::1]:8271 and
127.0.0.1:8271
-h, --help
Print help (see a summary with '-h')
```