notifyme-cli
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
From PyPI (Recommended)
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
- Open Telegram and message @BotFather
- Send
/newbotand follow the instructions - Save the bot token you receive
2. Get Your Chat ID
- Message @userinfobot on Telegram
- It will reply with your user information including your chat ID
- 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
Basic Usage (Recommended)
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
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if needed
- Submit a pull request
🤝 Contributing
We welcome contributions! Please see our Contributing Guide for details.
Quick Start for Contributors
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes and add tests
- Run tests:
make test - 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
🔗 Links
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.