SPOOK: spooky action at a distance!

A simple command line tool to trigger a command and/or an http server-sent event when files or directories change.

It is well-suited to the live generation and autoreload of HTML documents generated by command-line document processors such as Pandoc, Asciidoctor & friends.

Think of it as a super-minimalistic version of Watchman with server events signalling on top, or as a super-stripped-down version of LiveReload with a simple, standard signaling protocol.

Example use

In the simplest case, spook takes as arguments the files to be watched and the command to be triggered (with its own arguments, if any).

The following would for instance re-generate an html document with Pandoc each time the input files mydoc1.md or mydoc2.md change:

$ spook mydoc1.md mydoc2.md -- pandoc -o mydoc.html mydoc1.md mydoc2.md

The browser can also refresh HTML pages automatically by embedding a small javascript snippet (see the scripts directory) in the HTML and by enabling server-sent events with the --signal option, like so:

$ spook --signal mydoc1.md mydoc2.md -- pandoc -A spook_refresh_script.html -o mydoc.html mydoc1.md mydoc2.md

Autoreload works both with files opened directly in the browser and with files served by a local server (e.g. Python's SimpleHTTPServer).

More options

A handful of other options can be specified, e.g. to serve events from a different port, perform a preemptive trigger at launch, etc...

To see all available options, type:

$ spook --help

Platforms

This software is most definitely of the no-warranty, provided-as-is, mainly-tested-on-my-linux-box kind. But it should work on Linux/Mac/Windows, and with some luck on a couple of other OSes.

Server-sent events should be supported out-of-the-box on nearly all modern browsers.

Installation

The rust toolchain must be installed on your system. No panic, installing rust is a smooth ride: just let rustup guide you.

Once this is done, install spook with cargo:

$ cargo install spook

That's it.

License

This software is licensed under the Apache License, Version 2.0 or the MIT license, at your option.

Copyright (c) 2022 Serge Barral.