Tridactyl help page

Use :help <excmd> or scroll down to show help for a particular excmd. If you're still stuck, you might consider reading through the :tutor again.

The default keybinds can be found here or all active binds can be seen with :viewconfig nmaps. You can also view them with bind. Try bind j.

For more information, and FAQs, check out our readme on github.

Tridactyl is in a pretty early stage of development. Please report any issues and make requests for missing features on the GitHub project page. You can also get in touch using Matrix, Gitter, or IRC chat clients:

Matrix Chat Gitter Chat Freenode Chat

All three channels are mirrored together, so it doesn't matter which one you use.

How to use this help page

We've hackily re-purposed TypeDoc which is designed for internal documentation. Every function (excmd) on this page can be called via Tridactyl's command line which we call "ex". There is a slight change in syntax, however. Wherever you see:

function(arg1,arg2)

You should instead type

function arg1 arg2 into the Tridactyl command line (accessed via :)

A "splat" operator (...) means that the excmd will accept any number of space-delimited arguments into that parameter.

Above each function signature you will see any aliases or key sequences bound to it. The internal names for the various modes are used, which are listed here:

  • nmaps: normal mode binds
  • imaps: insert mode binds
  • inputmaps: input mode binds
  • ignoremaps: ignore mode binds
  • exaliases: aliases in the command mode

You do not need to worry about types. Return values which are promises will turn into whatever they promise to when used in composite.

At the bottom of each function's help page, you can click on a link that will take you straight to that function's definition in our code. This is especially recommended for browsing the config which is nigh-on unreadable on these pages.

Highlighted features:

  • Press b to bring up a list of open tabs in the current window; you can type the tab ID or part of the title or URL to choose a tab
  • Press Shift + Insert to enter "ignore mode". Press Shift + Insert again to return to "normal mode". <C-A-backtick> also works both ways.
  • Press f to start "hint mode", F to open in background (note: hint characters should be typed in lowercase)
  • Press o to :open a different page
  • Press s if you want to search for something that looks like a domain name or URL
  • bind new commands with e.g. :bind J tabnext
  • Type :help to see a list of available excmds
  • Use yy to copy the current page URL to your clipboard
  • [[and ]] to navigate through the pages of comics, paginated articles, etc
  • Pressing ZZ will close all tabs and windows, but it will only "save" them if your about:preferences are set to "show your tabs and windows from last time"
  • Press Ctrl-i in a text box to edit in an external editor (e.g. vim). Requires native messenger.
  • Change theme with colours default|dark|greenmat|shydactyl

There are some caveats common to all webextension vimperator-alikes:

  • To make Tridactyl work on addons.mozilla.org and some other Mozilla domains, you need to open about:config, run fixamo or add a new boolean privacy.resistFingerprinting.block_mozAddonManager with the value true, and remove the above domains from extensions.webextensions.restrictedDomains.
  • Tridactyl can't run on about:*, some file:* URIs, view-source:*, or data:*, URIs.
  • To change/hide the GUI of Firefox from Tridactyl, you can use guiset with the native messenger installed (see native and installnative). Alternatively, you can edit your userChrome yourself. There is an example file available in our repository.

If you want a more fully-featured vimperator-alike, your best option is Firefox ESR and Vimperator :)

Index

Functions

autocmd

  • autocmd(event: string, url: string, ...excmd: string[]): void
  • Set autocmds to run when certain events happen.

    Parameters

    • event: string

      Curently, 'TriStart', 'DocStart', 'DocLoad', 'DocEnd', 'TabEnter' and 'TabLeft' are supported.

    • url: string

      For DocStart, DocEnd, TabEnter, and TabLeft: a fragment of the URL on which the events will trigger, or a JavaScript regex (e.g, /www\.amazon\.co.*\/)

      We just use URL.search.

      For TriStart: A regular expression that matches the hostname of the computer the autocmd should be run on. This requires the native messenger to be installed, except for the ".*" regular expression which will always be triggered, even without the native messenger.

    • Rest ...excmd: string[]

      The excmd to run (use composite to run multiple commands)

    Returns void

autocmddelete

  • autocmddelete(event: string, url: string): void
  • Remove autocmds

    Parameters

    • event: string

      Curently, 'TriStart', 'DocStart', 'DocLoad', 'DocEnd', 'TabEnter' and 'TabLeft' are supported.

    • url: string

      For DocStart, DocEnd, TabEnter, and TabLeft: a fragment of the URL on which the events will trigger, or a JavaScript regex (e.g, /www\.amazon\.co.*\/)

    Returns void

autocontain

  • autocontain(domain: string, container: string): void
  • Automatically open a domain and all its subdomains in a specified container.

    For declaring containers that do not yet exist, consider using auconscreatecontainer true in your tridactylrc. This allows tridactyl to automatically create containers from your autocontain directives. Note that they will be random icons and colors.

    ** NB: This is an experimental feature, if you encounter issues please create an issue on github. **

    The domain is passed through as a regular expression so there are a few gotchas to be aware of:

    • Unescaped periods will match anything. autocontain google.co.uk work will match google!co$uk. Escape your periods or accept that you might get some false positives.
    • You can use regex in your domain pattern. autocontain google\,(co\.uk|com) work will match either google.co.uk or google.com.

      @param domain The domain which will trigger the autoContain directive. Includes all subdomains. @param container The container to open the url in.

    Parameters

    • domain: string
    • container: string

    Returns void

back

  • back(n?: number): void
  • Navigate back one page in history.

    Parameters

    • Default value n: number = 1

    Returns void

bind

  • bind(...args: string[]): void
  • Bind a sequence of keys to an excmd or view bound sequence.

    This is an easier-to-implement bodge while we work on vim-style maps.

    Examples:

    • bind G fillcmdline tabopen google
    • bind D composite tabclose | buffer #
    • bind j scrollline 20
    • bind F hint -b

    You can view binds by omitting the command line:

    • bind j
    • bind k

    You can bind to modifiers and special keys by enclosing them with angle brackets, for example bind <C-\>z fullscreen, unbind <F1> (a favourite of people who use TreeStyleTabs :) ), or bind <Backspace> forward.

    Modifiers are truncated to a single character, so Ctrl -> C, Alt -> A, and Shift -> S. Shift is a bit special as it is only required if Shift does not change the key inputted, e.g. <S-ArrowDown> is OK, but <S-a> should just be A.

    You can view all special key names here: https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values

    Use composite if you want to execute multiple excmds. Use fillcmdline to put a string in the cmdline and focus the cmdline (otherwise the string is executed immediately).

    You can bind to other modes with bind --mode={insert|ignore|normal|input} ..., e.g, bind --mode=insert emacs qall (NB: unlike vim, all preceeding characters will not be input).

    See also:

    Parameters

    • Rest ...args: string[]

    Returns void

blacklistadd

  • blacklistadd(url: string): void
  • Helper function to put Tridactyl into ignore mode on the provided URL.

    Simply creates a DocStart and TabEnter autocmd that runs mode ignore.

    Due to a Tridactyl bug, the only way to remove these rules once they are set is to delete all of your autocmds with unset autocmds.

    <!-- this should probably be moved to an ex alias once configuration has better help --!>

    Parameters

    • url: string

    Returns void

bmark

  • bmark(url?: string, ...titlearr: string[]): Promise<void>
  • Add or remove a bookmark.

    Optionally, you may give the bookmark a title. If no URL is given, a bookmark is added for the current page.

    If a bookmark already exists for the URL, it is removed, even if a title is given.

    Does not support creation of folders: you'll need to use the Firefox menus for that.

    Parameters

    • Optional url: string
    • Rest ...titlearr: string[]

      Title for the bookmark (can include spaces but not forward slashes, as these are interpreted as folders). If you want to put the bookmark in a folder, you can:

      • Specify it exactly: /Bookmarks Menu/Mozilla Firefox/My New Bookmark Title
      • Specify it by a subset: Firefox/My New Bookmark Title
      • and leave out the title if you want: Firefox/

    Returns Promise<void>

buffer

  • buffer(index: number | "#"): Promise<void>
  • Change active tab.

    Parameters

    • index: number | "#"

      Starts at 1. 0 refers to last tab of the current window, -1 to penultimate tab, etc.

      "#" means the tab that was last accessed in this window

      This is different from bufferall because index is the position of the tab in the window.

    Returns Promise<void>

bufferall

  • bufferall(id: string): Promise<object>
  • Change active tab.

    Parameters

    • id: string

      A string following the following format: "[0-9]+.[0-9]+", the first number being the index of the window that should be selected and the second one being the index of the tab within that window.

    Returns Promise<object>

changelistjump

  • changelistjump(n?: number): Promise<void>
  • Focus the tab which contains the last focussed input element. If you're lucky, it will focus the right input, too.

    Currently just goes to the last focussed input; being able to jump forwards and backwards is planned.

    Parameters

    • Optional n: number

    Returns Promise<void>

clipboard

  • clipboard(excmd?: "open" | "yank" | "yankshort" | "yankcanon" | "yanktitle" | "yankmd" | "tabopen", ...toYank: string[]): Promise<void>
  • Use the system clipboard.

    If excmd == "open", call open with the contents of the clipboard. Similarly for tabopen.

    If excmd == "yank", copy the current URL, or if given, the value of toYank, into the system clipboard.

    If excmd == "yankcanon", copy the canonical URL of the current page if it exists, otherwise copy the current URL.

    If excmd == "yankshort", copy the shortlink version of the current URL, and fall back to the canonical then actual URL. Known to work on https://yankshort.neocities.org/.

    If excmd == "yanktitle", copy the title of the open page.

    If excmd == "yankmd", copy the title and url of the open page formatted in Markdown for easy use on sites such as reddit.

    If you're on Linux and the native messenger is installed, Tridactyl will call an external binary (either xclip or xsel) to read or write to your X selection buffer. If you want another program to be used, set "externalclipboardcmd" to its name and make sure it has the same interface as xsel/xclip ("-i"/"-o" and reading from stdin).

    When doing a read operation (i.e. open or tabopen), if "putfrom" is set to "selection", the X selection buffer will be read instead of the clipboard. Set "putfrom" to "clipboard" to use the clipboard.

    When doing a write operation, if "yankto" is set to "selection", only the X selection buffer will be written to. If "yankto" is set to "both", both the X selection and the clipboard will be written to. If "yankto" is set to "clipboard", only the clipboard will be written to.

    Parameters

    • Default value excmd: "open" | "yank" | "yankshort" | "yankcanon" | "yanktitle" | "yankmd" | "tabopen" = "open"
    • Rest ...toYank: string[]

    Returns Promise<void>

comclear

  • comclear(name: string): void
  • Similar to vim's comclear command. Clears an excmd alias defined by command.

    For example: comclear helloworld will reverse any changes caused by command helloworld xxx

    See also:

    Parameters

    • name: string

    Returns void

command

  • command(name: string, ...definition: string[]): void
  • Similar to vim's :command. Maps one ex-mode command to another. If command already exists, this will override it, and any new commands added in a future release will be SILENTLY overridden. Aliases are expanded recursively.

    Examples:

    • command t tabopen
    • command tn tabnext_gt = command hello t This will expand recursively into 'hello'->'tabopen'

    Note that this is only for excmd->excmd mappings. To map a normal-mode command to an excommand, see bind.

    See also:

    Parameters

    • name: string
    • Rest ...definition: string[]

    Returns void

composite

  • composite(...cmds: string[]): Promise<any>
  • Split cmds on pipes (|) and treat each as its own command. Return values are passed as the last argument of the next ex command, e.g,

    composite echo yes | fillcmdline becomes fillcmdline yes. A more complicated example is the ex alias, command current_url composite get_current_url | fillcmdline_notrail, which is used in, e.g. bind T current_url tabopen.

    Workaround: this should clearly be in the parser, but we haven't come up with a good way to deal with |s in URLs, search terms, etc. yet.

    cmds are also split with semicolons (;) and don't pass things along to each other.

    The behaviour of combining ; and | in the same composite command is left as an exercise for the reader.

    Parameters

    • Rest ...cmds: string[]

    Returns Promise<any>

containerclose

  • containerclose(name: string): Promise<void>
  • Closes all tabs open in the same container across all windows.

    Parameters

    • name: string

      The container name.

    Returns Promise<void>

containercreate

  • containercreate(name: string, color?: string, icon?: string): Promise<void>
  • Creates a new container. Note that container names must be unique and that the checks are case-insensitive.

    Further reading https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/contextualIdentities/ContextualIdentity

    Example usage:

    • :containercreate tridactyl green dollar

    Parameters

    • name: string

      The container name. Must be unique.

    • Optional color: string

      The container color. Valid colors are: "blue", "turquoise", "green", "yellow", "orange", "red", "pink", "purple". If no color is chosen a random one will be selected from the list of valid colors.

    • Optional icon: string

      The container icon. Valid icons are: "fingerprint", "briefcase", "dollar", "cart", "circle", "gift", "vacation", "food", "fruit", "pet", "tree", "chill". If no icon is chosen, it defaults to "fingerprint".

    Returns Promise<void>

containerdelete

  • containerdelete(name: string): Promise<void>
  • Delete a container. Closes all tabs associated with that container beforehand. Note: container names are case-insensitive.

    Parameters

    • name: string

      The container name.

    Returns Promise<void>

containerupdate

  • containerupdate(name: string, uname: string, ucolor: string, uicon: string): Promise<void>
  • Update a container's information. Note that none of the parameters are optional and that container names are case-insensitive.

    Example usage:

    • Changing the container name: :containerupdate banking blockchain green dollar

    • Changing the container icon: :containerupdate banking banking green briefcase

    • Changing the container color: :containerupdate banking banking purple dollar

    Parameters

    • name: string

      The container name.

    • uname: string

      The new container name. Must be unique.

    • ucolor: string

      The new container color. Valid colors are: "blue", "turquoise", "green", "yellow", "orange", "red", "pink", "purple". If no color is chosen a random one will be selected from the list of valid colors.

    • uicon: string

      The new container icon. Valid icons are: "fingerprint", "briefcase", "dollar", "cart", "circle", "gift", "vacation", "food", "fruit", "pet", "tree", "chill".

    Returns Promise<void>

credits

  • credits(excmd?: string): Promise<void>
  • Display Tridactyl's contributors in order of commits in a user-friendly fashion

    Parameters

    • Optional excmd: string

    Returns Promise<void>

echo

  • echo(...str: string[]): Promise<string>

editor

  • editor(): Promise<void>
  • Opens your favourite editor (which is currently gVim) and fills the last used input with whatever you write into that file. Requires that the native messenger is installed, see native and installnative.

    Uses the editorcmd config option, default = auto looks through a list defined in native_background.ts try find a sensible combination. If it's a bit slow, or chooses the wrong editor, or gives up completely, set editorcmd to something you want. The command must stay in the foreground until the editor exits.

    The editorcmd needs to accept a filename, stay in the foreground while it's edited, save the file and exit.

    You're probably better off using the default insert mode bind of <C-i> (Ctrl-i) to access this.

    Returns Promise<void>

exclaim

  • exclaim(...str: string[]): Promise<void>
  • Run command in /bin/sh (unless you're on Windows), and print the output in the command line. Non-zero exit codes and stderr are ignored, currently.

    Requires the native messenger, obviously.

    If you want to use a different shell, just prepend your command with whatever the invocation is and keep in mode that most shells require quotes around the command to be executed, e.g. :exclaim xonsh -c "1+2".

    Aliased to ! but the exclamation mark must be followed with a space.

    Parameters

    • Rest ...str: string[]

    Returns Promise<void>

exclaim_quiet

  • exclaim_quiet(...str: string[]): Promise<string>
  • Like exclaim, but without any output to the command line.

    Parameters

    • Rest ...str: string[]

    Returns Promise<string>

fillcmdline

  • fillcmdline(...strarr: string[]): void
  • Set the current value of the commandline to string with a trailing space

    Parameters

    • Rest ...strarr: string[]

    Returns void

fillcmdline_nofocus

  • fillcmdline_nofocus(...strarr: string[]): Promise<any>
  • Show and fill the command line without focusing it

    Parameters

    • Rest ...strarr: string[]

    Returns Promise<any>

fillcmdline_notrail

  • fillcmdline_notrail(...strarr: string[]): void
  • Set the current value of the commandline to string without a trailing space

    Parameters

    • Rest ...strarr: string[]

    Returns void

fillcmdline_tmp

  • fillcmdline_tmp(ms: number, ...strarr: string[]): Promise<Object>
  • Shows str in the command line for ms milliseconds. Recommended duration: 3000ms.

    Parameters

    • ms: number
    • Rest ...strarr: string[]

    Returns Promise<Object>

fillinput

  • fillinput(selector: string, ...content: string[]): Promise<void>
  • Fills the element matched by selector with content and falls back to the last used input if the element can't be found. You probably don't want this; it's used internally for editor.

    That said, bind gs fillinput null [Tridactyl](https://addons.mozilla.org/en-US/firefox/addon/tridactyl-vim/) is my favourite add-on could probably come in handy.

    Parameters

    • selector: string
    • Rest ...content: string[]

    Returns Promise<void>

find

  • find(direction?: number): void
  • Start find mode. Work in progress.

    Parameters

    • Optional direction: number

      the direction to search in: 1 is forwards, -1 is backwards.

    Returns void

findnext

  • findnext(n: number): void
  • Highlight the next occurence of the previously searched for word.

    Parameters

    • n: number

    Returns void

fixamo

  • fixamo(): Promise<void>
  • Simply sets

     "privacy.resistFingerprinting.block_mozAddonManager":true
     "extensions.webextensions.restrictedDomains":""

    in about:config via user.js so that Tridactyl (and other extensions!) can be used on addons.mozilla.org and other sites.

    Requires native and a restart.

    Returns Promise<void>

fixamo_quiet

  • fixamo_quiet(): Promise<void>

focusinput

  • focusinput(nth: number | string): void
  • Focus the last used input on the page

    Parameters

    • nth: number | string

      focus the nth input on the page, or "special" inputs: "-l": last focussed input "-n": input after last focussed one "-N": input before last focussed one "-p": first password field "-b": biggest input field

    Returns void

followpage

  • followpage(rel?: "next" | "prev"): void
  • Find a likely next/previous link and follow it

    If a link or anchor element with rel=rel exists, use that, otherwise fall back to:

    1) find the last anchor on the page with innerText matching the appropriate followpagepattern. 2) call urlincrement with 1 or -1

    If you want to support e.g. French:

    set followpagepatterns.next ^(next|newer|prochain)\b|»|>>
    set followpagepatterns.prev ^(prev(ious)?|older|précédent)\b|»|>>

    Parameters

    • Default value rel: "next" | "prev" = "next"

      the relation of the target page to the current page: "next" or "prev"

    Returns void

forward

  • forward(n?: number): void
  • Navigate forward one page in history.

    Parameters

    • Default value n: number = 1

    Returns void

fullscreen

  • fullscreen(): Promise<void>

get

  • get(...keys: string[]): void
  • Puts the contents of config value with keys keys into the commandline and the background page console

    It's a bit rubbish, but we don't have a good way to provide feedback to the commandline yet.

    You can view the log entry in the browser console (Ctrl-Shift-j).

    For example, you might try get nmaps to see all of your current binds.

    Parameters

    • Rest ...keys: string[]

    Returns void

get_current_url

  • get_current_url(): Promise<any>

gobble

  • gobble(nChars: number, endCmd: string): Promise<void>
  • Initialize gobble mode.

    It will read nChars input keys, append them to endCmd and execute that string.

    Parameters

    • nChars: number
    • endCmd: string

    Returns Promise<void>

guiset

  • guiset(rule: string, option: string): Promise<void>
  • Change which parts of the Firefox user interface are shown. NB: This feature is experimental and might break stuff.

    Might mangle your userChrome. Requires native messenger, and you must restart Firefox each time to see any changes (this can be done using restart).

    View available rules and options here and here.

    Example usage: guiset gui none, guiset gui full, guiset tabs autohide.

    Some of the available options:

    • gui

      • full
      • none
    • tabs

      • always
      • autohide
    • navbar

      • always
      • autohide
      • none
    • hoverlink (the little link that appears when you hover over a link)

      • none
      • left
      • right
      • top-left
      • top-right
    • titlebar

      • hide
      • show

    If you want to use guiset in your tridactylrc, you might want to use guiset_quiet instead.

    Parameters

    • rule: string
    • option: string

    Returns Promise<void>

guiset_quiet

  • guiset_quiet(rule: string, option: string): Promise<MessageResp>

help

  • help(excmd?: string): Promise<void>
  • Show this page.

    :help something jumps to the entry for something. Something can be an excmd, an alias for an excmd or a binding.

    The "nmaps" list is a list of all the bindings for the command you're seeing and the "exaliases" list lists all its aliases.

    If there's a conflict (e.g. you have a "go" binding that does something and also a "go" excmd that does something else), the binding has higher priority.

    If the keyword you gave to :help is actually an alias for a composite command (see composite) , you will be taken to the help section for the first command of the pipeline. You will be able to see the whole pipeline by hovering your mouse over the alias in the "exaliases" list. Unfortunately there currently is now way to display these HTML tooltips from the keyboard.

    e.g. :help bind

    Parameters

    • Optional excmd: string

    Returns Promise<void>

hint

  • hint(option?: string, selectors?: string, ...rest: string[]): Promise<Object>
  • Hint a page.

    Parameters

    • Optional option: string
      • -b open in background
      • -y copy (yank) link's target to clipboard
      • -p copy an element's text to the clipboard
      • -P copy an element's title/alt text to the clipboard
      • -r read an element's text with text-to-speech
      • -i view an image
      • -I view an image in a new tab
      • -k delete an element from the page
      • -s save (download) the linked resource
      • -S save the linked image
      • -a save-as the linked resource
      • -A save-as the linked image
      • -; focus an element
      • -# yank an element's anchor URL to clipboard
      • -c [selector] hint links that match the css selector
      • bind ;c hint -c [class*="expand"],[class="togg"] works particularly well on reddit and HN
      • -w open in new window
      • -wp open in new private window
      • -pipe selector key e.g, -pipe * href returns the key. Only makes sense with composite, e.g, composite hint -pipe * textContent | yank. If you don't select a hint (i.e. press ), will return an empty string.
      • -W excmd... append hint href to excmd and execute, e.g, hint -W exclaim mpv to open YouTube videos.
      • -q* quick (or rapid) hints mode. Stay in hint mode until you press , e.g. :hint -qb to open multiple hints in the background or :hint -qW excmd to execute excmd once for each hint. This will return an array containing all elements or the result of executed functions (e.g. hint -qpipe a href will return an array of links).
      • -br deprecated, use -qb instead

      Excepting the custom selector mode and background hint mode, each of these hint modes is available by default as ;<option character>, so e.g. ;y to yank a link's target; ;g<option character> starts rapid hint mode for all modes where it makes sense, and some others.

      To open a hint in the background, the default bind is F.

      Related settings:

      • "hintchars": "hjklasdfgyuiopqwertnmzxcvb"
      • "hintfiltermode": "simple" | "vimperator" | "vimperator-reflow"
      • "relatedopenpos": "related" | "next" | "last"
      • "hintuppercase": "true" | "false"
      • "hintnames": "short" | "uniform" | "numeric"

      With "short" names, Tridactyl will generate short hints that are never prefixes of each other. With "uniform", Tridactyl will generate hints of uniform length. In either case, the hints are generated from the set in "hintchars".

      With "numeric" names, hints are always assigned using sequential integers, and "hintchars" is ignored. This has the disadvantage that some hints are prefixes of others (and you need to hit space or enter to select such a hint). But it has the advantage that the hints tend to be more predictable (e.g., a news site will have the same hints for its boilerplate each time you visit it, even if the number of links in the main body changes).

    • Optional selectors: string
    • Rest ...rest: string[]

    Returns Promise<Object>

home

  • home(all?: "false" | "true"): void
  • Go to the homepages you have set with set home [url1] [url2].

    @param all

     - if "true", opens all homepages in new tabs
     - if "false" or not given, opens the last homepage in the current tab

    Parameters

    • Default value all: "false" | "true" = "false"

    Returns void

installnative

  • installnative(): Promise<void>

js

  • js(...str: string[]): Promise<any>
  • Lets you execute JavaScript in the page context. If you want to get the result back, use composite js ... | fillcmdline

    Some of Tridactyl's functions are accessible here via the tri object. Just do console.log(tri) in the web console on the new tab page to see what's available.

    If you want to pipe an argument to js, you need to use the "-p" flag and then use the JS_ARG global variable, e.g:

    composite get_current_url | js -p alert(JS_ARG)

    Parameters

    • Rest ...str: string[]

    Returns Promise<any>

jsb

  • jsb(...str: string[]): Promise<any>
  • Lets you execute JavaScript in the background context. All the help from js applies. Gives you a different tri object.

    Parameters

    • Rest ...str: string[]

    Returns Promise<any>

jumpnext

  • jumpnext(n?: number): void

jumpprev

  • jumpprev(n?: number): void
  • Similar to Pentadactyl or vim's jump list.

    Parameters

    • Default value n: number = 1

    Returns void

loggingsetlevel

  • loggingsetlevel(logModule: string, level: string): void
  • Set the logging level for a given logging module.

    Parameters

    • logModule: string

      the logging module to set the level on

    • level: string

      the level to log at: in increasing verbosity, one of "never", "error", "warning", "info", "debug"

    Returns void

mode

mute

  • mute(...muteArgs: string[]): Promise<void>
  • Mute current tab or all tabs.

    Passing "all" to the excmd will operate on the mute state of all tabs. Passing "unmute" to the excmd will unmute. Passing "toggle" to the excmd will toggle the state of browser.tabs.tab.MutedInfo

    Parameters

    • Rest ...muteArgs: string[]

    Returns Promise<void>

native

  • native(): Promise<void>
  • Tells you if the native messenger is installed and its version.

    Returns Promise<void>

nativeopen

  • nativeopen(url: string, ...firefoxArgs: string[]): Promise<void>
  • Uses the native messenger to open URLs.

    Be seriously careful with this: you can use it to open any URL you can open in the Firefox address bar.

    You've been warned.

    Parameters

    • url: string
    • Rest ...firefoxArgs: string[]

    Returns Promise<void>

open

  • open(...urlarr: string[]): Promise<void>
  • Open a new page in the current tab.

    @param urlarr

      - if first word looks like it has a schema, treat as a URI
      - else if the first word contains a dot, treat as a domain name
      - else if the first word is a key of [[SEARCH_URLS]], treat all following terms as search parameters for that provider
      - else treat as search parameters for google

    Related settings:

     - "searchengine": "google" or any of [[SEARCH_URLS]]
     - "historyresults": the n-most-recent results to ask Firefox for before they are sorted by frequency. Reduce this number if you find your results are bad.

    Can only open about:* or file:* URLs if you have the native messenger installed, and on OSX you must set browser to something that will open Firefox from a terminal pass it commmand line options.

    Parameters

    • Rest ...urlarr: string[]

    Returns Promise<void>

open_quiet

  • open_quiet(...urlarr: string[]): Promise<void>
  • Like open but doesn't make a new entry in history.

    Parameters

    • Rest ...urlarr: string[]

    Returns Promise<void>

pin

  • pin(): Promise<void>

qall

  • qall(): Promise<void>

quickmark

  • quickmark(key: string, ...addressarr: string[]): Promise<void>
  • Bind a quickmark for the current URL or space-separated list of URLs to a key on the keyboard.

    Afterwards use go[key], gn[key], or gw[key] to open, tabopen, or winopen the URL respectively.

    Parameters

    • key: string
    • Rest ...addressarr: string[]

    Returns Promise<void>

reader

  • reader(): Promise<void>
  • Opens the current page in Firefox's reader mode. You currently cannot use Tridactyl while in reader mode.

    Returns Promise<void>

reload

  • reload(n?: number, hard?: boolean): Promise<void>
  • Reload the next n tabs, starting with activeTab, possibly bypassingCache

    Parameters

    • Default value n: number = 1
    • Default value hard: boolean = false

    Returns Promise<void>

reloadall

  • reloadall(hard?: boolean): Promise<void>
  • Reloads all tabs, bypassing the cache if hard is set to true

    Parameters

    • Default value hard: boolean = false

    Returns Promise<void>

reloadhard

  • reloadhard(n?: number): Promise<void>
  • Reload the next n tabs, starting with activeTab. bypass cache for all

    Parameters

    • Default value n: number = 1

    Returns Promise<void>

repeat

  • repeat(n?: number, ...exstr: string[]): void
  • Repeats a cmd n times. Falls back to the last executed command if cmd doesn't exist. Executes the command once if n isn't defined either.

    Parameters

    • Default value n: number = 1
    • Rest ...exstr: string[]

    Returns void

reset

  • reset(key: string): Promise<void>
  • Restores a sequence of keys to their default value.

    See also:

    Parameters

    • key: string

    Returns Promise<void>

restart

  • restart(): Promise<void>
  • Restarts firefox with the same commandline arguments.

    Warning: This can kill your tabs, especially if you :restart several times in a row

    Returns Promise<void>

sanitise

  • sanitise(...args: string[]): Promise<void>
  • Deletes various privacy-related items.

    The list of possible arguments can be found here: https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/browsingData/DataTypeSet

    Additional, tridactyl-specific arguments are:

    • commandline: Removes the in-memory commandline history.
    • tridactyllocal: Removes all tridactyl storage local to this machine. Use it with commandline if you want to delete your commandline history.
    • tridactylsync: Removes all tridactyl storage associated with your Firefox Account (i.e, all user configuration, by default). These arguments aren't affected by the timespan parameter.

    Timespan parameter: -t [0-9]+(m|h|d|w)

    Examples:

    • sanitise all -> Deletes everything
    • sanitise history -> Deletes all history
    • sanitise commandline tridactyllocal tridactylsync -> Deletes every bit of data Tridactyl holds
    • sanitise cookies -t 3d -> Deletes cookies that were set during the last three days.

    Parameters

    • Rest ...args: string[]

    Returns Promise<void>

scrollline

  • scrollline(n?: number): void
  • Scrolls the document of its first scrollable child element by n lines.

    The height of a line is defined by the site's CSS. If Tridactyl can't get it, it'll default to 22 pixels.

    Parameters

    • Default value n: number = 1

    Returns void

scrollpage

  • scrollpage(n?: number): void
  • Scrolls the document by n pages.

    The height of a page is the current height of the window.

    Parameters

    • Default value n: number = 1

    Returns void

scrollpx

  • scrollpx(a: number, b: number): Promise<void>
  • Scrolls the window or any scrollable child element by a pixels on the horizontal axis and b pixels on the vertical axis.

    Parameters

    • a: number
    • b: number

    Returns Promise<void>

scrollto

  • scrollto(a: number, b?: number | "x" | "y"): void
  • If two numbers are given, treat as x and y values to give to window.scrollTo If one number is given, scroll to that percentage along a chosen axis, defaulting to the y-axis

    Note that if a is 0 or 100 and if the document is not scrollable in the given direction, Tridactyl will attempt to scroll the first scrollable element until it reaches the very bottom of that element.

    Parameters

    • a: number
    • Default value b: number | "x" | "y" = "y"

    Returns void

searchsetkeyword

  • searchsetkeyword(keyword: string, url: string): void
  • Set a search engine keyword for use with *open or set searchengine

    deprecated

    use set searchurls.KEYWORD URL instead

    Parameters

    • keyword: string

      the keyword to use for this search (e.g. 'esa')

    • url: string

      the URL to interpolate the query into. If %s is found in the URL, the query is inserted there, else it is appended. If the insertion point is in the "query string" of the URL, the query is percent-encoded, else it is verbatim.

    Returns void

set

  • set(key: string, ...values: string[]): void
  • Set a key value pair in config.

    Use to set any string values found here

    e.g. set searchurls.google https://www.google.com/search?q= set logging.messaging info

    If no value is given, the value of the of the key will be displayed

    Parameters

    • key: string
    • Rest ...values: string[]

    Returns void

sleep

  • sleep(time_ms: number): Promise<void>
  • Sleep time_ms milliseconds. This is probably only useful for composite commands that need to wait until the previous asynchronous command has finished running.

    Parameters

    • time_ms: number

    Returns Promise<void>

source

  • source(...fileArr: string[]): Promise<void>
  • Runs an RC file from disk.

    If no argument given, it will try to open ~/.tridactylrc, ~/.config/tridactylrc or $XDG_CONFIG_HOME/tridactyl/tridactylrc in reverse order. You may use a _ in place of a leading . if you wish, e.g, if you use Windows.

    On Windows, the ~ expands to %USERPROFILE%.

    The RC file is just a bunch of Tridactyl excmds (i.e, the stuff on this help page). Settings persist in local storage; add sanitise tridactyllocal tridactylsync to make it more Vim like. There's an example file if you want it.

    Parameters

    • Rest ...fileArr: string[]

      the file to open. Must be an absolute path, but can contain environment variables and things like ~.

    Returns Promise<void>

source_quiet

  • source_quiet(...fileArr: string[]): Promise<void>
  • Same as source but suppresses all errors

    Parameters

    • Rest ...fileArr: string[]

    Returns Promise<void>

tabclose

  • tabclose(...indexes: string[]): Promise<void>
  • Close a tab.

    Known bug: autocompletion will make it impossible to close more than one tab at once if the list of numbers looks enough like an open tab's title or URL.

    Parameters

    • Rest ...indexes: string[]

      The 1-based indexes of the tabs to target. indexes < 1 wrap. If omitted, this tab.

    Returns Promise<void>

tabclosealltoleft

  • tabclosealltoleft(): Promise<void>
  • Close all tabs to the left of the current one

    Returns Promise<void>

tabclosealltoright

  • tabclosealltoright(): Promise<void>
  • Close all tabs to the right of the current one

    Returns Promise<void>

tabdetach

  • tabdetach(index?: number): Promise<void>
  • Detach a tab, opening it in a new window.

    Parameters

    • Optional index: number

      The 1-based index of the tab to target. index < 1 wraps. If omitted, this tab.

    Returns Promise<void>

tabduplicate

  • tabduplicate(index?: number): Promise<void>
  • Duplicate a tab.

    Parameters

    • Optional index: number

      The 1-based index of the tab to target. index < 1 wraps. If omitted, this tab.

    Returns Promise<void>

tabfirst

  • tabfirst(): Promise<void>

tablast

  • tablast(): Promise<void>

tabmove

  • tabmove(index?: string): Promise<void>
  • Move the current tab to be just in front of the index specified.

    Known bug: This supports relative movement with tabmove +pos and tabmove -pos, but autocomplete doesn't know that yet and will override positive and negative indexes.

    Put a space in front of tabmove if you want to disable completion and have the relative indexes at the command line.

    Binds are unaffected.

    Parameters

    • Default value index: string = "$"

      New index for the current tab.

      1,start,^ are aliases for the first index. 0,end,$ are aliases for the last index.

    Returns Promise<void>

tabnext

  • tabnext(increment?: number): Promise<void>
  • Switch to the next tab, wrapping round.

    If increment is specified, move that many tabs forwards.

    Parameters

    • Default value increment: number = 1

    Returns Promise<void>

tabnext_gt

  • tabnext_gt(index?: number): Promise<void>
  • Switch to the next tab, wrapping round.

    If an index is specified, go to the tab with that number (this mimics the behaviour of {count}gt in vim, except that this command will accept a count that is out of bounds (and will mod it so that it is within bounds as per tabmove, etc)).

    Parameters

    • Optional index: number

    Returns Promise<void>

tabonly

  • tabonly(): Promise<void>

tabopen

  • tabopen(...addressarr: string[]): Promise<void>
  • Like open, but in a new tab. If no address is given, it will open the newtab page, which can be set with set newtab [url]

    Use the -c flag followed by a container name to open a tab in said container. Tridactyl will try to fuzzy match a name if an exact match is not found. Use the -b flag to open the tab in the background. These two can be combined in any order, but need to be placed as the first arguments.

    Unlike Firefox's Ctrl-t shortcut, this opens tabs immediately after the currently active tab rather than at the end of the tab list because that is the authors' preference.

    If you would rather the Firefox behaviour set tabopenpos last. This preference also affects the clipboard, quickmarks, home, help, etc.

    If you would rather the URL be opened as if you'd middle clicked it, set tabopenpos related.

    Hinting is controlled by relatedopenpos

    Parameters

    • Rest ...addressarr: string[]

    Returns Promise<void>

tabprev

  • tabprev(increment?: number): Promise<object>
  • Switch to the previous tab, wrapping round.

    If increment is specified, move that many tabs backwards.

    Parameters

    • Default value increment: number = 1

    Returns Promise<object>

tssReadFromCss

  • tssReadFromCss(selector: string): void
  • Read text content of elements matching the given selector

    Parameters

    • selector: string

      the selector to match elements

    Returns void

ttscontrol

  • ttscontrol(action: string): Promise<void>
  • Cancel current reading and clear pending queue

    Arguments:

    • stop: cancel current and pending utterances

    Parameters

    • action: string

    Returns Promise<void>

ttsread

  • ttsread(mode: "-t" | "-c", ...args: string[]): Promise<void>
  • Read the given text using the browser's text to speech functionality and the settings currently set

    Parameters

    • mode: "-t" | "-c"

      the command mode -t read the following args as text -c read the content of elements matching the selector

    • Rest ...args: string[]

    Returns Promise<void>

ttsvoices

  • ttsvoices(): Promise<void>
  • Show a list of the voices available to the TTS system. These can be set in the config using ttsvoice

    Returns Promise<void>

tutor

  • tutor(newtab?: string): Promise<void>
  • Start the tutorial

    Parameters

    • Optional newtab: string

      whether to start the tutorial in a newtab. Defaults to current tab.

    Returns Promise<void>

unbind

  • unbind(...args: string[]): Promise<void>
  • Unbind a sequence of keys so that they do nothing at all.

    See also:

    Parameters

    • Rest ...args: string[]

    Returns Promise<void>

undo

  • undo(): Promise<void>
  • restore most recently closed tab in this window unless the most recently closed item was a window

    Returns Promise<void>

unfocus

  • unfocus(): void

unset

  • unset(...keys: string[]): void

updatenative

  • updatenative(interactive?: boolean): Promise<void>
  • Updates the native messenger if it is installed, using our GitHub repo. This is run every time Tridactyl is updated.

    If you want to disable this, or point it to your own native messenger, edit the nativeinstallcmd setting.

    Parameters

    • Default value interactive: boolean = true

    Returns Promise<void>

url2args

  • url2args(): Promise<string>
  • If the url of the current document matches one of your search engines, will convert it to a list of arguments that open/tabopen will understand. If the url doesn't match any search engine, returns the url without modifications.

    For example, if you have searchurls.gi set to "https://www.google.com/search?q=%s&tbm=isch", using this function on a page you opened using "gi butterflies" will return "gi butterflies".

    This is useful when combined with fillcmdline, for example like this: bind O composite url2args | fillcmdline open.

    Note that this might break with search engines that redirect you to other pages/add GET parameters that do not exist in your searchurl.

    Returns Promise<string>

urlincrement

  • urlincrement(count?: number): void
  • Increment the current tab URL

    Parameters

    • Default value count: number = 1

      the increment step, can be positive or negative

    Returns void

urlmodify

  • urlmodify(mode: "-t" | "-r" | "-q" | "-Q" | "-g", ...args: string[]): void
  • Open a URL made by modifying the current URL

    There are several modes:

    • Text replace mode: urlmodify -t <old> <new>

      Replaces the first instance of the text old with new.

      • http://example.com -> (-t exa peta) -> http://petample.com
    • Regex replacment mode: urlmodify -r <regexp> <new> [flags]

      Replaces the first match of the regexp with new. You can use flags i and g to match case-insensitively and to match all instances respectively

      • http://example.com -> (-r [ea] X g) -> http://XxXmplX.com
    • Query replace mode: urlmodify -q <query> <new_val>

      Replace the value of a query with a new one:

    • Query delete mode: urlmodify -Q <query>

      Deletes the given query (and the value if any):

      • http://e.com?id=foo&page=1 -> (-Q id) -> http://e.com?page=1
    • Graft mode: urlmodify -g <graft_point> <new_path_tail>

      "Grafts" a new tail on the URL path, possibly removing some of the old tail. Graft point indicates where the old URL is truncated before adding the new path.

      • graft_point >= 0 counts path levels, starting from the left (beginning). 0 will append from the "root", and no existing path will remain, 1 will keep one path level, and so on.
      • graft_point < 0 counts from the right (i.e. the end of the current path). -1 will append to the existing path, -2 will remove the last path level, and so on.
      http://website.com/this/is/the/path/component
      Graft point:       ^    ^  ^   ^    ^        ^
      From left:         0    1  2   3    4        5
      From right:       -6   -5 -4  -3   -2       -1

      Examples:

      • http://e.com/issues/42 -> (-g 0 foo) -> http://e.com/foo
      • http://e.com/issues/42 -> (-g 1 foo) -> http://e.com/issues/foo
      • http://e.com/issues/42 -> (-g -1 foo) -> http://e.com/issues/42/foo
      • http://e.com/issues/42 -> (-g -2 foo) -> http://e.com/issues/foo

    Parameters

    • mode: "-t" | "-r" | "-q" | "-Q" | "-g"

      The replace mode:

      • -t text replace
      • -r regexp replace
      • -q replace the value of the given query
      • -Q delete the given query
      • -g graft a new path onto URL or parent path of it
    • Rest ...args: string[]

    Returns void

urlparent

  • urlparent(count?: number): void
  • Go to the parent URL of the current tab's URL

    Parameters

    • Default value count: number = 1

    Returns void

urlroot

  • urlroot(): void

version

  • version(): void

viewconfig

  • viewconfig(key?: string): void
  • Opens the current configuration in Firefox's native JSON viewer in the current tab.

    NB: Tridactyl cannot run on this page!

    Parameters

    • Optional key: string

      The specific key you wish to view (e.g, nmaps).

    Returns void

viewcontainers

  • viewcontainers(): Promise<void>
  • Shows a list of the current containers in Firefox's native JSON viewer in the current tab.

    NB: Tridactyl cannot run on this page!

    Returns Promise<void>

viewsource

  • viewsource(url?: string): void
  • Display the (HTML) source of the current page.

    Behaviour can be changed by the 'viewsource' setting.

    If the 'viewsource' setting is set to 'default' rather than 'tridactyl', the url the source of which should be displayed can be given as argument. Otherwise, the source of the current document will be displayed.

    Parameters

    • Default value url: string = ""

    Returns void

winclose

  • winclose(): Promise<void>

winopen

  • winopen(...args: string[]): Promise<void>

yank

  • yank(...content: string[]): Promise<void>
  • Copy content to clipboard without feedback. Use clipboard yank for interactive use.

    Parameters

    • Rest ...content: string[]

    Returns Promise<void>

zoom

  • zoom(level?: number, rel?: string): Promise<void>
  • Parameters

    • Default value level: number = 0
    • Default value rel: string = "false"

    Returns Promise<void>