telert – Alerts for Your Terminal

Version 0.2.7

📱 Overview

Telert is a lightweight utility for multi-channel notifications for alerting when terminal commands or Python code completes. It also extends this notification capability to easily monitor processes, log files, and HTTP endpoints uptime. The tool supports multiple notification channels:

Messaging Apps: Telegram, Microsoft Teams, Slack, Discord
Email: SMTP email notifications
Mobile Devices: Pushover (Android & iOS)
Local Notifications: Desktop notifications, Audio alerts
Custom Integrations: HTTP endpoints for any service

Simple to use:

# Run a command and get notified when it finishes
telert run npm build

# Or pipe any command output for notification
find . -name "*.log" | telert "Log files found!"

# Monitor a log file and notify on error
telert monitor log --name "postgres" --file "/var/log/postgresql/postgresql-15-main.log" --pattern "ERROR|FATAL"

# Monitor a process and notify on high memory usage
telert monitor process --command-pattern "ps aux | grep postgres" --memory-threshold 2G

# Monitor a network endpoint and notify on failure
telert monitor network --name "myapp-health" --host "myapp.com" --port 80 --type http --interval 60 --timeout 5 --expected-status 200 --expected-content "healthy"

Perfect for long-running tasks, remote servers, CI pipelines, monitoring critical code, processes, logs, and network services.

Use it as a CLI tool, Python library, or a notification API. Telert is available:

As a Python package: pip install telert
As a Docker image: docker pull ghcr.io/navig-me/telert:latest
As a cloud-hosted API on Replit, Railway, Render or Fly.io with one-click deployments.

📋 Table of Contents

<details> <summary> View Table of Contents </summary>

Installation & Quick Start
Notification Providers
Features
Usage Guide
Monitoring
API Deployment to Cloud Platforms
Troubleshooting
Environment Variables
Message Formatting
Use Cases
Contributing

</details>

Documentation

<details> <summary> View Documentation Directory</summary>

For more detailed information, please refer to the docs directory:

</details>

🚀 Installation & Quick Start

Install and configure in seconds:

pip install telert

# Interactive setup wizard - easiest way to get started
telert init

# Or configure a notification provider manually
telert config desktop --app-name "My App" --set-default

Use in your shell directly or wrap any command:

# Pipe command output for notification
long_running_command | telert "Command finished!"

# Wrap a command to capture status and timing
telert run --label "Database Backup" pg_dump -U postgres mydb > backup.sql

# Get notified for any command taking longer than 30 seconds
eval "$(telert hook -l 30)"

Or use in your Python code:

from telert import send, telert, notify

# Simple notification
send("Script completed successfully!")

# Using the context manager
def process():
    with telert("Data processing", provider="telegram"):
        # Your long-running code here
        process_large_dataset()

# Using the function decorator
@notify("Database backup", provider="email")
def backup_database():
    # Backup code here
    return "Backup completed"

Or monitor processes, log files, and network endpoints:

# Monitor a process
telert monitor process --name "postgres" --command "ps aux | grep postgres" --memory-threshold 2G

# Monitor a log file
telert monitor log --file "/var/log/app.log" --pattern "ERROR|CRITICAL" --provider telegram

# Monitor a network endpoint
telert monitor network --host "myapp.com" --port 80 --type http --interval 60 --timeout 5 --expected-status 200 --expected-content "healthy"

Key benefits

📱 Get notified when commands finish (even when away from your computer)
📊 Monitor processes, log files, and network endpoints
⏱️ See exactly how long commands or code took to run
🚦 Capture success/failure status codes and tracebacks
📃 View command output snippets directly in notifications
🔄 Works with shell commands, pipelines, and Python code

📲 Notification Providers

Telert supports multiple notification services. Choose one or more based on your needs:

Telegram Setup

Telegram uses the official Bot API for reliable delivery. Messages exceeding Telegram's character limit (4096 characters) are automatically sent as text files.

# After creating a bot with @BotFather and getting your chat ID
telert config telegram --token "<token>" --chat-id "<chat-id>" --set-default
telert status  # Test your configuration

Detailed Telegram Setup Guide

Microsoft Teams Setup

Teams integration uses Power Automate (Microsoft Flow) to deliver notifications.

# After creating a HTTP trigger flow in Power Automate
telert config teams --webhook-url "<flow-http-url>" --set-default
telert status  # Test your configuration

Detailed Microsoft Teams Setup Guide

Slack Setup

Slack integration uses incoming webhooks for channel notifications.

# After creating a webhook at api.slack.com
telert config slack --webhook-url "<webhook-url>" --set-default
telert status  # Test your configuration

Detailed Slack Setup Guide

Discord Setup

Discord integration uses webhooks to send messages to channels.

# After creating a webhook in Discord
telert config discord --webhook-url "<webhook-url>" --set-default
telert status  # Test your configuration

# Optionally customize the bot name and avatar
telert config discord --webhook-url "<webhook-url>" --username "My Bot" --avatar-url "<avatar-image-url>" --set-default

Detailed Discord Setup Guide

Email Setup

Email integration uses standard SMTP protocol to send notifications.

# Basic configuration
telert config email --server smtp.example.com --port 587 -

Telert

Install / Use

README