Skip to content

Latest commit

 

History

History
87 lines (62 loc) · 3.13 KB

userscripts.asciidoc

File metadata and controls

87 lines (62 loc) · 3.13 KB
Raw

Writing qutebrowser userscripts

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: