vbatts/ntfy
1
0
Fork 0
Code Pull requests Activity

Docs

Browse source
This commit is contained in:
Philipp Heckel 2021-12-17 22:38:29 -05:00
parent a1f513f6a5
commit 5639cf7a0f
7 changed files with 105 additions and 17 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
cmd/publish.go
View file

@ -9,7 +9,7 @@ import (
var cmdPublish = &cli.Command{
Name: "publish",
Aliases: []string{"pub", "send", "push"},
Aliases: []string{"pub", "send", "push", "trigger"},
Usage: "Send message via a ntfy server",
UsageText: "ntfy send [OPTIONS..] TOPIC MESSAGE",
Action: execPublish,
@ -30,14 +30,15 @@ Examples:
ntfy pub --tags=warning,skull backups "Backups failed" # Add tags/emojis to message
ntfy pub --delay=10s delayed_topic Laterzz # Delay message by 10s
ntfy pub --at=8:30am delayed_topic Laterzz # Send message at 8:30am
ntfy trigger mywebhook # Sending without message, useful for webhooks
Please also check out the docs on publishing messages. Especially for the --tags and --delay options,
it has incredibly useful information: https://ntfy.sh/docs/publish/.`,
}
func execPublish(c *cli.Context) error {
if c.NArg() < 2 {
return errors.New("topic/message missing")
if c.NArg() < 1 {
return errors.New("topic missing")
}
title := c.String("title")
priority := c.String("priority")
@ -46,7 +47,10 @@ func execPublish(c *cli.Context) error {
noCache := c.Bool("no-cache")
noFirebase := c.Bool("no-firebase")
topicURL := expandTopicURL(c.Args().Get(0))
message := strings.Join(c.Args().Slice()[1:], " ")
message := ""
if c.NArg() > 1 {
message = strings.Join(c.Args().Slice()[1:], " ")
}
var options []client.PublishOption
if title != "" {
options = append(options, client.WithTitle(title))

2
cmd/subscribe.go
View file

@ -56,7 +56,7 @@ func execSubscribe(c *cli.Context) error {
if c.NArg() < 1 {
return errors.New("topic missing")
}
log.Printf("\x1b[1;33mThis command is incubating. The interface may change without notice.\x1b[0m")
fmt.Fprintln(c.App.ErrWriter, "\x1b[1;33mThis command is incubating. The interface may change without notice.\x1b[0m")
cl := client.DefaultClient
command := c.String("exec")
since := c.String("since")

4
docs/config.md
View file

@ -4,10 +4,10 @@ see [config.yml](https://github.com/binwiederhier/ntfy/blob/main/config/config.y
or using environment variables.
## Quick start
By default, simply running `ntfy` will start the server at port 80. No configuration needed. Batteries included 😀.
By default, simply running `ntfy serve` will start the server at port 80. No configuration needed. Batteries included 😀.
If everything works as it should, you'll see something like this:
```
$ ntfy
$ ntfy serve
2021/11/30 19:59:08 Listening on :80
```

10
docs/index.md
View file

@ -22,14 +22,20 @@ For this guide, we'll just use `mytopic` as our topic name:
That's it. After you tap "Subscribe", the app is listening for new messages on that topic.
## Step 2: Send a message
Now let's [send a message](publish.md) to our topic. It's easy in every language, since we're just using HTTP PUT or POST. The message
is in the request body. Here's an example showing how to publish a simple message using a POST request:
Now let's [send a message](publish.md) to our topic. It's easy in every language, since we're just using HTTP PUT/POST,
or with the [ntfy CLI](install.md). The message is in the request body. Here's an example showing how to publish a
simple message using a POST request:
=== "Command line (curl)"
```
curl -d "Backup successful 😀" ntfy.sh/mytopic
```
=== "ntfy CLI"
```
ntfy publish mytopic "Backup successful 😀"
```
=== "HTTP"
``` http
POST /mytopic HTTP/1.1

15
docs/install.md
View file

@ -1,10 +1,12 @@
# Install your own ntfy server
**Self-hosting your own ntfy server** is pretty straight forward. Just install the binary, package or Docker image, then
# Installing ntfy
The `ntfy` CLI allows you to [publish messages](publish.md), [subscribe to topics](subscribe/cli.md) as well as to
**self-host your own ntfy server**. It's all pretty straight forward. Just install the binary, package or Docker image,
configure it and run it. Just like any other software. No fuzz.
!!! info
The following steps are only required if you want to **self-host your own ntfy server**. If you just want to
[send messages using ntfy.sh](publish.md), you don't need to install anything.
The following steps are only required if you want to **self-host your own ntfy server** or you want to use the ntfy CLI.
If you just want to [send messages using ntfy.sh](publish.md), you don't need to install anything. You can just use
`curl`.
## General steps
The ntfy server comes as a statically linked binary and is shipped as tarball, deb/rpm packages and as a Docker image.
@ -12,7 +14,10 @@ We support amd64, armv7 and arm64.
1. Install ntfy using one of the methods described below
2. Then (optionally) edit `/etc/ntfy/config.yml` (see [configuration](config.md))
3. Then just run it with `ntfy serve` (or `systemctl start ntfy` when using the deb/rpm).
To run the ntfy server, then just run `ntfy serve` (or `systemctl start ntfy` when using the deb/rpm).
To send messages, use `ntfy publish`. To subscribe to topics, use `ntfy subscribe` (see [subscribing via CLI][subscribe/cli.md]
for details).
## Binaries and packages
Please check out the [releases page](https://github.com/binwiederhier/ntfy/releases) for binaries and

74
docs/publish.md
View file

@ -1,6 +1,7 @@
# Publishing
Publishing messages can be done via HTTP PUT or POST. Topics are created on the fly by subscribing or publishing to them.
Because there is no sign-up, **the topic is essentially a password**, so pick something that's not easily guessable.
Publishing messages can be done via HTTP PUT/POST or via the [ntfy CLI](install.md). Topics are created on the fly by
subscribing or publishing to them. Because there is no sign-up, **the topic is essentially a password**, so pick
something that's not easily guessable.
Here's an example showing how to publish a simple message using a POST request:
@ -9,6 +10,11 @@ Here's an example showing how to publish a simple message using a POST request:
curl -d "Backup successful 😀" ntfy.sh/mytopic
```
=== "ntfy CLI"
```
ntfy publish mytopic "Backup successful 😀"
```
=== "HTTP"
``` http
POST /mytopic HTTP/1.1
@ -67,6 +73,16 @@ a [title](#message-title), and [tag messages](#tags-emojis) 🥳 🎉. Here's an
ntfy.sh/phil_alerts
```
=== "ntfy CLI"
```
ntfy publish \
--title "Unauthorized access detected" \
--tags warning,skull \
--priority urgent \
mytopic \
"Remote access to phils-laptop detected. Act right away."
```
=== "HTTP"
``` http
POST /phil_alerts HTTP/1.1
@ -143,6 +159,13 @@ you can set the `X-Title` header (or any of its aliases: `Title`, `ti`, or `t`).
curl -H "t: Dogs are better than cats" -d "Oh my ..." ntfy.sh/controversial
```
=== "ntfy CLI"
```
ntfy publish \
-t "Dogs are better than cats" \
controversial "Oh my ..."
```
=== "HTTP"
``` http
POST /controversial HTTP/1.1
@ -216,6 +239,13 @@ You can set the priority with the header `X-Priority` (or any of its aliases: `P
curl -H p:4 -d "A high priority message" ntfy.sh/phil_alerts
```
=== "ntfy CLI"
```
ntfy publish \
-p 5 \
phil_alerts An urgent message
```
=== "HTTP"
``` http
POST /phil_alerts HTTP/1.1
@ -320,6 +350,13 @@ them with a comma, e.g. `tag1,tag2,tag3`.
curl -H ta:dog -d "Dogs are awesome" ntfy.sh/backups
```
=== "ntfy CLI"
```
ntfy publish \
--tags=warning,mailsrv13,daily-backup \
backups "Backup of mailsrv13 failed"
```
=== "HTTP"
``` http
POST /backups HTTP/1.1
@ -395,6 +432,13 @@ to be delivered in 3 days, it'll remain in the cache for 3 days and 12 hours. Al
curl -H "Delay: 1639194738" -d "Unix timestamps are awesome" ntfy.sh/itsaunixsystem
```
=== "ntfy CLI"
```
ntfy publish \
--at="tomorrow, 10am" \
hello "Good morning"
```
=== "HTTP"
``` http
POST /hello HTTP/1.1
@ -473,6 +517,11 @@ For instance, assuming your topic is `mywebhook`, you can simply call `/mywebhoo
curl ntfy.sh/mywebhook/trigger
```
=== "ntfy CLI"
```
ntfy trigger mywebhook
```
=== "HTTP"
``` http
GET /mywebhook/trigger HTTP/1.1
@ -510,6 +559,13 @@ Here's an example with a custom message, tags and a priority:
curl "ntfy.sh/mywebhook/publish?message=Webhook+triggered&priority=high&tags=warning,skull"
```
=== "ntfy CLI"
```
ntfy publish \
-p 5 --tags=warning,skull \
mywebhook "Webhook triggered"
```
=== "HTTP"
``` http
GET /mywebhook/publish?message=Webhook+triggered&priority=high&tags=warning,skull HTTP/1.1
@ -559,6 +615,13 @@ are still delivered to connected subscribers, but [`since=`](subscribe/api.md#fe
curl -H "Cache: no" -d "This message won't be stored server-side" ntfy.sh/mytopic
```
=== "ntfy CLI"
```
ntfy publish \
--no-cache \
mytopic "This message won't be stored server-side"
```
=== "HTTP"
``` http
POST /mytopic HTTP/1.1
@ -624,6 +687,13 @@ to `no`. This will instruct the server not to forward messages to Firebase.
curl -H "Firebase: no" -d "This message won't be forwarded to FCM" ntfy.sh/mytopic
```
=== "ntfy CLI"
```
ntfy publish \
--no-firebase \
mytopic "This message won't be forwarded to FCM"
```
=== "HTTP"
``` http
POST /mytopic HTTP/1.1

5
docs/subscribe/cli.md
View file

@ -1,3 +1,6 @@
# Subscribe via CLI
XXXXXXXXXxxx
!!! info
The `ntfy subscribe` command is incubating. It's very much work in progress.
(This page is a stub. I'll write something once I'm happy with what the command looks like.)