Writing qutebrowser userscripts
===============================
The Compiler <mail@qutebrowser.org>

qutebrowser is extensible by writing userscripts which can be called via the
`:spawn --userscript` command, or via a key binding.

You can also call a userscript via hints so they get the selected hint URL by
calling `:hint links userscript ...`.

These userscripts are similar to the (non-javascript) dwb userscripts. They can
be written in any language which can read environment variables and write to a
FIFO. Note they are *not* related to Greasemonkey userscripts.

Note for simple things such as opening the current page with another browser or
mpv, a simple key binding to something like `:spawn mpv {url}` should suffice.

Also note userscripts need to have the executable bit set (`chmod +x`) for
qutebrowser to run them.

To call a userscript, it needs to be stored in your config or data directory under
`userscripts` (for example: `~/.local/share/qutebrowser/userscripts/myscript`),
or just use an absolute path.

NOTE: On Windows, only userscripts with `com`, `bat`, or `exe` extensions will
be launched. As an additional resource, see
https://www.ii.com/qutebrowser-userscripts-on-windows/[Infinite Ink:
qutebrowser Userscripts on Windows].

Getting information
-------------------

The following environment variables will be set when a userscript is launched:

- `QUTE_MODE`: Either `hints` (started via hints) or `command` (started via
  command or key binding).
- `QUTE_USER_AGENT`: The currently set user agent, if customized.
- `QUTE_FIFO`: The FIFO or file to write commands to.
- `QUTE_HTML`: Path of a file containing the HTML source of the current page.
- `QUTE_TEXT`: Path of a file containing the plaintext of the current page.
- `QUTE_CONFIG_DIR`: Path of the directory containing qutebrowser's configuration.
- `QUTE_DATA_DIR`: Path of the directory containing qutebrowser's data.
- `QUTE_DOWNLOAD_DIR`: Path of the downloads directory.
- `QUTE_COMMANDLINE_TEXT`: Text currently in qutebrowser's command line. Note
  this is only useful for userscripts spawned (e.g. via a keybinding) when
  qutebrowser is still in command mode. If you want to receive arguments passed
  to your userscript via `:spawn`, use the normal way of getting commandline
  arguments (e.g. `$@` in bash or `sys.argv` / `argparse` / ... in Python).
- `QUTE_VERSION`: The version of qutebrowser, as a string like "2.0.0". Note that this
  was added in v2.0.0, thus older versions can only be detected by the absence of this
  variable.

In `command` mode:

- `QUTE_URL`: The current page URL.
- `QUTE_TITLE`: The title of the current page.
- `QUTE_SELECTED_TEXT`: The text currently selected on the page.
- `QUTE_COUNT`: The `count` from the spawn command running the userscript.

In `hints` mode:

- `QUTE_URL`: The URL selected via hints.
- `QUTE_CURRENT_URL`: The current page URL.
- `QUTE_SELECTED_TEXT`: The plain text of the element selected via hints.
- `QUTE_SELECTED_HTML`: The HTML of the element selected via hints.

Sending commands
----------------

Normal qutebrowser commands can be written to `$QUTE_FIFO` and will be
executed.

On Unix/macOS, this is a named pipe and commands written to it will get executed
immediately.

On Windows, this is a regular file, and the commands in it will be executed as
soon as your userscript terminates. This means when writing multiple commands,
you should append to the file (`>>` in bash) rather than overwrite it (`>`).

Examples
--------

Opening the currently selected word on https://www.dict.cc/[dict.cc]:

[source,bash]
----
#!/bin/bash

echo "open -t https://www.dict.cc/?s=$QUTE_SELECTED_TEXT" >> "$QUTE_FIFO"
----

Libraries
---------

Some third-party libraries are available to make writing userscripts easier:

- Python: https://github.com/hiway/python-qutescript[python-qutescript]
- Node.js: https://www.npmjs.com/package/qutejs[qutejs]