pingwire

Telegram alerts for workers, cron jobs, and scripts.

Pingwire is a tiny Node.js npm alert CLI for worker monitoring, cron job notifications, process failure alerts, and DevOps automation through reusable Telegram notification channels.

• Website: https://skbilisim.com/en/projects/pingwire
• npm: https://www.npmjs.com/package/@sksoftofficial/pingwire

MVP channel: Telegram bot. Plain-text messages only for now.

Configure a Telegram channel

1. Create a Telegram bot with BotFather.
2. Get the chat id for the destination chat/user/group.
3. Add the channel:

pingwire channels add
pingwire channels add --cooldown-seconds 600

The add flow asks for:

1. Channel id — your reusable reference, e.g. main, ops-1. It must start and end with an alphanumeric character and may contain only alphanumeric characters and -.
2. Provider — currently only telegram.
3. Telegram bot token.
4. Telegram pairing — Pingwire prints a 4-digit code and waits while you DM your bot:

/pair 1234

When the correct pair command arrives, Pingwire saves that Telegram chat id for the channel. New channels default to a 300-second duplicate notification cooldown; set --cooldown-seconds <seconds> during add, or edit the channel JSON later. Use 0 to disable cooldown.

Pingwire stores each channel in ~/.pingwire/channels/<channel-id>.json, for example ~/.pingwire/channels/main.json. Duplicate notification state is stored in ~/.pingwire/cache/ and cleaned up on every notify call. Override the home directory with PINGWIRE_HOME=/path/to/dir.

Security note: the MVP stores channel secrets in local plaintext JSON with restrictive file permissions. Treat ~/.pingwire/channels/*.json as sensitive.

Channels

pingwire channels
pingwire channels add
pingwire channels show main
pingwire channels enable main
pingwire channels disable main
pingwire channels remove main
pingwire channels test main --message "hello"

show masks Telegram bot tokens in normal output.

Notify

Notify an explicit channel:

pingwire notify \
  --channel main \
  --message "Worker job failed: task 3421 was marked error" \
  --app worker \
  --severity error

Minimal usage:

pingwire notify --channel main --message "Worker failed"

Cooldown behavior:

• Pingwire hashes message, app, and severity together.
• If the same alert is sent to the same channel during that channel's cooldown window, it is skipped.
• Default cooldown is 300 seconds.
• Configure per channel with --cooldown-seconds <seconds> when adding the channel or by editing the channel JSON.
• Cache files are empty files named by the alert hash under ~/.pingwire/cache/<channel-id>/.
• Expired cache files are cleaned up on every notify call using each file's modified time.

Module usage

import { createPingwire } from 'pingwire';

const notifier = createPingwire();
await notifier.send({
  message: 'Worker job failed: task 3421 was marked error',
  severity: 'error',
  app: 'worker',
});

The CLI uses configured channels from ~/.pingwire/channels/*.json.

Alert shape

{
  message: string,
  severity: 'info' | 'warning' | 'error' | 'critical',
  app: string | null,
  createdAt: string
}