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: Eitherhints(started via hints) orcommand(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: Thecountfrom 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