Pushover from the terminal: send alerts, watch emergency receipts, inspect quota, and keep a redacted local notification ledger.
pushover-pp-cli covers the full official API instead of stopping at send-message. It adds agent-safe env defaults, receipt lifecycle tools, quota preflight, and local history so alerts are auditable.
Printed by @twidtwid (Todd Dailey).
Authentication
Use a Pushover application token and user key. Set PUSHOVER_APP_TOKEN and PUSHOVER_USER_KEY, or pass --app-token and --user-key explicitly. Legacy PUSHOVER_TOKEN/PUSHOVER_USER names are accepted for local compatibility.
Quick Start
# Check send budget before test notifications
pushover-pp-cli quota --json
# Send a low-priority test notification
pushover-pp-cli notify "Printing Press test" --priority low --json
# Review sends recorded by the CLI
pushover-pp-cli history list --since 24h --json
Unique Features
These capabilities aren't available in any other tool for this API.
Agent-native plumbing
-
notify — Send a notification from an argument or stdin with env/config defaults, named priorities, and emergency validation.
Lets agents send test or operational notifications without leaking token values or remembering the raw endpoint shape.
pushover-pp-cli notify "Printing Press test" --priority low --json
Receipt operations
-
emergency watch — Send or monitor an emergency notification receipt, polling acknowledgement status and supporting cancellation.
Turns emergency notifications from fire-and-forget sends into an auditable on-call workflow.
pushover-pp-cli emergency watch --receipt <receipt> --poll-interval 30s --cancel-on-timeout --json
Operational safety
-
quota — Show monthly send limit, remaining sends, and reset time from the app limits endpoint.
Agents can check send budget before fanout or repeated test sends.
pushover-pp-cli quota --json
Local state that compounds
-
history — Search and export a local redacted ledger of notifications sent by this CLI and receipt outcomes.
Shows what this CLI sent, when, with which priority, without storing raw user keys or tokens.
pushover-pp-cli history list --since 24h --json
-
inbox sync — Download Open Client messages into local SQLite before optional server-side delete-through.
Makes Pushover usable as both send channel and retrievable inbox for agents that own an Open Client device.
pushover-pp-cli inbox sync --device-id <device-id> --json
Usage
Run pushover-pp-cli --help for the full command reference and flag list.
Commands
notify
Send an agent-safe notification from an argument, --message, or stdin. Uses PUSHOVER_APP_TOKEN and PUSHOVER_USER_KEY when flags are omitted, accepts named priorities, validates emergency retry fields, and records a redacted local history row.
pushover-pp-cli notify - Send a Pushover notification with env defaults and local history
emergency
Watch emergency-priority receipts until acknowledgement, expiry, callback, or timeout.
pushover-pp-cli emergency watch - Poll an emergency receipt at a safe cadence
quota
Check application send quota before test sends or batches.
pushover-pp-cli quota - Show monthly limit, remaining sends, and reset time
history
Inspect this CLI's local redacted notification ledger.
pushover-pp-cli history - List locally recorded notification sendspushover-pp-cli history show - Show one local history row
inbox
Download Open Client messages into local SQLite before optional delete-through.
pushover-pp-cli inbox sync - Store downloaded Open Client messages locallypushover-pp-cli inbox list - List locally synced Open Client messages
apps
Inspect application-level message quotas
pushover-pp-cli apps limits - Check monthly message limit, remaining sends, and reset time
devices
Manage Open Client devices
pushover-pp-cli devices create - Register a new Open Client desktop devicepushover-pp-cli devices delete-through - Delete downloaded Open Client messages up to a highest message id
glances
Update Pushover Glances widgets
pushover-pp-cli glances update - Update Glances widget fields
groups
Create, inspect, and manage Pushover delivery groups
pushover-pp-cli groups add-user - Add a user to a delivery grouppushover-pp-cli groups create - Create a delivery grouppushover-pp-cli groups disable-user - Temporarily disable a group userpushover-pp-cli groups enable-user - Re-enable a disabled group userpushover-pp-cli groups get - Get a delivery group's name and userspushover-pp-cli groups list - List delivery groups owned by the accountpushover-pp-cli groups remove-user - Remove a user from a delivery grouppushover-pp-cli groups rename - Rename a delivery group
licenses
Assign and inspect Pushover license credits
pushover-pp-cli licenses assign - Assign a pre-paid license credit to a user or emailpushover-pp-cli licenses credits - Check remaining license credits
messages
Send application notifications and download Open Client messages
pushover-pp-cli messages download - Download pending messages for an Open Client devicepushover-pp-cli messages send - Send a Pushover notification
receipts
Inspect and cancel emergency-priority message receipts
pushover-pp-cli receipts cancel - Cancel retries for one emergency-priority receiptpushover-pp-cli receipts cancel-by-tag - Cancel active emergency-priority retries matching a tagpushover-pp-cli receipts get - Get emergency-priority receipt status
sounds
Discover notification sounds
pushover-pp-cli sounds list - List built-in and account custom notification sounds
subscriptions
Manage Pushover subscription migrations
pushover-pp-cli subscriptions migrate - Migrate an existing user key into a subscription user key
teams
Manage Pushover for Teams membership
pushover-pp-cli teams add-user - Add a user to a teampushover-pp-cli teams get - Show team information and userspushover-pp-cli teams remove-user - Remove a user from a team
users
Validate users and log in for Open Client sessions
pushover-pp-cli users login - Log in a user for Open Client and return a user key plus session secretpushover-pp-cli users validate - Validate a user or group key and optional device
Output Formats
# Human-readable table (default in terminal, JSON when piped)
pushover-pp-cli groups list --app-token your-token-here
# JSON for scripting and agents
pushover-pp-cli groups list --app-token your-token-here --json
# Filter to specific fields
pushover-pp-cli groups list --app-token your-token-here --json --select id,name,status
# Dry run — show the request without sending
pushover-pp-cli groups list --app-token your-token-here --dry-run
# Agent mode — JSON + compact + no prompts in one flag
pushover-pp-cli groups list --app-token your-token-here --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Explicit retries - add
--idempotent to create retries when a no-op success is acceptable
- Confirmable -
--yes for explicit confirmation of destructive actions
- Piped input - write commands can accept structured input when their help lists
--stdin
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 5 API error, 7 rate limited, 10 config error.
Health Check
pushover-pp-cli doctor
Verifies configuration and connectivity to the API.
Configuration
Config file: ~/.config/pushover-pp-cli/config.toml
Static request headers can be configured under headers; per-command header overrides take precedence.
Troubleshooting
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
- notification send returns invalid user — Run users validate with the same user key and optional device before saving the destination
- priority 2 send fails — Provide retry >= 30 and expire <= 10800; use emergency watch for a safer flow
- 429 quota response — Run quota and wait until reset or reduce send volume
Sources & Inspiration
This CLI was built by studying these projects and resources:
Generated by CLI Printing Press