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 started
shellhorn/complete - Command finished
shellhorn/error - Unexpected errors
shellhorn/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) 🐚📯

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)

Source distribution for shellhorn 1.0.0
File	Size	Uploaded
shellhorn-1.0.0.tar.gz	26.2 kB	Aug 26, 2025	Details

Built distribution (wheel)

Table of built distributions (wheels) for shellhorn 1.0.0
File	Interpreter	ABI	Platform	Reset
shellhorn-1.0.0-py3-none-any.whl 26.6 kB Aug 26, 2025	Python 3	none	any	Details

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	Aug 26, 2025
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	Aug 26, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.5`