DWB(1) Manual Page

NAME

SYNOPSIS

DESCRIPTION

dwb(1) is a small webbrowser based on WebKit and GTK which aims to be mostly
keyboard-driven.

OPTIONS

-c, --check-script-syntax=script

Checks if a the syntax of a script that uses the javascript api is correct.

-d, --delete-profile=profile

Deletes a profile.

-e, --embed=wid

Embed dwb into <wid>.

-f, --force

Force restoring a previously saved session, even if it seems that another
process has opened a session with the same name.

--fifo

Use a fifo for single instance instead of dbus, all instances must pass this
option to use the fifo.

-l, --list-sessions

List previously saved sessions. A * indicates that another instance has
currently opened the session.

-n, --new-instance

New instance, overrides setting
single-instance.

-p, --profile=profilename

Load configuration for profile profilename.

-r, --restore=sessionname

Restore session with name sessionname
or the default session, if sessionname is omitted.

-R, --override-restore

Open a new session, even if save-session is enabled.

-S, --enable-scripts

Enables the javascript interface, if there are scripts in
$XDG_CONFIG_HOME/dwb/userscripts that use the javascript api this option is
not needed.

--set-as-default

Sets dwb as default browser, if called with no arguments it will be set for all
mimetypes listed in dwb.desktop, if the first argument is mimetype it will be
set for all succeding mimetypes, e.g. dwb --set-as-default "mimetype text/html"
if the first argument is extension it will be set for all succeeding filename
extensions, e.g. dwb --set-as-default "extension html htm".

-x, --execute=commands

Execute a list of dwb commands separated by ;;, see
CUSTOM COMMANDS
and COMMAND OVERVIEW for details.
If single instance is enabled all commands will be executed in the primary
instance.

-v, --version

Show version information and exit.

MODES

dwb has different modes:

Normal mode

The default mode. Pressing Escape always enter
normal mode, all keyboard inputs will be interpreted as shortcuts, keypresses
are not sent to the webview.

Insert mode

Used for editing text elements in a webpage.

Hint mode

Follow links via hints.

Command mode

Execute dwb commands from the builtin commandline.

SHORTCUTS

Normal mode shortcuts

[n]j

Scroll [n times] down (command: scroll_down, aliases: down).

[n]k

Scroll [n times] up (command: scroll_up, aliases: up).

[n]h

Scroll [n times] left (command: scroll_left, aliases: left).

[n]l

Scroll [n times] right (command: scroll_right, aliases: right).

[n]gg

Scroll to the top or to n% of the page (command: scroll_top, aliases: top).

[n]G

Scroll to the bottom or to n% of the page (command: scroll_bottom, aliases: bottom).

Allow persistent cookie for the current website. The domain will be saved in
cookies.allow.
Cookies that are allowed by the cookies.allow whitelist are stored in
$XDG_CONFIG_HOME/dwb/$profilename/cookies. (command
allow_cookie, aliases: cookie).

CS

Allow session cookie for the current website. The domain will be saved in
cookies_session.allow.
This is only useful if cookies-store-policy is set to never, see
cookies-store-policy for details. (command
allow_session_cookie, aliases: scookie).

CT

Allow session cookies for the current website temporarily. Only first party
cookies are allowed. The domain is not saved to a whitelist and the cookies will
not be saved persitently. (command
allow_session_cookie_tmp,
aliases:
tcookie).

[n]yy

Yank the url of tab n or of current tab if n is omitted to clipboard
(command
yank).

yY

Yank the url of tab n or of current tab if n is omitted to primary
selection (command yank_primary, aliases: pyank).

yt

Yank the title of tab n or of current tab if n is omitted to clipboard
(command yank_title, aliases: tyank).

yT

Yank the title of tab n or of current tab if n is omitted to primary
selection (command yank_title_primary, aliases: tpyank).

Paste from clipboard and load in a new tab (command tab_paste, aliases: tpaste).

PP

Paste from primary selection and load in a new tab (command tab_paste_primary,
aliases: tppaste).

wp

Paste from clipboard and load in a new window (command paste_nw, aliases:
winpaste).

wP

Paste from primary selection and load in a new window (command
paste_primary_nw, aliases: winppaste).

[n]ad

Cancel the download with number n or the first download in the lists of running
downloads if n is omitted. (command cancel_download).

gs

Add a searchengine. Textfields can be chosen with tab and a keyword must be
specified. The first defined searchengine will be the default searchengine. The
keyword can be used in all open commands, e.g.
:open <keyword> <searchterm> (command save_search_field, aliases: search).

gd

Download the current site. (command download).

Sb

Show bookmarks (command show_bookmarks, aliases: sbookmarks).

Sq

Show quickmarks (command show_quickmarks, aliases: squickmarks).

Sh

Show history (command show_history, aliases: shistory).

Sd

Show download (command show_downloads, aliases: sdownloads).

Sk

Show keys (command show_keys, aliases: skeys).

Ss

Show settings (command show_settings, aliases: ssettings).

ss

Set setting, the interactive version of the command set, for changing settings
in scripts use set instead (command set_setting).

sl

Set local setting, changes a setting but doesn’t save the setting to
configuration file. The interactive version of the command local_set, for
changing settings locally in scripts use local_set instead
(command set_local_setting).

Load a html string. This command is mainly intended for use in userscripts (command
load_html).

unbound

Load a html string in a new tab. This command is mainly intended for use in userscripts (command
load_html_tab).

unbound

Execute a javascript snippet that uses the the internal javascript api. This
command only works if the javascript interface is enabled, i.e. if there are
scripts in $XDG_CONFIG_HOME/dwb/userscripts that use the api or if dwb is
started with -S/--enable-scripts (command
eval).

Tab (S-Tab)

In normal mode Tab shows the next (previous) shortcut, that matches the
currently entered keysequence.
When opening a url, the next (previous) item in command
history, bookmarks or history will be completed. In hint mode the next (previous)
hint will get focus. Tab also completes settings and shortcut-settings.
When initiating a download, full paths (downloads and spawning programs) and
binaries (spawning programs) in PATH will be completed.
In command mode tab will complete builtin commands and urls if the command
accepts an url.

Textentry shortcuts

C-h

Delete a single letter.

C-w

Delete word back.

C-e

Delete word forward.

C-u

Delete to the beginning of the entry.

C-i

Delete to the end of the entry.

C-f

Move cursor one word forward.

C-b

Move cursor one word back.

C-j

Show next item in command history.

C-k

Show previous item in command history.

C-x

When initalizing a download, C-x toggles between choosing a file path and
choosing a spawning application.

C-g

Alternative shortcut for activate.

C-c

Alternative shortcut for escape, the corresponding setting is
entry_escape.

C-p

Init local path completion.

C-H

Init history completion.

C-B

Init bookmark completion.

C-I

Init input history completion.

C-S

Init searchengine completion.

C-U

Init userscript completion.

C-p

Complete local path.

Shortcut syntax

All printable shortcuts are case sensitive, i.e. aH means press a then press
shift, then press h. Shortcuts can be combined with a modifier, valid modifiers
are Control, Mod1, Mod4 and Shift
where Shift can only be used with non printable keys such as F1, space, Tab, … .
Non printable keys must be surrounded by @, e.g. "Control @F1@", Shift @space@.
\ and @ itself must be escaped with \.

CUSTOM COMMANDS

Custom commands are a sequence of dwb commands that can be bound to a shortcut.
The syntax is

<shortcut>:<command>;;<command>;;...

where shortcut is the shortcut for the commandsequence, : may be escaped with \:
and command is of the form

Write html of current website to a
file or stdout if no argument is given

eval

Execute a javascript snippet that
uses the internal javascript api

execute_javascript

exja, js

Execute a javascript snippet

execute_userscript

Execute userscript

find_backward

bfind

Find backward

find_backward_ic

ibfind

Find backward case sensitive

find_forward

ffind

Find forward

find_forward_ic

iffind

Find forward case sensitive

find_next

fnext

Find next

find_previous

fprev

Find previous

focus_input

Focus next input

focus_next

tabnext

Focus next tab

focus_prev

tabprev

Focus previous tab

focus_tab

tab

Focus nth tab

fullscreen

fs

Toggle fullscreen

hints

hi

Follow hints

hints_background

backhints, bhi

Follow hints in a background tab

hints_clipboard

chints, chi

Save link location to clipboard

hints_download

dhints, dhi

Download via hints

hints_editable

ehints, ehi

Focus editable elements

hints_images

ihints, ihi

Follow images

hints_images_tab

itabhints, ithi

Follow images in a new tab

hints_images_background

ibackhints

Follow images in a background tab

hints_links

lhints, lhi

Follow links

hints_primary

phints, phi

Save link location to primary
selection

hints_rapid

rhints, rhi

Open new tabs in background
rapidly

hints_rapid_win

wrhints, wrhi

Open new windows rapidly

hints_tab

tabhints, thi

Follow hints in a new tab

hints_url

uhints, uhi

Set hints url in commandline

hints_url_tab

utabhints, uthi

Set hints url in commandline,
open in a new tab

hints_url_background

ubackhints

Set hints url in commandline,
open in a background tab

hints_win

winhints, whi

Follow hints in a new window

history_back

ba, back

Go back

history_forward

fo, forward

Go forward

insert_mode

i, insert

Insert mode
local_set Set a setting only for the running
instance, don’t save it to the
configuration file

lock_domain

dlock

Lock tab to current domain

lock_uri

ulock

Lock tab to current uri

new_tab

Open next navigation action in
new tab

new_win

Open next navigation action in
new window

only

Close all tabs except for the
current one

open

o

Open url

open_editor

editor

Open external editor for
input/textarea

open_url

Open, edit current url

paste

Open from clipboard

paste_primary

ppaste

Open from primary selection

presentation_mode

present

Toggle presentation mode

print

ha

Print page

print_preview

Show a print preview

protect

prot

Protect/unprotect tab

proxy

Toggle proxy

quickmark

qmarks

Open quickmark

quit

q

Quit

reload

re

Reload current page

reload_bookmarks

Reload bookmark file

reload_bypass_cache

refull

Reload without using cached data

reload_quickmarks

Reload quickmark file

reload_userscripts

Reload userscripts

save

Save all configuration files

save_named_session

wqn

Save current session with name

save_quickmark

qmark, quickmark

Save a quickmark

save_search_field

search

Add a new searchengine

save_session

wq

Save current session

scroll_bottom

bottom

Scroll to bottom of the page

scroll_down

down

Scroll down

scroll_halfpage_down

halfdown

Scroll one-half page down

scroll_halfpage_up

halfup

Scroll one-half page up

scroll_left

left

Scroll left

scroll_page_down

pagedown

Scroll one page down

scroll_page_up

pageup

Scroll one page up

scroll_right

right

Scroll right

scroll_top

top

Scroll to the top of the page

scroll_up

up

Scroll up

sanitize

Clears history and cookies,
sanitize history only clears history
sanitize cookies only clears cookies

set

Set a setting

set_key

keys

Set keybinding

set_local_setting

Set a setting for the running instance
interactively

set_setting

Set a setting interactive

show_keys

skeys

Show and modify keyboard
configuration

show_settings

ssettings

Show and modify global properties

start_page

home

Open the default homepage

stop_loading

st, stop

Stop loading current page

tab_bookmarks

tabmarks

Show bookmarks, open in new tab

tabdo

Execute a command in all tabs

tabgrep

Focus a tab by pattern or regular
expression, regular expressions must
start with /

tab_hist_back

tba, tabback

Go back in a new tab

tab_hist_forward

tfo, tabforward

Go forward in a new tab

tab_move

tabm

Move tab

tab_move_left

tabl

Move tab left

tab_move_right

tabr

Move tab right

tab_new

Open a new blank tab

tab_paste

tpaste

Open from clipboard in a new tab

tab_paste_primary

tppaste

Open from primary selection in a
new tab

tab_quickmark

tabqmarks

Open quickmark in a new tab

tabopen

t, topen

Open in a new tab

tabopen_url

Open in a new tab, edit current
url

toggle_bars

bars

Toggle tabbar and statusbar

toggle_hidden_files

hidden

Toggle hidden files in directory
listings

toggle_plugins_host

hplugin

Toggle plugin blocker for host

toggle_plugins_host_tmp

tuplugin

Toggle plugin blocker for domain
for this session

toggle_plugins_uri

uplugin

Toggle plugin blocker for uri

toggle_plugins_uri_tmp

tuplugin

Toggle plugin blocker for uri for
this session

toggle_scripts_host

hscript

Toggle scripts for current domain

toggle_scripts_host_tmp

thscript

Toggle scripts for current host
for this session

toggle_scripts_uri

uscript

Toggle scripts for current uri

toggle_scripts_uri_tmp

tuscript

Toggle scripts for current uri
for this session

toggle_setting

tog, toggle

Toggle a setting

toggle_local_setting

loctog

Toggle a setting for the current
session

toggle_statusbar

sbar

Toggle statusbar

toggle_tab

ttab

Toggle between current and last tab

toggle_tabbar

tbar

Toggle tabbar

undo

u

Undo closing last tab

view_source

so, source

View page source

visible

vis

Toggle visibility of a tab

web_inspector

insp, inspect

Open the webinspector

win_bookmarks

winmarks

Show bookmarks, open in new
window

win_hist_back

wba, winback

Go back in a new window

win_hist_forward

wfo, winforward

Go forward in a new window

win_paste

wpaste

Open from clipboard in a new
window

win_paste_primary

wppaste

Open primary selection in a new
window

win_quickmark

winqmarks

Open quickmark in a new window

winopen

w, wopen

Open in a new window

winopen_url

Open in a new window, edit
current url

yank

Yank url to clipboard

yank_primary

pyank

Yank url to primary selection

yank_title

tyank

Yank title to clipboard

yank_title_primary

tpyank

Yank title to primary selection

zoom

z

Zoom

zoom_in

zi

Zoom in

zoom_out

zo

Zoom out

dwb can be customized in a web interface (command show_settings) or via command line (command
set_setting). Modified settings will be saved in ~/.config/dwb/settings
when closing dwb. Shortcuts can also be modified in a web interface (command
show_keys) or via command line (command set_key). Shortcuts will be saved
in $HOME/.config/dwb/keys.

Whether to enable the Frame Flattening. With this setting each subframe is expanded
to its contents, which will flatten all the frames to become one scrollable page.
Whether file uris can be accessed. Possible values: true/false,
default value: false.

Whether to enable the Spatial Navigation. This feature consists in the ability
to navigate between focusable elements in a Web page, such as hyperlinks and
form controls, by using Left, Right, Up and Down arrow keys.
Possible values: true/false,
default value: false.

Block advertisements using a filterlist, see also
.IR adblocker-filterlist .
Default value:
false.

adblocker-filterlist

A path to a adblock plus compatible filterlist for the adblocker or a path to a
directory with filterlists.
Default value:
NULL.

addressbar-dns-lookup

Whether to perform a dns lookup for text typed into the address bar. If set to
true dwb performs a dns lookup for all text that does not have a valid scheme
and does not contain whitespaces. Default value:
false.

Maximum time in seconds after a persistent cookie expires, the suffix m can be
used for minutes, h for hours, and d for days, the maximum will only be used
if it is smaller than the original expiration time. Setting cookie-expiration to
0 will use the original expiration time of the cookie.

cookies-store-policy

The storage policy for cookies, possible values are session, persistent, and
never. If set to session all session cookies are accepted, only cookies with
a matching domain in cookies.allow will be stored persistently. If set to
persistent all cookies are stored persistently. If set to never the cookies
allowed by cookies_session.allow are allowed for the current session and cookies
allowed by cookies.allow are save persistently, all other cookies are rejected.
Default value: session.

cookies-accept-policy

The accept policy for cookies. always will accept all cookies, nothirdparty
will accept all cookies except for third party cookies, never will reject all
cookies. This setting also affects session cookies. default value: always.

The end color for the download progress gradient color, default value
#00aa00.

download-external-command

A command that will be invoked if download-use-external-program is set. There
are four variables that can be used in the command: dwb_uri will be replaced
with the download-uri, dwb_output will be replaced with the fullpath of the
destination, dwb_cookies will be replaced with the path to the cookie-file,
dwb_referer will be replaced with the uri of the site the download started,
dwb_proxy will be replaced with the proxy url if dwb uses a proxy.
Additionally the environment-variables DWB_URI, DWB_FILENAME, DWB_COOKIES,
DWB_REFERER, DWB_MIME_TYPE, DWB_PROXY and DWB_USER_AGENT are set. Default value:
xterm -e wget dwb_uri -O dwb_output --load-cookies dwb_cookies.

download-directory

The default download directory, if empty, the current working directory is used
or the last download path is used. default value: NULL.

download-no-confirm

Whether to start downloads immediately without asking for a path,
download-directory needs to be set to an existing path. default value:
false.

download-use-external-program

Whether to use an external download program specified in
download-external-programm or the builtin download helper. Possible values:
true/false, default value: false.

Left offset of hints in pixel, negative values will shift hints to the left, positive
values to the right,
default value: 0.

hint-offset-top

Top offset of hints in pixel, negative values will shift hints to the top, positive
values to the bottom,
default value: 0.

hint-opacity

The opacity of a hint. Possible values: a decimal from 0.0 to 1.0,
default value: 0.75.

hint-style

The type of hints, that are used. When set to "number", letters will match the
links text. Possible values: letter/number, default value: letter.

hints-key-lock

Timeout in milliseconds all keypresses are ignored after following a hint,
default value: 250

history-length

The urls that are saved in the browsing history. Specifying a too large value
can make tab-completion slow. Possible values: number of urls,
default value: 500.

javascript-api

Whether to enable the javascript api. If set to disabled the javascript
context won’t be initialized, meaning that also extensions won’t work. If set to
automatic the javascript context will automatically be initialized if scripts that use
the api are present in $XDG_CONFIG_HOME/dwb/userscripts or extensions are
installed. If set to enabled the javascript context will always be
initialized, useful if no scripts are present in
$XDG_CONFIG_HOME/dwb/userscripts but the javascript api is used from commandline
or in a custom command. The javascript context is only initialized on startup,
so changing the value needs a restart. Default value:
automatic.

Whether to defer loading of a tab until a tab is focused, especially
useful on startup and with slow internet connections, default value: false.

max-visible-completions

The maximum number of visible completions, default value: 11.

maximum-tabs

Limits the maximum number of visible tabs, 0 means no limit. If
tab-orientation is set to vertical-left or vertical-right the number of
maximum tabs is computed automatically and maximum-tabs will be ignored, default
value: 0.

Maximum length of navigation history. enable-private-browsing must be disabled to
save command history at all. default value: 500.

new-tab-position-policy

Controls the position of a newly created tab, possible values are right,
a new tab is created right of the current tab, left, a new tab is created left
of the current tab, rightmost, a new tab is created left of the last tab and
leftmost, a new tab is created left of the first tab. Default value: right.

Keysstrokes that will be passed to the website, webkit means only webkit builtin
shortcuts will be passed through, all means all will be passed through, none
means no keystrokes will be passed through, default value: webkit.

The proxy-url, can also be set via the http_proxy environment variable. Possible
values: an url string, default value: NULL.

save-session

Save the session when dwb is closed and restore the last saved session when
invoking dwb. Possible values: true/false, default value: true.

scheme-handler

A script or application that handles uris that cannot be loaded by dwb. dwb only
loads uris with scheme http, https, file, about and dwb; support for
e.g. ftp is provided through a scheme handler. The scheme handler can either be
an application or a script. The first command line argument will be the uri for
your application, so you can simply set this to xdg-open. There are also the
environment variables DWB_URI, DWB_SCHEME, DWB_COOKIES, DWB_USER_AGENT,
DWB_PROXY and DWB_REFERER available which can be used in a script, for
example:

Whether to show the tabbar if only one tab is open, default value: true.

searchengine-submit-pattern

The pattern which will be replaced with the search terms.

scroll-step

The step-increment in pixels for scrolling. If set to a value lower or equal 0,
the default step-increment will be used. default value: 0.0.

scrollbars

Whether scrollbars should be enabled. default value: false.

single-instance

Only one instance of dwb per user. This option will be overridden by the
command line option -n. Possible values: true/false,
default value: true.

ssl-strict

Whether to allow only save ssl-certificates. default value: true.

ssl-ca-cert

Path to ssl-certificate, only with libsoup < 2.38.

ssl-use-system-ca-file

Whether to use the system certification file, only with libsoup >= 2.38.
default value: true.

ssl-trusted-color

Color of the url in the statusbar for ssl-encrypted sites and trusted
certificate. default value: #00ff00.

ssl-untrusted-color

Color of the url in the statusbar for ssl-encrypted sites and untrusted
certificate. default value: #ff0000.

startpage

The default startpage. Possible values: an url or "about:blank" for an empty
startpage, default value: about:blank.

sync-files

Type of files to sync, see also file-sync-interval.
Possible values are all, cookies, history, session or a combination,
default value: all.

tab-orientation (GTK2 only)

Orientation of tabs, possible values are horizontal, vertical-left and
vertical-right, if set to vertical-left or vertical-right t and T in
widget-packing will be ignored, instead tabs are placed left/right to the
webview respectively, default value: horizontal.

tab-width (GTK2 only)

Width of vertical tabs in pixel, will be ignored for horizontal tabs, horizontal tabs
will always use the complete space, default value 100.

tabbar-visible

When the tabbar is hidden specifies the number of seconds the tabbar is visible
when switching between tabs, default value: 2.

The foreground color of the tab of the focused tab. Possible values: an rgb
color-string, default value: #ffffff.

tab-normal-bg-color

The background color the tab of a not focused tab. Possible values: an rgb
color-string, default value: #505050.

tab-normal-fg-color

The foreground color of the tab of a not focused tab. Possible values: an rgb
color-string, default value: #cccccc.

tab-normal-fg-color

The foreground color of the tab of a not focused tab. Possible values: an rgb
color-string, default value: #cccccc.

tab-protected-color

The color of the tabnumber of protected tabs. Possible values: an rgb color-string,
default value: #ff0000.

tab-number-color

The color of the tabnumber. Possible values: an rgb color-string,
default value: #ff0000.

tabbed-browsing

Enable tabbed-browsing. If disabled, all new window/new tab requests will be
opened in a new window,
default value:
true.

update-search-delay

Delay in milliseconds before updating search results. If set to 0 search results
will be updated after every keypress. If set to a value greater than 0 search
results will be updated after that delay but only if the search-term has not
changed since the timeout started. It is recommended to set this value greater
than 0, default value: 200.

widget-packing

A string consisting of 4 characters, where possible characters are: d, w,
T, t, S and s. The order of the widgets correspond the the order of
characters in the string where d corresponds to the download bar, t and T
to the tab bar where T means that the tabbar will not be visible, w to the
webview and s and S to the statusbar where S means that the statusbar
won’t be visible. Default value: dtws.

FILES

Userscripts

Userscripts can be stored in
~/.config/dwb/userscripts.
The first argument of the script will be the current url, the second argument is
the title, the third argument will be the profile name, the fourth argument is
the numerical modifier and the fifth argument is a commandline argument. Also
the variables
DWB_URI,
DWB_TITLE,
DWB_PROFILE,
DWB_NUMMOD,
DWB_ARGUMENT,
DWB_REFERER,
DWB_PROXY,
and
DWB_USER_AGENT
are set.
The keybinding for
the script must be defined in the script itself in a commented line of the form
<comment symbols> dwb: <keybinding>.

dwb also provides a small javascript api, scripts that use the api must have the
special shebang #!javascript or start with //!javascript for details see
also http://portix.bitbucket.org/dwb/api/ and dwb-js(7).