Shoutrrr

A notification library for gophers and their furry friends.
Heavily inspired by caronc/apprise.

Table of Contents

• Full Documentation
• Installation
  • From Source
  • Binaries
  • Container Images
  • Go Package
  • GitHub Action
• Usage
  • CLI
  • Go Package Usage
  • Docker
  • GitHub Action Usage
  • Use as a Package
    • Option 1 - Using the direct send command
    • Option 2 - Using a sender
      • Single URL
      • Multiple URLs
  • Use Through the CLI
  • Use as a GitHub Action
• Supported Services
• Contributors ✨
• Related Project(s)

Full Documentation

Visit the project's GitHub Page for full documentation.

Installation

From Source

go install github.com/nicholas-fedor/shoutrrr/shoutrrr@latest

Binaries

Install the latest release binary to $HOME/go/bin (ensure it's in your PATH).

• Windows (amd64):

  New-Item -ItemType Directory -Path $HOME\go\bin -Force | Out-Null; iwr (iwr https://api.github.com/repos/nicholas-fedor/shoutrrr/releases/latest | ConvertFrom-Json).assets.where({$_.name -like "*windows_amd64*.zip"}).browser_download_url -OutFile shoutrrr.zip; Add-Type -AssemblyName System.IO.Compression.FileSystem; ($z=[System.IO.Compression.ZipFile]::OpenRead("$PWD\shoutrrr.zip")).Entries | ? {$_.Name -eq 'shoutrrr.exe'} | % {[System.IO.Compression.ZipFileExtensions]::ExtractToFile($_, "$HOME\go\bin\$($_.Name)", $true)}; $z.Dispose(); rm shoutrrr.zip; if (Test-Path "$HOME\go\bin\shoutrrr.exe") { Write-Host "Successfully installed shoutrrr.exe to $HOME\go\bin" } else { Write-Host "Failed to install shoutrrr.exe" }
  

• Linux (amd64):

  mkdir -p $HOME/go/bin && curl -L $(curl -s https://api.github.com/repos/nicholas-fedor/shoutrrr/releases/latest | grep -o 'https://[^"]*linux_amd64[^"]*\.tar\.gz') | tar -xz --strip-components=1 -C $HOME/go/bin shoutrrr
  

• macOS (amd64):

  mkdir -p $HOME/go/bin && curl -L $(curl -s https://api.github.com/repos/nicholas-fedor/shoutrrr/releases/latest | grep -o 'https://[^"]*darwin_amd64[^"]*\.tar\.gz') | tar -xz --strip-components=1 -C $HOME/go/bin shoutrrr
  

Note

Visit the releases page for other architectures (e.g., arm, arm64, i386, riscv64).

Container Images

• Docker Hub:

  docker pull nickfedor/shoutrrr:latest
  

• GHCR:

  docker pull ghcr.io/nicholas-fedor/shoutrrr:latest
  

Note

Tags: latest (stable), vX.Y.Z (specific version), nightly (development), platform-specific (e.g., amd64-nightly).

Go Package

go get github.com/nicholas-fedor/shoutrrr@latest

GitHub Action

- name: Shoutrrr
  uses: nicholas-fedor/shoutrrr-action@v1
  with:
    url: ${{ secrets.SHOUTRRR_URL }}
    title: Deployed ${{ github.sha }}
    message: See changes at ${{ github.event.compare }}.

Usage

CLI

shoutrrr send --url "slack://hook:T00000000-B00000000-XXXXXXXXXXXXXXXXXXXXXXXX@webhook" --message "Hello, Slack!"

Go Package Usage

import "github.com/nicholas-fedor/shoutrrr"

errs := shoutrrr.Send("slack://hook:T00000000-B00000000-XXXXXXXXXXXXXXXXXXXXXXXX@webhook", "Hello, Slack!")
if len(errs) > 0 {
    // Handle errors
}

Docker

docker run --rm nickfedor/shoutrrr:latest send --url "slack://hook:T00000000-B00000000-XXXXXXXXXXXXXXXXXXXXXXXX@webhook" --message "Hello, Slack!"

GitHub Action Usage

See installation example above.

Use as a Package

Option 1 - Using the direct send command

url := "slack://token-a/token-b/token-c"
err := shoutrrr.Send(url, "Hello world (or slack channel) !")

Option 2 - Using a sender

Single URL

url := "slack://token-a/token-b/token-c"
sender, err := shoutrrr.CreateSender(url)
sender.Send("Hello world (or slack channel) !", map[string]string { /* ... */ })

Multiple URLs

urls := []string {
  "slack://token-a/token-b/token-c"
  "discord://token@channel"
}
sender, err := shoutrrr.CreateSender(urls...)
sender.Send("Hello world (or slack channel) !", map[string]string { /* ... */ })

Use Through the CLI

shoutrrr send [OPTIONS] <URL> <Message [...]>

Use as a GitHub Action

You can also use Shoutrrr in a GitHub Actions workflow.

name: Deploy
on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - [Your other workflow steps]

      - name: Shoutrrr
        uses: nicholas-fedor/shoutrrr-action@v0.0.11
        with:
          url: ${{ secrets.SHOUTRRR_URL }}
          title: Deployed ${{ github.sha }}
          message: See changes at ${{ github.event.compare }}.

Supported Services

Service	Description
Bark	iOS push notifications
Discord	Discord webhooks
Generic	Custom HTTP webhooks
Google Chat	Google Chat webhooks
Gotify	Gotify push notifications
IFTTT	IFTTT webhooks
Join	Join push notifications
Lark	Lark (Feishu) webhooks
Logger	Local logging (for testing)
Matrix	Matrix rooms
Mattermost	Mattermost webhooks
MQTT	MQTT message broker
Notifiarr	Notifiarr message forwarding
Ntfy	Ntfy push notifications
Opsgenie	Opsgenie alerts
PagerDuty	PagerDuty incident notifications
Pushbullet	Pushbullet push notifications
Pushover	Pushover push notifications
Rocket.Chat	Rocket.Chat webhooks
Slack	Slack webhooks or Bot API
SMTP	Email notifications
Teams	Microsoft Teams webhooks
Telegram	Telegram bots
Twilio	Twilio SMS notifications
Zulip	Zulip chat
XMPP	XMPP messages (if enabled)

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Nicholas Fedor 💻 📖 🚧 👀	Amir Schnell 💻	nils måsén 💻 📖 🚧	Luka Peschke 💻 📖	MrLuje 💻 📖	Simon Aronsson 💻 📖 🚧	Arne Jørgensen 📖 💻
Alexei Tighineanu 💻	Alexandru Bonini 💻	Senan Kelly 💻	JonasPf 💻	claycooper 📖	Derzsi Dániel 💻	Joseph Kavanagh 💻 🐛
Justin Steven 🐛	Carlos Savcic 💻 📖	PythonGermany 💻	Noel O'Brien 💻 📖	Caleb Lemoine 💻 📖	Eddie 'Sergeant' M 📖

This project follows the all-contributors specification. Contributions of any kind welcome!

Related Project(s)

• Watchtower - Automate Docker container image updates.
• Shoutrrr GitHub Action - Notifications using Shoutrrr in GitHub Actions.
• Bezel - A lightweight server monitoring platform that includes Docker statistics, historical data, and alert functions.
• WatchYourLAN - Lightweight network IP scanner with web GUI.
• DNSControl- Infrastructure as code for DNS.
• docker-volume-backup - Backup Docker volumes locally or to any S3, WebDAV, Azure Blob Storage, Dropbox, Google Drive or SSH compatible storage.
• BirdNET-Go - An AI solution for continuous avian monitoring and identification.