shellhorn 1.0.0

🐚📯 A lightweight command wrapper that sounds the horn when your shell commands complete, fail, or die unexpectedly

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) 🐚📯