Metadata-Version: 2.4
Name: pagerduty-oncall-ack
Version: 0.6.0
Summary: Acknowledge PagerDuty incidents only while the configured user is on call.
Author: nithishduda-ai
License-Expression: MIT
Project-URL: Homepage, https://nithishduda-ai.github.io/pagerduty-oncall-ack/
Project-URL: Documentation, https://nithishduda-ai.github.io/pagerduty-oncall-ack/
Project-URL: Repository, https://github.com/nithishduda-ai/pagerduty-oncall-ack
Project-URL: Issues, https://github.com/nithishduda-ai/pagerduty-oncall-ack/issues
Project-URL: Changelog, https://github.com/nithishduda-ai/pagerduty-oncall-ack/blob/main/CHANGELOG.md
Project-URL: Security, https://github.com/nithishduda-ai/pagerduty-oncall-ack/security/policy
Keywords: pagerduty,incident-response,on-call,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: tui
Requires-Dist: textual>=0.89; extra == "tui"
Dynamic: license-file

# 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

### Homebrew (macOS and Linux)

```sh
brew install nithishduda-ai/tap/pagerduty-oncall-ack
pd-auto-ack --version
```

The Homebrew package includes the optional terminal dashboard. See the [Homebrew guide](docs/homebrew.md) for upgrade, uninstall, and troubleshooting steps.

### pipx (macOS and Linux)

`pipx` keeps CLI tools in isolated Python environments.

macOS with Homebrew:

```sh
brew install pipx
pipx ensurepath
exec zsh -l
```

Linux:

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

Install the CLI:

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

Install the optional terminal dashboard:

```sh
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:

```sh
pipx inject pagerduty-oncall-ack textual
```

Upgrade an existing install:

```sh
pipx upgrade pagerduty-oncall-ack
```

The installed CLI command is `pd-auto-ack`.

## Quick Start

Create a starter config file:

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

Validate configuration and PagerDuty access:

```sh
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:

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

Run continuously in dry-run mode:

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

Run continuously in live mode:

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

Open the optional terminal dashboard:

```sh
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](https://nithishduda-ai.github.io/pagerduty-oncall-ack/)
- [PyPI package](https://pypi.org/project/pagerduty-oncall-ack/)
- [Changelog](CHANGELOG.md)
- [Quick start](docs/quick-start.md)
- [Homebrew install and upgrades](docs/homebrew.md)
- [Configuration](docs/configuration.md)
- [Command reference](docs/commands.md)
- [How it works](docs/how-it-works.md)
- [Rollout, rate limits, and operations](docs/rollout.md)
- [Local development](docs/development.md)

## Security

Please report suspected vulnerabilities through GitHub's private vulnerability reporting flow from the repository Security tab. See [SECURITY.md](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>
