From 5639cf7a0f8247eb1d668e214fe3919ebb686a3f Mon Sep 17 00:00:00 2001 From: Philipp Heckel Date: Fri, 17 Dec 2021 22:38:29 -0500 Subject: [PATCH] Docs --- cmd/publish.go | 12 ++++--- cmd/subscribe.go | 2 +- docs/config.md | 4 +-- docs/index.md | 10 ++++-- docs/install.md | 15 ++++++--- docs/publish.md | 74 +++++++++++++++++++++++++++++++++++++++++-- docs/subscribe/cli.md | 5 ++- 7 files changed, 105 insertions(+), 17 deletions(-) diff --git a/cmd/publish.go b/cmd/publish.go index 3db8146c..5211bb65 100644 --- a/cmd/publish.go +++ b/cmd/publish.go @@ -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)) diff --git a/cmd/subscribe.go b/cmd/subscribe.go index b2d2fc6e..10846e1a 100644 --- a/cmd/subscribe.go +++ b/cmd/subscribe.go @@ -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") diff --git a/docs/config.md b/docs/config.md index 57625622..4f83e96c 100644 --- a/docs/config.md +++ b/docs/config.md @@ -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 ``` diff --git a/docs/index.md b/docs/index.md index c8c85501..4213e254 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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 diff --git a/docs/install.md b/docs/install.md index c9ee08ef..4f3eea13 100644 --- a/docs/install.md +++ b/docs/install.md @@ -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 diff --git a/docs/publish.md b/docs/publish.md index 77b3c514..c7d01dec 100644 --- a/docs/publish.md +++ b/docs/publish.md @@ -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 diff --git a/docs/subscribe/cli.md b/docs/subscribe/cli.md index 3e578a8f..9f492b95 100644 --- a/docs/subscribe/cli.md +++ b/docs/subscribe/cli.md @@ -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.)