# 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 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.

## 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.

In `command` mode:

- `QUTE_URL`: The current 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_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 dict.cc:

    #!/bin/bash

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

## Libraries

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

- Python: python-qutescript

- Node.js: qutejs