Skip to main content

notifyme-cli

CI PyPI version Python versions License: MIT codecov

A command-line tool that sends Telegram notifications when long-running commands complete. Never miss when your builds, tests, or data processing jobs finish!

✨ Features

  • 🔔 Get notified via Telegram when commands finish
  • ⏱️ Shows command duration and exit status
  • 📝 Add custom messages to notifications
  • 🛠️ Easy setup with interactive configuration
  • 🎯 Works with any command-line program
  • 💾 Secure local configuration storage

📦 Installation

pip install notifyme-cli

From Source

git clone https://github.com/judeosbert/notifyme-cli.git
cd notifyme-cli
pip install -e .

Development Installation

git clone https://github.com/judeosbert/notifyme-cli.git
cd notifyme-cli
pip install -e ".[dev]"

Setup

1. Create a Telegram Bot

  1. Open Telegram and message @BotFather
  2. Send /newbot and follow the instructions
  3. Save the bot token you receive

2. Get Your Chat ID

  1. Message @userinfobot on Telegram
  2. It will reply with your user information including your chat ID
  3. Save the chat ID (it's a number like 123456789)

3. Configure notify-me

Run the setup command and enter your bot token and chat ID:

notifyme setup

The setup will test the connection and confirm everything works.

📱 Usage

Run commands and then notify when complete:

# Send default "Task complete" message
python train_model.py && notifyme

# Send custom message
make build && notifyme -m "Build finished"

# Chain multiple commands
npm test && npm build && notifyme -m "CI pipeline complete"

Direct Message Sending

Send a message directly:

notifyme                                    # Send "Task complete"
notifyme -m "Hello from the command line!"  # Send custom message

Command Wrapper (Alternative)

Execute commands with notification wrapper:

notifyme --exec python train_model.py
notifyme --exec -m "Training complete!" python train_model.py

Test Configuration

Test your setup:

notifyme test

Command Examples

# Long-running build with notification (recommended)
docker build -t myapp . && notifyme -m "Docker build complete"

# Database backup with notification
pg_dump mydatabase > backup.sql && notifyme -m "Backup finished"

# Machine learning training
python train.py --epochs 100 && notifyme -m "Model training done"

# Run tests and get notified
pytest tests/ && notifyme

# Complex pipeline
bash ./process_data.sh && notifyme -m "Data processing complete"

# Using the wrapper (alternative method)
notifyme --exec pytest tests/
notifyme --exec -m "Training complete!" python train.py

Configuration

Configuration is stored in ~/.notify-me/config.json. The file contains:

{
  "bot_token": "your-bot-token-here",
  "chat_id": "your-chat-id-here"
}

Security

  • Your bot token and chat ID are stored locally on your machine
  • No data is sent to external servers except Telegram's API
  • Configuration file has restricted permissions (600)

Notification Format

Notifications include:

  • ✅/❌ Success or failure status
  • Command that was executed
  • Execution time
  • Timestamp
  • Custom message (if provided)
  • Exit code (if command failed)

Example notification:

✅ Command completed successfully

Message: Training finished!

Command: python train_model.py
Duration: 2.3 hours
Time: 2024-11-17 14:30:22

Troubleshooting

"Bot not configured" Error

Run notifyme setup to configure your bot token and chat ID.

"Connection error" or timeout

  • Check your internet connection
  • Verify your bot token is correct
  • Make sure your bot hasn't been deleted

"Telegram API error"

  • Verify your chat ID is correct
  • Make sure you've sent at least one message to your bot
  • Check that your bot token is valid

Permission errors

The configuration directory ~/.notify-me/ should be writable by your user.

Development

Running Tests

python -m pytest tests/

Installing for Development

pip install -e ".[dev]"

License

MIT License - see LICENSE file for details.

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if needed
  5. Submit a pull request

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Start for Contributors

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Make your changes and add tests
  4. Run tests: make test
  5. Submit a pull request

📝 Changelog

See CHANGELOG.md for a detailed history of changes.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

⭐ Support

If you find this project helpful, please consider:

  • Giving it a star on GitHub ⭐
  • Reporting bugs or requesting features through issues
  • Contributing to the codebase
  • Sharing it with others who might find it useful

🤖 Built with AI

This project was created with the assistance of AI (GitHub Copilot) to demonstrate modern Python development practices and open-source project structure. The AI helped with:

  • Code architecture and implementation
  • Comprehensive documentation and examples
  • GitHub workflows and community templates
  • Testing and quality assurance setup
  • Open-source best practices

Metadata

Release files for notifyme-cli 1.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for notifyme-cli 1.0.1
File Size Uploaded Provenance Actions
notifyme_cli-1.0.1.tar.gz 13.0 kB Without provenance Details for notifyme_cli-1.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for notifyme-cli 1.0.1
File Interpreter ABI Platform Actions
notifyme_cli-1.0.1-py3-none-any.whl Python 3 none any Details for notifyme_cli-1.0.1-py3-none-any.whl

Total release size: 23.1 kB

Release files / notifyme_cli-1.0.1.tar.gz

Download URL notifyme_cli-1.0.1.tar.gz
Size 13.0 kB
Tags Source
SHA-256 checksum
How to use checksums
fcb096deb1da49cb2efa5b9d4a4807c345ea7f886ffcf41b51413ab8dba69563
BLAKE2b-256 checksum
How to use checksums
15ef30a6aad2c5155e1734b41752f4f9b8598c513ac03303f8838be877f7d424
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.7

Release files / notifyme_cli-1.0.1-py3-none-any.whl

Download URL notifyme_cli-1.0.1-py3-none-any.whl
Size 10.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
799ebf931510000db468ce14927ab39f2bf1755ce6b0a44d730292d30c8ca74e
BLAKE2b-256 checksum
How to use checksums
2431afd84a46b84d9a67e3f97740c9e1dc79db89e0129e5db974a23037f6b71e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.7

Security for notifyme-cli 1.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page