156 lines
3.9 KiB
Markdown
156 lines
3.9 KiB
Markdown
# 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 }}.
|
|
```
|