Running Periodic Scripts with macOS Launchd

Build periodic execution scripts using macOS Launchd like Cron. Environment variable setup is tedious, so minimize plist configuration.

Configuration is as follows:

plist → wrapper shell → main shell

Wrapper Script

Set environment variables, execute actual script, redirect to logs.

#!/bin/bash

# Set XDG environment variables
export XDG_STATE_HOME="${XDG_STATE_HOME:-$HOME/.local/state}"

# Create log directory
LOG_DIR="$XDG_STATE_HOME/cron-like"
mkdir -p "$LOG_DIR"

# Execute actual script with log redirection
exec "$HOME/.local/bin/cron-like/every-minute.sh" \
    >> "$LOG_DIR/stdout.log" 2>> "$LOG_DIR/stderr.log"

plist Configuration

Configuration for every-minute execution.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>localhost.cron.every-minute</string>
    <key>ProgramArguments</key>
    <array>
        <string>/bin/bash</string>
        <string>/Users/username/.local/bin/cron-like/launchd.sh</string>
    </array>
    <key>StartInterval</key>
    <integer>60</integer>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>

Setup Script

Automate complete setup.

#!/bin/bash

set -e

# Create directories
mkdir -p "$HOME/.local/bin/cron-like"
mkdir -p "$HOME/.local/state/cron-like"
mkdir -p "$HOME/Library/LaunchAgents"

# Create wrapper script
cat > "$HOME/.local/bin/cron-like/launchd.sh" <<'EOF'
#!/bin/bash

# Set XDG environment variables
export XDG_STATE_HOME="${XDG_STATE_HOME:-$HOME/.local/state}"

# Create log directory
LOG_DIR="$XDG_STATE_HOME/cron-like"
mkdir -p "$LOG_DIR"

# Execute actual script with log redirection
exec "$HOME/.local/bin/cron-like/every-minute.sh" \
    >> "$LOG_DIR/stdout.log" 2>> "$LOG_DIR/stderr.log"
EOF

# Create execution script
cat > "$HOME/.local/bin/cron-like/every-minute.sh" <<'EOF'
#!/bin/bash

# Actual processing
echo "[$(date '+%Y-%m-%d %H:%M:%S')] Running every-minute task"

# Add actual processing here
EOF

# Grant execution permissions
chmod +x "$HOME/.local/bin/cron-like/launchd.sh"
chmod +x "$HOME/.local/bin/cron-like/every-minute.sh"

# Create plist
LABEL="localhost.cron.every-minute"
PLIST_PATH="$HOME/Library/LaunchAgents/${LABEL}.plist"

cat > "$PLIST_PATH" <<EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>${LABEL}</string>
    <key>ProgramArguments</key>
    <array>
        <string>/bin/bash</string>
        <string>$HOME/.local/bin/cron-like/launchd.sh</string>
    </array>
    <key>StartInterval</key>
    <integer>60</integer>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>
EOF

# Syntax check
plutil -lint "$PLIST_PATH"

# Unload if already loaded
launchctl list | grep -q "$LABEL" && launchctl unload "$PLIST_PATH" 2>/dev/null || true

# Load
launchctl load "$PLIST_PATH"

echo "✓ Setup complete!"
echo "  Scripts: $HOME/.local/bin/cron-like/"
echo "  Logs:    $HOME/.local/state/cron-like/"
echo "  plist:   $PLIST_PATH"
echo ""
echo "Commands:"
echo "  tail -f $HOME/.local/state/cron-like/stdout.log"
echo "  launchctl start $LABEL"
echo "  launchctl unload $PLIST_PATH"