DWBREMOTE(1)

NAME
dwbremote - dwb remote control

SYNOPSIS

dwbremote [OPTION] <command> <arguments>

DESCRIPTION

dwbremote allows one to control dwb from command line. It communicates with dwb instances by setting its XProperties. Return values will be printed to stdout. To use dwbremote enable-ipc must be enabled in the dwb instance to communicate with.

dwbremote tries to find windows depending on the options passed, if no options are used or no windows were found it will use the environment variable DWB_WINID, if it is not set it will use the last dwb window that had focus. In userscripts executed by dwb the environment variable DWB_WINID will always be set and will point to the window that executed the script. Passing more than one option sends the command to all matching windows.

OPTIONS

-a --all
    Sends a command to all windows.

-c --class wm_class
    Search for window id by WM_CLASS.

-i --id window_id
    Send comands to window with id window_id, window ids in hexadecimal format must start with 0x.

-l --list
    List all dwb window ids with enabled ipc.

-n --name wm_name
    Search for window id by WM_NAME.

-p --pid pid
    Search for window id by process id pid.

-s --show-id
    Print the window id in every response, the window id will be prepended to the response.

COMMANDS

add_hooks [hook ...]
    Adds a list of hooks without actually connecting to the hook, see hook for a list of hooks and clear_hooks.

bind command:shortcut [command:shortcut ...]
    Bind a shorcut or command, to bind only a commandline command without binding a shortcut command:none must be used, to bind only a shortcut without binding a commandline command none:shortcut.

clear_hooks [hook ...]
    Removes a list of hooks so the will no longer be emitted. To re-enable hooks add_hooks can be sent. For a list of hooks see hook.

confirm [prompt message]
    Shows a confirmation prompt. Returns true if y was pressed and false if n or Escape was pressed.

execute command
    Executes a command, the command is parsed the same way as if executed from commandline. A shorthand for execute is prepending : to the command, i.e. dwbremote execute scroll_down is equivalent to dwbremote :scroll_down

get argument
    Gets miscellaneous properties

    Arguments

        all_domains
            Gets newline separated list of all domains.

        all_hosts
            Gets newline separated list of all hosts.

        all_titles
            Gets newline separated list of all titles.

        all_uris
            Gets newline separated list of all uris.

        current_tab
            Gets number of the current tab, starting at 1.

        [n] domain
            Gets the effective top level domain of the nth tab or current tab is n is omitted, e.g. for www.example.co.uk it will return example.co.uk.

        [n] history
            Gets the newline separated history list of the nth tab or current tab if n is omitted. The first field is the history number, negative values indicate back history items, positive numbers indicate forward history items, 0 indicates the current uri.

        [n] host
            Gets the host of the nth tab or current tab is n is omitted.

        ntabs
            Gets total number of tabs.

        profile
            Gets the profile name.

        session
            Gets the name of the session.

        setting <name>
            Gets a setting, only the current local settings from the instance are received so they might differ from the settings in $HOME/.config/dwb/settings, e.g. if they were changed with local_set.

        [n] title
            Gets the title of the nth tab or current tab is n is omitted.

        [n] uri
            Gets the uri of the nth tab or current tab is n is omitted.

hook hook [hook ...]
    Connect to a list of hooks.

    Hooks

        change_mode
            Emitted when the mode changes, return format: change_mode <mode>

            mode
                The new mode, can be one of normal, insert, hint, command or caret

        close_tab
            Emitted when a tab is closed, return format: close_tab <n>

            n
                Number of tab that was closed

        document_finished
            Emitted when the DOM document load has been finished for a frame, return format: document_finished <n> <mainframe>

            n
                Number of the tab

            mainframe
                true if it is the DOM document of the mainframe has been finshed loading, false if the DOM document of a subframe has been finshed.

        download_finished
            Emitted when a download has been finished, return format: download_finished <destination_uri>

            destination_uri
                The destination uri of the download, e.g. file:///tmp/download.pdf

        execute
            Emitted when a command is executed, return format: execute <command> <argument> <n>

            command
                Command that is executed

            argument
                Argument if it is a commandline command with argument or none

            n
                Numerical modifier or -1

        focus_tab
            Emitted when a tab gets focus, return format: focus_tab <n>

            n
                Number of tab that gets focus

        hook
            Emitted when the command hook, add_hooks or clear_hooks is executed, return format: hook <action> <hooks>

            action
                Either add if add_hooks or hook is executed, clear if clear_hooks is executed

            hooks
                List of hooks.

        load_committed
            Emitted when new page load has been committed, return format: load_committed <n> <uri>

            n
                Number of the tab

            uri
                Uri that will be loaded

        load_finished
            Emitted when a page load has finished, return format: load_finished <n> <uri>

            n
                Number of the tab

            uri
                Uri that will be loaded

        navigation
            Emitted when a tab or a frame in a tab requests a new page load, return format: navigation <n> <mainframe> <uri>

            n
                Number of the tab

            mainframe
                true if it is the mainframe, false if it is a subframe that requests the new page load

            uri
                Uri that will be loaded

        new_tab
            Emitted when new tab is created, return format: new_tab <n>

            n
                Number of the new tab

prompt promptmessage
    Shows a prompt dialog.

pwd_prompt promptmessage
    Shows a password dialog. Note that using password prompt is not save.

EXAMPLES

Executing commands

        dwbremote :tabopen example.com
        dwbremote -pid 1234 execute 2close

Getting properties

        uri="$(dwbremote -id 0x1000001 get uri)"
        title="$(dwbremote -id 0x1000001 get 2 title)"
        scripts_enabled="$(dwbremote -class foo setting enable-settings)"

User/Password prompt

        username="$(dwbremote prompt Username:)"
        if [ "$username" ]; then
            password="$(dwbremote pwd_prompt Password:)"
        fi

Multiple hooks with one dwbremote instance

        #!/bin/bash
        if [ "$DWB_WINID" ]; then
            DWBRC=dwbremote
        else
            DWBRC="dwbremote -class foo"
        fi
        while read -a array; do
            hook="${array[0]}"
            case "$hook" in
                navigation)
                    ...
                    ;;
                load_finished)
                    ...
                    ;;
                close_tab)
                    ...
                    ;;
            esac
        done < <("$DWBRC" hook navigation load_finished close_tab)

Binding multiple shortcuts

        while read -a array; do
            bind="${array[0]}"
            case "$bind" in
                none:xx)
                    ...
                    ;;
                foobar:gx)
                    ...
                    ;;
            esac
        done < <(dwbremote -pid 1234 bind none:xx foobar:gx)

SEE ALSO

dwb(1)