@@ 2,3 2,41 @@ shoved
======
*When push comes to shove... it spawns a process.*
+
+`shoved` is a push notification daemon for Linux systems using the
+[Web Push API](https://developer.mozilla.org/en-US/docs/Web/API/Push_API) and the
+[Mozilla Push Service](https://mozilla-push-service.readthedocs.io/en/latest/).
+These notifications are encrypted by the source and decrypted locally, so the push
+service cannot read their content.
+
+## How to Use
+This repository includes source code for two executables: `shoved` and `shoved-register`.
+`shoved` must be running to receive push notifications and register new handlers.
+It is recommended to set this up to automatically start on login, for example in your
+desktop environment or as a systemd user service. (a system-wide mode is also supported
+but personally I've had trouble getting desktop notifications to show with that setup)
+
+To set up a service for push notifications, you probably want one of these:
+- [shoved-matrix](https://git.sr.ht/~vpzom/shoved-matrix) - for notifications from Matrix
+
+If you want to write your own handler, see the following section.
+
+## Handler Interface
+To register a new handler, run the `shoved-register` command with the filepath of your
+handler executable. If successful, the command will print a JSON object with subscription
+information in this structure:
+
+```
+{
+ "endpoint": "https://updates.push.services.mozilla.com/wpush/v1/SOMETHING_GOES_HERE",
+ "keys": {
+ "auth": "SomethingGoesHere",
+ "p256dh": "SomethingMuchLongerGoesHere"
+ }
+}
+```
+
+These values should then be sent to the service so it can begin sending pushes.
+
+When a push is received, `shoved` will run the specified handler executable and pass
+the contents of the received message as stdin.