1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
|
# Getting started
## As a package
Using shoutrrr is easy! There is currently two ways of using it as a package.
### Using the direct send command
Easiest to use, but very limited.
```go
url := "slack://token-a/token-b/token-c"
err := shoutrrr.Send(url, "Hello world (or slack channel) !")
```
### Using a sender
Using a sender gives you the ability to preconfigure multiple notification services and send to all of them with the same `Send(message, params)` method.
```go
urlA := "slack://token-a/token-b/token-c"
urlB := "telegram://110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw@telegram?channels=@mychannel"
sender, err := shoutrrr.CreateSender(urlA, urlB)
// Send notifications instantly to all services
sender.Send("Hello world (or slack/telegram channel)!", map[string]string { "title": "He-hey~!" })
// ...or bundle notifications...
func doWork() error {
// ...and send them when leaving the scope
defer sender.Flush(map[string]string { "title": "Work Result" })
sender.Enqueue("Started doing %v", stuff)
// Maybe get creative...?
defer func(start time.Time) {
sender.Enqueue("Elapsed: %v", time.Now().Sub(start))
}(time.Now())
if err := doMoreWork(); err != nil {
sender.Enqueue("Oh no! %v", err)
// This will send the currently queued up messages...
return
}
sender.Enqueue("Everything went very well!")
// ...or this:
}
```
## Through the CLI
Start by running the `build.sh` script.
You may then run the shoutrrr executable:
```shell
$ ./shoutrrr
Usage:
./shoutrrr <ActionVerb> [...]
Possible actions: send, verify, generate
```
On a system with Go installed you can install the latest Shoutrrr CLI
command with:
```shell
go install github.com/nicholas-fedor/shoutrrr/shoutrrr@latest
```
### Commands
#### Send
Send a notification using the supplied notification service url.
```bash
$ shoutrrr send \
--url "<SERVICE_URL>" \
--message "<MESSAGE BODY>"
```
#### Verify
Verify the validity of a notification service url.
```bash
$ shoutrrr verify \
--url "<SERVICE_URL>"
```
#### Generate
Generate and display the configuration for a notification service url.
```bash
$ shoutrrr generate [OPTIONS] <SERVICE>
```
| Flags | Description |
| ---------------------------- | ------------------------------------------------|
| `-g, --generator string` | The generator to use (default "basic") |
| `-p, --property stringArray` | Configuration property in key=value format |
| `-s, --service string` | The notification service to generate a URL for |
**Note**: Service can either be supplied as the first argument or using the `-s` flag.
For more information on generators, see [Generators](./generators/overview.md).
### Options
#### Debug
Enables debug output from the CLI.
| Flags | Env. | Default | Required |
| --------------- | ---------------- | ------- | -------- |
| `--debug`, `-d` | `SHOUTRRR_DEBUG` | `false` | |
#### URL
The target url for the notifications generated, see [overview](./services/overview).
| Flags | Env. | Default | Required |
| ------------- | -------------- | ------- | -------- |
| `--url`, `-u` | `SHOUTRRR_URL` | N/A | ✅ |
## From a GitHub Actions workflow
You can also use Shoutrrr from a GitHub Actions workflow.
See this example and the [action on GitHub
Marketplace](https://github.com/marketplace/actions/shoutrrr-action):
```yaml
name: Deploy
on:
push:
branches:
- main
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Some other steps needed for deploying
run: ...
- name: Shoutrrr
uses: nicholas-fedor/shoutrrr-action@v1
with:
url: ${{ secrets.SHOUTRRR_URL }}
title: Deployed ${{ github.sha }}
message: See changes at ${{ github.event.compare }}.
```
|
