datadog_slo_overrides_cli 0.1.1

CLI to set overrides idempotently for multiple SLO's

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.