VIMB(1)

🦋 VIMB(1) — the Vimb Manual, part 1 🦋

okay bestie, welcome to the Vimb Manual — this is the page for VIMB(1) and we're gonna get through it together, no cap 💖

---

✨ NAME ✨

Vimb — Vim Browser — a modal web browser built on WebKit, inspired by Vim: the great editor. 👑

✨ SYNOPSIS ✨

vimb [OPTIONS] [URI|file|-]

✨ DESCRIPTION ✨

So like, Vimb is a WebKit-based web browser that literally behaves like the Vimperator plugin for Firefox, and it steals its whole usage paradigm from the great editor, Vim. The goal? A completely keyboard-driven, efficient and pleasurable browsing experience. That's the dream, and it ate. 🔥

---

✨ OPTIONS ✨

Okay so first the housekeeping rules, bestie 👇

• If no URI or file is given, Vimb opens the configured home-page.
• If URI is -, Vimb reads the HTML to display from stdin.

ngl this one matters: mandatory arguments to long options are mandatory for short options too. 🫶

• -C, --cmd CMD — run CMD as an ex command line right before the first page is loaded. Use the flag more than once and the commands get called in the order you gave them. You can also pass several ex commands inside one CMD if you separate them with "|". Obsessed. 💅

vimb --cmd "set dark-mode=on|set header=Referer,DNT=1"

• -c, --config FILE — use a custom configuration given as FILE. And no worries, this also gets applied to any newly spawned instances. ✨
• -e, --embed WINID — [DEPRECATED - GTK4 removed XEmbed support]. This option is no longer functional. GTK4 removed the GtkPlug/GtkSocket XEmbed support. For tabbed integration alternatives, see the project documentation. 😭
• -i, --incognito — start an instance with user data read-only (peep the FILES section for that). 🙈
• -h, --help — show help options. classic.
• -p, --profile PROFILE-NAME — create or open the specified configuration profile. Config data for the profile lives in a directory named PROFILE-NAME under the default directory for configuration data. 🎀
• -v, --version — print build and version information, then quit. bye bestie 👋
• --no-maximize — no attempt is made to maximize the window. 🪟
• --bug-info — prints info about the libraries in use, for bug reports, then quits. very "here's my receipt" of it. 🧾

---

✨ MODES ✨

Vimb is modal, and it has these main modes, iykyk:

🌸 Normal Mode

The default mode. Pressing Escape always enters normal mode. main character energy, honestly.

🌸 Input Mode

Used for editing text elements in a webpage. 🖊️

🌸 Command Mode

Executes ex commands from the builtin inputbox (the commandline). 💻

🌸 Pass-Through Mode

In Pass-Through mode, only the <Esc> and <C-[> keybindings are interpreted by Vimb — every other keystroke is given to the webview to handle. This lets you use a website's own configured keybindings, the ones that might otherwise get swallowed by Vimb. 🦋

---

💅 NORMAL MODE COMMANDS 💅

Okay bestie, these are the Normal Mode commands. Some of them take a numeric count that multiplies the effect, and if a command supports that count it’s shown as [N]. No cap, that [N] is your little multiplier fairy. 🧚

🎀 General 🎀

• : — Start Command Mode and print : to the input box.
• gi — Set the cursor to the first editable element in the page and switch to Input Mode.
• i — Set the cursor to the last focused element in the page and switch to Input Mode. If no element was focused before, the first element is focused like with gi.
• CTRL-Z — Switch Vimb into Pass-Through Mode.
• gf — Open the configured editor (editor-command) with the current page’s content.
• gF — Open the Web Inspector for the current page.
• CTRL-V — Pass the next key press directly to GTK.
• CTRL-Q — Quit the browser if there are no running downloads.

🦋 Tabs 🦋

Vimb supports tabbed browsing within a single window. Slay, tabs, we love her. 💖

• gt — Go to the next tab.
• gT — Go to the previous tab.
• g0 — Go to the first tab.
• g$ — Go to the last tab.

🌸 Navigation 🌸

• o — Start Command Mode and print :open to the input box. Yes, with the trailing space.
• O — Start Command Mode and print :open URI to the input box.
• t — Start Command Mode and print :tabopen to the input box. Trailing space again, iconic.
• T — Start Command Mode and print :tabopen URI to the input box.
• gh — Open the configured home-page.
• gH — Open the configured home-page in a new tab.
• u — Open the last closed page.
• U — Open the last closed page in a new tab.
• CTRL-P — Open the oldest entry from the read it later queue in the current browser window.
• ["x]p — Open the URI out of the register x or, if not given, from the clipboard.
• ["x]P — Open the URI out of the register x or, if not given, from the clipboard in a new tab.
• [N]CTRL-O — Go back N steps in the browser history.
• [N]CTRL-I — Go forward N steps in the browser history.
• [N]gu — Go to the Nth descendent directory of the current opened URI.
• gU — Go to the domain of the current opened page.
• r — Reload the website.
• R — Reload the website without using caches.
• CTRL-C — Stop loading the current page.
• CTRL-LeftMouse, MiddleMouse — Opens the clicked link in a new tab.
• Shift-LeftMouse — Push the link url under the cursor to the end of the Read It Later queue like the :qpush command.

🌈 Motion 🌈

• [N]CTRL-F — Scroll N pages down.
• [N]CTRL-B — Scroll N pages up.
• [N]CTRL-D — Scroll N half pages down.
• [N]CTRL-U — Scroll N half pages up.
• [N]gg — Scroll to the top of the current page. Or if N is given, to N% of the page.
• [N]G — Scroll to the bottom of the current page. Or if N is given, to N% of the page.
• 0, ^ — Scroll to the absolute left of the document. Unlike in Vim, 0 and ^ work exactly the same way.
• $ — Scroll to the absolute right of the document.
• [N]h — Scroll N steps to the left of page.
• [N]l — Scroll N steps to the right of page.
• [N]j — Scroll page N steps down.
• [N]k — Scroll page N steps up.
• m{a-z} — Set a page mark {a-z} at the current position on the page. Such set marks are only available on the current page; if the page is left, all marks will be removed.
• m{A-Z} — Set a page mark {A-Z} at the current position on the page. These marks are permanent across any page.
• '{a-z} — Jump to the mark {a-z} on the current page.
• '{A-Z} — Jump to the global mark {A-Z} on a (possibly) different page.
• '' — Jumps to the position before the latest jump, or where the last m' command was given.

💅 Hinting 💅

Hinting in Vimb is how you accomplish the tasks that you would do with the mouse in common mouse-driven browsers: open a URI, yank a URI, save a page and so on. When hinting is started, the relevant elements on the page will be marked by labels generated from configured hint-keys. Hints can be selected by using <Tab>, <C-I> or <C-Tab>, <C-O>, by typing the chars of the label, or filtering the elements by some text that is part of the hinted element (like URI, link text, button label) or any combination of these methods. If <enter> is pressed, the current active hint will be fired. If only one possible hint remains, this will be fired automatically. ✨

Syntax:

;{mode}{hint}

Start Hints mode. Different elements depending on mode are highlighted and numbered. Elements can be selected either by typing their label, or by typing part of their text (hint) to narrow down the result. When an element has been selected, it is automatically clicked or used (depending on mode) and hint mode ends.

The filtering of hints by text splits the query at ' ' and use the single parts as separate queries to filter the hints. This is useful for hints that have a lot of filterable chars in common and many chars are required to make a distinct selection. For example ;over tw will easily select the second hint out of {'very long link text one', 'very long link text two'}.

The following keys have special meanings in Hints modes:

• <CR> — Selects the first highlighted element, or the current focused.
• <Tab> — Moves the focus to the next hint element.
• <S-Tab> — Moves the focus to the previous hint element.
• <Esc>, CTRL-C, CTRL-[ — Exits Hints mode without selecting an element.

🎀 Hint modes 🎀

• f — Is an alias for the ;o hint mode.
• F — Is an alias for the ;t hint mode.
• ;o — Open hint’s location in the current window.
• ;t — Open hint’s location in a new tab.
• ;s — Saves the hint’s destination under the configured download-path.
• ;O — Generate an :open prompt with hint’s URI.
• ;T — Generate an :tabopen prompt with hint’s URI.
• ;e — Open the configured editor (editor-command) with the hinted form element’s content. If the file in editor is saved and the editor is closed, the file content will be put back in the form field.
• ;i — Open hinted image in the current window.
• ;I — Open hinted image in a new tab.
• ;k — Kill (remove) hinted element from the page.
• ;p — Push the hint’s URI to the end of the Read It Later queue like the :qpush command. This is only available if Vimb was compiled with the QUEUE feature.
• ;P — Push the hint’s URI to the beginning of the Read It Later queue like the :qunshift command. This is only available if Vimb was compiled with the QUEUE feature.
• ;x — Hints like ;o, but instead of opening the hinted URI, the x-hint-command is run in Vimb.
• ["x];y — Yank hint’s destination location into primary and secondary clipboard and into the register x.
• ["x];Y — Yank hint’s text description or form text into primary and secondary clipboard and into the register x.

Syntax:

g;{mode}{hint}

Start an extended hints mode and stay there until <Esc> is pressed. Like normal hinting, except that after a hint is selected, hints remain visible so that another one can be selected with the same action as the first. Note that the extended hint mode can only be combined with the following hint modes I o p P s t y Y.

💫 Motion 💫

Motions commands are like those for normal mode except that CTRL is used as modifier. But they can not be used together with a count.

• CTRL-F — Scroll one page down.
• CTRL-B — Scroll one page up.
• CTRL-D — Scroll half page down.
• CTRL-U — Scroll half page up.
• CTRL-J — Scroll one step down.
• CTRL-K — Scroll one step up.

⭐ Searching ⭐

• /QUERY, ?QUERY — Start searching for QUERY in the current page. / start search forward, ? in backward direction.
• *, # — Start searching for the current selected text, or if no text is selected for the content of the primary or secondary clipboard. * start the search in forward direction and # in backward direction.

⚠️ Note that these commands will yank the text selection into the clipboard and may remove other content from there! Bestie, please be aware. 😭

• [N]n — Search for the *N*nth next search result depending on current search direction.
• [N]N — Search for the *N*nth previous search result depending on current search direction.
• <CR> — Perform a click on element containing the current highlighted search result.

🔥 Zooming 🔥

• [N]zi — Zoom-In the text of the page by N steps.
• [N]zo — Zoom-Out the text of the page by N steps.
• [N]zI — Full-Content Zoom-In the page by N steps.
• [N]zO — Full-Content Zoom-Out the page by N steps.
• zz — Reset Zoom.

🍓 Yank 🍓

• ["x]y — Yank the URI or current page into register x and clipboard.
• ["x]Y — Yank the current selection into register x and clipboard.

---

💻 COMMAND MODE 💻

Commands that are listed below are ex-commands like in Vim, that are typed into the inputbox (the command line of vimb). The commands may vary in their syntax or in the parts they allow, but in general they follow a simple syntax.

:[:| ][N]cmd[name][!][ lhs][ rhs]

Where lhs (left hand side) must not contain any unescaped space. The syntax of the rhs (right hand side) if this is available depends on the command. At the moment the count parts [N] of commands is parsed, but currently there is no command that uses the count.

Commands that are typed interactivly are normally recorded into command history and register. To avoid this, the commands can be prefixed by one or more additional : or whitespace.

Multiple commands, separated by a | can be given in a single command line and will be executed consecutively. The pipe can be included as an argument to a command by escaping it with a backslash. Following commands process the entire command-line string literally. These commands will include any | as part of their argument string and so can not be followed by another command.

• autocmd
• cmap, cnoremap, imap, inoremap, nmap, nnoremap
• eval
• normal
• open, tabopen
• shellcmd, shellex

⌨️ Command Line Editing ⌨️

• <Esc>, CTRL-[, CTRL-C — Ignore all typed content and switch back to normal mode.
• <CR> — Submit the entered ex command or search query to run it.
• CTRL-H — Deletes the char before the cursor.
• CTRL-W — Deletes the last word before the cursor.
• CTRL-U — Remove everything between cursor and prompt.
• CTRL-B — Moves the cursor directly behind the prompt :.
• CTRL-E — Moves the cursor after the prompt in inputbox.
• CTRL-V — Pass the next key press directly to GTK.
• CTRL-R {a-z"%:/;} — drops the contents of whatever register you name right at the cursor 💥 oh and peep the :reg[ister] command section if you wanna know what lives in registers.

🎀 Command Line History 🎀

• Tab — kicks off completion of whatever's in the inputbox, going forward.
• S-Tab — same completion vibe but backwards, bestie.
• Up — steps backward through your command history.
• Down — steps forward through the command history. Also yanks the current selection into register x and the clipboard, no cap.

🌐 Open 🌐

• :o[pen] [URI] — opens the given URI in the tab you're chilling in right now. If URI is empty, boom, the configured 'home-page' gets opened instead.
• :t[abopen] [URI] — same energy but in a new tab. Empty URI? Again, the configured 'home-page' opens. ✨

📑 Tabs 📑

• :tabc[lose] — closes the current tab. And if that was the last tab? The whole browser window closes. like, gone-gone 😭
• :tabn[ext] — hop over to the next tab.
• :tabp[rev], :tabp[revious] — hop back to the previous tab.
• :tabfirst — yeet yourself to the first tab.
• :tablast — yeet yourself to the last tab.

⌨️ Key Mapping ⌨️

Key mappings let you change what pressing keys actually does — main character energy for your keyboard fr. Each key mapping belongs to a mode and only works while that mode is active. These commands let you swap one sequence of key presses for another.

Syntax:

:{m}map {lhs} {rhs}

Heads up, this part is important: the {lhs} ends at the first space it finds. So if you want a space inside your {lhs}, you gotta escape it with a single '\' — there are examples below, don't stress 🫶.

The {rhs} starts at the first non-space character. Want a {rhs} that begins with a space? Use "<Space>".

Standard key mapping commands exist for these modes, m:

• n — Normal mode: when you're just browsing normally.
• i — Insert mode: when you're interacting with text fields on a website.
• c — Command Line mode: when you're typing into Vimb's command line.

Most keys in a key sequence are just represented by the literal character you see on screen when you press them. But a bunch of those characters have special meanings, and some keys have no visual representation at all — so yeah, we need a special notation for those.

Special key names look like <...>. Here's the whole guest list: <Left>, <Up>, <Right>, <Down> for the cursor keys, plus <Tab>, <Esc>, <CR>, <Space>, <BS>, <F1>-<F12> and <C-A>-<C-Z>. Now — if you want an actual sequence of keys like "<", "C", "R", ">", then escape with a backslash: "<CR>". And if you want a backslash followed by a special key, use <Bslash>.

• :nm[ap] {lhs} {rhs}
• :im[ap] {lhs} {rhs}
• :cm[ap] {lhs} {rhs}

Map the key sequence lhs to rhs for whichever modes that map command applies to. Then — plot twist — the result, including rhs, gets scanned again for more mappings. That's what gives you nested and recursive mappings. 🔥

:cmap <C-G>h /home/user/downloads/

Adds a keybind that inserts a file path into the input box. Super handy for the :save command, which you could then use like ":save ^Gh".

:nmap <F1> :set scripts=on<CR>:open !glib<Tab><CR>

This enables scripts and looks up the first bookmarked URI with the tag glib, then opens it immediately when F1 gets pressed. iconic.

:nmap \ \  50G

Example that maps two spaces to jump to 50% of the page.

• :nn[oremap] {lhs} {rhs}
• :ino[remap] {lhs} {rhs}
• :cno[remap] {lhs} {rhs}

Maps the key sequence lhs to rhs for the mode the map command applies to — but it disallows mapping of rhs, so no nested/recursive shenanigans. Lowkey the go-to when you're redefining an existing command.

• :nu[nmap] {lhs}
• :iu[nmap] {lhs}
• :cu[nmap] {lhs}

Removes the mapping of lhs for the applicable mode. bye felicia 👋

🔖 Bookmarks 🔖

• :bma [tags] — saves the currently open URI, with tags, into the bookmark file. 🎀
• :bmr [URI] — removes all bookmarks for the given URI — or, if you don't give one, for the page that's currently open.

🛠️ Handlers 🛠️

Handlers let you point external scripts at alternative URI methods — so the weird protocols get handled too, periodt.

• :handler-add handler=cmd — adds a handler that directs handler links to the external cmd. The cmd can contain one placeholder %s, which gets filled with the full URI given when the command is called.

:handler-add mailto=urxvt -e mutt %s

to start your email client for mailto links.

:handler-add magnet=xdg-open %s

to open magnet links with xdg-open.

:handler-add ftp=urxvt -e wget %s -P ~/ftp-downloads

to handle ftp downloads via wget.

• :handler-remove handler — removes the handler for the given URI handler.

✨ Shortcuts ✨

Shortcuts let you open a URI built from a named template plus extra parameters. If a shortcut called dd is defined, you can fire it off with :open dd list of parameters and it'll open the generated URI. Obsessed tbh.

They're especially convenient with search engines, where the URI is standardised and just one parameter is user-defined.

• :shortcut-add shortcut=URI — adds a shortcut with the shortcut name and URI template. The URI can contain multiple placeholders $0-$9, which get filled by the parameters you give when calling the shortcut. Those parameters get split into as many parameters as the highest used placeholder — yes, really.

Wanna use spaces inside parameters? Group them by wrapping in single or double quotes — like in the map example below.

:shortcut-add dl=https://duckduckgo.com/lite/?q=$0

to set up a search engine. Call it with :open dl my search phrase.

:shortcut-add gh=https://github.com/$0/$1

to build URIs from given parameters. Call it like :open gh fanglingsu vimb.

:shortcut-add map=https://maps.google.com/maps?saddr=$0&daddr=$1

to search for a route — all but the last parameter must be quoted if they contain spaces, like :open map "city hall, London" railway station, London.

• :shortcut-remove shortcut — removes the search engine for the given shortcut.
• :shortcut-default shortcut — sets the given shortcut as the default, i.e. the shortcut that gets used when no shortcut is given and the string you're opening isn't a URI. And ngl, it doesn't matter whether the shortcut is already in use or not — you can still set it.

⚙️ Settings ⚙️

• :se[t] var=value — sets configuration values named by var. For a boolean variable you should use 'on', 'off', 'true' or 'false'. Colors go in as hex values like '#f57700'. And spaces or extra equals signs in the value just work, no quotes needed: for example, ":set sans-serif-font=Some Sans Font". slay 💅
• :se[t] var+=value — adds the value to a number option, or appends the value to a string option. When the option is a comma-separated list, a comma gets added too — unless the value was empty.
• :se[t] var^=value — multiplies the value into a number option, or prepends the value to a string option. Comma-separated list? A comma gets added, unless the value was empty.
• :se[t] var-=value — subtracts the value from a number option, or removes the value from a string option if it's there. Comma-separated list? A comma gets deleted, unless that leaves the option empty.
• :se[t] var? — shows the currently set value of the variable. VAR.
• :se[t] var! — toggles the value of the boolean variable var and displays the new set value. flip it and reverse it 🦋

📚 Queue 📚

The queue lets you mark URIs for later reading. And the tea is that this list is shared between the single instances of Vimb. 👑

• :qpu[sh] [URI] — pushes URI — or, if you don't give one, the current URI — to the end of the queue.
• :qun[shift] [URI] — pushes URI — or, if not given, the current URI — to the beginning of the queue.
• :qp[op] — opens the oldest queue entry in the current browser window and removes it from the queue.
• :qc[lear] — removes every entry from the queue. clean slate ✨

🤖 Automatic commands 🤖

An autocommand is a command that runs automatically in response to some event — like a URI being opened. Autocommands are very powerful. Use them with care and they'll save you from typing a million commands, fr fr.

Autocommands are built from these properties:

• group — when the [group] argument isn't given, Vimb uses the current group as defined with ':augroup'; otherwise it uses the group defined with [group]. Groups are useful for removing multiple grouped autocommands in one go.
• event — you can give a comma-separated list of event names. No white space allowed in this list, okay?

Events:

• LoadStarting — fired before a new page is going to be opened. No data has been sent or received yet, and the load may still fail for transport issues.
• LoadStarted — fired if a new page is going to be opened. No data has been received yet, and the load may still fail for transport issues.
• LoadCommitted — fired if the first data chunk has arrived, meaning the necessary transport requirements are established and the load is being performed. This is the right event to toggle content-related settings like 'scripts', 'plugins' and such things. 👑
• LoadFinished — fires when everything required to display on the page has been loaded.
• DownloadStarted — fired right after a download is started.
• DownloadFinished — fired if a Vimb managed download is finished.
• DownloadFailed — fired if a Vimb managed download failed. 😭

• pat — a comma-separated list of patterns, matched in order to check if an autocommand applies to the URI associated with an event. To use ',' within a single pattern, it must be escaped as '\,'.

Patterns

• * — matches any sequence of chars. and yeah, that includes / — unlike shell patterns, bestie, this one does not care.
• ? — matches any single character, except /.
• {one,two} — matches one or two. any {, , and } inside this pattern has to be escaped with a \. and heads up: * and ? have no special meaning inside the curly braces, they're just lil guys in there.
• \ — backslash is your escape hatch, use it to kill the special meaning of ?*{}, in the pattern or pattern list.

cmd — any ex command that vimb understands. the leading : is not required btw, you can just drop it. and you can chain multiple commands by separating them with | ✨

---

autocommands, the whole saga 💅

• :au[tocmd] [group] {event} {pat} {cmd} — adds cmd to the list of commands Vimb will execute automatically on event for a URI matching pat (see autocmd-patterns). Vimb always adds the cmd after existing autocommands, so they run in the order you gave them. no queue-jumping, periodt.
• :au[tocmd]! [group] {event} {pat} {cmd} — removes all autocommands associated with event whose patterns match pat, and adds the command cmd. ⚠️ note that the pattern is not matched literally to find autocommands to remove, like Vim does. Vimb matches the autocommand pattern with pat. if [group] is not given, it deletes autocommands in the current group, as noted above.
• :au[tocmd]! [group] {event} {pat} — removes all autocommands associated with event and which pattern matches pat in the given group (current group by default).
• :au[tocmd]! [group] * {pat} — removes all autocommands with patterns matching pat for all events in the given group (current group by default).
• :au[tocmd]! [group] {event} — removes all autocommands for event in the given group (current group by default).
• :au[tocmd]! [group] — removes all autocommands in the given group (current group by default). full reset energy.
• :aug[roup] {name} — defines the autocmd group name for the following :autocmd commands. the name end selects the default group.
• :aug[roup]! {name} — deletes the autocmd group name.

Example, iconic behaviour:

:aug github
:  au LoadCommitted * set scripts=off|set cookie-accept=never
:  au LoadCommitted http{s,}://github.com/* set scripts=on
:aug end

---

🎀 Misc 🎀

:cl[eardata] [dataTypes] [timespan] — asynchronously clears the website data of the given list of dataTypes modified in the past timespan. note that dataTypes must not contain spaces. if timespan is not given, all website data will be removed. and ngl this is a big one: this affects all running instances of vimb 🫶

dataTypes is a comma separated list of these types:

• memory-cache — memory cache.
• disk-cache — HTTP disk cache.
• session-storage — session storage data.
• local-storage — local storage data.
• indexeddb-databases — IndexedDB databases.
• plugin-data — plugin data.
• cookies — cookies. note that the cookies are not cleared in case a timespan is given. lowkey important.
• hsts-cache — HTTP Strict Transport Security cache.
• - — can be used to clear all known data types in case a timespan is used.

The timespan is given as a sequence of '[multiplier]unit' tupels with these units:

• y — year (365 days)
• w — week (7 days)
• d — day
• h — hour
• m — minute
• s — second

Example time, bestie:

:cleardata

to clear all known website data types without any timespan restriction.

:cleardata - 5m

to clear all known website data types modified in the last 5 minutes.

:cleardata local-storage,session-storage,cookies

to completely clear the cookies, local- and session-storage without time restrictions.

:cleardata disk-cache 2d4h

to clear the disk cache that was modified in the past two days and four hours.

---

:sh[ellcmd] cmd — runs the given shell cmd syncron and prints the output into the inputbox. the following patterns in cmd get expanded: '~username', '~/', '$VAR' and '${VAR}'. a \ before these patterns disables the expansion. 🙈

These environment variables are set for the called shell commands:

• VIMB_URI — this variable is set by Vimb every time a new page is opened, to the URI of the page.
• VIMB_SELECTION — this variable is set to the current selected text on the page.
• VIMB_TITLE — contains the title of the current opened page.
• VIMB_PID — contains the pid of the running Vimb instance.
• VIMB_WIN_ID — holds the X-Window id of the Vimb window.
• VIMB_XID — holds the X-Window id of the Vimb window.

:sh[ellcmd]! cmd — like :sh[ellcmd] but asynchronous, so it doesn't sit there blocking you. main character energy.

Example:

:sh! /bin/sh -c 'echo "`date` $VIMB_URI" >> myhistory.txt'

---

:shelle[x] cmd — like :sh[ellcmd] but instead of printing the output into the inputbox, it runs the output as ex commands line by line. honestly kind of unhinged in the best way 💀

Example:

:shellex bash -c "sqlite3 \"file:\$XDG_CONFIG_HOME/chromium/Default/History?mode=ro\" \"SELECT url, title FROM urls ORDER BY last_visit_time DESC\" | dmenu -l 20 | awk -F'|' '{print \"open \" \$1}'"

to select an entry from the Chromium history and open in the current window.

---

:s[ave] [path] — downloads the current opened page into the configured download directory. if path is given, it downloads under this file name or path. path is expanded and can therefore contain '~/', '${ENV}' and '~user' pattern. cute.

:so[urce] [file] — read ex commands from file.

:q[uit] — closes the current tab. if this is the last tab, the browser window is closed. 🚪 this will be refused if there are running downloads.

:q[uit]! — closes the current tab independent from a running download. no thoughts, just exit.

:quita[ll] — closes all tabs and quits the browser. this will be refused if there are running downloads in any tab.

:quita[ll]! — closes all tabs and quits the browser independent from running downloads. bye bestie 👋

:reg[ister] — displays the contents of all registers.

The registers, aka the ✨vault✨:

• "a — "z — 26 named registers "a to "z. Vimb fills these registers only when you say so.
• ": — last executed ex command.
• "" — last yanked content.
• "% — curent opened URI.
• "/ — last search phrase.
• "; — contains the last hinted URL.

:e[val] javascript — runs the given javascript in the current page and displays the evaluated value.

Example: :eval document.cookie

:e[val]! javascript — like :eval, but there is nothing print to the input box. silent slay.

:no[rmal] [cmds] — execute normal mode commands cmds. this makes it possible to execute normal mode commands typed on the input box. 🎀

cmds cannot start with a space. put a count of 1 (one) before it, "1 " is one space.

Example: :set scripts!|no! R

:no[rmal]! [cmds] — like :normal, but no mapping is applied to cmds.

:ha[rdcopy] — print the current document. opens a GUI dialog where you can select the printer, number of copies, orientation, etc. very grown-up of you tbh 🖨️

---

🦋 INPUT MODE 🦋

• <Esc>, CTRL-[ — switch back to normal mode.
• CTRL-O — executes the next command as a normal mode command and then returns to input mode. quick little detour.
• CTRL-T — open the configured editor with the content of the current form field.
• CTRL-V — pass the next key press directly to WebKit.
• CTRL-Z — enter the pass-through mode.

---

🌸 COMPLETIONS 🌸

The completions are triggered by pressing <Tab> or <S-Tab> in the activated inputbox. depending on the current inserted content, different completions get started. the completion takes additional typed chars to filter the completion list that is shown. filtering as you type, we love to see it ✨

commands

the completion for commands is started when at least : is shown in the inputbox. if initial chars are passed, the completion will lookup those commands that begin with the given chars.

settings

the setting name completion is started if at least :set is shown in inputbox, and it also matches settings that begin with the already typed setting prefix.

history

the history of URIs is shown for the :open and :tabopen commands. this completion looks up every given word in the history URI and titles. only those history items are shown where the title or URI contains all tags.

:open foo bar<Tab>

will complete only URIs that contain the words foo and bar.

bookmarks

the bookmark completion is similar to the history completion, but does match only the tags of the bookmarks. the bookmark completion is started by :open !, :tabopen ! or :bmr and does a prefix search for all given words in the bookmark tags.

:open !foo ba

will match all bookmarks that have tags starting with "foo" and "ba". if the bookmark does not have any tags set, the URL is split on .' and /' into tags.

:bmr tag

will match all bookmarks that have tags starting with "tag".

bookmark tags

the bookmark tag completion allows the insertion of already used bookmarks for the :bma commands.

search

the search completion allows a filtered list of already done searches. this completion starts by / or ? in inputbox and performs a prefix comparison for further typed chars.

---

🌈 SETTINGS 🌈

all the settings listed below can be set with the `:set' command. see Settings under COMMAND MODE for syntax. iykyk 👑

allow-file-access-from-file-urls(bool)

indicates whether file access is allowed from file URLs. by default, when something is loaded using a file URI, cross origin requests to other file resources are not allowed.

---

and that's just the opening act of the settings list btw — there's a whole parade of them coming, so stay tuned bestie 💜

• allow-universal-access-from-file-urls (bool) — this is the "can JS peek at your whole filesystem?" switch 🫣. It says whether JavaScript running in the context of a file scheme URL is allowed to access content from any origin. Default behaviour: when something's loaded via a file scheme URL, access to the local file system and arbitrary local storage is not allowed. So by default, no, bestie, the page can't rummage through your stuff 💅
• caret (bool) — whether to enable accessibility-enhanced keyboard navigation. Yes it's literally called caret. Cute.
• cookie-accept (string) — the cookie accept policy. Your options are always, never, or origin (which accepts all non-third-party cookies) 🍪
• closed-max-items (int) — max number of stored last closed URLs. Set it to 0 and closed URLs just... won't be stored at all. Gone, reduced to atoms 💀
• completion-css (string) — CSS style applied to the inputbox completion list items. Make that dropdown iconic ✨
• completion-hover-css (string) — CSS style applied to the inputbox completion list item that's currently hovered by the mouse 🖱️
• completion-selected-css (string) — CSS style applied to the inputbox completion list item that's currently selected. The chosen one 👑
• cursiv-font (string) — the font family used as the default for content using cursive font. (Yes, the option name is spelled cursiv-font — that's canon, don't come for me 🙈)
• dark-mode (bool) — whether to enable dark mode. Websites can use the prefers-color-scheme media query to adjust styles according to this option 🌙
• default-charset (string) — the default text charset used when interpreting content with an unspecified charset.
• default-font (string) — the font family to use as the default for content that does not specify a font 🎀
• default-zoom (int) — default Full-Content zoom level in percent. Default is 100.
• download-command (string) — a command with placeholder %s that gets invoked to download a URI, in case 'download-use-external' is enabled.

The following additional environment variables are available:

• $VIMB_URI — the URI of the current opened page, normally the page where the download was started from, also known as the referer.
• $VIMB_DOWNLOAD_PATH — the setting value of 'download-path', which would normally be used for downloads.

:set download-command=/bin/sh -c "cd '$VIMB_DOWNLOAD_PATH' && curl -sLJOC - -e '$VIMB_URI' %s"

• download-path (string) — path to the default download directory. If no download directory is set, downloads get written into $HOME/Downloads. It must be an absolute path, no exceptions bestie. You can take advantage of the :shellex command to expand relative paths or environment variables:

:shellex sh -c "echo -n :set download-path=; realpath ~/downloads/"

• download-use-external (bool) — indicates if the external download tool set as 'download-command' should be used to handle downloads. If this is disabled, Vimb will handle the download itself 💪
• editor-command (string) — command with placeholder %s called if a form field is opened with $EDITOR, to spawn the editor — like x-terminal-emulator -e vim %s. To use Gvim as the editor, it's necessary to call it with -f so it runs in the foreground 🧚
• font-size (int) — the default font size used to display text.
• fullscreen (bool) — show the current window full-screen. Main character energy, entire screen, no notes 🖥️
• hardware-acceleration-policy (string) — this setting decides how to enable and disable hardware acceleration.
  • ondemand — enables hardware acceleration when the web contents request it, disabling it again when no longer needed.
  • always — enforce hardware acceleration to be enabled.
  • never — disables it completely.

Heads up babe: disabling hardware acceleration might cause some websites to not render correctly or consume more CPU 😭

• header (list) — comma separated list of headers that replaces default headers sent by WebKit, or adds new headers. The format for the header list elements is name[=[value]].

Note that these headers will replace already existing headers. If there's no = after the header name, then the complete header will be removed from the request; if the = is present, it means the header value is set to an empty value.

Note that WebKit reuses already-set headers in the case of a reload of a page. So if headers were removed that were previously used to access a certain page, and the page is reloaded or opened via back/forward history, the header will still be sent. To apply the new header setting properly it's required to request another page, or to open the current page new via O<Cr> 😮‍💨

To use = within a header value, the value must be quoted like shown in the example for the Cookie header:

:set header=DNT=1,User-Agent,Cookie='name=value'

That one sends the Do Not Track header with each request and removes the User-Agent header completely from the request. Slay 🎀

• hint-follow-last (bool) — if on, vimb automatically follows the last remaining hint on the page. If off, hints are fired only if Enter is pressed.
• hint-keys-same-length (bool) — if on, all hint labels will have the same length, so no hints will be ambiguous. No cap, very satisfying.
• hint-timeout (int) — timeout before automatically following a non-unique numerical hint. To disable auto-fire of hints, set this value to 0 ⏰
• hint-keys (string) — the keys used to label and select hints. With its default value, each hint has a unique label which can be typed to select it, while all other characters are used to filter hints based on their text. With a value such as asdfg;lkjh, each hint is "labeled" based on the characters of the home row 🏠

If the hint-keys string starts with a 0, the keys are considered to follow the rules of numeric labeling. So the first char of the label will never start with the 0.

Note that the hint matching by label built of hint-keys is case sensitive. In this, vimb differs from some other browsers that show hint labels in upper case but match them lowercase.

To have upper case hint labels, it's possible to add the following css to the style.css file in vimb's configuration directory:

"span[vimbhint="label"] {text-transform: uppercase !important;}"

• hint-match-element (bool) — if this is set to 'true', typed chars that are not part of the set 'hint-keys' are used to filter hinted DOM elements by their text value. If 'hint-keys' are set to chars instead of numbers, it might be useful to disable matching of the elements by 'hint-match-element=false' 🦋
• histignore (string) — determines whether a URI should be saved in the history file. This option must be a valid POSIX Extended Regular Expression. If a URI matches this regular expression, then it won't be saved in the history. If this option is empty, then any URI will be saved in the history 🙈
• history-max-items (int) — maximum number of unique items stored in search-, command- or URI history. If history-max-items is set to 0, the history file will not be changed. This setting has no effect if option --incognito is set 🕵️
• home-page (string) — homepage that vimb opens if started without a URI.
• html5-database (bool) — whether to enable HTML5 client-side SQL database support. Client-side SQL database allows web pages to store structured data and be able to use SQL to manipulate that data asynchronously. Fancy 💅
• html5-local-storage (bool) — whether to enable HTML5 localStorage support. localStorage provides simple synchronous storage access.
• images (bool) — determines whether images should be automatically loaded or not 🖼️
• incsearch (bool) — while typing a search command, show where the pattern typed so far matches. Literally the best feature, watching the matches light up as you type is chef's kiss 😭✨
• input-autohide (bool) — if enabled, the inputbox will be hidden whenever it contains no text.
• input-css (string) — CSS style applied to the inputbox in normal state.
• input-error-css (string) — CSS style applied to the inputbox in case of a displayed error. Make your errors pretty 💀
• intelligent-tracking-prevention (bool) — whether WebKit's Intelligent Tracking Prevention (ITP) is enabled. Iconic acronym, iconic behaviour 👑
• javascript-can-access-clipboard (bool) — whether JavaScript is allowed to read from the clipboard. This does not block JavaScript from writing to the clipboard; only read access is controlled by the underlying WebKit setting. Read that again bestie, only reads 👀
• javascript-can-open-windows-automatically (bool) — whether JavaScript can open popup windows automatically without user interaction. Keep this in mind before you get 40 popups 🙈
• javascript-enable-markup (bool) — whether JavaScript markup is enabled. Disabling can help with some older systems (ppc, ppc64, etc.) that don't have complete JavaScript support to run webpages without crashing 🫶
• geolocation (string) — controls website access to the geolocation API. Your choices: always, never, or ask (which displays a prompt each time) 📍
• media (bool) — enable or disable all media support. When disabled, WebKitGTK will not attempt to play any audio or video content, which can be useful on systems where GStreamer is not fully configured, or to prevent crashes caused by missing GStreamer plugins (such as autoaudiosink) 🔇
• media-playback-allows-inline (bool) — whether media playback is full-screen only or inline playback is allowed. Setting it to false allows specifying that media playback should always be fullscreen.
• media-playback-requires-user-gesture (bool) — whether a user gesture (such as clicking the play button) is required to start media playback or load media. Setting it on requires a gesture by the user to start playback, or to load the media 👆
• media-stream (bool) — enable or disable support for MediaSource on pages. MediaSource is an experimental proposal which extends HTMLMediaElement to allow JavaScript to generate media streams for playback 🌈
• mediasource (bool) — enable or disable support for MediaSource on pages. MediaSource is an experimental proposal which extends HTMLMediaElement to allow JavaScript to generate media streams for playback. (Yes, it says the same thing as media-stream — they're twins, we love them both equally 💖)
• minimum-font-size (int) — the minimum font size used to display text. No more squinting, periodt.
• monospace-font (string) — the font family that gets used as the default for anything using a monospace font. code vibes only 💻
• monospace-font-size (int) — the default font size for that monospace font.
• notification (string) — controls whether websites can touch the notification API, the one that fires notifications off via dbus. the options are always, never, and ask (which means it shows you a prompt every single time, bestie 🫶).
• print-backgrounds (bool) — whether background images should actually get drawn during printing.
• prevent-newwindow (bool) — whether links that would normally pop open in a new tab just open in the current tab instead. heads up: this option does not affect links fired by hinting, so don't come for me.
• sans-serif-font (string) — the font family used as the default for content in sans-serif font.
• scripts (bool) — literally decides whether JavaScript executes inside a page or not. that's it, that's the whole thing 👑
• scroll-step (int) — how many pixels vimb scrolls when you hit 'j' or 'k'.
• scroll-multiplier (int) — a multiplier that bumps up the scroll distance when the window gets scrolled by the mouse wheel. scroll girlies rise 🖱️
• serif-font (string) — the font family used as the default for content in serif font.
• show-titlebar (bool) — determines whether the titlebar is shown (on systems that provide window decoration, so like, some of them). defaults to true.
• site-specific-quirks (bool) — enables the site-specific compatibility workarounds. the "this site is weird and we're handling it" switch ✨
• smooth-scrolling (bool) — enable or disable support for smooth scrolling.
• spatial-navigation (bool) — whether to enable Spatial Navigation. this feature is all about being able to navigate between focusable elements in a web page — hyperlinks, form controls, that kind of thing — by using the Left, Right, Up and Down arrow keys. so if you press Right, heuristics figure out whether there's an element you might be reaching toward on the right, and if there's more than one candidate, which element you probably actually want. lowkey genius 🧭
• spell-checking (bool) — enable or disable the spell checking feature.
• spell-checking-languages (string) — sets a comma separated list of spell checking languages used for spell checking. the locale string is typically in the form lang_*COUNTRY*, where lang is an ISO-639 language code and COUNTRY is an ISO-3166 country code. for instance sv_FI for Swedish as written in Finland, or pt_BR for Portuguese as written in Brazil 🌍
• status-bar (bool) — indicates if the status bar should be shown.
• status-bar-show-settings (bool) — whether to show settings on the status bar. this puts some runtime settings that were specified at compile time on the right hand side of the status bar. cute little flex 💅
• status-css (string) — CSS style applied to the status bar on none https pages.
• status-ssl-css (string) — CSS style applied to the status bar on https pages with a trusted certificate. green flag energy ✅
• status-ssl-invalid-css (string) — CSS style applied to the status bar on https pages with an untrusted certificate. 🚩
• strict-ssl (bool) — if 'on', vimb will not load an untrusted https site. periodt, no exceptions.
• stylesheet (bool) — if 'on', the user defined styles-sheet is used.
• tabs-to-links (bool) — whether the Tab key cycles through elements on the page.

if true, pressing Tab focuses the next element in the web view. otherwise the web view just interprets Tab key presses as normal key presses — and if the selected element is editable, Tab will insert an actual Tab character. two very different lives, honestly 😭

• timeoutlen (int) — the time in milliseconds that's waited for a key code or a mapped key sequence to complete. the "how long do I hold the door open for you" of keybindings ⏳
• user-agent (string) — the user-agent string used by WebKit.
• user-scripts (bool) — if 'on', the user scripts get injected into every page.
• webaudio (bool) — enable or disable support for WebAudio on pages. WebAudio is an experimental proposal for allowing web pages to generate Audio WAVE data from JavaScript. experimental!! so like, keep that in mind bestie 🎧
• webgl (bool) — enable or disable support for WebGL on pages.
• webinspector (bool) — determines whether or not developer tools, such as the Web Inspector, are enabled. dev girlies stay winning 🔍
• x-hint-command (string) — the command used if hint mode ;x is fired. it can be any vimb command string. note that the command gets run through the mapping mechanism of vimb, so it might change the behaviour by adding or changing mappings. iykyk.

:set x-hint-command=:sh! curl -e <C-R>% <C-R>;

this fills the inputbox with the prefilled download command and replaces <C-R>%' with the current URI and <C-R>;' with the URI of the hinted element. so good.

:nnoremap ;f :set x-hint-command=:sh! firefox '<C-R>;<CR><CR>;x

this makes the key sequence ";f" start hinting and then open the hinted URI in firefox. literally iconic 🔥

---

🎀 FILES 🎀

• $XDG_CONFIG_HOME/vimb[/PROFILE] — directory for configuration data. if executed with -p PROFILE parameter, configuration is read from this subdirectory.
  • config — Ex commands from this file are executed on startup.
  • scripts.js — this file can be used to run user scripts, which get injected into every page that gets opened.
  • style.css — file for userdefined CSS styles. these files are used if the config variable stylesheet is enabled.
• $XDG_DATA_HOME/vimb[/PROFILE] — directory for runtime data. if executed with -p PROFILE parameter, data files are written from this subdirectory.
  • cookies.db — Sqlite cookie storage. this file will not be touched if option --incognito is set. 🥸
  • closed — holds the URIs of last closed browser windows. this file will not be touched if option --incognito is set.
  • history — this file holds the history of unique opened URIs. this file will not be touched if option --incognito is set.
  • bookmark — this file holds the list of bookmarked URIs with tags.
  • command — this file holds the history of commands and search queries performed via input box. this file will not be touched if option --incognito is set.
  • queue — holds the read it later queue filled by qpush.
  • search — this file holds the history of search queries. this file will not be touched if option --incognito is set.

ok so the theme here is that --incognito keeps its hands off like five separate files. respect the privacy bestie 🙈

---

🌈 ENVIRONMENT 🌈

• http_proxy, HTTP_PROXY — if either environment variable is non-empty, the specified host and optional port is used to tunnel requests. for example: HTTP_PROXY=localhost:8118.

---

💀 REPORTING BUGS 💀

found a bug? report bugs to the main project page on https://github.com/fanglingsu/vimb/issues or on the mailing list https://lists.sourceforge.net/lists/listinfo/vimb-users. we love a paper trail ✨

---

👑 AUTHOR 👑

Daniel Carl — that's the main character right there 🫶

---

and that's the whole page, bestie, we made it to the end 🎉 this is vimb/4.0.0, dated 09 2026, section VIMB(1) — go forth and browse, you're literally so good at this now 💖🦋🌸