JobDone – Job Completion Notification Tool

Whether you're compiling kernels, training models, or just waiting for sleep 600 to finish, JobDone ensures you never miss the moment your job ends—successfully, tragically, or somewhere in between.

---

🚀 Quick Start

Build & Install

make build
# Binary located at dist/jobdone
make install   # Installs to /usr/local/bin for root, ~/.local/bin for regular users

Configuration (YAML)

• Config file locations:

  • ~/.config/jobdone/config.yaml
  • .jobdone.yaml in project root

• Initialize template:

mkdir -p ~/.config/jobdone
cp .jobdone.yaml.template ~/.config/jobdone/config.yaml
# Edit channels, webhook, email, etc. as needed

---

🔔 Notification Examples

Always Notify

long_task && jobdone -j long_task -c email

Notify on Success or Failure

my_job; jobdone -j my_job -e $? --on failure -c email
my_job; jobdone -j my_job -e $? --on success -c email

Use STDIN as Message

my_job && echo "Task finished" | jobdone --stdin -j my_job -c desktop

---

📧 Email Notifications

Via CLI

jobdone -c email \
  --email-to you@example.com --email-from noreply@example.com \
  --smtp-host smtp.example.com --smtp-port 587 --smtp-user myuser \
  --smtp-pass-prompt -t "Job Done"

Via Environment Variables

export JOBDONE_SMTP_HOST=smtp.example.com
export JOBDONE_SMTP_PORT=587
export JOBDONE_SMTP_USER=myuser
export JOBDONE_SMTP_PASS=secret
export JOBDONE_EMAIL_FROM=noreply@example.com
export JOBDONE_EMAIL_TO=me@example.com
jobdone -c email -j build

---

🌐 Webhook Notifications

• Request format: POST to --webhook-url with application/json
• Example payload:

{
  "title": "Job Done",
  "message": "Job testjob finished with exit code 0.",
  "context": {
    "job": "testjob",
    "status": "success",
    "exit_code": 0,
    "host": "xxx",
    "user": "xxx",
    "timestamp": "2025-10-18T12:34:56Z",
    "source": "jobdone"
  }
}

• Custom headers:

  • CLI: --header "X-Token: your-token" (repeatable)
  • YAML: webhook.headers: { X-Token: ${JOBDONE_WEBHOOK_TOKEN} }

• Multiple URLs:

  • CLI: repeat --webhook-url
  • YAML: webhook.urls: [url1, url2]

---

⚙️ CLI Options & Defaults

• Configuration priority: CLI > YAML > ENV
• YAML search order:
  1. ~/.config/jobdone/config.yaml
  2. ./.jobdone.yaml
  3. ./jobdone.yaml
  4. ./config.yaml
  5. Or use --config PATH to specify

General Options

| Option | Description | |--------|-------------| | --version | Print version info | | -j, --job | Job name (default: job) | | -t, --title | Notification title (default: Job Done) | | -m, --message | Custom message (default: auto-generated) | | --stdin | Read message from STDIN | | -e, --exit-code | Exit code (default: 0) | | --on | Trigger condition: success, failure, always (default: always) | | -c, --channel | Notification channels (default: webhook,desktop if webhook configured, else desktop) | | --timeout | Timeout in seconds (default: 10.0) | | --retries | Retry count (default: 0) | | --backoff | Backoff in seconds (default: 2.0) | | --config | Path to config file | | -v, --verbose | Verbose logging | | --dry-run | Print payload without sending |

---

🌍 Environment Variables

| Variable | Description | |----------|-------------| | JOBDONE_CHANNELS | Comma-separated list of channels | | JOBDONE_WEBHOOK_URLS | Comma-separated list of webhook URLs | | JOBDONE_EMAIL_TO | Comma-separated list of email recipients | | JOBDONE_SMTP_HOST / PORT / USER / PASS | SMTP configuration | | JOBDONE_EMAIL_FROM | Sender address | | JOBDONE_ON | Trigger condition | | JOBDONE_RETRIES / BACKOFF / TIMEOUT | Retry/backoff/timeout settings |

---

🌐 Webhook Options

| Option | Description | |--------|-------------| | --webhook-url | Webhook URL (repeatable) | | --header | Custom headers (repeatable) |

Note: YAML does not support environment variable interpolation. Use CLI for dynamic values like --header "X-Token: $JOBDONE_WEBHOOK_TOKEN".

---

📧 Email Options

| Option | Description | |--------|-------------| | --email-to | Email recipients (repeatable) | | --email-subject | Email subject (default: --title) | | --smtp-host / --smtp-port / --smtp-user / --smtp-pass | SMTP settings | | --smtp-pass-prompt | Prompt for password interactively | | --email-from | Sender address |

• Connection strategy:
  • Port 465: implicit SSL
  • Other ports: plaintext with STARTTLS fallback
• Authentication strategy:
  • Uses smtp_user or falls back to email.from
  • If authentication fails, sending may still proceed depending on server policy