📟 run scripts on ntfy.sh events
Go to file
sophie d081387fc8 bump 2022-09-22 11:41:07 +01:00
bin implement prototype 2022-07-31 03:03:30 +01:00
docs update demo gif 2022-08-11 16:59:10 +01:00
.gitignore Initial commit 2022-07-31 02:20:30 +01:00
LICENSE Initial commit 2022-07-31 02:20:30 +01:00
README.md change git clone link to codeberg 2022-09-22 12:19:28 +02:00
conf.json bump version 2022-07-31 22:44:08 +01:00
index.js implement security 2022-08-11 16:46:47 +01:00
package-lock.json add usage and installation instructions to the readme 2022-07-31 23:31:57 +01:00
package.json bump 2022-09-22 11:41:07 +01:00



run scripts on ntfy.sh events


ntfy.sh.sh requires node.js (unfortunately) so you need to have that installed

from npm

$ npm i -g ntfy.sh.sh

from source

$ git clone https://codeberg.org/zvava/ntfy.sh.sh.git

$ cd ntfy.sh.sh

$ npm i # install dependencies

$ npm i -g # add to path


to use, run the command ntfyshsh (no periods!!) in the terminal, some useful arguments;

-h or --help will list all possible arguments as well as the location of the configuration file

-l or --list lists all of the topics and tasks with their respective ids in the configuration file

-s or --send takes a topic name/id and a task name/id argument, then sends that task to the topic

not specifying any argument will start ntfy.sh.sh and listen for tasks on all topics in the configuration file


configuration is stored in the conf.json file in the package directory. it contains an array of topic objects;

{ // a topic object
	"host": "ntfy.sh" // optional, hostname or ip of a ntfy.sh instance
	"http": false,    // optional, if true use http instead of https
	"topic": "computer-alerts", // required, topic to subscribe to
	"key": "password", // optional, used to add entropy to the event token

	// tasks to perform in the format of <task name> to <array of commands>
	// the following are examples for windows commandline, but ntfy.sh.sh runs anywhere node.js does
	"tasks": {
		// opening an application
		"open file manager": [ "start explorer ." ],
		// run command with output to stdout
		"run test": [ "echo hi" ],
		// run a script in a new window
		"run script": ["start cmd /C \"bin\\script.bat\""],
		// execute multiple commands
		"enter hacker mode": [ "start cmd /C \"color 0a && tree C:", "start cmd /C \"color 0a && tree C:" ],


when ntfy.sh.sh dispatches an event, it uses a token as the message (eg. 6057429153136659). when ntfy.sh.sh receives an event it generates tokens locally and compares them to the one in the event, if one matches the task specified by the token will be ran.

as ntfy.sh is unauthenticated by default, the keys you set in the configuration can help you to somewhat better protect you on public ntfy.sh instances. if a key is not set it is treated as if it were an empty string. the generated token is simply a random integer seeded with the current unix timestamp with 20 seconds of percision combined with the task and key

n.b. if anyone other then you has access to the stream, they can repeat the task you just called for up to 20 seconds, the only guaranteeably secure method to use ntfy.sh.sh is to use a self-hosted ntfy.sh instance with access control (todo: allow ntfy.sh.sh to send/receive authenticated events)