Shell & Cron

Helper functions for bash, zsh, and cron job monitoring.

Shell Helper Function

Add this nudge() function to your ~/.bashrc or ~/.zshrc. It wraps any command with automatic timing, exit code capture, and output piping to the nudge API:

~/.bashrc

nudge() {
  # Capture the command to run
  local cmd="$@"
  local label="${NUDGE_LABEL:-$1}"
  local start end duration exit_code output

  # Record start time
  start=$(date +%s)

  # Run the command and capture output + exit code
  output=$( eval "$cmd" 2>&1 )
  exit_code=$?

  # Calculate duration
  end=$(date +%s)
  duration=$(( end - start ))

  # Determine status from exit code
  local status="done"
  if [ $exit_code -ne 0 ]; then
    status="failed"
  fi

  # Send the nudge
  curl -s https://nudge.sh/$NUDGE_TOKEN \
    -d status="$status" \
    -d exit_code=$exit_code \
    -d duration=$duration \
    -d label="$label" \
    --data-urlencode output="$output" \
    >/dev/null

  # Print the original output and preserve exit code
  echo "$output"
  return $exit_code
}

After adding the function, reload your shell:

bash

source ~/.bashrc
# or
source ~/.zshrc

Usage Examples

Prefix any long-running command with nudge and you will receive an SMS when it completes:

bash

# Build a frontend project
nudge npm run build

# Run a deployment
nudge make deploy

# Train a model
nudge python train.py

# Run a database migration
nudge php artisan migrate

# Run your test suite
nudge php artisan test

# Compress a large file
nudge tar czf archive.tar.gz /data/logs

Pipe-friendly

The nudge() function prints the original command output to stdout and preserves the exit code, so it works seamlessly in pipelines and scripts.

Cron Jobs

Use && and || to send a nudge when a cron job completes or fails:

crontab

# Nudge on success only
0 2 * * * /usr/bin/pg_dump mydb > /backups/db.sql && curl -s https://nudge.sh/YOUR_TOKEN -d status="done" -d label="db-backup"

crontab

# Nudge on failure only
0 2 * * * /usr/bin/pg_dump mydb > /backups/db.sql || curl -s https://nudge.sh/YOUR_TOKEN -d status="failed" -d label="db-backup"

crontab

# Nudge on both success and failure
0 2 * * * /usr/bin/pg_dump mydb > /backups/db.sql && curl -s https://nudge.sh/YOUR_TOKEN -d status="done" -d label="db-backup" || curl -s https://nudge.sh/YOUR_TOKEN -d status="failed" -d label="db-backup"

Cron environment

Cron jobs run in a minimal shell environment. You cannot use $NUDGE_TOKEN unless you explicitly set it in the crontab or script. Use the cron wrapper below for a cleaner approach.

Cron Wrapper Script

For cron jobs that need full output capture, timing, and exit code reporting, save this wrapper script and call it from your crontab:

/usr/local/bin/nudge-cron

#!/usr/bin/env bash
# nudge-cron -- wrapper that captures output and sends a nudge
# Usage: nudge-cron [label] [command...]
#   e.g. nudge-cron db-backup pg_dump mydb > /backups/db.sql

set -euo pipefail

# Configuration
NUDGE_TOKEN="${NUDGE_TOKEN:?NUDGE_TOKEN is not set}"
NUDGE_API="https://nudge.sh/$NUDGE_TOKEN"

# Parse arguments
LABEL="${1:?Usage: nudge-cron [label] [command...]}"
shift

# Capture timing, output, and exit code
START=$(date +%s)
OUTPUT=$( "$@" 2>&1 ) && EXIT_CODE=0 || EXIT_CODE=$?
DURATION=$(( $(date +%s) - START ))

# Set status based on exit code
if [ $EXIT_CODE -eq 0 ]; then
  STATUS="done"
else
  STATUS="failed"
fi

# Send the nudge
curl -s "$NUDGE_API" \
  -d status="$STATUS" \
  -d exit_code=$EXIT_CODE \
  -d duration=$DURATION \
  -d label="$LABEL" \
  --data-urlencode output="$OUTPUT" \
  >/dev/null

exit $EXIT_CODE

Make it executable and use it in your crontab:

bash

chmod +x /usr/local/bin/nudge-cron

crontab

# Set your token once at the top of the crontab
NUDGE_TOKEN="your-api-token-here"

# Nightly database backup
0 2 * * * /usr/local/bin/nudge-cron db-backup pg_dump -Fc mydb -f /backups/db.dump

# Weekly log rotation
0 0 * * 0 /usr/local/bin/nudge-cron log-rotate /usr/sbin/logrotate /etc/logrotate.conf

# Hourly health check
0 * * * * /usr/local/bin/nudge-cron health-check curl -sf https://example.com/health

Environment Variables

Both the nudge() shell function and the nudge-cron wrapper read these environment variables:

Variable	Required	Description
NUDGE_TOKEN	REQUIRED	Your nudge.sh API token. Get it from the Getting Started guide.
NUDGE_LABEL	optional	Default label for the `nudge()` shell function. If not set, the label defaults to the first word of the command (e.g. `npm`, `python`, `make`).

~/.bashrc

# Required -- your API token
export NUDGE_TOKEN="your-api-token-here"

# Optional -- default label for all nudges from this shell
export NUDGE_LABEL="dev-machine"

Override per-command

You can override NUDGE_LABEL for a single command without changing your default: NUDGE_LABEL=deploy nudge make production

Previous API Reference Next CI/CD