Shellhorn
Get phone notifications when your long-running shell commands finish. Perfect for ML training, builds, or any command you don't want to babysit.
# Install
pip install shellhorn
# Just prepend any command
shellhorn python3 my-training-script.py # Get notified when done
Quick Setup
Pushover (phone notifications):
shellhorn config set notifications.pushover.app_token YOUR_TOKEN
shellhorn config set notifications.pushover.user_key YOUR_USER
shellhorn config set notifications.pushover.enabled true
MQTT (centralized monitoring):
shellhorn config set notifications.mqtt.broker_host mqtt.example.com
shellhorn config set notifications.mqtt.enabled true
Test it:
shellhorn config test # Sends test notification
Usage
# Any command works - just prepend with shellhorn
shellhorn make build && make test
shellhorn ./deploy-script.sh
shellhorn python3 -m pytest --long-running-tests
shellhorn npm run build
What you get:
- Success notifications with duration
- Failure alerts with exit codes
- Orphaned process detection (via MQTT monitor)
- Works with pipes, redirects, and complex commands
- Start notifications disabled by default (you know when you started it!)
More Options
Environment Variables (alternative to config commands)
export SHELLHORN_PUSHOVER_TOKEN=your_app_token
export SHELLHORN_PUSHOVER_USER=your_user_key
export SHELLHORN_MQTT_BROKER=mqtt.example.com
CLI Override (one-time config)
shellhorn --pushover-token=xxx --pushover-user=yyy python3 script.py
shellhorn --mqtt-broker=localhost python3 script.py
Config Commands
shellhorn config show # View current config
shellhorn config test # Test notifications
shellhorn --version # Show version
# Notification preferences (start notifications off by default)
shellhorn config set preferences.notify_start true # Enable start notifications
shellhorn config set preferences.notify_success false # Disable success notifications
MQTT Details
Topics:
shellhorn/start- Command startedshellhorn/complete- Command finishedshellhorn/error- Unexpected errorsshellhorn/interrupt- Interrupted (Ctrl+C)
Message format:
{
"command": "python3 script.py",
"status": "success",
"duration": 123.45,
"client_id": "shellhorn_123456789"
}
Monitor (Centralized Alerts)
Deploy the monitor to get alerts when hosts disconnect unexpectedly:
# Quick start with Docker (from GitHub Container Registry)
docker run -d --name shellhorn-monitor \
-e MQTT_BROKER=192.168.1.100 \
-e PUSHOVER_TOKEN=xxx -e PUSHOVER_USER=yyy \
ghcr.io/mitchins/shellhorn/monitor:latest
# Or with config file (YAML)
docker run -d -v ./monitor.yaml:/config/monitor.yaml \
ghcr.io/mitchins/shellhorn/monitor:latest
Perfect for detecting lost commands when machines shut down or disconnect. See monitor/ directory for full setup.
Perfect for ML training, CI/CD pipelines, data processing, or any command you don't want to babysit. The name "Shellhorn" comes from shell (command wrapper) + horn (notification alerts) 🐚📯
1 maintainer
Metadata
1 maintainer
Release files for shellhorn 1.0.0
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 |
|---|---|---|---|---|
| shellhorn-1.0.0.tar.gz | 26.2 kB | Without provenance | Details for shellhorn-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| shellhorn-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for shellhorn-1.0.0-py3-none-any.whl |
Total release size: 52.8 kB
Release files / shellhorn-1.0.0.tar.gz
| Download URL | shellhorn-1.0.0.tar.gz |
|---|---|
| Size | 26.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c4ba8bb1c8a16de44c4fc6a135dac01fd1e16f8fc7c10de3d3a95a22e1bd5bb8
|
|
BLAKE2b-256 checksum How to use checksums |
11e23e1177f166c362e131ff704349148438cb784cd8a5861f9cb4f9bb49731b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.5
|
Release files / shellhorn-1.0.0-py3-none-any.whl
| Download URL | shellhorn-1.0.0-py3-none-any.whl |
|---|---|
| Size | 26.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
aad7137be363ce17a7be9c4cc7fd8b656ca220ec5003ca68646ef3e2f2c0ec4a
|
|
BLAKE2b-256 checksum How to use checksums |
5093ebe4157ad0555468db9f7c04f5fb6a1b63874b9999fe2c1341d30b04c214
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.5
|
Security for shellhorn 1.0.0
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.
