INTRODUCTION

Any program can only be really useful if it complies with the Unix philosophy. Web browsers (and other tools that work with HTML, such as feed readers) are frequent violators of this principle:

The Uzbl project was started as an attempt to resolve this.

EDITIONS

"Uzbl" is an umbrella project consisting of different flavors. In the future more things may come, but for now:

uzbl-core

Main component meant for integration with other tools and scripts.

uzbl-browser

A minimal browser which encompasses a default configuration file, event manager and a selection of scripts which gives a comparable browsing experience to the more common browsers.

uzbl-tabbed

A flavor of uzbl built on top of uzbl-browser which adds tabbed browsing.

Throughout the documentation, when referring to uzbl we mean uzbl-core, unless otherwise specified.

CONFIGURATION / CONTROL:

The general idea is that Uzbl by default is very bare bones. You can send it commands to update settings and perform actions, through various interfaces. There is a limited, built-in default configuration. It sets a basic status bar, title format, and network connection settings. By default, there are no keybindings defined at all (default keybindings would be counterproductive when you try to customize). For examples of the possibilities what you can do, please see the sample configurations, and wiki page.

There are several interfaces to interact with Uzbl:

When uzbl forks a new instance (e.g., "open in new window") it will use the same command line arguments (e.g., the same --config <file>), except for --named. If you made changes to the configuration at runtime, these are not passed on to the child.

WebKit1 vs. WebKit2

WebKit2 changes many things compared to WebKit1, some of which impact uzbl greatly. This version of uzbl only supports WebKit1 while older version tried to support both at the same time.

For a uzbl built on WebKit2 check out the next branch

COMMAND SYNTAX

Uzbl will read commands via standard input, named FIFO pipe (once fifo_dir is set) and Unix socket (once socket_dir is set). For convenience, uzbl can also be instructed to read commands from a file on startup by using the --config option. Indeed, the config file is nothing more than a list of commands with support for comments (using the # character).

Each command starts with the name of a command or a uzbl variable that expands to it. A command is terminated by a newline. Empty lines and lines that start with the hash sign (ignoring leading whitespace) are ignored by the parser. Command names are always written in lowercase.

A list of commands supported by uzbl is given here. Optional arguments are given in square brackets ([]) with literal strings options in lowercase separated by a pipe (|) character. N indicates an integer value and other uppercase values are placeholders describing what the value should be. Required options are given in angle brackets (<>). Arguments on which argument splitting is not performed are given in curly braces ({}). Variable arguments are indicated with ellipses (...). As an example:

`example1 <a|b> <N> [URI...]`

means that the command example requires its first argument which must either be a literal a or b, a second argument which is an integer, and any remaining arguments are treated as URIs. Another example:

`example2 <KEY> {VALUE}`

means that the first argument is split off used as a key and the remaining string is used verbatim. The command example2 key many args would have key as KEY and many args as VALUE.

Navigation

Page

Cookie

Display

Content

Search

Execution

Uzbl

Variable

VARIABLES AND CONSTANTS

Uzbl has a lot of internal variables and constants. You can get the values (see the print command), and for variables you can also change the value at runtime. Some of the values can be passed at start up through command line arguments, others need to be set by using commands (e.g., in the configuration file).

Integer variables may be negative, boolean values should be either 0 or 1. Commands are variables intended to be executed as uzbl commands. All user variables are treated as strings.

Uzbl

Communication

Handler

Window

UI

Customization

Printing

Network

Security

Inspector

Page

JavaScript

Image

Spell checking

Form

Text

Font

Font size

Note: font sizes are in points.

Features

HTML5 Database

Hacks

Constants

Constants may not be assigned to. When dumping variables using dump_config, they are written as comments.

VARIABLE EXPANSION

Variable expansion works similarly to shell interpreters (sh, bash, etc.). This means you can construct strings with uzbl variables in them and have uzbl replace the variable name with its contents.

In order to let uzbl know what to expand you'll need to prepend @ to the variable name:

print The variable \@show_status contains @show_status

The above example demonstrates two things:

As in the shell you can use @{uzbl_var} to denote the beginning/end of the variable name in cases where it is not obvious what belongs to the name and what not, e.g., print @{show_status}foobar

There are multiple constructs for more complex expansion.

Shell expansion

Uzbl command expansion

JavaScript expansion

XML escaping

JavaScript API

Uzbl has a JavaScript API available via the js uzbl command. There is a global uzbl object can control uzbl through two properties: variables and commands. For example, to set the verbose variable:

uzbl.variables.verbose = 1

To call the back command:

uzbl.commands.back()

All arguments to commands be converted to strings, so {} will appear to commands as [object Object], not JavaScript objects.

Accessing the web page

Currently, access to the webpage is not available through the uzbl context. This is currently impossible with WebKit2 (since even uzbl does not have access to the page's JavaScript context) and crashes WebKit1.

TITLE AND STATUS BAR EVALUATION

The contents of the status bar can be customized by setting the status_format variable. The contents of the window title can be customized by setting the title_format_short variable (which is used when the status bar is displayed) and the title_format_long variable (which is used when the status bar is not displayed). Their values can be set using the expansion and substitution techniques described above.

These variables are expanded in multiple stages; once when the variable is set, and again every time that the status bar or window title are updated. Expansions that should be evaluated on every update need to be escaped:

set title_format_short = @(date)@
# this expansion will be evaluated when the variable is set.
# the title will stay constant with the date that the variable was set.

set title_format_short = \@(date)\@
# this expansion will be evaluated when the window title is updated.
# the date in the title will change when you change pages, for example.

set title_format_short = \\\@(date)\\\@
# the title will stay constant as a literal "@(date)@"

The status_format and status_format_right variables can contain Pango markup . In these variables, expansions that might produce the characters <, & or > should be wrapped in @[]@ substitutions so that they don't interfere with the status bar's markup; see the sample config for examples.

EXTERNAL SCRIPTS

You can use external scripts with Uzbl the following ways:

Scripts called by uzbl (the commands starting with spawn) have access to the following environment variables:

Handler scripts (download_handler, navigation_handler, request_handler, mime_handler, authentication_handler, permission_handler, tls_error_handler, file_chooser_handler, and color_chooser_handler) are called with special arguments:

WINDOW MANAGER INTEGRATION

As mentined before, the contents of the window title can be customized by setting the title_format_short variable and the title_format_long variable (see above to figure out when each of them is used). You can also set icon variable to path of the icon file. Some advanced window managers can also take WM_WINDOW_ROLE in account, which can be set by modifying window_role variable.

Uzbl does not automatically use the current page's favicon as its icon. This can, however, be done with external scripts.

Uzbl sets the UZBL_URI property on its window which is always the uri of the page loaded into uzbl, except for web inspector windows which does not have the property.

EVENTS

Unlike commands, events are not handled in uzbl itself, but are dispatched asynchronously through a text stream on stdout and/or through a socket. You'll usually use uzbl by connecting it to a so-called "event manager" (EM).

An EM is a privileged communicator with uzbl. EM sockets are given on the command line via the --connect-socket argument. EM sockets receive requests in addition to events. All sockets receive event output. Please be aware that events contain sensitive information such as cookie data and keystrokes (e.g., passwords).

An example EM is shipped with uzbl called uzbl-event-manager. See its documentation for more.

Many of the features of larger browsers are intended to be implemented via an EM. The EM receives all events and requests from uzbl and can implement history, keybindings, cookie management, and more. For more on the EM shipped with uzbl, see its documentation

Format

Events are reported in the following format.

 EVENT <NAME> <EVENT_NAME> {DETAILS}

Events are line-oriented, so newlines are not supported within events.

Requests use the following format:

REQUEST-<COOKIE> <REQUEST_NAME> [ARGUMENTS...]

Only EM sockets receive REQUEST lines. Currently, if a reply is not received within one second from uzbl sending a request, uzbl will continue without a reply. This is because the request blocks the GUI thread. Replies to a request use the following format:

REPLY-<COOKIE> <REPLY>

If the cookie does not match the cookie from the request, uzbl will ignore it.

Built-in events

Uzbl will report various events by default. All of these events are part of uzbl itself and will be emitted based on what is happening within uzbl-core.

Navigation
Input
Commands
Uzbl
Page
Window
Download
Cookie

COMMAND LINE ARGUMENTS

uzbl is invoked as

uzbl-core [ARGUMENTS] [URI]

where arguments and uri are both optional. arguments can be:

uzbl-core scheme://address will work as you expect. If you don't provide the scheme:// part, it will check if the argument is an existing file in the filesystem, if it is, it will prepend file://, if not, it will prepend http://.

BUGS

Please report new issues to Uzbl's issues page on github