{"id":27718515,"url":"https://github.com/navig-me/telert","last_synced_at":"2025-05-13T13:12:55.013Z","repository":{"id":289614120,"uuid":"971123250","full_name":"navig-me/telert","owner":"navig-me","description":"Command‑line and Python utility that alerts the moment a command finishes executing","archived":false,"fork":false,"pushed_at":"2025-05-03T06:04:14.000Z","size":3160,"stargazers_count":24,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-03T06:15:42.241Z","etag":null,"topics":["alert","cli","command-line","discord","fly-io","microsoft-teams","notification","pushover","railway","render","replit","rest-api","slack","slack-bot","teams","telegram"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/navig-me.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-23T03:50:04.000Z","updated_at":"2025-05-03T06:04:06.000Z","dependencies_parsed_at":"2025-04-24T06:46:56.089Z","dependency_job_id":"5f94157f-ecc8-4e64-8662-e56bf62825e9","html_url":"https://github.com/navig-me/telert","commit_stats":null,"previous_names":["navig-me/telert"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/navig-me%2Ftelert","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/navig-me%2Ftelert/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/navig-me%2Ftelert/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/navig-me%2Ftelert/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/navig-me","download_url":"https://codeload.github.com/navig-me/telert/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253948447,"owners_count":21988959,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alert","cli","command-line","discord","fly-io","microsoft-teams","notification","pushover","railway","render","replit","rest-api","slack","slack-bot","teams","telegram"],"created_at":"2025-04-27T06:01:10.673Z","updated_at":"2025-05-13T13:12:54.999Z","avatar_url":"https://github.com/navig-me.png","language":"Python","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/navig-me/telert/raw/main/telert.png\" alt=\"telert logo\" width=\"150\"\u003e\n\u003c/p\u003e\n\n# telert – Alerts for Your Terminal\n\n**Version 0.1.40**\n\n[![GitHub Stars](https://img.shields.io/github/stars/navig-me/telert?style=social)](https://github.com/navig-me/telert/stargazers)\n[![PyPI version](https://img.shields.io/pypi/v/telert)](https://pypi.org/project/telert/)\n[![Downloads](https://static.pepy.tech/personalized-badge/telert?period=month\u0026units=international_system\u0026left_color=grey\u0026right_color=blue\u0026left_text=downloads)](https://pepy.tech/project/telert)\n[![License](https://img.shields.io/github/license/navig-me/telert)](https://github.com/navig-me/telert/blob/main/docs/LICENSE)\n[![Marketplace](https://img.shields.io/badge/GitHub%20Marketplace-Use%20this%20Action-blue?logo=github)](https://github.com/marketplace/actions/telert-run)\n[![VS Code Marketplace](https://vsmarketplacebadges.dev/version/Navig.telert-vscode.svg?subject=VS%20Code%20Marketplace\u0026style=flat-square)](https://marketplace.visualstudio.com/items?itemName=Navig.telert-vscode)\n\n\n## 📱 Overview\n\nTelert is a lightweight utility that sends notifications when your terminal commands or Python code completes. It supports multiple notification channels:\n\n- **Messaging Apps**: Telegram, Microsoft Teams, Slack, Discord\n- **Mobile Devices**: Pushover (Android \u0026 iOS)\n- **Local Notifications**: Desktop notifications, Audio alerts\n- **Custom Integrations**: HTTP endpoints for any service\n\nPerfect for long-running tasks, remote servers, CI pipelines, or monitoring critical code.\n\nUse it as a CLI tool, Python library, or a notification API. Telert is available:\n- As a Python package: `pip install telert`\n- As a Docker image: `docker pull ghcr.io/navig-me/telert:latest`\n- As a cloud-hosted API on [Replit](https://replit.com/@mihir95/Telert-CLI-Notifier), [Railway](https://railway.com/template/A_kYXt?referralCode=vj4bEA), [Render](https://render.com/deploy?repo=https://github.com/navig-me/telert-notifier) or [Fly.io](https://github.com/navig-me/telert-notifier?tab=readme-ov-file#-deploy-manually-on-flyio) with one-click deployments.\n\n\n\u003cimg src=\"https://github.com/navig-me/telert/raw/main/docs/telert-demo.svg\" alt=\"telert demo\" width=\"600\"\u003e\n\n\n## 📋 Table of Contents\n- [Installation \u0026 Quick Start](#-installation--quick-start)\n- [Notification Providers](#-notification-providers)\n  - [Telegram](#telegram-setup)\n  - [Microsoft Teams](#microsoft-teams-setup)\n  - [Slack](#slack-setup)\n  - [Discord](#discord-setup)\n  - [Pushover](#pushover-setup)\n  - [Custom HTTP Endpoints](#custom-http-endpoint-setup)\n  - [Audio Alerts](#audio-alerts-setup)\n  - [Desktop Notifications](#desktop-notifications-setup)\n  - [Managing Multiple Providers](#managing-multiple-providers)\n- [Features](#-features)\n- [Usage Guide](#-usage-guide)\n  - [Command Line Interface](#command-line-interface-cli)\n  - [Python API](#python-api)\n  - [Docker Usage](#docker-usage)\n- [API Deployment to Cloud Platforms](#-api-deployment-to-cloud-platforms)\n- [Troubleshooting](#-troubleshooting)\n- [Environment Variables](#-environment-variables)\n- [Message Formatting](#-message-formatting)\n  - [Telegram Formatting](#telegram-formatting)\n  - [Cross-Platform Formatting](#other-providers)\n- [Use Cases](#-use-cases-and-tips)\n- [Contributing](#-contributing--license)\n\n## 🚀 Installation \u0026 Quick Start\n\n```bash\n# Install from PyPI (works on any OS with Python 3.8+)\npip install telert\n\n# Interactive setup wizard - easiest way to get started\ntelert init\n\n# Or configure a notification provider manually\ntelert config desktop --app-name \"My App\" --set-default\n\n# Basic usage - pipe command output\nlong_running_command | telert \"Command finished!\"\n\n# Or wrap a command to capture status and timing\ntelert run --label \"Database Backup\" pg_dump -U postgres mydb \u003e backup.sql\n```\n\n### Key benefits\n\n- 📱 Get notified when commands finish (even when away from your computer)\n- ⏱️ See exactly how long commands or code took to run\n- 🚦 Capture success/failure status codes and tracebacks\n- 📃 View command output snippets directly in your notifications\n- 🔄 Works with shell commands, pipelines, and Python code\n\n## 📲 Notification Providers\n\nTelert supports multiple notification services. Choose one or more based on your needs:\n\n### Telegram Setup\n\nTelegram uses the official Bot API for reliable delivery.\n\n```bash\n# After creating a bot with @BotFather and getting your chat ID\ntelert config telegram --token \"\u003ctoken\u003e\" --chat-id \"\u003cchat-id\u003e\" --set-default\ntelert status  # Test your configuration\n```\n\n[**Detailed Telegram Setup Guide**](https://github.com/navig-me/telert/blob/main/docs/TELEGRAM.md)\n\n### Microsoft Teams Setup\n\nTeams integration uses Power Automate (Microsoft Flow) to deliver notifications.\n\n```bash\n# After creating a HTTP trigger flow in Power Automate\ntelert config teams --webhook-url \"\u003cflow-http-url\u003e\" --set-default\ntelert status  # Test your configuration\n```\n\n[**Detailed Microsoft Teams Setup Guide**](https://github.com/navig-me/telert/blob/main/docs/TEAMS.md)\n\n### Slack Setup\n\nSlack integration uses incoming webhooks for channel notifications.\n\n```bash\n# After creating a webhook at api.slack.com\ntelert config slack --webhook-url \"\u003cwebhook-url\u003e\" --set-default\ntelert status  # Test your configuration\n```\n\n[**Detailed Slack Setup Guide**](https://github.com/navig-me/telert/blob/main/docs/SLACK.md)\n\n### Discord Setup\n\nDiscord integration uses webhooks to send messages to channels.\n\n```bash\n# After creating a webhook in Discord\ntelert config discord --webhook-url \"\u003cwebhook-url\u003e\" --set-default\ntelert status  # Test your configuration\n\n# Optionally customize the bot name and avatar\ntelert config discord --webhook-url \"\u003cwebhook-url\u003e\" --username \"My Bot\" --avatar-url \"\u003cavatar-image-url\u003e\" --set-default\n```\n\n[**Detailed Discord Setup Guide**](https://github.com/navig-me/telert/blob/main/docs/DISCORD.md)\n\n### Pushover Setup\n\nPushover provides mobile notifications to Android and iOS devices.\n\n```bash\n# After signing up at pushover.net and creating an app\ntelert config pushover --token \"\u003capp-token\u003e\" --user \"\u003cuser-key\u003e\" --set-default\ntelert status  # Test your configuration\n```\n\n[**Detailed Pushover Setup Guide**](https://github.com/navig-me/telert/blob/main/docs/PUSHOVER.md)\n\n### Custom HTTP Endpoint Setup\n\nSend to any HTTP service with configurable URLs, headers, and payload templates.\n\n```bash\n# Basic configuration\ntelert config endpoint --url \"https://api.example.com/notify\" --set-default\n\n# Advanced configuration example\ntelert config endpoint \\\n  --url \"https://api.example.com/notify/{status_code}\" \\\n  --method POST \\\n  --header \"Authorization: Bearer abc123\" \\\n  --payload-template '{\"text\": \"{message}\"}' \\\n  --name \"My Service\" \\\n  --set-default\n```\n\n[**Detailed Custom Endpoint Guide**](https://github.com/navig-me/telert/blob/main/docs/ENDPOINT.md)\n\n### Audio Alerts Setup\n\nPlay a sound notification when your command completes.\n\n```bash\n# Use the built-in sound\ntelert config audio --set-default\n\n# Or use a custom sound file with volume control\ntelert config audio --sound-file \"/path/to/alert.wav\" --volume 0.8 --set-default\n```\n\nWorks on all platforms; for MP3 support on Windows: `pip install telert[audio]`\n\n### Desktop Notifications Setup\n\nShow notifications in your operating system's notification center.\n\n```bash\n# Configure with default icon\ntelert config desktop --app-name \"My App\" --set-default\n\n# Or with custom icon\ntelert config desktop --app-name \"My App\" --icon-path \"/path/to/icon.png\" --set-default\n```\n\n**macOS users**: Install terminal-notifier for better reliability: `brew install terminal-notifier`  \n**Linux users**: Install notify-send: `sudo apt install libnotify-bin` (Debian/Ubuntu)\n\n### Managing Multiple Providers\n\nConfigure and use multiple notification services at once:\n\n```bash\n# Set multiple default providers in priority order\ntelert config set-defaults --providers \"slack,desktop,audio\"\n\n# Add a provider to existing defaults without replacing them\ntelert config audio --sound-file \"/path/to/sound.mp3\" --add-to-defaults\n\n# Send to multiple providers \ntelert send --provider \"slack,telegram\" \"Multi-provider message\"\n\n# Send to all configured providers\ntelert send --all-providers \"Important alert!\"\n```\n\nConfiguration is stored in `~/.config/telert/config.json` and can be overridden with environment variables.\n\n---\n\n## ✨ Features\n\n| Mode           | What it does | Example |\n|----------------|--------------|---------|\n| **Run**        | Wraps a command, times it, sends notification with exit code. | `telert run --label \"RSYNC\" rsync -a /src /dst` |\n| **Filter**     | Reads from stdin so you can pipe command output. | `long_job \\| telert \"compile done\"` |\n| **Hook**       | Generates a Bash snippet so **every** command \u003e *N* seconds notifies automatically. | `eval \"$(telert hook -l 30)\"` |\n| **Send**       | Low-level \"send arbitrary text\" helper. | `telert send --provider slack \"Build complete\"` |\n| **Python API** | Use directly in Python code with context managers and decorators. | `from telert import telert, send, notify` |\n| **GitHub Action** | Run commands in GitHub Actions with notifications. | `uses: navig-me/telert/actions/run@v1` |\n| **CI Integration** | GitLab CI templates and CircleCI orbs for notifications. | `extends: .telert-notify` |\n| **Docker** | Run as CLI tool or notification API server in Docker. | `docker run ghcr.io/navig-me/telert:latest` |\n| **Multi-provider** | Configure and use multiple notification services (Telegram, Teams, Slack, Pushover, Audio, Desktop). | `telert config desktop --app-name \"My App\"` |\n\n---\n\n## 📋 Usage Guide\n\n### Command Line Interface (CLI)\n\n\u003e **Note**: When using the `run` command, do not use double dashes (`--`) to separate telert options from the command to run. The correct syntax is `telert run [options] command`, not `telert run [options] command`.\n\n#### Run Mode\nWrap any command to receive a notification when it completes:\n\n```bash\n# Basic usage - notify when command finishes (uses default provider)\ntelert run npm run build\n\n# Add a descriptive label\ntelert run --label \"DB Backup\" pg_dump -U postgres mydb \u003e backup.sql\n\n# Show notification only when a command fails\ntelert run --only-fail rsync -av /src/ /backup/\n\n# Send to a specific provider\ntelert run --provider teams --label \"ML Training\" python train_model.py\n\n# Send to multiple specific providers\ntelert run --provider \"slack,telegram\" --label \"CI Build\" make all\n\n# Send to all configured providers\ntelert run --all-providers --label \"Critical Backup\" backup.sh\n\n# Custom notification message\ntelert run --message \"Training complete! 🎉\" python train_model.py\n\n# Run in silent mode (output only in notification, not displayed in terminal)\nTELERT_SILENT=1 telert run python long_process.py\n```\n\nCommand output is shown in real-time by default. Use `TELERT_SILENT=1` environment variable if you want to capture output for the notification but not display it in the terminal.\n\n#### Filter Mode\nPerfect for adding notifications to existing pipelines:\n\n```bash\n# Send notification when a pipeline completes (uses default provider)\nfind . -name \"*.log\" | xargs grep \"ERROR\" | telert \"Error check complete\"\n\n# Process and notify with specific provider\ncat large_file.csv | awk '{print $3}' | sort | uniq -c | telert --provider slack \"Data processing finished\"\n\n# Send to multiple providers\nfind /var/log -name \"*.err\" | grep -i \"critical\" | telert --provider \"telegram,desktop\" \"Critical errors found\"\n\n# Send to all providers\nbackup.sh | telert --all-providers \"Database backup complete\"\n```\n\n\u003e **Note:** In filter mode, the exit status is not captured since commands in a pipeline run in separate processes.\n\u003e For exit status tracking, use Run mode or add explicit status checking in your script.\n\n#### Send Mode\nSend custom messages from scripts to any provider:\n\n```bash\n# Simple text message (uses default provider(s))\ntelert send \"Server backup completed\"\n\n# Send to a specific provider\ntelert send --provider teams \"Build completed\"\ntelert send --provider slack \"Deployment started\"\n\n# Send to multiple specific providers at once\ntelert send --provider \"telegram,slack,desktop\" \"Critical alert!\"\n\n# Send to all configured providers\ntelert send --all-providers \"System restart required\"\n\n# Show details of message delivery with verbose flag\ntelert send --all-providers --verbose \"Message sent to all providers\"\n\n# Send status from a script\nif [ $? -eq 0 ]; then\n  telert send \"✅ Deployment successful\"\nelse\n  # Send failure notification to all providers\n  telert send --all-providers \"❌ Deployment failed with exit code $?\"\nfi\n```\n\n#### Shell Hook\nGet notifications for ALL commands that take longer than a certain time:\n\n```bash\n# Configure Bash to notify for any command taking longer than 30 seconds\neval \"$(telert hook -l 30)\"\n\n# Add to your .bashrc for persistent configuration\necho 'eval \"$(telert hook -l 30)\"' \u003e\u003e ~/.bashrc\n```\n\n#### CLI Help\n```bash\n# View all available commands\ntelert --help\n\n# Get help for a specific command\ntelert run --help\n```\n\n### Using Shell Built-ins with telert\n\nWhen using `telert run` with shell built-in commands like `source`, you'll need to wrap them in a bash call:\n\n```bash\n# This will fail\ntelert run source deploy.sh\n\n# This works\ntelert run bash -c \"source deploy.sh\"\n```\n\nFor convenience, we provide a wrapper script that automatically handles shell built-ins:\n\n```bash\n# Download the wrapper script\ncurl -o ~/bin/telert-wrapper https://raw.githubusercontent.com/navig-me/telert/main/telert-wrapper.sh\nchmod +x ~/bin/telert-wrapper\n\n# Now you can use shell built-ins directly\ntelert-wrapper run source deploy.sh\n```\n\n### Python API\n\n#### Configuration\n```python\nfrom telert import (\n    configure_telegram, configure_teams, configure_slack, configure_discord, configure_pushover,\n    configure_audio, configure_desktop, configure_providers,\n    set_default_provider, set_default_providers, \n    is_configured, get_config, list_providers\n)\n\n# Configure one or more providers\nconfigure_telegram(\"\u003ctoken\u003e\", \"\u003cchat-id\u003e\")\nconfigure_teams(\"\u003cwebhook-url\u003e\")\nconfigure_slack(\"\u003cwebhook-url\u003e\")\nconfigure_discord(\"\u003cwebhook-url\u003e\")  # Basic Discord configuration\n# Or with custom bot name and avatar\nconfigure_discord(\"\u003cwebhook-url\u003e\", username=\"My Bot\", avatar_url=\"https://example.com/avatar.png\")\nconfigure_pushover(\"\u003capp-token\u003e\", \"\u003cuser-key\u003e\")\nconfigure_audio()  # Uses built-in sound\n# Or with custom sound: configure_audio(\"/path/to/alert.wav\", volume=0.8)\n\n# Configure custom HTTP endpoint\nfrom telert.messaging import Provider, configure_provider\nconfigure_provider(\n    Provider.ENDPOINT,\n    url=\"https://api.example.com/notify\",\n    method=\"POST\",\n    headers={\"Authorization\": \"Bearer abc123\"},\n    payload_template='{\"text\": \"{message}\"}',\n    name=\"My API\",\n    timeout=30\n)\n\n# Configure provider and add to existing defaults (without replacing them)\nconfigure_desktop(\"My App\", add_to_defaults=True)  # Uses built-in icon\n\n# Configure multiple providers at once\nconfigure_providers([\n    {\"provider\": \"telegram\", \"token\": \"\u003ctoken\u003e\", \"chat_id\": \"\u003cchat-id\u003e\"},\n    {\"provider\": \"slack\", \"webhook_url\": \"\u003cwebhook-url\u003e\"},\n    {\"provider\": \"audio\"}\n], set_as_defaults=True)  # Optionally set these as defaults in the given order\n\n# Check if specific provider is configured\nif not is_configured(\"audio\"):\n    configure_audio(\"/path/to/bell.wav\")\n\n# Get configuration for a specific provider\ndesktop_config = get_config(\"desktop\")\nprint(f\"Using app name: {desktop_config['app_name']}\")\n\n# List all providers and see which is default\nproviders = list_providers()\nfor p in providers:\n    print(f\"{p['name']} {'(default)' if p['is_default'] else ''}\")\n\n# Set a single default provider\nset_default_provider(\"audio\")\n\n# Set multiple default providers in priority order\nset_default_providers([\"slack\", \"desktop\", \"audio\"])\n```\n\n#### Simple Messaging\n```python\nfrom telert import send\n\n# Send using default provider(s)\nsend(\"Script started\")  # Uses default providers in configured priority order\n\n# Send to specific provider\nsend(\"Processing completed with 5 records updated\", provider=\"teams\")\n\n# Send to multiple specific providers\nsend(\"Critical error detected!\", provider=[\"slack\", \"telegram\"])\n\n# Send to all configured providers\nsend(\"Major system error\", all_providers=True)\n\n# Provider-specific examples\nsend(\"Send to mobile device\", provider=\"pushover\")\nsend(\"Play a sound alert\", provider=\"audio\")\nsend(\"Show a desktop notification\", provider=\"desktop\")\nsend(\"Send to Discord channel\", provider=\"discord\") \nsend(\"Send to custom HTTP endpoint\", provider=\"endpoint\")\n\n# Check delivery results\nresults = send(\"Important message\", provider=[\"slack\", \"telegram\"])\nfor provider, success in results.items():\n    if not success:\n        print(f\"Failed to send to {provider}\")\n```\n\n#### Context Manager\nThe `telert` context manager times code execution and sends a notification when the block completes:\n\n```python\nfrom telert import telert\nimport time\n\n# Basic usage\nwith telert(\"Data processing\"):\n    # Your long-running code here\n    time.sleep(5)\n\n# Include results in the notification\nwith telert(\"Calculation\") as t:\n    result = sum(range(1000000))\n    t.result = {\"sum\": result, \"status\": \"success\"}\n\n# Only notify on failure\nwith telert(\"Critical operation\", only_fail=True):\n    # This block will only send a notification if an exception occurs\n    risky_function()\n    \n# Specify a provider\nwith telert(\"Teams notification\", provider=\"teams\"):\n    # This will notify via Teams regardless of the default provider\n    teams_specific_operation()\n    \n# Send to multiple providers\nwith telert(\"Important calculation\", provider=[\"slack\", \"telegram\"]):\n    # This will send to both Slack and Telegram\n    important_calculation()\n    \n# Send to all configured providers\nwith telert(\"Critical operation\", all_providers=True):\n    # This will send to all configured providers\n    critical_function()\n    \n# Use audio notifications\nwith telert(\"Long calculation\", provider=\"audio\"):\n    # This will play a sound when done\n    time.sleep(5)\n    \n# Use desktop notifications\nwith telert(\"Database backup\", provider=\"desktop\"):\n    # This will show a desktop notification when done\n    backup_database()\n    \n# Send to mobile device\nwith telert(\"Long-running task\", provider=\"pushover\"):\n    # This will send to Pushover when done\n    time.sleep(60)\n    \n# Send to Discord channel\nwith telert(\"Discord notification\", provider=\"discord\"):\n    # This will notify via Discord when done\n    discord_specific_operation()\n    \n# Send to custom HTTP endpoint\nwith telert(\"API operation\", provider=\"endpoint\"):\n    # This will send to your configured HTTP endpoint when done\n    api_operation()\n```\n\n#### Function Decorator\nThe `notify` decorator makes it easy to monitor functions:\n\n```python\nfrom telert import notify\n\n# Basic usage - uses function name as the label\n@notify()\ndef process_data():\n    # Code that might take a while\n    return \"Processing complete\"\n\n# Custom label and only notify on failure\n@notify(\"Database backup\", only_fail=True)\ndef backup_database():\n    # This will only send a notification if it raises an exception\n    return \"Backup successful\"\n\n# Function result will be included in the notification\n@notify(\"Calculation\")\ndef calculate_stats(data):\n    return {\"mean\": sum(data)/len(data), \"count\": len(data)}\n\n# Send notification to specific provider\n@notify(\"Slack alert\", provider=\"slack\")\ndef slack_notification_function():\n    return \"This will be sent to Slack\"\n    \n# Send to multiple providers\n@notify(\"Important function\", provider=[\"telegram\", \"desktop\"])\ndef important_function():\n    return \"This will be sent to both Telegram and Desktop\"\n    \n# Send to all configured providers\n@notify(\"Critical function\", all_providers=True)\ndef critical_function():\n    return \"This will be sent to all providers\"\n    \n# Use audio notifications\n@notify(\"Audio alert\", provider=\"audio\")\ndef play_sound_on_completion():\n    return \"This will play a sound when done\"\n    \n# Use desktop notifications\n@notify(\"Desktop alert\", provider=\"desktop\")\ndef show_desktop_notification():\n    return \"This will show a desktop notification when done\"\n    \n# Send to mobile device\n@notify(\"Mobile alert\", provider=\"pushover\")\ndef send_mobile_notification():\n    return \"This will send to Pushover when done\"\n    \n# Send to Discord\n@notify(\"Discord alert\", provider=\"discord\")\ndef send_to_discord():\n    return \"This will send to Discord when done\"\n    \n# Send to custom HTTP endpoint\n@notify(\"API alert\", provider=\"endpoint\")\ndef send_to_api():\n    return \"This will send to your configured HTTP endpoint when done\"\n```\n\n### Docker Usage\n\nTelert is available as a Docker image that can be used in both CLI and server modes.\n\n#### Pull the Official Image\n\n```bash\ndocker pull ghcr.io/navig-me/telert:latest\n```\n\n#### CLI Mode Examples\n\n```bash\n# Test telert status\ndocker run --rm ghcr.io/navig-me/telert:latest status\n\n# Configure and send a notification\ndocker run --rm \\\n  -e TELERT_TELEGRAM_TOKEN=your_token \\\n  -e TELERT_TELEGRAM_CHAT_ID=your_chat_id \\\n  ghcr.io/navig-me/telert:latest send \"Hello from Docker!\"\n```\n\n#### Server Mode Example\n\n```bash\n# Run telert as a notification API server\ndocker run -d --name telert-server \\\n  -p 8000:8000 \\\n  -e TELERT_TELEGRAM_TOKEN=your_token \\\n  -e TELERT_TELEGRAM_CHAT_ID=your_chat_id \\\n  ghcr.io/navig-me/telert:latest serve\n\n# Send a notification via the API\ncurl -X POST http://localhost:8000/send \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"message\": \"Hello from the API!\"}'\n```\n\nFor more detailed information on Docker usage, including configuration persistence and API endpoints, see the [Docker documentation](https://github.com/navig-me/telert/blob/main/docs/DOCKER.md).\n\n### GitHub Actions Integration\n\nTelert can be used in GitHub Actions workflows to run commands and receive notifications when they complete:\n\n```yaml\n- name: Run tests with notification\n  uses: navig-me/telert/actions/run@v1\n  with:\n    command: npm test\n    label: Run Tests\n    provider: telegram\n    token: ${{ secrets.TELEGRAM_BOT_TOKEN }}\n    chat-id: ${{ secrets.TELEGRAM_CHAT_ID }}\n```\n\n#### Inputs\n\n| Input | Description | Required |\n|-------|-------------|----------|\n| `command` | The command to run | Yes |\n| `label` | Label to identify the command | No |\n| `provider` | Notification provider to use | No |\n| `all-providers` | Send to all configured providers | No |\n| `only-fail` | Only notify on failure | No |\n| `message` | Custom notification message | No |\n| `token` | Telegram/Pushover token | No |\n| `chat-id` | Telegram chat ID | No |\n| `webhook-url` | Webhook URL for Teams/Slack/Discord | No |\n| `user-key` | Pushover user key | No |\n\nFor more examples and detailed usage, see the [CI/CD Integrations documentation](https://github.com/navig-me/telert/blob/main/docs/CI-CD.md).\n\n### GitLab CI Integration\n\nTelert provides a GitLab CI template for easy integration:\n\n```yaml\ninclude:\n  - remote: 'https://raw.githubusercontent.com/navig-me/telert/main/.github/actions/run/gitlab-ci-template.yml'\n\nbuild:\n  extends: .telert-notify\n  variables:\n    TELERT_COMMAND: \"npm run build\"\n    TELERT_LABEL: \"Build Project\"\n    TELERT_PROVIDER: \"telegram\"\n  script:\n    - npm run build\n```\n\n### CircleCI Orb\n\nTelert is also available as a CircleCI Orb:\n\n```yaml\nversion: 2.1\norbs:\n  telert: telert/notify@1.0.0\n\njobs:\n  build:\n    docker:\n      - image: cimg/node:16.13\n    steps:\n      - checkout\n      - telert/run-notify:\n          command: \"npm run build\"\n          label: \"Build Project\"\n          provider: \"telegram\"\n```\n\n## 🌐 API Deployment to Cloud Platforms\n\nTelert can be deployed as a notification API on cloud platforms like [Replit](https://replit.com/@mihir95/Telert-CLI-Notifier), [Railway](https://railway.com/template/A_kYXt?referralCode=vj4bEA), [Render](https://render.com/deploy?repo=https://github.com/navig-me/telert-notifier) or [Fly.io](https://github.com/navig-me/telert-notifier?tab=readme-ov-file#-deploy-manually-on-flyio). This is useful for CI/CD pipelines or services that can make HTTP requests but can't install Python.\n\n[![Run on Replit](https://replit.com/badge/github/navig-me/telert-replit)](https://replit.com/@mihir95/Telert-CLI-Notifier)\n[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/template/A_kYXt?referralCode=vj4bEA)\n[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/navig-me/telert-notifier)\n\nClick on any of the buttons above or use the [Deployment Templates](https://github.com/navig-me/telert-notifier) to deploy your own instance.\n\nOnce deployed, you can send notifications by making HTTP requests to your API:\n\n```bash\ncurl -X POST https://your-deployment-url.example.com/send \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"message\": \"Build complete!\"}'\n```\n\nFor more details on deployment options and configuration, see the [telert-notifier repository](https://github.com/navig-me/telert-notifier).\n\n## 🔧 Troubleshooting\n\n### Desktop Notifications Issues\n\n- **macOS**: If desktop notifications aren't working:\n  - Install terminal-notifier: `brew install terminal-notifier`\n  - Check notification permissions in System Preferences → Notifications\n  - Ensure your terminal app (iTerm2, Terminal, VS Code) has notification permissions\n\n- **Linux**: \n  - Install notify-send: `sudo apt install libnotify-bin` (Debian/Ubuntu)\n  - Ensure your desktop environment supports notifications\n\n- **Windows**:\n  - PowerShell must be allowed to run scripts\n  - Check Windows notification settings\n\n### Connection Issues\n\n- If you're getting connection errors with Telegram, Teams, or Slack:\n  - Verify network connectivity\n  - Check if your token/webhook URLs are correct\n  - Ensure firewall rules allow outbound connections\n\n### Audio Issues\n\n- **No sound playing**:\n  - Check if your system's volume is muted\n  - Install required audio players (macOS: built-in, Linux: mpg123/paplay/aplay, Windows: winsound/playsound)\n  - For MP3 support on Windows: `pip install telert[audio]`\n\n\n---\n## 🌿 Environment Variables\n\n### Configuration Variables\n\n| Variable                  | Effect                                      |\n|---------------------------|---------------------------------------------|\n| `TELERT_DEFAULT_PROVIDER` | Set default provider(s) to use (comma-separated for multiple) |\n| `TELERT_TOKEN` or `TELERT_TELEGRAM_TOKEN` | Telegram bot token         |\n| `TELERT_CHAT_ID` or `TELERT_TELEGRAM_CHAT_ID` | Telegram chat ID       |\n| `TELERT_TEAMS_WEBHOOK`    | Microsoft Teams Power Automate HTTP URL     |\n| `TELERT_SLACK_WEBHOOK`    | Slack webhook URL                           |\n| `TELERT_DISCORD_WEBHOOK`  | Discord webhook URL                         |\n| `TELERT_DISCORD_USERNAME` | Discord webhook bot name (default: Telert)  |\n| `TELERT_DISCORD_AVATAR_URL` | Discord webhook bot avatar URL           |\n| `TELERT_PUSHOVER_TOKEN`   | Pushover application token                  |\n| `TELERT_PUSHOVER_USER`    | Pushover user key                           |\n| `TELERT_AUDIO_FILE`       | Path to sound file for audio notifications  |\n| `TELERT_AUDIO_VOLUME`     | Volume level for audio notifications (0.0-1.0) |\n| `TELERT_DESKTOP_APP_NAME` | Application name for desktop notifications  |\n| `TELERT_DESKTOP_ICON`     | Path to icon file for desktop notifications |\n| `TELERT_ENDPOINT_URL`     | URL for custom HTTP endpoint notifications   |\n| `TELERT_ENDPOINT_METHOD`  | HTTP method to use (default: POST)           |\n| `TELERT_ENDPOINT_HEADERS` | JSON string of headers for HTTP requests      |\n| `TELERT_ENDPOINT_PAYLOAD` | Payload template for HTTP requests           |\n| `TELERT_ENDPOINT_NAME`    | Friendly name for the custom endpoint        |\n| `TELERT_ENDPOINT_TIMEOUT` | Request timeout in seconds (default: 20)     |\n\n### Runtime Variables\n\n| Variable          | Effect                                            |\n|-------------------|---------------------------------------------------|\n| `TELERT_LONG`     | Default threshold (seconds) for `hook`            |\n| `TELERT_SILENT=1` | Capture and include command output in notification, but don't display in real-time |\n\n### Example Usage\n\n```bash\n# Set multiple default providers (will use in fallback order)\nexport TELERT_DEFAULT_PROVIDER=\"slack,audio,desktop\"\n\n# Configure Telegram via environment\nexport TELERT_TELEGRAM_TOKEN=\"your-bot-token\"\nexport TELERT_TELEGRAM_CHAT_ID=\"your-chat-id\"\n\n# Configure Slack\nexport TELERT_SLACK_WEBHOOK=\"https://hooks.slack.com/services/...\"\n\n# Configure Discord\nexport TELERT_DISCORD_WEBHOOK=\"https://discord.com/api/webhooks/...\"\nexport TELERT_DISCORD_USERNAME=\"Alert Bot\"  # Optional\n\n# Configure desktop notifications\nexport TELERT_DESKTOP_APP_NAME=\"MyApp\"\n\n# Send a message (will use default providers in order)\ntelert send \"Environment variable configuration works!\"\n```\n\nUsing environment variables is especially useful in CI/CD pipelines or containerized environments where you don't want to create a config file. Environment variables take precedence over the configuration file, making them perfect for temporary overrides.\n\n---\n## 📝 Message Formatting\n\n### Message Formatting Support\n\nTelert provides formatting options for messages, with different levels of support across providers.\n\n#### Telegram Formatting\n\nTelegram fully supports rich formatting with both HTML and Markdown options:\n\n```bash\n# Send a message with HTML formatting (auto-detected)\ntelert send \"Project build \u003cb\u003ecompleted\u003c/b\u003e with \u003ci\u003ezero\u003c/i\u003e errors\"\n\n# Or explicitly specify HTML parsing mode\ntelert send --parse-mode HTML \"Project build \u003cb\u003ecompleted\u003c/b\u003e with \u003ci\u003ezero\u003c/i\u003e errors\"\n\n# Send with Markdown formatting (auto-detected)\ntelert send \"Project build **completed** with *zero* errors\"\n\n# Or explicitly specify Markdown parsing mode\ntelert send --parse-mode MarkdownV2 \"Project build **completed** with *zero* errors\"\n```\n\nSupported HTML tags in Telegram:\n- `\u003cb\u003e`, `\u003cstrong\u003e` - Bold text\n- `\u003ci\u003e`, `\u003cem\u003e` - Italic text\n- `\u003cu\u003e` - Underlined text\n- `\u003cs\u003e`, `\u003cstrike\u003e`, `\u003cdel\u003e` - Strikethrough text\n- `\u003ccode\u003e` - Monospace text\n- `\u003cpre\u003e` - Pre-formatted text\n- `\u003ca href=\"...\"\u003e` - Links\n\nSupported Markdown formatting in Telegram:\n- `**text**` or `__text__` - Bold text\n- `*text*` or `_text_` - Italic text\n- `` `text` `` - Monospace text\n- ```text``` - Pre-formatted text\n- `~~text~~` - Strikethrough text\n- `[link text](https://example.com)` - Links\n\n#### Other Providers\n\nFor providers that don't natively support HTML or Markdown formatting (Slack, Teams, Discord, Pushover, etc.), Telert automatically strips the formatting tags while preserving the content. This ensures that your messages remain readable across all providers.\n\n**HTML Tag Stripping**: When a message with HTML tags is sent to non-Telegram providers, Telert extracts the text content while removing the tags.\n\n**Markdown Conversion**: When a message with Markdown formatting is sent to non-Telegram providers, Telert removes the formatting characters while keeping the text content.\n\nExample:\n```bash\n# When sending to Telegram, this shows bold and italic text\n# When sending to other providers, formatting is stripped but text is preserved\ntelert send --provider \"telegram,slack,discord\" \"Project \u003cb\u003ecompleted\u003c/b\u003e with \u003ci\u003ezero\u003c/i\u003e errors\"\n\n# Same with Markdown formatting\ntelert send --provider \"telegram,pushover,teams\" \"Project **completed** with *zero* errors\" \n```\n\n**Multi-provider usage**:\n```bash\n# Send to multiple providers at once with automatic formatting handling\ntelert send --all-providers \"Build \u003cb\u003esuccessful\u003c/b\u003e: version 1.0.0 released!\"\n```\n\nNote: Telert intelligently handles the formatting based on each provider's capabilities. You only need to format your message once, and Telert will ensure it displays properly across all providers. This makes it easy to send the same notification to multiple services without worrying about formatting compatibility.\n\n---\n\n## 💡 Use Cases and Tips\n\n### Server Administration\n- Get notified when backups complete\n- Monitor critical system jobs\n- Alert when disk space runs low\n\n```bash\n# Alert when disk space exceeds 90%\ndf -h | grep -E '[9][0-9]%' | telert \"Disk space alert!\"\n\n# Monitor a system update\ntelert run --label \"System update\" apt update \u0026\u0026 apt upgrade -y\n```\n\n### Data Processing\n- Monitor long-running data pipelines\n- Get notified when large file operations complete\n- Track ML model training progress\n\n```python\nfrom telert import telert, notify\nimport pandas as pd\n\n@notify(\"Data processing\")\ndef process_large_dataset(filename):\n    df = pd.read_csv(filename)\n    # Process data...\n    return {\"rows_processed\": len(df), \"outliers_removed\": 15}\n```\n\n### CI/CD Pipelines\n- Get notified when builds complete\n- Alert on deployment failures\n- Track test suite status\n\n```bash\n# In a CI/CD environment using environment variables\nexport TELERT_TOKEN=\"your-token\"\nexport TELERT_CHAT_ID=\"your-chat-id\"\n\n# Alert on build completion\ntelert run --label \"CI Build\" npm run build\n```\n\n### Monitor when Code Completes (Visual Studio Code Extension)\n- Monitor and notify when commands or Python code complete directly within VS Code.\n- Wrap Python functions or code blocks with a click and automatically receive alerts on success or failure.\n- Install the extension from the [Visual Studio Code Marketplace](https://marketplace.visualstudio.com/items?itemName=Navig.telert-vscode)\n\n\n---\n\n### Releasing to PyPI\n \n The project is automatically published to PyPI when a new GitHub release is created:\n \n 1. Update version in both `pyproject.toml`, `README.md` and `telert/__init__.py`\n 2. Commit the changes and push to main\n3. Create a new GitHub release with a tag like `v0.1.34`\n 4. The GitHub Actions workflow will automatically build and publish to PyPI\n \n To manually publish to PyPI if needed:\n \n ```bash\n # Install build tools\n pip install build twine\n \n # Build the package\n python -m build\n \n # Upload to PyPI\n twine upload dist/*\n ```\n\n---\n\n## 🤝 Contributing / License\n\nPRs \u0026 issues welcome!  \nLicensed under the MIT License – see `LICENSE`.\n\n\n## 👏 Acknowledgements\n\nThis project has been improved with help from all contributors who provide feedback and feature suggestions. If you find this tool useful, consider [supporting the project on Buy Me a Coffee](https://www.buymeacoffee.com/mihirk) ☕\n\n### Need a VPS for Your Projects?\n\nTry these providers with generous free credits:\n\n- [Vultr](https://www.vultr.com/?ref=9752934-9J) — $100 free credits\n- [DigitalOcean](https://m.do.co/c/cdf2b5a182f2) — $200 free credits\n","funding_links":["https://www.buymeacoffee.com/mihirk"],"categories":["Productivity Tools","The AWESOME list","Development","\u003ca name=\"productivity\"\u003e\u003c/a\u003eProductivity","System Monitor","Uncategorized"],"sub_categories":["Development Tools","Devops","Sevelt Libraries","Uncategorized"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnavig-me%2Ftelert","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnavig-me%2Ftelert","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnavig-me%2Ftelert/lists"}