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 and settings can be found here and active binds can be seen with :viewconfig nmaps or with bind.

Tridactyl also provides a few functions to manipulate text in the command line or text areas that can be found here. There are also a few commands only available in the command line which can be found here.

Ex-commands available exclusively in hint mode are listed here

We also have a wiki which may be edited by anyone.

How to use this help page

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
  • exmaps: commandline mode binds

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.

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

Caveats

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 and add a new boolean privacy.resistFingerprinting.block_mozAddonManager with the value true, as well as remove those 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 nativeinstall). Alternatively, you can edit your userChrome yourself.

Getting help

For more information, and FAQs, check out our readme and troubleshooting guide 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 Libera Chat

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

Index

Variables

Functions

Variables

Const autocmd_logger

autocmd_logger: Logger = new Logging.Logger("autocmds")

Functions

apropos

  • apropos(...helpItems: string[]): Promise<any>
  • Search through the help pages. Accepts the same flags as help. Only useful in interactive usage with completions; the command itself is just a wrapper for help.

    Parameters

    • Rest ...helpItems: string[]

    Returns Promise<any>

autocmd

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

    Parameters

    • event: string

      Currently, 'TriStart', 'DocStart', 'DocLoad', 'DocEnd', 'TabEnter', 'TabLeft', 'FullscreenChange', 'FullscreenEnter', 'FullscreenLeft', 'HistoryState', 'HistoryPushState', 'HistoryReplace', 'UriChange', 'AuthRequired', 'BeforeRedirect', 'BeforeRequest', 'BeforeSendHeaders', 'Completed', 'ErrorOccured', 'HeadersReceived', 'ResponseStarted', and 'SendHeaders' are supported

      • DocStart: When a webpage loading. Exactly, when tridactyl is loading in a page.
      • DocLoad: When the whole html parsed, not including image/css loaded. (Just like jquery $(fn) or the DOMContentLoaded event.)
      • DocEnd: When a webpage unloaded/closed or backward/forward in history. Exactly, the pagehide event.
      • TabEnter: When a tab get focus.
      • TabLeft: When a tab lost focus or closed.

      The 'HistoryState' event is triggered when a page uses the web history API to change the page location / URI. It should be used in preference to 'UriChange' below since it will use almost no resources. The 'UriChange' event may work on websites where 'HistoryState' does not.

      The 'HistoryPushState' is triggered only when a page call 'history.pushState' to change URI, and 'HistoryReplace' is for 'history.replace'. By the way, the HistoryPopState is not implemented.

      The 'UriChange' event is for "single page applications" which change their URIs without triggering DocStart or DocLoad events. It uses a timer to check whether the URI has changed, which has a small impact on battery life on pages matching the url parameter. We suggest using it sparingly.

    • url: string

      For DocStart, DocEnd, TabEnter, and TabLeft: 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.

      For AuthRequired, BeforeRedirect, BeforeRequest, BeforeSendHeaders, Completed, ErrorOccured, HeadersReceived, ResponseStarted and SendHeaders, a URL match pattern

    • Rest ...excmd: string[]

      The excmd to run (use composite to run multiple commands), except for AuthRequired, BeforeRedirect, BeforeRequest, BeforeSendHeaders, Completed, ErrorOccured, HeadersReceived, ResponseStarted and SendHeaders, events where it must be an inline JavaScript function which maps details objects specific to the event to blocking responses. This JavaScript function will run in the background context.

      For example: autocmd BeforeRequest https://www.bbc.co.uk/* () => ({redirectUrl: "https://old.reddit.com"}). Note the brackets which ensure JavaScript returns a blocking response object rather than interpreting it as a block statement.

      For DocStart, DocLoad, DocEnd, TabEnter, TabLeft, FullscreenEnter, FullscreenLeft, FullscreenChange and UriChange: magic variables are available which are replaced with the relevant string at runtime:

      • TRI_FIRED_MOZ_TABID: Provides Mozilla's tabID associated with the fired event.
      • TRI_FIRED_TRI_TABINDEX: Provides tridactyls internal tab index associated with the fired event.
      • TRI_FIRED_MOZ_WINID: Provides Mozilla's windowId associated with the fired event.
      • TRI_FIRED_MOZ_OPENERTABID: The ID of the tab that opened this tab.
      • TRI_FIRED_ACTIVE: Whether the tab is active in its window. This may be true even if the tab's window is not currently focused.
      • TRI_FIRED_AUDIBLE: Indicates whether the tab is producing sound (even if muted).
      • TRI_FIRED_MUTED: Indicates whether the tab is muted.
      • TRI_FIRED_DISCARDED: Whether the tab is discarded. A discarded tab is one whose content has been unloaded from memory.
      • TRI_FIRED_HEIGHT: The height of the tab in pixels.
      • TRI_FIRED_WIDTH: The width of the tab in pixels.
      • TRI_FIRED_HIDDEN: Whether the tab is hidden.
      • TRI_FIRED_INCOGNITO: Whether the tab is in a private browsing window.
      • TRI_FIRED_ISARTICLE: True if the tab can be rendered in Reader Mode, false otherwise.
      • TRI_FIRED_LASTACCESSED: Time at which the tab was last accessed, in milliseconds since the epoch.
      • TRI_FIRED_PINNED: Whether the tab is pinned.
      • TRI_FIRED_TITLE: The title of the tab.
      • TRI_FIRED_URL: The URL of the document that the tab is displaying.

      For example: autocmd DocStart .*example\.com.* zoom 150 false TRI_FIRED_MOZ_TABID.

      For debugging, use :set logging.autocmds debug and check the Firefox web console. WebRequest events have no logging.

    Returns Promise<void>

autocmddelete

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

    Parameters

    • event: string

      An event from autocmd

    • url: string

      Exactly the "url" you entered when you made the autocmd you wish to delete. See :viewconfig autocmds if you have forgotten.

    Returns Promise<void>

autocontain

  • autocontain(...args: string[]): Promise<void>
  • Automatically open a domain and all its subdomains in a specified container.

    NB: You should use this command with an -s (sane mode) or -u (URL mode) flag. Usage without a flag uses an incorrect regular expression which may cause weird behaviour and has been left in for compatibility reasons.

    This function accepts a -u flag to treat the pattern as a URL rather than a domain. For example: autocontain -u ^https?://([^/]*\.|)youtube\.com/ google is equivalent to autocontain -s youtube\.com google

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

    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 -s google.co.uk work will match google!co$uk. Escape your periods (i.e. \.) or accept that you might get some false positives.
    • You can use regex in your pattern. autocontain -s google\.(co\.uk|com) work will match either google.co.uk or google.com. If multiple rules match a certain URL, the one with the longest regex will be picked.

    This should now peacefully coexist with the Temporary Containers and Multi-Account Containers addons. Do not trust this claim. If a fight starts the participants will try to open infinite tabs. It is strongly recommended that you use a tridactylrc so that you can abort a sorceror's-apprentice scenario by killing firefox, commenting out all of autocontainer directives in your rc file, and restarting firefox to clean up the mess. There are a number of strange behaviors resulting from limited coordination between extensions. Redirects can be particularly surprising; for example, with :autocontain -s will-redirect.example.org example set and will-redirect.example.org redirecting to redirected.example.org, navigating to will-redirect.example.org will result in the new tab being in the example container under some conditions and in the firefox-default container under others.

    Pass an optional space-separated list of proxy names to assign a proxy (followed by failover proxies) to a URL and open in a specified container. For example: autocontain [-{u,s}] pattern container proxy1 proxy2

    To assign a proxy and open in no container, use "firefox-default" or "none" as a container name. See also:

    Parameters

    • Rest ...args: string[]

      a regex pattern to match URLs followed by the container to open the URL in followed by an optional space-separated list of proxy names.

    Returns Promise<void>

back

  • back(...args: string[]): void
  • Navigate back one page in history.

    Parameters

    • Rest ...args: string[]

    Returns void

bind

  • bind(...args: string[]): Promise<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 | tab # -> close current tab and switch to most recent previous tab
    • 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|ex|hint} ..., e.g, bind --mode=insert emacs qall (NB: unlike vim, all preceeding characters will not be input), or bind --mode=hint <C-[> hint.reset.

    bind --mode=browser [key sequence] [ex command] binds to a special mode which can be accessed all the time in all browser tabs - even tabs in which Tridactyl cannot run. It comes with a few caveats:

    • you may only have a few browser-mode binds at once. At the time of writing, this is 20, with 3 initially taken by Tridactyl. If you desperately need more, file an issue.
    • the key sequence must consist of a single, simple key with at least one and no more than two modifiers. An error will be thrown if you try to bind to an invalid key sequence.
    • the ex command you bind to may not work fully unless you are on a tab which Tridactyl has access to. Generally, browser-wide actions like making or closing tabs will work but tab-specific actions like scrolling down or entering hint mode will not.

    A list of editor functions can be found here.

    See also:

    Parameters

    • Rest ...args: string[]

    Returns Promise<void>

bindshow

  • bindshow(...args: string[]): Promise<any>

bindurl

  • bindurl(pattern: string, mode: string, keys: string, ...excmd: string[]): Promise<void>
  • Like bind but for a specific url pattern (also see seturl).

    Parameters

    • pattern: string

      Mandatory. The regex pattern on which the binding should take effect.

    • mode: string

      Optional. The mode the binding should be in (e.g. normal, insert, ignore, input). Defaults to normal.

    • keys: string

      Mandatory. The keys that should be bound.

    • Rest ...excmd: string[]

      Optional. Without it, will display what keys are bound to in mode.

    Returns Promise<void>

bindwizard

  • bindwizard(...args: string[]): Promise<void>
  • Generate a key sequence from keypresses. Once Enter is pressed, the command line is filled with a bind command with the key sequence and provided arguments, which you can choose to modify and execute.

    If you have :set keyboardlayoutforce true, it will bind commands to physical keys regardless of layout.

    Accepts the same arguments as bind (except for the key sequence which will be generated):

    • bindwizard [command], then press the keys you want to bind, then hit Enter.
    • bindwizard --mode=[mode] [command] also works.

    You can execute it without arguments to see what is bound to the keys you type.

    Parameters

    • Rest ...args: string[]

    Returns Promise<void>

blacklistadd

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

    Simply creates a DocStart autocmd that runs mode ignore. NB: ignore mode does have a few keybinds by default - see :viewconfig ignoremaps. These can be unbound with, e.g. :unbind --mode=ignore <C-o>, or :unbindurl [url] --mode=ignore <C-o>.

    Remove sites from the blacklist with blacklistremove [url] or autocmddelete DocStart [url].

    If you're looking for a way to temporarily disable Tridactyl, this might be what you're looking for. If you need to disable Tridactyl more thoroughly on a page look at :help superignore instead.

    Parameters

    • url: string

    Returns Promise<void>

bmark

  • bmark(url?: string, ...titlearr: string[]): Promise<BookmarkTreeNode>
  • 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<BookmarkTreeNode>

bmarks

  • bmarks(opt: string, ...urlarr: string[]): Promise<any>
  • Works exactly like open, but only suggests bookmarks.

    If you want to use optional flags, you should run :set completions.Bmark.autoselect false to prevent the spacebar from inserting the URL of the top bookmark.

    Parameters

    • opt: string

      Optional. Has to be -t in order to make bmarks open your bookmarks in a new tab.

    • Rest ...urlarr: string[]

      any argument accepted by open, or tabopen if opt is "-t" (e.g. -c [container] to open a bookmark in a container)

    Returns Promise<any>

changelistjump

  • changelistjump(): 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.

    Returns Promise<void>

clearsearchhighlight

  • clearsearchhighlight(): void

clipboard

  • clipboard(excmd?: "open" | "yank" | "yankshort" | "yankcanon" | "yanktitle" | "yankmd" | "yankorg" | "xselpaste" | "tabopen", ...toYank: string[]): Promise<any>
  • 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. yankorg is similar but for Emacs orgmode.

    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" | "yankorg" | "xselpaste" | "tabopen" = "open"
    • Rest ...toYank: string[]

    Returns Promise<any>

colourscheme

  • colourscheme(...args: string[]): Promise<any>
  • Changes the current theme.

    If THEMENAME is any of the themes that can be found in the Tridactyl repo (e.g. 'dark'), the theme will be loaded from Tridactyl's internal storage.

    If THEMENAME is set to any other value except --url, Tridactyl will attempt to use its native binary (see native) in order to load a CSS file named THEMENAME from disk. The CSS file has to be in a directory named "themes" and this directory has to be in the same directory as your tridactylrc. If this fails, Tridactyl will attempt to load the theme from its internal storage.

    Lastly, themes can be loaded from URLs with :colourscheme --url [url] [themename]. They are stored internally - if you want to update the theme run the whole command again.

    Note that the theme name should NOT contain any dot.

    Example: :colourscheme mysupertheme On linux, this will load ~/.config/tridactyl/themes/mysupertheme.css

    NB: due to Tridactyl's architecture, the theme will take a small amount of time to apply as each page is loaded. If this annoys you, you may use userContent.css to make changes to Tridactyl earlier. For example, users using the dark theme may like to put

    :root {
        --tridactyl-bg: black !important;
        --tridactyl-fg: white !important;
    }
    

    in their userContent.css. Follow issue #2510 if you would like to find out when we have made a more user-friendly solution.

    Parameters

    • Rest ...args: string[]

    Returns Promise<any>

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[]): Promise<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'

    Commands/aliases are expanded as in a shell, so, given the commands above, entering :tn 43 will expand to :tabnext_gt 43. You can use this to create your own ex-commands in conjunction with js, specifically js -p and js -d.

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

    If you wish to have a command that has semi-colons in it (e.g. some JavaScript or hint -;), first bind a command to it. For example, command hint_focus -;, and then composite hint_focus; !s xdotool key Menu.

    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(): Promise<Tab>
  • Display Tridactyl's contributors in order of commits in a user-friendly fashion

    Returns Promise<Tab>

drawingerasertoggle

  • drawingerasertoggle(): void
  • Switch between pen and eraser for drawingstart Suggested usage: bind e drawingerasertoggle. If you have a digital pen, map the button to e to switch easily.

    Returns void

drawingstart

  • drawingstart(): void
  • Drawable variant of no_mouse_mode In this mode, you can use the mouse or a digital stylus to draw. To switch to an eraser, use drawingerasertoggle Use mouse_mode to return, or refresh page. Suggested usage: `autocmd DocLoad .* drawingstart

    Warning: Windows Ink enabled input devices don't work, disable it for your browser, or use a mouse.

    Returns void

echo

  • echo(...str: string[]): string

editor

  • editor(): Promise<any>
  • 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 nativeinstall.

    Uses the editorcmd config option, default = auto looks through a list defined in lib/native.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. By default the filename is added to the end of editorcmd, if you require control over the position of that argument, the first occurrence of %f in editorcmd is replaced with the filename. %l, if it exists, is replaced with the line number of the cursor and %c with the column number. For example:

    set editorcmd terminator -u -e "vim %f '+normal!%lGzv%c|'"
    

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

    This function returns a tuple containing the path to the file that was opened by the editor and its content. This enables creating commands such as the following one, which deletes the temporary file created by the editor:

    alias editor_rm composite editor | jsb -p tri.native.run(`rm -f '${JS_ARG[0]}'`)
    bind --mode=insert <C-i> editor_rm
    bind --mode=input <C-i> editor_rm
    

    Returns Promise<any>

elementunhide

  • elementunhide(): Promise<void>
  • Restore the most recently hidden element. Repeated invocations restore the next-most-recently-hidden element.

    (Elements can be hidden with ;K and :hint -K.)

    Returns Promise<void>

escapehatch

  • escapehatch(): Promise<void>
  • Magic escape hatch: if Tridactyl can't run in the current tab, return to a tab in the current window where Tridactyl can run, making such a tab if it doesn't currently exist. If Tridactyl can run in the current tab, return focus to the document body from e.g. the URL bar or a video player.

    Only useful if called from a background context, e.g. at the end of an RC file to ensure that when you start the browser you don't get trapped on an about: page, or via bind --mode=browser escapehatch (bound to <C-,> by default).

    NB: when called via bind --mode=browser, we return focus from the address bar by opening and closing the "sidebar" (which is used exclusively for this purpose). If escapehatch is called in any other way, we cannot do this as Mozilla thinks it might spook you : ).

    This sidebar hack will close other sidebars such a TreestyleTabs. You can disable it with :set escapehatchsidebarhack false, but Tridactyl will no longer be able to get focus back from certain places such as the address bar.

    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're using exclaim with arguments coming from a pipe, consider using shellescape to properly escape arguments and to prevent unsafe commands.

    If you want to use a different shell, just prepend your command with whatever the invocation is and keep in mind 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>

extoptions

  • extoptions(...optionNameArgs: string[]): Promise<any>
  • Opens optionsUrl for the selected extension in a popup window.

    NB: Tridactyl cannot run on this page!

    Parameters

    • Rest ...optionNameArgs: string[]

    Returns Promise<any>

fillcmdline

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

    Parameters

    • Rest ...strarr: string[]

    Returns Promise<any>

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[]): Promise<any>
  • Set the current value of the commandline to string without a trailing space

    Parameters

    • Rest ...strarr: string[]

    Returns Promise<any>

fillcmdline_tmp

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

    Parameters

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

    Returns Promise<void>

fillinput

  • fillinput(selector: string, ...content: string[]): 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 used to be 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 void

find

  • find(...args: string[]): Promise<void>
  • Rudimentary find mode, left unbound by default as we don't currently support incsearch. Suggested binds:

     bind / fillcmdline find
     bind ? fillcmdline find --reverse
     bind n findnext --search-from-view
     bind N findnext --search-from-view --reverse
     bind gn findselect
     bind gN composite findnext --search-from-view --reverse; findselect
     bind ,<Space> nohlsearch
    

    Argument: A string you want to search for.

    This function accepts two flags: -? or --reverse to search from the bottom rather than the top and -: n or --jump-to n to jump directly to the nth match.

    The behavior of this function is affected by the following setting:

    findcase: either "smart", "sensitive" or "insensitive". If "smart", find will be case-sensitive if the pattern contains uppercase letters.

    Known bugs: find will currently happily jump to a non-visible element, and pressing n or N without having searched for anything will cause an error.

    Parameters

    • Rest ...args: string[]

    Returns Promise<void>

findnext

  • findnext(...args: string[]): Promise<void>
  • Jump to the next nth searched pattern.

    Available flags:

    • -f or --search-from-view to search from the current view instead of the previous match
    • -? or --reverse to reverse the sign of the number

    Parameters

    • Rest ...args: string[]

    Returns Promise<void>

findselect

  • findselect(): void
  • Highlight the current find-mode match result and enter the visual mode.

    Returns void

firefoxsyncpull

  • firefoxsyncpull(): Promise<void>
  • Replaces your local configuration with that stored in the Firefox Sync area.

    It does not merge your configurations: it overwrites.

    Also see firefoxsyncpush.

    Returns Promise<void>

firefoxsyncpush

  • firefoxsyncpush(): Promise<void>
  • Pushes your local configuration to the Firefox Sync area.

    It does not merge your configurations: it overwrites.

    Also see firefoxsyncpull.

    Returns Promise<void>

fixamo

  • fixamo(): Promise<void>
  • Used to simply set

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

    Removed at the request of the Firefox Security team. Replacements exist in our exemplar RC file.

    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(...args: string[]): void
  • Navigate forward one page in history.

    Parameters

    • Rest ...args: string[]

    Returns void

fullscreen

  • fullscreen(): Promise<Window>

get

  • get(...keys: string[]): any
  • 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 any

getclip

  • getclip(from?: "clipboard" | "selection"): Promise<string>
  • Fetches the content of the clipboard/selection buffer depending on user's preferences

    Exposed for use with composite, e.g. composite getclip | fillcmdline

    Parameters

    • Optional from: "clipboard" | "selection"

    Returns Promise<string>

gobble

  • gobble(numKeysOrTerminator: string, endCmd: string, ...args: string[]): Promise<void>
  • Initialize gobble mode.

    If numKeysOrTerminator is a number, it will read the provided amount of keys; If numKeysOrTerminator is a key or key combination like 'k', '' or ''; it will read keys until the provided key is pressed. Then it will append the keypresses to endCmd and execute that string, also appending arguments if provided.

    Parameters

    • numKeysOrTerminator: string
    • endCmd: string
    • Rest ...args: string[]

    Returns Promise<void>

goto

  • goto(...selector: string[]): Promise<void>
  • Jump to selector.

    Parameters

    • Rest ...selector: 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).

    Also flips the preference toolkit.legacyUserProfileCustomizations.stylesheets to true so that FF will read your userChrome.

    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
    • statuspanel (hoverlink + the indicator that appears when a website is loading)

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

    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(...helpItems: string[]): Promise<any>
  • Show this page.

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

    On the ex command page, 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, a "go" excmd that does something else and a "go" setting that does a third thing), the binding is chosen first, then the setting, then the excmd. In such situations, if you want to let Tridactyl know you're looking for something specfic, you can specify the following flags as first arguments:

    -a: look for an alias -b: look for a binding -e: look for an ex command -s: look for a setting

    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 no way to display these HTML tooltips from the keyboard.

    e.g. :help bind

    Parameters

    • Rest ...helpItems: string[]

    Returns Promise<any>

hint

  • hint(...args: string[]): Promise<any>
  • Hint a page.

    Parameters

    • Rest ...args: string[]

      Arguments to the :hint command. Multiple flags can be combined as long as they don't conflict. Selectors can be specified either standalone (without a flag preceding them) or with the -c option. Arguments that take callbacks (-F or -W) should be specified last, as they consume the rest of the command line.

      Hinting action flags (only one can be specified):

      • -t open in a new foreground tab
      • -b open in background
      • -y copy (yank) link's target to clipboard
      • -p copy an element's text to the clipboard
      • -h select an element (as if you click-n-dragged over it)
      • -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 irreversibly deletes an element from the page (until reload)
      • -K hides an element on the page; hidden elements can be restored using elementunhide.
      • -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 and set it as the element or the child of the element to scroll
      • -# yank an element's anchor URL to clipboard
      • -w open in new window
      • -wp open in new private window
      • -z scroll an element to the top of the viewport
      • -pipe selector key e.g, -pipe a href returns the URL of the chosen link on a page. Only makes sense with composite, e.g, composite hint -pipe .some-class>a textContent | yank. If you don't select a hint (i.e. press ), will return an empty string. Most useful when used like -c to do things other than opening links. NB: the query selector cannot contain any spaces.
      • -W excmd... append hint href to excmd and execute, e.g, hint -W mpvsafe to open YouTube videos. NB: appending to bare exclaim is dangerous - see get exaliases.mpvsafe for an example of how to to it safely. If you need to use a query selector, use -pipe instead.
      • -F [callback] - run a custom callback on the selected hint, e.g. hint -JF e => {tri.excmds.tabopen("-b",e.href); e.remove()}.

      Element selection flags:

      • -c [selector] hint links that match the css selector
      • bind ;c hint -c [class*="expand"],[class="togg"] works particularly well on reddit and HN
      • this works with most other hint modes, with the caveat that if other hint mode takes arguments your selector must contain no spaces, i.e. hint -c[yourOtherFlag] [selector] [your other flag's arguments, which may contain spaces]
      • -x [selector] exclude the matched elements from hinting
      • -f [text] hint links and inputs that display the given text
      • bind <c-e> hint -f Edit
      • Backslashes can escape spaces: bind <c-s> hint -f Save\ as
      • -fr [text] use RegExp to hint the links and inputs
      • -J* disable javascript hints. Don't generate hints related to javascript events. This is particularly useful when used with the -c option when you want to generate only hints for the specified css selectors. Also useful on sites with plenty of useless javascript elements such as google.com
      • -V create hints for invisible elements. By default, elements outside the viewport when calling :hint are not hinted, this includes them anyways.

      Hinting mode selection:

      • -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).
      • For example, use bind ;jg hint -Jc .rc > .r > a on google.com to generate hints only for clickable search results of a given query
      • -! execute all hints without waiting for a selection
      • For example, hint -!bf Comments opens in background tabs all visible links whose text matches Comments

      Deprecated options:

      • -br deprecated, use -qb instead

      Excepting the custom selector mode, background hint mode and the "immediate" modifier, 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.

      Ex-commands available exclusively in hint mode are listed here

      Related settings:

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

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

      There are some extra hint "modes" that are actually just normal-mode binds. We'll list them here:

      • ;gv - "open link in MPV" - only available if you have native installed and mpv on your PATH
      • ;m and ;M - do a reverse image search using Google in the current tab and a new tab
      • ;x and ;X - move cursor to element and perform a real click or ctrl-shift-click (to open in a new foreground tab). Only available on Linux, if you have native installed and xdotool on your PATH
      • ;d and ;gd - open links in discarded background tabs (defer loading until tab is switched to)

      NB: by default, hinting respects whether links say they should be opened in new tabs (i.e. target=_blank). If you wish to override this you can use :hint -JW open to force the hints to open in the current tab. JavaScript hints (grey ones) will always open wherever they want, but if you want to include these anyway you can use :hint -W open.

    Returns Promise<any>

home

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

    Parameters

    • Default value all: "false" | "true" = "false"
      • if "true", opens all homepages in new tabs
      • if "false" or not given, opens the last homepage in the current tab

    Returns Promise<any>

issue

  • issue(): Promise<Tab>

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`
    

    Parameters

    • Rest ...str: string[]

    Returns Promise<any>

    Last value of the JavaScript statement

    Usage:

       `js [-p] javascript code ... [arg]`
    
       `js [-s|-r|-p] javascript_filename [arg]`
    
    • options
      • -p pass an argument to js for use with composite. The argument is passed as the last space-separated argument of js, i.e. str[str.length-1] and stored in the magic variable JS_ARG - see below for example usage.
    • d[delimiter character] to take a space-separated array of arguments after the delimiter, stored in the magic variable JS_ARGS (which is an array).
      • -s load the js source from a Javascript file.
      • -r load the js source from a Javascript file relative to your RC file. (NB: will throw an error if no RC file exists)

    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 or "-d" flag with an argument and then use the JS_ARG global variable, e.g:

    `composite get_current_url | js -p alert(JS_ARG)`
    

    To run JavaScript from a source file:

    `js -s ~/JSLib/my_script.js`
    

    To run a JavaScript file relative to your RC file, e.g. ~/.config/tridactyl/sample.js

    `js -r sample.js`
    

    js executes JavaScript in local scope. If you want to reuse the code in other :js calls, you can add your functions or variables into a global namespace, like window. or tri., e.g.:

    `js tri.hello = function (){ alert("hello world!") };`
    `js tri.hello()`
    

    You can use -d to make your own ex-commands:

     `command loudecho js -dwindow.alert(JS_ARGS.join(" "))€`
    

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 which has access to more excmds and web-extension APIs.

    Parameters

    • Rest ...str: string[]

    Returns Promise<any>

jsonview

  • jsonview(...json: string[]): Promise<any[]>
  • View a JSON object in Firefox's JSON viewer.

    Parameters

    • Rest ...json: string[]

    Returns Promise<any[]>

jsua

  • jsua(): Promise<void>
  • Like jsb but preserves "user action" intent for use with certain web extension APIs. Can only be called with browser mode binds, e.g.

    :bind --mode=browser <C-.> jsua browser.sidebarAction.open(); tri.excmds.sidebaropen("https://mail.google.com/mail/mu")

    Returns Promise<void>

jumble

  • jumble(): void

jumpnext

  • jumpnext(n?: number): Promise<void>

jumpprev

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

    When you scroll on a page, either by using the mouse or Tridactyl's key bindings, your position in the page will be saved after jumpdelay milliseconds (:get jumpdelay to know how many milliseconds that is). If you scroll again, you'll be able to go back to your previous position by using :jumpprev 1. If you need to go forward in the jumplist, use :jumpprev -1.

    Known bug: Tridactyl will use the same jumplist for multiple visits to a same website in the same tab, see github issue 834.

    Parameters

    • Default value n: number = 1

    Returns Promise<void>

keyfeed

  • keyfeed(mapstr: string): Promise<void>
  • Feed some keys to Tridactyl's parser. E.g. keyfeed jkjkjkjkjkjkjkjkjkjkjkjkjkjkjkjkjkjkjkjkjkjjkj.

    NB:

    • Does not function like Vim's noremap - bind j keyfeed j will cause an infinite loop.
    • Doesn't work in exmode - i.e. keyfeed t<CR> won't work.

    Parameters

    • mapstr: string

    Returns Promise<void>

keymap

  • keymap(source: string, target: string): any

markadd

  • markadd(key: string): Promise<void>
  • Adds a global or a local mark. In case of a local mark, it will be assigned to the current page url. If a mark is already assigned, it is overwritten.

    Parameters

    • key: string

      the key associated with the mark

    Returns Promise<void>

markaddglobal

  • markaddglobal(key: string): Promise<void>
  • Assigns a global mark to the given key. If a mark is already assigned, it is overwritten. Global marks are persisted between browser restarts.

    Parameters

    • key: string

    Returns Promise<void>

markaddlocal

  • markaddlocal(key: string): Promise<void>
  • Assigns a local mark to the current url and the given key. If a mark is already assigned, it is overwritten. Two urls are considered the same if they're identical ignoring anchors. Local marks are not persisted between browser restarts.

    Parameters

    • key: string

    Returns Promise<void>

markjump

  • markjump(key: string): Promise<void>
  • Jumps to a local mark, a global mark, or the location before the last mark jump. [a-z] are local marks, [A-Z] are global marks and '`' is the location before the last mark jump.

    Parameters

    • key: string

      the key associated with the mark

    Returns Promise<void>

markjumpbefore

  • markjumpbefore(): Promise<void>
  • Jumps to a location saved before the last mark jump as long as the tab it's located in exists and its url didn't change. Overwrites the location before the last mark jump - repeating this method will jump back and forth between two locations.

    Returns Promise<void>

markjumpglobal

  • markjumpglobal(key: string): Promise<void>
  • Jumps to a global mark. If the tab with the mark no longer exists or its url differs from the mark's url, jumps to another tab with the mark's url or creates it first if such tab does not exist.

    Parameters

    • key: string

      the key associated with the mark

    Returns Promise<void>

markjumplocal

  • markjumplocal(key: string): Promise<void>
  • Jumps to a local mark.

    Parameters

    • key: string

      the key associated with the mark

    Returns Promise<void>

mktridactylrc

  • mktridactylrc(...args: string[]): Promise<string | void>
  • Writes current config to a file.

    NB: an RC file is not required for your settings to persist: all settings are stored in a local Firefox storage database by default as soon as you set them.

    With no arguments supplied the excmd will try to find an appropriate config path and write the rc file to there. Any argument given to the excmd excluding the -f flag will be treated as a path to write the rc file to relative to the native messenger's location (~/.local/share/tridactyl/). By default, it silently refuses to overwrite existing files.

    The RC file will be split into sections that will be created if a config property is discovered within one of them:

    • General settings
    • Binds
    • Aliases
    • Autocmds
    • Autocontainers
    • Logging

    Note:

    • Subconfig paths fall back to using js tri.config.set(key: obj) notation.
    • This method is also used as a fallback mechanism for objects that didn't hit any of the heuristics.

    Available flags:

    • -f will overwrite the config file if it exists.
    • --clipboard write config to clipboard - no native required

    Parameters

    • Rest ...args: string[]

      an optional string of arguments to be parsed.

    Returns Promise<string | void>

    the parsed config.

mode

  • Switch mode.

    For now you probably shouldn't manually switch to other modes than normal and ignore. Make sure you're aware of the key bindings (ignoremaps) that will allow you to go come back to normal mode from ignore mode before you run :mode ignore otherwise you're going to have a hard time re-enabling Tridactyl.

    Example: - mode ignore to ignore almost all keys.

    If you're looking for a way to temporarily disable Tridactyl, mode ignore might be what you're looking for.

    Note that when in ignore mode, Tridactyl will not switch to insert mode when focusing text areas/inputs. This is by design.

    New feature: you can add modes as simply as adding binds with bind --mode=[newmodename] and then enter the mode with mode [newmodename].

    Parameters

    Returns void

mouse_mode

  • mouse_mode(): void

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<any>

nativeinstall

  • nativeinstall(): Promise<any>

nativeopen

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

    Be seriously careful with this:

    1. the implementation basically execs firefox --new-tab <your shell escaped string here>
    2. you can use it to open any URL you can open in the Firefox address bar, including ones that might cause side effects (firefox does not guarantee that about: pages ignore query strings).

    You've been warned.

    This uses the browser setting to know which binary to call. If you need to pass additional arguments to firefox (e.g. '--new-window'), make sure they appear before the url.

    Parameters

    • Rest ...args: string[]

    Returns Promise<void>

neo_mouse_mode

  • neo_mouse_mode(): void
  • Matrix variant of no_mouse_mode

    "There is no mouse".

    Coincidentally added to Tridactyl at the same time as we reached 1337 stars on GitHub.

    Returns void

nmode

  • nmode(mode: string, n: number, ...endexArr: string[]): Promise<void>
  • Initialize n [mode] mode.

    In this special mode, a series of key sequences are executed as bindings from a different mode, as specified by the mode argument. After the count of accepted sequences is n, the finalizing ex command given as the endexArr argument is executed, which defaults to mode ignore.

    Example: :nmode normal 1 mode ignore This looks up the next key sequence in the normal mode bindings, executes it, and switches the mode to ignore. If the key sequence does not match a binding, it will be silently passed through to Firefox, but it will be counted for the termination condition.

    Parameters

    • mode: string
    • n: number
    • Rest ...endexArr: string[]

    Returns Promise<void>

no_mouse_mode

  • no_mouse_mode(): void
  • Hides the cursor and covers the current page in an overlay to prevent clicking on links with the mouse to force yourself to use hint mode.

    To bring back mouse control, use mouse_mode or refresh the page.

    Suggested usage: autocmd DocLoad .* no_mouse_mode

    "There is no mouse".

    Returns void

open

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

    Parameters

    • Rest ...urlarr: string[]
      • 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 searchengine

      Related settings: searchengine, historyresults

      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.

    Returns Promise<any>

open_quiet

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

    Parameters

    • Rest ...urlarr: string[]

    Returns Promise<any>

parseWinTabIndex

  • parseWinTabIndex(id: string): Promise<number[]>
  • Given a string of the format windowIndex.tabIndex, returns a tuple of numbers corresponding to the window index and tab index or the current window and tab if the string doesn't have the right format.

    Parameters

    • id: string

    Returns Promise<number[]>

perfdump

  • perfdump(...filters: string[]): Promise<any>
  • Dump the raw json for our performance counters. Filters with trailing slashes are class names, :start | :end | :measure specify what type of sample to pass through, and all others are function names. All filters must match for a sample to be dumped.

    Tridactyl does not collect performance information by default. To get this data you'll have to set the configuration option perfcounters to "true". You may also want to examine the value of perfsamples.

    Parameters

    • Rest ...filters: string[]

    Returns Promise<any>

perfhistogram

  • perfhistogram(...filters: string[]): Promise<any>
  • Pretty-print a histogram of execution durations for you. Arguments are as above, with the addition that this automatically filters to counter samples of type :measure.

    Note that this will display its output by opening a data: url with text in the place of your current tab.

    Parameters

    • Rest ...filters: string[]

    Returns Promise<any>

pied_piper_mouse_mode

  • pied_piper_mouse_mode(): void

pin

  • pin(): Promise<Tab>

proxyadd

  • proxyadd(name: string, url: string): Promise<void>
  • Add a proxy for use with autocontain or :set proxy

    Parameters

    • name: string

      The name of the proxy you want to set

    • url: string

      The proxy URL. List of supported protcols are "http", "https" or equivalently "ssl", "socks5" or equivalently "socks" and "socks4".

      Examples:

      • proxyadd work https://admin:[email protected]:1337
      • proxyadd kyoto socks://10.0.100.10:1080?proxyDNS=false
      • proxyadd alice socks4://10.0.100.10:3128

      These proxy settings are used by autocontainers. See autocontain

    Returns Promise<void>

proxyremove

  • proxyremove(name: string): void
  • Remove proxies.

    Parameters

    • name: string

      The proxy name that should be removed.

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

    Example:

    • quickmark m https://mail.google.com/mail/u/0/#inbox

    Parameters

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

    Returns Promise<void>

reader

  • reader(...args: string[]): Promise<void>
  • Open the current page as an article in reader view for easier reading. Flags --tab and --window open the article in new tabs and windows respectively.

    Use :reader --old to use Firefox's built-in reader mode, which Tridactyl can't run on.

    NB: the reader page is a privileged environment which has access to all Tridactyl functions, notably the native messenger if you have it installed. We are parsing untrusted web-content to run in this environment. Mozilla's readability library will strip out most of these, then we use a sanitation library, js-xss, to strip out any remaining unsafe tags, but if there was a serious bug in this library, and a targeted attack against Tridactyl, an attacker could get remote code execution. If you're worried about this, use :reader --old instead or only use :reader on pages you trust.

    You may use userContent.css to enhance or override default styling of the new reader view. The body of the page has id tridactyl-reader and the article content follows in a main tag. Therefore to alter default styling, you can do something like this in your userContent.css:

    #tridactyl-reader > main {
      width: 80vw !important;
      text-align: left;
    }
    

    Follow issue #4657 if you would like to find out when we have made a more user-friendly solution.

    Parameters

    • Rest ...args: string[]

    Returns Promise<void>

recontain

  • recontain(containerName: string): 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[]>

reloadallbut

  • reloadallbut(hard?: boolean): Promise<void[]>
  • Reloads all tabs except the current one, bypassing the cache if hard is set to true You probably want to use reloaddead instead if you just want to be able to ensure Tridactyl is loaded in all tabs where it can be

    Parameters

    • Default value hard: boolean = false

    Returns Promise<void[]>

reloaddead

  • reloaddead(hard?: boolean): Promise<void[]>
  • Reloads all tabs which Tridactyl isn't loaded in

    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[]>

removepref

  • removepref(key: string): Promise<void>
  • Remove a setting from your user.js file.

    Parameters

    • key: string

      The key that should be set. Must not be quoted. Must not contain spaces.

    Returns Promise<void>

repeat

  • repeat(n?: number, ...exstr: string[]): Promise<void>
  • Repeats a cmd n times. If cmd doesn't exist, re-executes the last exstr that was executed in the tab. Executes the command once if n isn't defined either.

    This re-executes the last exstr, not the last excmd. Some excmds operate internally by constructing and evaluating exstrs, others by directly invoking excmds without going through the exstr parser. For example, aucmds and keybindings evaluate exstrs and are repeatable, while commands like :bmarks directly invoke :tabopen and you'll repeat the :bmarks rather than the internal :tabopen.

    It's difficult to execute this in the background script (:jsb, :run_excmd, :autocmd TriStart, :source), but if you you do, it will re-execute the last exstr that was executed in the background script. What this may have been is unpredictable and not precisely encouraged.

    Parameters

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

    Returns Promise<void>

reset

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

    Parameters

    • mode: string

      Optional. The mode the key should be reset in. Defaults to normal.

    • key: string

      The key that should be reset.

      See also:

    Returns Promise<void>

reseturl

  • reseturl(pattern: string, mode: string, key: string): 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>

rot13

  • rot13(n: number): void
  • Perform rot13.

    Transforms all text nodes in the current tab via rot13. Only characters in the ASCII range are considered.

    Parameters

    • n: number

      number of characters to shift.

    Returns void

rssexec

  • rssexec(url: string, type?: string, ...title: string[]): Promise<any>
  • Execute rsscmd for an rss link.

    If url is undefined, Tridactyl will look for rss links in the current page. If it doesn't find any, it will display an error message. If it finds multiple urls, it will offer completions in order for you to select the link you're interested in. If a single rss feed is found, it will automatically be selected.

    Parameters

    • url: string
    • Optional type: string
    • Rest ...title: string[]

    Returns Promise<any>

run_exstr

  • run_exstr(...commands: string[]): Promise<any>
  • Hacky ex string parser.

    Use it for fire-and-forget running of background commands in content.

    Parameters

    • Rest ...commands: string[]

    Returns Promise<any>

sanitise

  • sanitise(...args: string[]): Promise<void>
  • Deletes various bits of Firefox or Tridactyl data

    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, including any saved usernames / passwords(!)
    • 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>

saveas

  • saveas(...args: string[]): Promise<any>
  • Download the current document.

    If you have the native messenger v>=0.1.9 installed, the function accepts an optional argument, filename, which can be:

    • An absolute path
    • A path starting with ~, which will be expanded to your home directory
    • A relative path, relative to the native messenger executable (e.g. ~/.local/share/tridactyl on linux). If filename is not given, a download dialogue will be opened. If filename is a directory, the file will be saved inside of it, its name being inferred from the URL. If the directories mentioned in the path do not exist or if a file already exists at this path, the file will be kept in your downloads folder and an error message will be given.

    NB: if a non-default save location is chosen, Firefox's download manager will say the file is missing. It is not - it is where you asked it to be saved.

    Flags:

    • --overwrite: overwrite the destination file.
    • --cleanup: removes the downloaded source file e.g. $HOME/Downlods/downloaded.doc if moving it to the desired directory fails.

    Parameters

    • Rest ...args: string[]

    Returns Promise<any>

scrollline

  • scrollline(n?: number, mult?: number): Promise<boolean>
  • 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
    • Default value mult: number = 1

    Returns Promise<boolean>

scrollpage

  • scrollpage(n?: number, count?: number): Promise<any>
  • Scrolls the document by n pages. The height of a page is the current height of the window.

    Parameters

    • Default value n: number = 1
    • Default value count: number = 1

      How many times to scroll. Used to facilitate key binds with counts for <C-F> etc., not really useful otherwise.

    Returns Promise<any>

scrollpx

  • scrollpx(a: number, b: number): Promise<any>
  • 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<any>

scrolltab

  • scrolltab(tabId: number, scrollX: number, scrollY: number, message: string): Promise<void>
  • Scrolls to a given position in a tab identified by tabId and prints a message in it.

    Parameters

    • tabId: number
    • scrollX: number
    • scrollY: number
    • message: string

    Returns Promise<void>

scrollto

  • scrollto(a: number | string, b?: number | "x" | "y"): Promise<any>
  • 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. If the number has 'c' appended to it, it will be interpreted in radians.

    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.

    Examples:

    • scrollto 50 -> scroll halfway down the page.
    • scrollto 3.14c -> scroll approximately 49.97465213% of the way down the page.

    Parameters

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

    Returns Promise<any>

set

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

    Use to set any values found here.

    Arrays should be set using JS syntax, e.g. :set blacklistkeys ["/",","].

    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.

    See also: unset

    Parameters

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

    Returns any

setmode

  • setmode(mode: string, key: string, ...values: string[]): Promise<void>
  • Usage: setmode mode key values

    Parameters

    • mode: string

      The Mode the setting should be set for, e.g. insert or ignore.

    • key: string

      The name of the setting you want to set, e.g. allowautofocus

    • Rest ...values: string[]

      The value you wish for, e.g. true

      Currently this command is only supported for the following settings:

      Example:

      • setmode ignore allowautofocus true

    Returns Promise<void>

setnull

  • setnull(...keys: string[]): Promise<void>
  • "Delete" a default setting. E.g. setnull searchurls.github means open github test would search your default search engine for "github test".

    Parameters

    • Rest ...keys: string[]

    Returns Promise<void>

setpref

  • setpref(key: string, ...value: string[]): Promise<void>
  • Write a setting to your user.js file. Requires a restart after running to take effect.

    Parameters

    • key: string

      The key that should be set. Must not be quoted. Must not contain spaces.

    • Rest ...value: string[]

      The value the key should take. Quoted if a string, unquoted otherwise.

      Note that not all of the keys Firefox uses are suggested by Tridactyl.

      e.g.: setpref general.warnOnAboutConfig false

    Returns Promise<void>

seturl

  • seturl(pattern: string, key: string, ...values: string[]): Promise<void>
  • Usage: seturl [pattern] key values

    Parameters

    • pattern: string

      The URL regex pattern the setting should be set for, e.g. ^https://en.wikipedia.org or /index.html. Defaults to the current url if values is a single word.

    • key: string

      The name of the setting you want to set, e.g. followpagepatterns.next

    • Rest ...values: string[]

      The value you wish for, e.g. next

      Example:

      • seturl .*\.fr followpagepatterns.next suivant
      • seturl website.fr followpagepatterns.next next

      When multiple patterns can apply to a same URL, the pattern that has the highest priority is used. You can set the priority of a pattern by using :seturl pattern priority 10. By default every pattern has a priority of 10.

      Note that the patterns a regex-like, not glob-like. This means that if you want to match everything, you need to use .* instead of *.

      If you'd like to run an ex-command every time a page loads, see autocmd instead.

    Returns Promise<void>

shellescape

  • shellescape(...quoteme: string[]): Promise<string>
  • Escape command for safe use in shell with composite. E.g: composite js MALICIOUS_WEBSITE_FUNCTION() | shellescape | exclaim ls

    Parameters

    • Rest ...quoteme: string[]

    Returns Promise<string>

sidebaropen

  • sidebaropen(...urllike: string[]): Promise<void>
  • EXPERIMENTAL: like open but loads queries in the sidebar. Doesn't actually open the sidebar - see sidebartoggle.

    Not all schemas are supported, such as about:* and Firefox's built-in search engines. Tridactyl's searchurls and jsurls work fine - :set searchengine google will be sufficient for most users.

    If you try to open the command line in the sidebar things will break.

    Parameters

    • Rest ...urllike: string[]

    Returns Promise<void>

sidebartoggle

  • sidebartoggle(): Promise<void>
  • Toggle the side bar. Can only be called through browser mode binds, e.g.

    :bind --mode=browser <C-.> sidebartoggle

    Returns Promise<void>

sleep

  • sleep(time_ms: number): Promise<unknown>
  • 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<unknown>

snow_mouse_mode

  • snow_mouse_mode(): void

source

  • source(...args: string[]): Promise<void>
  • Runs an RC file from disk or a URL

    This function accepts a flag: --url to load a RC from a URL.

    If no argument given, it will try to open ~/.tridactylrc, ~/.config/tridactyl/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.

    If no url is specified with the --url flag, the current page's URL is used to locate the RC file. Ensure the URL you pass (or page you are on) is a "raw" RC file, e.g. https://raw.githubusercontent.com/tridactyl/tridactyl/master/.tridactylrc and not https://github.com/tridactyl/tridactyl/blob/master/.tridactylrc.

    Tridactyl won't run on many raw pages due to a Firefox bug with Content Security Policy, so you may need to use the source --url [URL] form.

    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. There's an example file if you want it.

    There is a bug where not all lines of the RC file are executed if you use sanitise at the top of it. We instead recommend you put :bind ZZ composite sanitise tridactyllocal; qall in your RC file and use ZZ to exit Firefox.

    Parameters

    • Rest ...args: string[]

      the file/URL to open. For files: must be an absolute path, but can contain environment variables and things like ~.

    Returns Promise<void>

source_quiet

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

    Parameters

    • Rest ...args: string[]

    Returns Promise<void>

tab

  • tab(...id: string[]): Promise<any>
  • Change active tab.

    Parameters

    • Rest ...id: string[]

      A bare number means the current window is used. Starts at 1. 0 refers to last tab of the current window, -1 to penultimate tab, etc.

      A string following the following format: "[0-9]+.[0-9]+" means 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. taball has completions for this format.

      "%" denotes the current tab and "#" denotes the tab that was last accessed in this window. "P", "A", "M" and "D" indicate tab status (i.e. a pinned, audible, muted or discarded tab). Use :set completions.Tab.statusstylepretty true to display unicode characters instead. "P","A","M","D" can be used to filter by tab status in either setting.

      A non integer string means to search the URL and title for matches, in this window if called from tab, all windows if called from taball. Title matches can contain '*' as a wildcard.

    Returns Promise<any>

tab_helper

  • tab_helper(interactive: boolean, anyWindow: boolean, ...key: string[]): Promise<any>
  • Helper to change active tab. Used by tab and taball.

    Parameters

    • interactive: boolean

      Controls if we should prompt if multiple matches are found, or just pick the first match

    • anyWindow: boolean

      True if we should search in all windows, or just the current one.

    • Rest ...key: string[]

      String or int tab search key, see tab for usage.

    Returns Promise<any>

taball

  • taball(...id: string[]): Promise<any>
  • Wrapper for tab with multi-window completions

    Parameters

    • Rest ...id: string[]

    Returns Promise<any>

tabaudio

  • tabaudio(): Promise<Tab>
  • Switch to the tab currently playing audio, if any.

    Returns Promise<Tab>

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>

tabcloseallto

  • tabcloseallto(side: string): Promise<void>
  • Close all tabs to the side specified

    Parameters

    • side: string

    Returns Promise<void>

tabdetach

  • tabdetach(index?: number): Promise<Window>
  • 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<Window>

tabduplicate

  • tabduplicate(index?: number): Promise<Tab>
  • 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<Tab>

tabgrab

  • tabgrab(id: string): Promise<Tab | Tab[]>
  • Moves a tab identified by a windowIndex.tabIndex id to the current window. Only works for windows of the same type (can't grab a non-private tab from a private window and can't grab a private tab from a non-private window).

    Parameters

    • id: string

    Returns Promise<Tab | Tab[]>

tabmove

  • tabmove(index?: string): Promise<Tab | Tab[]>
  • 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<Tab | Tab[]>

tabnext

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

    If increment is specified, move that many tabs forwards.

    Parameters

    • Default value increment: number = 1

    Returns Promise<Tab>

tabnext_gt

  • tabnext_gt(index?: number): Promise<any>
  • 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<any>

tabonly

  • tabonly(): Promise<void>

tabopen

  • tabopen(...addressarr: string[]): Promise<Tab>
  • 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 (opening the tab in no container can be enforced with "firefox-default" or "none"). If any autocontainer directives are configured and -c is not set, Tridactyl will try to use the right container automatically using your configurations.

    Use the -b flag to open the tab in the background.

    Use the -w flag to wait for the web page to load before "returning". This only makes sense for use with composite, which waits for each command to return before moving on to the next one, e.g. composite tabopen -b -w news.bbc.co.uk ; tabnext.

    The special flag "--focus-address-bar" should focus the Firefox address bar after opening if no URL is provided.

    These three 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

    Also see the searchengine and searchurls settings.

    Parameters

    • Rest ...addressarr: string[]

    Returns Promise<Tab>

tabopenwait

  • tabopenwait(...addressarr: string[]): Promise<Tab>
  • Like tabopen but waits for the DOM to load before resolving its promise. Useful if you're hoping to execute ex-commands in that tab.

    Parameters

    • Rest ...addressarr: string[]

    Returns Promise<Tab>

tabprev

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

    If increment is specified, move that many tabs backwards.

    Parameters

    • Default value increment: number = 1

    Returns Promise<Tab>

tabpush

  • tabpush(windowId?: number): Promise<Tab | Tab[]>
  • Pushes the current tab to another window. Only works for windows of the same type (can't push a non-private tab to a private window or a private tab to a non-private window). If windowId is not specified, pushes to the next newest window, wrapping around.

    Parameters

    • Optional windowId: number

    Returns Promise<Tab | Tab[]>

tabqueue

  • tabqueue(...addresses: string[]): Promise<unknown>
  • Passes its first argument to tabopen -b. Once the tab opened by tabopen -b is activated/selected/focused, opens its second argument with tabopen -b. Once the second tab is activated/selected/focused, opens its third argument with tabopen -b and so on and so forth until all arguments have been opened in a new tab or until a tab is closed without being activated/selected/focused.

    Example usage: tabqueue http://example.org http://example.com http://example.net composite hint -qpipe a href | tabqueue

    Parameters

    • Rest ...addresses: string[]

    Returns Promise<unknown>

tabrename

  • tabrename(index: string, ...name: string[]): Promise<any>
  • Rename a tab.

    Parameters

    • index: string

      Index of the target tab.

    • Rest ...name: string[]

      Tab name.

    Returns Promise<any>

tabsort

  • tabsort(...callbackchunks: string[]): Promise<void>

text2qr

  • text2qr(...args: string[]): Promise<void>
  • Generates a QR code for the given text. By default opens in new tab. Default binds close the new tab after 5 seconds. If no text is passed as an argument then it checks if any text is selected and creates a QR code for that. If no selection is found then it creates QR code for the current tab's URL

    text2qr --popup [...] will open the QR code in a new popup window

    text2qr --window [...] will open the QR code in a new window

    text2qr --current [...] will open in the current tab

    text2qr --timeout <timeout in seconds> [...] closes the tab/window/popup after specified number of seconds

    Example: text2qr --timeout 5 --popup hello world

    Parameters

    • Rest ...args: string[]

    Returns Promise<void>

tgroupabort

  • tgroupabort(): Promise<any>
  • Delete all tab group information for the current window and show all tabs.

    Returns Promise<any>

tgroupclose

  • tgroupclose(name?: string): Promise<string>
  • Close all tabs in a tab group and delete the group.

    Parameters

    • Optional name: string

      The name of the tab group to close. If not specified, close the current tab group and switch to the previously active tab group.

      Do nothing if there is only one tab group - to discard all tab group information, use tgroupabort.

    Returns Promise<string>

tgroupcreate

  • tgroupcreate(name: string): Promise<string>
  • Create a new tab group in the current window. NB: use tgroupswitch instead in most cases, since it will create non-existent tab groups before switching to them.

    Tab groups are a way of organizing different groups of related tabs within a single window. Groups allow you to have different named contexts and show only the tabs for a single group at a time.

    Parameters

    • name: string

      The name of the tab group to create.

      If no tab groups exist, set the tab group name for all existing tabs in the window. Otherwise open a new tab and hide all tabs in the old tab group.

      Tab groups exist only for a single window.

    Returns Promise<string>

tgrouplast

  • tgrouplast(): Promise<string>
  • Switch to the previously active tab group.

    Returns Promise<string>

tgroupmove

  • tgroupmove(name: string): Promise<string>
  • Move the current tab to another tab group, creating it if it does not exist.

    Parameters

    • name: string

      The name of the tab group to move the tab to.

      If this is the last tab in the tab group, also switch to tab group, keeping the current tab active.

    Returns Promise<string>

tgrouprename

  • tgrouprename(name: string): Promise<string>
  • Rename the current tab group.

    Parameters

    • name: string

      The new name of the tab group.

    Returns Promise<string>

tgroupswitch

  • tgroupswitch(name: string): Promise<string>
  • Switch to a different tab group, hiding all other tabs.

    "%" denotes the current tab group and "#" denotes the tab group that was last active. "A" indates a tab group that contains an audible tab. Use :set completions.Tab.statusstylepretty true to display a unicode character instead.

    Parameters

    • name: string

      The name of the tab group to switch to.

      If the tab group does not exist, act like tgroupcreate.

    Returns Promise<string>

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<any>
  • Show a list of the voices available to the TTS system. These can be set in the config using ttsvoice

    Returns Promise<any>

tutor

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

    Parameters

    • Optional newtab: string

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

    Returns Promise<any>

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>

unbindurl

  • unbindurl(pattern: string, mode: string, keys: string): Promise<void>
  • Unbind a sequence of keys you have set with bindurl. Note that this kills a bind, which means Tridactyl will pass it to the page on pattern. If instead you want to use the default setting again, use reseturl.

    Parameters

    • pattern: string

      a regex to match URLs on which the key should be unbound

    • mode: string

      Optional. The mode in which the key should be unbound. Defaults to normal.

    • keys: string

      The keybinding that should be unbound

      example: unbindurl jupyter --mode=ignore I

      This unbinds I in ignore mode on every website the URL of which contains jupyter, while keeping the binding active everywhere else.

      Also see bind, bindurl, seturl, unbind, unseturl, setmode, unsetmode

    Returns Promise<void>

undo

  • undo(item?: string): Promise<number>
  • Restore the most recently closed item. The default behaviour is to restore the most recently closed tab in the current window unless the most recently closed item is a window.

    Supplying either "tab" or "window" as an argument will specifically only restore an item of the specified type. Supplying "tab_strict" only restores tabs that were open in the current window.

    Parameters

    • Default value item: string = "recent"

      The type of item to restore. Valid inputs are "recent", "tab", "tab_strict" and "window".

    Returns Promise<number>

    The tab or window id of the restored item. Returns -1 if no items are found.

unfocus

  • unfocus(): void
  • Blur (unfocus) the active element and enter normal mode

    Returns void

unset

  • unset(...keys: string[]): Promise<void>
  • Reset a config setting to default

    Parameters

    • Rest ...keys: string[]

    Returns Promise<void>

unsetmode

  • unsetmode(mode: string, key: string): Promise<void>
  • Reset a mode-specific setting.

    usage: unsetmode mode key

    Parameters

    • mode: string

      The mode the setting should be unset on, e.g. insert.

    • key: string

      The key that should be unset.

      Example: unsetmode ignore allowautofocus

      Note that this removes a setting from the mode-specific config, it doesn't "invert" it. This means that if you have a setting set to false in your global config and the same setting set to false in a mode-specific setting, using unseturl will result in the setting still being set to false.

    Returns Promise<void>

unseturl

  • unseturl(pattern: string, key: string): Promise<void>
  • Reset a site-specific setting.

    usage: unseturl [pattern] key

    Parameters

    • pattern: string

      The pattern the setting should be unset on, e.g. .*wiki.*. Defaults to the current url.

    • key: string

      The key that should be unset.

      Example: unseturl youtube.com gimode

      Note that this removes a setting from the site-specific config, it doesn't "invert" it. This means that if you have a setting set to false in your global config and the same setting set to false in a site-specific setting, using unseturl will result in the setting still being set to false.

      Also note that pattern should match exactly the one that was used when using seturl.

    Returns Promise<void>

updatecheck

  • updatecheck(source?: "manual" | "auto_polite" | "auto_impolite"): Promise<boolean>
  • Checks if there are any stable updates available for Tridactyl.

    Related settings:

    • update.nag = true | false - checks for updates on Tridactyl start.
    • update.nagwait = 7 - waits 7 days before nagging you to update.
    • update.checkintervalsecs = 86400 - waits 24 hours between checking for an update.

    Parameters

    • Default value source: "manual" | "auto_polite" | "auto_impolite" = "manual"

    Returns Promise<boolean>

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, multiplier?: number): void
  • Increment the current tab URL

    Parameters

    • Default value count: number = 1

      the increment step, can be positive or negative

    • Default value multiplier: number = 1

      multiplies the count so that e.g. 5<C-x> works.

    Returns void

urlmodify

  • urlmodify(mode: "-t" | "-r" | "-s" | "-q" | "-Q" | "-g" | "-tu" | "-ru" | "-su" | "-qu" | "-Qu" | "-gu", ...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 set mode: urlmodify -s <query> <value>

      Sets the value of a query to be a specific one. If the query already exists, it will be replaced.

    • 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
    • URL Input: urlmodify -*u <arguments> <URL>

      Each mode can be augmented to accept a URL as the last argument instead of the current url.

      Examples:

      • urlmodify -tu <old> <new> <URL>
      • urlmodify -su <query> <value> <URL>
      • urlmodify -gu <graft_point> <new_path_tail> <URL>

    Parameters

    • mode: "-t" | "-r" | "-s" | "-q" | "-Q" | "-g" | "-tu" | "-ru" | "-su" | "-qu" | "-Qu" | "-gu"

      The replace mode:

      • -t text replace
      • -r regexp replace
      • -s set the value of the given query
      • -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
      • -*u Use last argument as URL input instead of current URL
    • Rest ...args: string[]

    Returns void

urlmodify_js

  • urlmodify_js(mode: "-t" | "-r" | "-s" | "-q" | "-Q" | "-g" | "-tu" | "-ru" | "-su" | "-qu" | "-Qu" | "-gu", ...args: string[]): any
  • Like urlmodify but returns the modified URL for use with js and composite

    E.g.

    :composite urlmodify_js -t www. old. | tabopen

    Parameters

    • mode: "-t" | "-r" | "-s" | "-q" | "-Q" | "-g" | "-tu" | "-ru" | "-su" | "-qu" | "-Qu" | "-gu"
    • Rest ...args: string[]

    Returns any

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(): Promise<any>

viewconfig

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

    Parameters

    • Rest ...key: string[]

      The specific key you wish to view (e.g, nmaps, autocmds.DocLoad). Also accepts the arguments --default or --user to view the default configuration, or your changes.

      NB: the configuration won't update if you refresh the page - you need to run :viewconfig again.

    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(...ids: string[]): Promise<void[]>
  • Close a window.

    Parameters

    • Rest ...ids: string[]

    Returns Promise<void[]>

winmerge

  • winmerge(...windowIds: string[]): Promise<void>
  • Moves all of the targetted window's tabs to the current window. Only works for windows of the same type (can't merge a non-private tab with a private window).

    Parameters

    • Rest ...windowIds: string[]

    Returns Promise<void>

winopen

  • winopen(...args: string[]): Promise<any>
  • Like tabopen, but in a new window.

    winopen -private [...] will open the result in a private window (and won't store the command in your ex-history ;) ).

    winopen -popup [...] will open it in a popup window. You can combine the two for a private popup.

    winopen -c containername [...] will open the result in a container while ignoring other options given. See tabopen for more details on containers.

    Example: winopen -popup -private ddg.gg

    Parameters

    • Rest ...args: string[]

    Returns Promise<any>

wintitle

  • wintitle(...title: string[]): Promise<Window>
  • Add/change a prefix to the current window title

    Example: wintitle [Hovercraft research]

    Protip: unicode emojis work :)

    Parameters

    • Rest ...title: string[]

    Returns Promise<Window>

yank

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

    e.g. yank bob puts "bob" in the clipboard; composite js document.title | yank puts the document title in the clipboard.

    Parameters

    • Rest ...content: string[]

    Returns Promise<any[]>

yankimage

  • yankimage(url: string): Promise<void>
  • Copy an image to the clipboard.

    Parameters

    • url: string

      Absolute URL to the image to be copied. You can obtain an absolute URL from a relative one using tri.urlutils.getAbsoluteURL.

    Returns Promise<void>

zoom

  • zoom(level?: number, rel?: string, tabId?: string): Promise<void>
  • Sets the current page's zoom level anywhere between 30% and 300%.

    If you overshoot the level while using relative adjustments i.e. level > 300% or level < 30% the zoom level will be set to it's maximum or minimum position. Relative adjustments are made * in percentage points, i.e. :zoom +10 true increases the zoom level from 50% to 60% or from * 200% to 210%.

    Parameters

    • Default value level: number = 0

      The zoom level to set. Treated as percentage value if larger than 3 or smaller than -3.

    • Default value rel: string = "false"

      Set the zoom adjustment to be relative to current zoom level.

    • Default value tabId: string = "auto"

      The tabId to apply zoom level too. If set to 'auto' it will default to the current active tab. This uses mozilla's internal tabId and not tridactyl's tabId.

    Returns Promise<void>