Debian Codegraph @

README.md

raw
1 <!-- markdownlint-disable -->
2 <div align="center">
3
4 <a href="https://github.com/nicholas-fedor/shoutrrr">
5 <img src="https://raw.githubusercontent.com/nicholas-fedor/shoutrrr/refs/heads/main/docs/assets/media/shoutrrr-logotype.svg" width="450" />
6 </a>
7
8 # Shoutrrr
9
10 A notification library for gophers and their furry friends.<br />
11 Heavily inspired by <a href="https://github.com/caronc/apprise">caronc/apprise</a>.
12
13 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/nicholas-fedor/shoutrrr/badge)](https://scorecard.dev/viewer/?uri=github.com/nicholas-fedor/shoutrrr)
14 [![codecov](https://codecov.io/gh/nicholas-fedor/shoutrrr/branch/main/graph/badge.svg)](https://codecov.io/gh/nicholas-fedor/shoutrrr)
15 [![Codacy Badge](https://app.codacy.com/project/badge/Grade/47eed72de79448e2a6e297d770355544)](https://www.codacy.com/gh/nicholas-fedor/shoutrrr/dashboard?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=nicholas-fedor/shoutrrr&amp;utm_campaign=Badge_Grade)
16 [![report card](https://goreportcard.com/badge/github.com/nicholas-fedor/shoutrrr)](https://goreportcard.com/badge/github.com/nicholas-fedor/shoutrrr)
17 [![go.dev reference](https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&logoColor=white&style=flat-square)](https://pkg.go.dev/github.com/nicholas-fedor/shoutrrr)
18 [![github code size in bytes](https://img.shields.io/github/languages/code-size/nicholas-fedor/shoutrrr.svg?style=flat-square)](https://github.com/nicholas-fedor/shoutrrr)
19 [![license](https://img.shields.io/github/license/nicholas-fedor/shoutrrr.svg?style=flat-square)](https://github.com/nicholas-fedor/shoutrrr/blob/main/LICENSE)
20 [![Pulls from DockerHub](https://img.shields.io/docker/pulls/nickfedor/shoutrrr.svg)](https://hub.docker.com/r/nickfedor/shoutrrr)
21 [![godoc](https://godoc.org/github.com/nicholas-fedor/shoutrrr?status.svg)](https://godoc.org/github.com/nicholas-fedor/shoutrrr) <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
22 [![All Contributors](https://img.shields.io/badge/all_contributors-20-orange.svg?style=flat-square)](#contributors-)
23 <!-- ALL-CONTRIBUTORS-BADGE:END -->
24 </div>
25 <!-- markdownlint-restore -->
26
27 ## Table of Contents
28
29 - [Full Documentation](#full-documentation)
30 - [Installation](#installation)
31 - [From Source](#from-source)
32 - [Binaries](#binaries)
33 - [Container Images](#container-images)
34 - [Go Package](#go-package)
35 - [GitHub Action](#github-action)
36 - [Usage](#usage)
37 - [CLI](#cli)
38 - [Go Package Usage](#go-package-usage)
39 - [Docker](#docker)
40 - [GitHub Action Usage](#github-action-usage)
41 - [Use as a Package](#use-as-a-package)
42 - [Option 1 - Using the direct send command](#option-1---using-the-direct-send-command)
43 - [Option 2 - Using a sender](#option-2---using-a-sender)
44 - [Single URL](#single-url)
45 - [Multiple URLs](#multiple-urls)
46 - [Use Through the CLI](#use-through-the-cli)
47 - [Use as a GitHub Action](#use-as-a-github-action)
48 - [Supported Services](#supported-services)
49 - [Contributors ✨](#contributors-)
50 - [Related Project(s)](#related-projects)
51
52 ## Full Documentation
53
54 Visit the project's [GitHub Page](https://shoutrrr.nickfedor.com) for full documentation.
55
56 ## Installation
57
58 ### From Source
59
60 ```bash
61 go install github.com/nicholas-fedor/shoutrrr/shoutrrr@latest
62 ```
63
64 ### Binaries
65
66 Install the latest release binary to `$HOME/go/bin` (ensure it's in your `PATH`).
67
68 - **Windows (amd64):**
69
70 ```powershell
71 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" }
72 ```
73
74 - **Linux (amd64):**
75
76 ```bash
77 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
78 ```
79
80 - **macOS (amd64):**
81
82 ```bash
83 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
84 ```
85
86 > [!Note]
87 > Visit the [releases page](https://github.com/nicholas-fedor/shoutrrr/releases) for other architectures (e.g., arm, arm64, i386, riscv64).
88
89 ### Container Images
90
91 - **[Docker Hub](https://hub.docker.com/r/nickfedor/shoutrrr):**
92
93 ```bash
94 docker pull nickfedor/shoutrrr:latest
95 ```
96
97 - **[GHCR](https://github.com/users/nicholas-fedor/packages/container/package/shoutrrr):**
98
99 ```bash
100 docker pull ghcr.io/nicholas-fedor/shoutrrr:latest
101 ```
102
103 > [!Note]
104 > Tags: `latest` (stable), `vX.Y.Z` (specific version), `nightly` (development), platform-specific (e.g., `amd64-nightly`).
105
106 ### Go Package
107
108 ```bash
109 go get github.com/nicholas-fedor/shoutrrr@latest
110 ```
111
112 ### GitHub Action
113
114 ```yaml
115 - name: Shoutrrr
116 uses: nicholas-fedor/shoutrrr-action@v1
117 with:
118 url: ${{ secrets.SHOUTRRR_URL }}
119 title: Deployed ${{ github.sha }}
120 message: See changes at ${{ github.event.compare }}.
121 ```
122
123 ## Usage
124
125 ### CLI
126
127 ```bash
128 shoutrrr send --url "slack://hook:T00000000-B00000000-XXXXXXXXXXXXXXXXXXXXXXXX@webhook" --message "Hello, Slack!"
129 ```
130
131 ### Go Package Usage
132
133 ```go
134 import "github.com/nicholas-fedor/shoutrrr"
135
136 errs := shoutrrr.Send("slack://hook:T00000000-B00000000-XXXXXXXXXXXXXXXXXXXXXXXX@webhook", "Hello, Slack!")
137 if len(errs) > 0 {
138 // Handle errors
139 }
140 ```
141
142 ### Docker
143
144 ```bash
145 docker run --rm nickfedor/shoutrrr:latest send --url "slack://hook:T00000000-B00000000-XXXXXXXXXXXXXXXXXXXXXXXX@webhook" --message "Hello, Slack!"
146 ```
147
148 ### GitHub Action Usage
149
150 See installation example [above](#github-action).
151
152 ### Use as a Package
153
154 #### Option 1 - Using the direct send command
155
156 ```go
157 url := "slack://token-a/token-b/token-c"
158 err := shoutrrr.Send(url, "Hello world (or slack channel) !")
159 ```
160
161 #### Option 2 - Using a sender
162
163 ##### Single URL
164
165 ```go
166 url := "slack://token-a/token-b/token-c"
167 sender, err := shoutrrr.CreateSender(url)
168 sender.Send("Hello world (or slack channel) !", map[string]string { /* ... */ })
169 ```
170
171 ##### Multiple URLs
172
173 ```go
174 urls := []string {
175 "slack://token-a/token-b/token-c"
176 "discord://token@channel"
177 }
178 sender, err := shoutrrr.CreateSender(urls...)
179 sender.Send("Hello world (or slack channel) !", map[string]string { /* ... */ })
180 ```
181
182 ### Use Through the CLI
183
184 ```bash
185 shoutrrr send [OPTIONS] <URL> <Message [...]>
186 ```
187
188 ### Use as a GitHub Action
189
190 You can also use Shoutrrr in a GitHub Actions workflow.
191
192 ```yaml
193 name: Deploy
194 on:
195 push:
196 branches:
197 - main
198
199 jobs:
200 build:
201 runs-on: ubuntu-latest
202 steps:
203 - [Your other workflow steps]
204
205 - name: Shoutrrr
206 uses: nicholas-fedor/[email protected]
207 with:
208 url: ${{ secrets.SHOUTRRR_URL }}
209 title: Deployed ${{ github.sha }}
210 message: See changes at ${{ github.event.compare }}.
211 ```
212
213 ## Supported Services
214
215 | Service | Description |
216 |--------------|--------------------------------------|
217 | Bark | iOS push notifications |
218 | Discord | Discord webhooks |
219 | Generic | Custom HTTP webhooks |
220 | Google Chat | Google Chat webhooks |
221 | Gotify | Gotify push notifications |
222 | IFTTT | IFTTT webhooks |
223 | Join | Join push notifications |
224 | Lark | Lark (Feishu) webhooks |
225 | Logger | Local logging (for testing) |
226 | Matrix | Matrix rooms |
227 | Mattermost | Mattermost webhooks |
228 | MQTT | MQTT message broker |
229 | Notifiarr | Notifiarr message forwarding |
230 | Ntfy | Ntfy push notifications |
231 | Opsgenie | Opsgenie alerts |
232 | PagerDuty | PagerDuty incident notifications |
233 | Pushbullet | Pushbullet push notifications |
234 | Pushover | Pushover push notifications |
235 | Rocket.Chat | Rocket.Chat webhooks |
236 | Slack | Slack webhooks or Bot API |
237 | SMTP | Email notifications |
238 | Teams | Microsoft Teams webhooks |
239 | Telegram | Telegram bots |
240 | Twilio | Twilio SMS notifications |
241 | Zulip | Zulip chat |
242 | XMPP | XMPP messages (if enabled) |
243
244 ## Contributors ✨
245
246 Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
247
248 <!-- markdownlint-disable -->
249 <!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
250 <!-- prettier-ignore-start -->
251 <!-- markdownlint-disable -->
252 <table>
253 <tbody>
254 <tr>
255 <td align="center" valign="top" width="14.28%"><a href="https://github.com/nicholas-fedor"><img src="https://avatars2.githubusercontent.com/u/71477161?v=4?s=100" width="100px;" alt="Nicholas Fedor"/><br /><sub><b>Nicholas Fedor</b></sub></a><br /><a href="https://github.com/nicholas-fedor/shoutrrr/commits?author=nicholas-fedor" title="Code">πŸ’»</a> <a href="https://github.com/nicholas-fedor/shoutrrr/commits?author=nicholas-fedor" title="Documentation">πŸ“–</a> <a href="#maintenance-nicholas-fedor" title="Maintenance">🚧</a> <a href="https://github.com/nicholas-fedor/shoutrrr/pulls?q=is%3Apr+reviewed-by%3Anicholas-fedor" title="Reviewed Pull Requests">πŸ‘€</a></td>
256 <td align="center" valign="top" width="14.28%"><a href="https://github.com/amirschnell"><img src="https://avatars3.githubusercontent.com/u/9380508?v=4?s=100" width="100px;" alt="Amir Schnell"/><br /><sub><b>Amir Schnell</b></sub></a><br /><a href="https://github.com/nicholas-fedor/shoutrrr/commits?author=amirschnell" title="Code">πŸ’»</a></td>
257 <td align="center" valign="top" width="14.28%"><a href="https://piksel.se"><img src="https://avatars2.githubusercontent.com/u/807383?v=4?s=100" width="100px;" alt="nils mΓ₯sΓ©n"/><br /><sub><b>nils mΓ₯sΓ©n</b></sub></a><br /><a href="https://github.com/nicholas-fedor/shoutrrr/commits?author=piksel" title="Code">πŸ’»</a> <a href="https://github.com/nicholas-fedor/shoutrrr/commits?author=piksel" title="Documentation">πŸ“–</a> <a href="#maintenance-piksel" title="Maintenance">🚧</a></td>
258 <td align="center" valign="top" width="14.28%"><a href="https://github.com/lukapeschke"><img src="https://avatars1.githubusercontent.com/u/17085536?v=4?s=100" width="100px;" alt="Luka Peschke"/><br /><sub><b>Luka Peschke</b></sub></a><br /><a href="https://github.com/nicholas-fedor/shoutrrr/commits?author=lukapeschke" title="Code">πŸ’»</a> <a href="https://github.com/nicholas-fedor/shoutrrr/commits?author=lukapeschke" title="Documentation">πŸ“–</a></td>
259 <td align="center" valign="top" width="14.28%"><a href="https://github.com/MrLuje"><img src="https://avatars0.githubusercontent.com/u/632075?v=4?s=100" width="100px;" alt="MrLuje"/><br /><sub><b>MrLuje</b></sub></a><br /><a href="https://github.com/nicholas-fedor/shoutrrr/commits?author=MrLuje" title="Code">πŸ’»</a> <a href="https://github.com/nicholas-fedor/shoutrrr/commits?author=MrLuje" title="Documentation">πŸ“–</a></td>
260 <td align="center" valign="top" width="14.28%"><a href="http://simme.dev"><img src="https://avatars0.githubusercontent.com/u/1596025?v=4?s=100" width="100px;" alt="Simon Aronsson"/><br /><sub><b>Simon Aronsson</b></sub></a><br /><a href="https://github.com/nicholas-fedor/shoutrrr/commits?author=simskij" title="Code">πŸ’»</a> <a href="https://github.com/nicholas-fedor/shoutrrr/commits?author=simskij" title="Documentation">πŸ“–</a> <a href="#maintenance-simskij" title="Maintenance">🚧</a></td>
261 <td align="center" valign="top" width="14.28%"><a href="https://arnested.dk"><img src="https://avatars2.githubusercontent.com/u/190005?v=4?s=100" width="100px;" alt="Arne JΓΈrgensen"/><br /><sub><b>Arne JΓΈrgensen</b></sub></a><br /><a href="https://github.com/nicholas-fedor/shoutrrr/commits?author=arnested" title="Documentation">πŸ“–</a> <a href="https://github.com/nicholas-fedor/shoutrrr/commits?author=arnested" title="Code">πŸ’»</a></td>
262 </tr>
263 <tr>
264 <td align="center" valign="top" width="14.28%"><a href="https://github.com/atighineanu"><img src="https://avatars1.githubusercontent.com/u/27206712?v=4?s=100" width="100px;" alt="Alexei Tighineanu"/><br /><sub><b>Alexei Tighineanu</b></sub></a><br /><a href="https://github.com/nicholas-fedor/shoutrrr/commits?author=atighineanu" title="Code">πŸ’»</a></td>
265 <td align="center" valign="top" width="14.28%"><a href="https://github.com/ellisab"><img src="https://avatars2.githubusercontent.com/u/1402047?v=4?s=100" width="100px;" alt="Alexandru Bonini"/><br /><sub><b>Alexandru Bonini</b></sub></a><br /><a href="https://github.com/nicholas-fedor/shoutrrr/commits?author=ellisab" title="Code">πŸ’»</a></td>
266 <td align="center" valign="top" width="14.28%"><a href="https://senan.xyz"><img src="https://avatars0.githubusercontent.com/u/6832539?v=4?s=100" width="100px;" alt="Senan Kelly"/><br /><sub><b>Senan Kelly</b></sub></a><br /><a href="https://github.com/nicholas-fedor/shoutrrr/commits?author=sentriz" title="Code">πŸ’»</a></td>
267 <td align="center" valign="top" width="14.28%"><a href="https://github.com/JonasPf"><img src="https://avatars.githubusercontent.com/u/2216775?v=4?s=100" width="100px;" alt="JonasPf"/><br /><sub><b>JonasPf</b></sub></a><br /><a href="https://github.com/nicholas-fedor/shoutrrr/commits?author=JonasPf" title="Code">πŸ’»</a></td>
268 <td align="center" valign="top" width="14.28%"><a href="https://github.com/claycooper"><img src="https://avatars.githubusercontent.com/u/3612906?v=4?s=100" width="100px;" alt="claycooper"/><br /><sub><b>claycooper</b></sub></a><br /><a href="https://github.com/nicholas-fedor/shoutrrr/commits?author=claycooper" title="Documentation">πŸ“–</a></td>
269 <td align="center" valign="top" width="14.28%"><a href="http://ko-fi.com/disyer"><img src="https://avatars.githubusercontent.com/u/16326697?v=4?s=100" width="100px;" alt="Derzsi DΓ‘niel"/><br /><sub><b>Derzsi DΓ‘niel</b></sub></a><br /><a href="https://github.com/nicholas-fedor/shoutrrr/commits?author=darktohka" title="Code">πŸ’»</a></td>
270 <td align="center" valign="top" width="14.28%"><a href="https://josephkav.io"><img src="https://avatars.githubusercontent.com/u/4267227?v=4?s=100" width="100px;" alt="Joseph Kavanagh"/><br /><sub><b>Joseph Kavanagh</b></sub></a><br /><a href="https://github.com/nicholas-fedor/shoutrrr/commits?author=JosephKav" title="Code">πŸ’»</a> <a href="https://github.com/nicholas-fedor/shoutrrr/issues?q=author%3AJosephKav" title="Bug reports">πŸ›</a></td>
271 </tr>
272 <tr>
273 <td align="center" valign="top" width="14.28%"><a href="https://ring0.lol"><img src="https://avatars.githubusercontent.com/u/1893909?v=4?s=100" width="100px;" alt="Justin Steven"/><br /><sub><b>Justin Steven</b></sub></a><br /><a href="https://github.com/nicholas-fedor/shoutrrr/issues?q=author%3Ajustinsteven" title="Bug reports">πŸ›</a></td>
274 <td align="center" valign="top" width="14.28%"><a href="https://github.com/serverleader"><img src="https://avatars.githubusercontent.com/u/34089?v=4?s=100" width="100px;" alt="Carlos Savcic"/><br /><sub><b>Carlos Savcic</b></sub></a><br /><a href="https://github.com/nicholas-fedor/shoutrrr/commits?author=serverleader" title="Code">πŸ’»</a> <a href="https://github.com/nicholas-fedor/shoutrrr/commits?author=serverleader" title="Documentation">πŸ“–</a></td>
275 <td align="center" valign="top" width="14.28%"><a href="https://github.com/PythonGermany"><img src="https://avatars.githubusercontent.com/u/97847597?v=4?s=100" width="100px;" alt="PythonGermany"/><br /><sub><b>PythonGermany</b></sub></a><br /><a href="https://github.com/nicholas-fedor/shoutrrr/commits?author=PythonGermany" title="Code">πŸ’»</a></td>
276 <td align="center" valign="top" width="14.28%"><a href="https://github.com/noelob"><img src="https://avatars.githubusercontent.com/u/643338?v=4?s=100" width="100px;" alt="Noel O'Brien"/><br /><sub><b>Noel O'Brien</b></sub></a><br /><a href="https://github.com/nicholas-fedor/shoutrrr/commits?author=noelob" title="Code">πŸ’»</a> <a href="https://github.com/nicholas-fedor/shoutrrr/commits?author=noelob" title="Documentation">πŸ“–</a></td>
277 <td align="center" valign="top" width="14.28%"><a href="https://caleblemoine.dev"><img src="https://avatars.githubusercontent.com/u/21261388?v=4?s=100" width="100px;" alt="Caleb Lemoine"/><br /><sub><b>Caleb Lemoine</b></sub></a><br /><a href="https://github.com/nicholas-fedor/shoutrrr/commits?author=circa10a" title="Code">πŸ’»</a> <a href="https://github.com/nicholas-fedor/shoutrrr/commits?author=circa10a" title="Documentation">πŸ“–</a></td>
278 <td align="center" valign="top" width="14.28%"><a href="http://hieddie.org"><img src="https://avatars.githubusercontent.com/u/205121303?v=4?s=100" width="100px;" alt="Eddie 'Sergeant' M"/><br /><sub><b>Eddie 'Sergeant' M</b></sub></a><br /><a href="https://github.com/nicholas-fedor/shoutrrr/commits?author=sgtM-devs" title="Documentation">πŸ“–</a></td>
279 </tr>
280 </tbody>
281 </table>
282
283 <!-- markdownlint-restore -->
284 <!-- prettier-ignore-end -->
285
286 <!-- ALL-CONTRIBUTORS-LIST:END -->
287 <!-- markdownlint-restore -->
288
289 This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
290
291 ## Related Project(s)
292
293 - [Watchtower](https://github.com/nicholas-fedor/watchtower) - Automate Docker container image updates.
294 - [Shoutrrr GitHub Action](https://github.com/nicholas-fedor/shoutrrr-action) - Notifications using Shoutrrr in GitHub Actions.
295 - [Bezel](https://github.com/henrygd/beszel) - A lightweight server monitoring platform that includes Docker statistics, historical data, and alert functions.
296 - [WatchYourLAN](https://github.com/aceberg/WatchYourLAN) - Lightweight network IP scanner with web GUI.
297 - [DNSControl](https://github.com/StackExchange/dnscontrol)- Infrastructure as code for DNS.
298 - [docker-volume-backup](https://github.com/offen/docker-volume-backup) - Backup Docker volumes locally or to any S3, WebDAV, Azure Blob Storage, Dropbox, Google Drive or SSH compatible storage.
299 - [BirdNET-Go](https://github.com/tphakala/birdnet-go) - An AI solution for continuous avian monitoring and identification.