# Shoutrrr
A notification library for gophers and their furry friends.
Heavily inspired by
caronc/apprise.
[](https://scorecard.dev/viewer/?uri=github.com/nicholas-fedor/shoutrrr)
[](https://codecov.io/gh/nicholas-fedor/shoutrrr)
[](https://www.codacy.com/gh/nicholas-fedor/shoutrrr/dashboard?utm_source=github.com&utm_medium=referral&utm_content=nicholas-fedor/shoutrrr&utm_campaign=Badge_Grade)
[](https://goreportcard.com/badge/github.com/nicholas-fedor/shoutrrr)
[](https://pkg.go.dev/github.com/nicholas-fedor/shoutrrr)
[](https://github.com/nicholas-fedor/shoutrrr)
[](https://github.com/nicholas-fedor/shoutrrr/blob/main/LICENSE)
[](https://hub.docker.com/r/nickfedor/shoutrrr)
[](https://godoc.org/github.com/nicholas-fedor/shoutrrr)
[](#contributors-)
## Table of Contents
- [Full Documentation](#full-documentation)
- [Installation](#installation)
- [From Source](#from-source)
- [Binaries](#binaries)
- [Container Images](#container-images)
- [Go Package](#go-package)
- [GitHub Action](#github-action)
- [Usage](#usage)
- [CLI](#cli)
- [Go Package Usage](#go-package-usage)
- [Docker](#docker)
- [GitHub Action Usage](#github-action-usage)
- [Use as a Package](#use-as-a-package)
- [Option 1 - Using the direct send command](#option-1---using-the-direct-send-command)
- [Option 2 - Using a sender](#option-2---using-a-sender)
- [Single URL](#single-url)
- [Multiple URLs](#multiple-urls)
- [Use Through the CLI](#use-through-the-cli)
- [Use as a GitHub Action](#use-as-a-github-action)
- [Supported Services](#supported-services)
- [Contributors β¨](#contributors-)
- [Related Project(s)](#related-projects)
## Full Documentation
Visit the project's [GitHub Page](https://shoutrrr.nickfedor.com) for full documentation.
## Installation
### From Source
```bash
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):**
```powershell
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):**
```bash
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):**
```bash
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](https://github.com/nicholas-fedor/shoutrrr/releases) for other architectures (e.g., arm, arm64, i386, riscv64).
### Container Images
- **[Docker Hub](https://hub.docker.com/r/nickfedor/shoutrrr):**
```bash
docker pull nickfedor/shoutrrr:latest
```
- **[GHCR](https://github.com/users/nicholas-fedor/packages/container/package/shoutrrr):**
```bash
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
```bash
go get github.com/nicholas-fedor/shoutrrr@latest
```
### GitHub Action
```yaml
- 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
```bash
shoutrrr send --url "slack://hook:T00000000-B00000000-XXXXXXXXXXXXXXXXXXXXXXXX@webhook" --message "Hello, Slack!"
```
### Go Package Usage
```go
import "github.com/nicholas-fedor/shoutrrr"
errs := shoutrrr.Send("slack://hook:T00000000-B00000000-XXXXXXXXXXXXXXXXXXXXXXXX@webhook", "Hello, Slack!")
if len(errs) > 0 {
// Handle errors
}
```
### Docker
```bash
docker run --rm nickfedor/shoutrrr:latest send --url "slack://hook:T00000000-B00000000-XXXXXXXXXXXXXXXXXXXXXXXX@webhook" --message "Hello, Slack!"
```
### GitHub Action Usage
See installation example [above](#github-action).
### Use as a Package
#### Option 1 - Using the direct send command
```go
url := "slack://token-a/token-b/token-c"
err := shoutrrr.Send(url, "Hello world (or slack channel) !")
```
#### Option 2 - Using a sender
##### Single URL
```go
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
```go
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
```bash
shoutrrr send [OPTIONS]