diff --git a/client/config.go b/client/config.go index 1b43fa1..76fcc1f 100644 --- a/client/config.go +++ b/client/config.go @@ -11,6 +11,7 @@ type Config struct { Subscribe []struct { Topic string Command string + // If []map[string]string TODO This would be cool } } diff --git a/docs/static/img/cli-subscribe-video-1.mp4 b/docs/static/img/cli-subscribe-video-1.mp4 new file mode 100644 index 0000000..f7cab25 Binary files /dev/null and b/docs/static/img/cli-subscribe-video-1.mp4 differ diff --git a/docs/static/img/cli-subscribe-video-2.webm b/docs/static/img/cli-subscribe-video-2.webm new file mode 100644 index 0000000..e885dab Binary files /dev/null and b/docs/static/img/cli-subscribe-video-2.webm differ diff --git a/docs/subscribe/cli.md b/docs/subscribe/cli.md index fc64aa4..334611f 100644 --- a/docs/subscribe/cli.md +++ b/docs/subscribe/cli.md @@ -23,7 +23,7 @@ you may want to edit the `default-host` option: default-host: https://ntfy.myhost.com ``` -## Sending messages +## Publish using the ntfy CLI You can send messages with the ntfy CLI using the `ntfy publish` command (or any of its aliases `pub`, `send` or `trigger`). There are a lot of examples on the page about [publishing messages](../publish.md), but here are a few quick ones: @@ -45,13 +45,76 @@ quick ones: "Somebody just bought the thing that you sell" ``` +=== "Send at 8:30am" + ``` + ntfy pub --at=8:30am delayed_topic Laterzz + ``` + === "Triggering a webhook" ``` ntfy trigger mywebhook ntfy pub mywebhook ``` -## Using the systemd service +## Subscribe using the ntfy CLI +You can subscribe to topics using `ntfy subscribe`. Depending on how it is called, this command +will either print or execute a command for every arriving message. There are a few different ways +in which the command can be run: + +### Stream messages and print JSON +If run like this `ntfy subscribe TOPIC`, the command prints the JSON representation of every incoming +message. This is useful when you have a command that wants to stream-read incoming JSON messages. +Unless `--poll` is passed, this command stays open forever. + +``` +$ ntfy sub mytopic +{"id":"nZ8PjH5oox","time":1639971913,"event":"message","topic":"mytopic","message":"hi there"} +{"id":"sekSLWTujn","time":1639972063,"event":"message","topic":"mytopic","tags":["warning","skull"],"message":"Oh no, something went wrong"} +``` + +
+ +
Subscribe in JSON mode
+
+ +### Execute a command for every incoming message +If run like this `ntfy subscribe TOPIC COMMAND`, a COMMAND is executed for every incoming messages. +The message fields are passed to the command as environment variables and can be used in scripts: + +
+ +
Execute command on incoming messages
+
+ +| Variable | Aliases | Description | +|---|---|--- +| `$NTFY_ID` | `$id` | Unique message ID | +| `$NTFY_TIME` | `$time` | Unix timestamp of the message delivery | +| `$NTFY_TOPIC` | `$topic` | Topic name | +| `$NTFY_MESSAGE` | `$message`, `$m` | Message body | +| `$NTFY_TITLE` | `$title`, `$t` | Message title | +| `$NTFY_PRIORITY` | `$priority`, `$p` | Message priority (1=min, 5=max) | +| `$NTFY_TAGS` | `$tags`, `$ta` | Message tags (comma separated list) | + + Examples: + ntfy sub mytopic 'notify-send "$m"' # Execute command for incoming messages + ntfy sub topic1 /my/script.sh # Execute script for incoming messages + +### Using a config file +ntfy subscribe --from-config +Service mode (used in ntfy-client.service). This reads the config file (/etc/ntfy/client.yml +or ~/.config/ntfy/client.yml) and sets up subscriptions for every topic in the "subscribe:" +block (see config file). + + Examples: + ntfy sub --from-config # Read topics from config file + ntfy sub --config=/my/client.yml --from-config # Read topics from alternate config file + +The default config file for all client commands is /etc/ntfy/client.yml (if root user), +or ~/.config/ntfy/client.yml for all other users. + + +### Using the systemd service ``` [Service]