Command Reference

Use pd-auto-ack --help to see all commands.

pd-auto-ack init

Creates a starter configuration file.

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

What it does:

• Creates the env file if it does not exist.
• Writes placeholders for required values and optional filters.
• Sets file permissions to 0600 where supported.
• Does not call PagerDuty.

Useful flags:

• --env-file PATH: choose where to create the config file.
• --force: overwrite an existing config file.

pd-auto-ack doctor

Validates local configuration without calling PagerDuty.

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

What it does:

• Loads the env file.
• Verifies local config parsing.
• Shows whether key values are configured.
• Does not call PagerDuty.
• Does not acknowledge anything.

Use this first when debugging a config file.

pd-auto-ack check

Validates PagerDuty API access and shows current on-call/incident state without acknowledging anything.

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

What it does:

• Calls PagerDuty to validate the API token.
• Resolves the configured user.
• Shows whether the user is currently on call.
• Lists open incidents assigned to that user.
• Separately shows which triggered incidents are eligible for acknowledgement.
• Does not acknowledge anything.

Use this after doctor and before run.

pd-auto-ack run

Runs the auto-ack decision flow.

Dry-run one cycle:

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

Continuous dry-run:

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

Continuous live mode:

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

What it does:

• Checks whether the configured user is on call.
• If the user is not on call, exits or waits for the next poll.
• If the user is on call, displays open incidents assigned to that user.
• Treats triggered incidents as eligible for acknowledgement.
• Treats already acknowledged incidents as visible but not eligible for acknowledgement.
• In dry-run mode, prints what it would acknowledge.
• In live mode with --apply, acknowledges matching incidents.

Useful flags:

• --env-file PATH: load config from a specific env file.
• --once: run one poll cycle and exit. This is the default for run.
• --watch: keep polling until stopped with Ctrl-C.
• --interval SECONDS: wait this many seconds between polls in --watch mode.
• --apply: live mode. Actually acknowledge matching incidents.
• --dry-run: force dry-run mode even if PD_APPLY=true is set in the env file.

pd-auto-ack tui

Opens an optional k9s-style terminal dashboard.

Install the dashboard extra for a fresh install:

pipx install "pagerduty-oncall-ack[tui]"

For an existing pipx install:

pipx inject pagerduty-oncall-ack textual

Dry-run dashboard:

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

Live dashboard:

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

What it does:

• Opens a full-screen terminal UI.
• Refreshes on the configured interval.
• Shows on-call state, open incidents, eligible triggered incidents, selected incident details, recent events, and API calls made in the last poll.
• Uses the same safety rules as run.
• Starts in dry-run mode unless --apply or PD_APPLY=true is set.
• Requires an interactive terminal.

Keys:

• r: refresh now.
• p: pause or resume polling.
• q: quit.

Useful flags:

• --env-file PATH: load config from a specific env file.
• --interval SECONDS: wait this many seconds between refreshes.
• --apply: live mode. Actually acknowledge matching incidents.
• --dry-run: force dry-run mode even if PD_APPLY=true is set in the env file.

Common Flags

• --env-file PATH: path to the config file. Example: ~/.pd-auto-ack.env.
• --user-id USER_ID: override PD_USER_ID from the env file.
• --from-email EMAIL: override PD_FROM_EMAIL from the env file.
• --service-id SERVICE_ID: restrict incident lookup to a service. Can be repeated.
• --team-id TEAM_ID: restrict incident lookup to a team. Can be repeated.
• --escalation-policy-id POLICY_ID: restrict on-call checks to an escalation policy. Can be repeated.
• --schedule-id SCHEDULE_ID: restrict on-call checks to a schedule. Can be repeated.
• --timeout SECONDS: PagerDuty API request timeout.
• --max-pages COUNT: pagination safety limit for list requests.
• --quiet: only print errors.