PagerDuty On-Call Ack

pagerduty-oncall-ack installs the pd-auto-ack CLI. It acknowledges PagerDuty incidents only when the configured user is currently on call.

It is intentionally narrow:

• Checks whether the user is on call.
• Displays open incidents assigned to that user.
• Acknowledges only triggered incidents.
• Does not resolve, reassign, rename, or add notes to incidents.

Install

Recommended install uses pipx, which keeps CLI tools in isolated Python environments.

macOS with Homebrew:

brew install pipx
pipx ensurepath
exec zsh -l

Linux:

python3 -m pip install --user pipx
python3 -m pipx ensurepath
exec "$SHELL" -l

Install the CLI:

pipx install pagerduty-oncall-ack
pd-auto-ack --version

Install the optional terminal dashboard:

pipx install "pagerduty-oncall-ack[tui]"
pd-auto-ack tui --env-file ~/.pd-auto-ack.env

For an existing pipx install, add the dashboard dependency with:

pipx inject pagerduty-oncall-ack textual

Upgrade an existing install:

pipx upgrade pagerduty-oncall-ack

If you installed an older release when the package was named pagerduty-auto-ack, reinstall once under the new package name:

pipx uninstall pagerduty-auto-ack
pipx install pagerduty-oncall-ack

The CLI command remains pd-auto-ack.

Quick Start

Create a starter config file:

pd-auto-ack init --env-file ~/.pd-auto-ack.env
nano ~/.pd-auto-ack.env

Validate configuration and PagerDuty access:

pd-auto-ack doctor --env-file ~/.pd-auto-ack.env
pd-auto-ack check --env-file ~/.pd-auto-ack.env

Run one dry-run cycle:

pd-auto-ack run --env-file ~/.pd-auto-ack.env --once

Run continuously in dry-run mode:

pd-auto-ack run --env-file ~/.pd-auto-ack.env --watch --interval 30

Run continuously in live mode:

pd-auto-ack run --env-file ~/.pd-auto-ack.env --watch --interval 30 --apply

Open the optional terminal dashboard:

pd-auto-ack tui --env-file ~/.pd-auto-ack.env

Required PagerDuty Access

The PagerDuty token needs permissions equivalent to:

• oncalls.read
• incidents.read
• incidents.write

Documentation

• Documentation site
• PyPI package
• Changelog
• Quick start
• Configuration
• Command reference
• How it works
• Rollout, rate limits, and operations
• Local development

Security

Please report suspected vulnerabilities through GitHub's private vulnerability reporting flow from the repository Security tab. See SECURITY.md.

Safety Summary

The CLI only acknowledges incidents when all of these are true:

• the configured user is currently on call
• the incident is triggered
• the incident is assigned to that user

Dry-run mode is the default. Live mode requires --apply or PD_APPLY=true.

API References

The implementation follows PagerDuty's REST API reference and published OpenAPI schema:

• https://developer.pagerduty.com/api-reference/
• https://github.com/PagerDuty/api-schema