datadog slo overrides CLI

CLI to set overrides idempotently for multiple SLO's

Usage

Set Datadog SLO corrections ("SLO overrides") on many SLOs at once, selected by tag. A correction excludes a time window from an SLO's error budget (e.g. for planned downtime); this tool is the bulk, idempotent, scriptable way to apply them.

Install

uv tool install datadog_slo_overrides_cli   # global `datadog-slo-overrides` command
# or run without installing:
uvx --from datadog_slo_overrides_cli datadog-slo-overrides --help
# or, from a checkout:
uv run datadog-slo-overrides --help

Check the installed version with datadog-slo-overrides --version.

Commands

Command	What it does
set	Preview (default) or --apply corrections (overrides) to every SLO matching the tags.
list	List SLOs matching the tags and their monitor downtime in a window, excluding downtime already covered by an override.
init-config	Write a starter config of non-secret defaults.
init-envrc	Write a starter .envrc for optional, direnv-managed credential loading.
commands list	Print a tree of every command this CLI provides.

Credentials

The tool never stores credentials. They are resolved in this order (first wins):

1. --api-key / --app-key flags
2. DD_API_KEY / DD_APP_KEY environment variables
3. an optional .envrc in the config dir, loaded via direnv

direnv-loaded values can never override a flag or a real environment variable.

Optional direnv setup (keep secret-fetching logic in a file that direnv's approval model governs, rather than the tool executing shell itself):

datadog-slo-overrides init-envrc                 # writes ~/.config/datadog-slo-overrides/.envrc
# it pre-fills DD_API_KEY / DD_APP_KEY exports; review and adjust the source if needed, then:
direnv allow ~/.config/datadog-slo-overrides

If the .envrc is present but unapproved, or doesn't export the keys, the tool prints an actionable hint instead of failing silently. The config dir honours XDG_CONFIG_HOME.

Selecting SLOs

• --tag key:value — repeat to require several tags. One tag is sent to Datadog's (single-tag) server query; the rest are ANDed client-side.
• --tags-query "<raw>" — a raw single-tag Datadog query, used as-is instead of --tag.

Idempotency strategies

set is idempotent: re-running the same command never creates duplicate corrections. --strategy controls when an existing correction counts as already covering your window:

--strategy	Skips (creates nothing) when…
skip-if-covered (default)	your window is fully inside an existing correction
skip-if-overlap	any existing correction overlaps your window (may leave gaps)
skip-if-exact	an existing correction matches your window exactly

Examples

Preview which SLOs would be corrected (dry run — nothing is written):

datadog-slo-overrides set --tag app:gitlab --tag customer:sbp \
    --start 2026-06-10T22:00 --end 2026-06-11T00:00

Apply a 2-hour scheduled-maintenance correction:

datadog-slo-overrides set --tag app:gitlab --tag customer:sbp \
    --start 2026-06-10T22:00 --end 2026-06-11T00:00 \
    --category "Scheduled Maintenance" --description "DB maintenance" \
    --apply

When a matched SLO is already covered, it is skipped rather than duplicated:

Already satisfied under --strategy skip-if-covered (will skip): 1
  SBP - SLO monitor for the sbp gitlab Website  (fbb8a2c3…)  -> correction d9e08dd2-…

DRY RUN — would create 0, skip 1 already present. Re-run with --apply to write.

Configuration file

init-config writes non-secret defaults (site, timezone, category, strategy) to ~/.config/datadog-slo-overrides/config.toml. CLI flags override the config, which overrides the built-in defaults. Credentials are never read from this file.

datadog-slo-overrides init-config

Run datadog-slo-overrides set --help for the full list of options.

Listing downtime

list shows each matching SLO's monitor downtime (from Datadog's Downtimes API) within a window, and excludes any downtime already covered by an SLO correction (override) — so what remains is the downtime that is not yet accounted for. The window defaults to the start of the current month through now; set --start/--end to change it. Tag selection is optional (omit both --tag and --tags-query to list every SLO).

# Uncovered downtime this month, for SLOs tagged app:gitlab:
datadog-slo-overrides list --tag app:gitlab

# A specific window:
datadog-slo-overrides list --tag app:gitlab --start 2026-07-01 --end 2026-07-15

Tags query : app:gitlab
Window     : 2026-07-01 00:00 → 2026-07-17 14:30 UTC
Matched    : 2 SLO(s)

SBP - SLO monitor for the sbp gitlab Website  (fbb8a2c3…)
  monitors: 12345
  • 2026-07-09 10:00 → 2026-07-09 11:00  (monitor 12345)  "deploy mute"

Only type: monitor SLOs link to monitors (via monitor_ids), so metric and time-slice SLOs show no monitor downtime. Downtimes targeted by monitor tags/scope (rather than a specific monitor id) can't be mapped to an SLO from the list alone, and are reported as a note at the end.

Command tree

datadog-slo-overrides commands list

Prints a tree of every command the CLI provides.

Developing further

Development flow as Paleofuturistic Python

Prerequisite: uv

Setup

• Fork and clone this repository.
• On first run of any workflow command, the bootstrap step will prompt to install pre-commit hooks.

Workflow

All commands are invoked via ./workflow.cmd <namespace>.<task>:

Command	Description
./workflow.cmd format	Format code and sort imports
./workflow.cmd lint	Run all linters (ruff, pylint, ty, complexipy, commitizen)
./workflow.cmd test	Run all tests (pytest)
./workflow.cmd build	Run security checks and build the package
./workflow.cmd release -i <type>	Bump version, tag, push, build, publish, and upload SBOM
./workflow.cmd quality	Run code quality analysis (pyscn)
./workflow.cmd secure	Run security audit and generate SBOM
./workflow.cmd document	Build and view documentation (properdocs)
./workflow.cmd develop.pre-commit	Run all pre-commit hooks on the codebase
./workflow.cmd bootstrap --force	Re-run the development environment setup

Development cycle

• Add dependencies: uv add some_lib_you_need
• Develop (optional, tinker: uvx --with-editable . ptpython)
• Format: ./workflow.cmd format
• Lint: ./workflow.cmd lint
• Test: ./workflow.cmd test
• Build: ./workflow.cmd build
• Review docs: ./workflow.cmd document
• Make a pull request.