XDOTOOL(1)

NAME
xdotool - command-line X11 automation tool

SYNOPSIS
xdotool cmd args...

DESCRIPTION
xdotool lets you programatically (or manually) simulate keyboard input and mouse activity, move and resize windows, etc. It does this using X11's XTEST extension and other Xlib functions.

There is some support for Extended Window Manager Hints (aka EWMH or NetWM). See the "EXTENDED WINDOW MANAGER HINTS" section for more information.

KEYBOARD COMMANDS

key [options] keystroke
    Options:

    --window windowid
        Send keystrokes to a specific window id. See SENDEVENT below.

    --clearmodifiers
        Clear modifiers before sending keystrokes. See CLEARMODIFIERS below.

    Type a given keystroke. Examples being "alt+r", "Control_L+J", "ctrl+alt+n", "BackSpace".

    Generally, any valid X Keysym string will work. Multiple keys are separated by '+'. Aliases exist for "alt", "ctrl", "shift", "super", and "meta" which all map to Foo_L, such as Alt_L and Control_L, etc.

    In cases where your keyboard doesn't actually have the key you want to type, xdotool will automatically find an unused keycode and use that to type the key.

    Example: Send the keystroke "F2"
     xdotool key F2

    Example: Send 'a' with an accent over it (not on english keyboards, but still works with xdotool)
     xdotool key Aacute

keydown [options] keystroke
    Same as above, except only keydown events are sent.

keyup keystroke
    Same as above, except only keyup events are sent.

type [options] something to type
    Options:

    --window windowid
        Send keystrokes to a specific window id. See SENDEVENT below.

    --delay milliseconds
        Delay between keystrokes. Default is 12ms.

    --clearmodifiers
        Clear modifiers before sending keystrokes. See CLEARMODIFIERS below.

    Types as if you had typed it. Supports newlines and tabs (ASCII newline and tab). Each keystroke is separated by a delay given by the delay option.

    Example: to type 'Hello world!' you would do:
     xdotool type 'Hello world!'

MOUSE COMMANDS

mousemove [options] x y
    Move the mouse to the specific X and Y coordinates on the screen

    --window WINDOW
        Specify a window to move relative to. Coordinates 0,0 are at the top left of the window you choose.

    --clearmodifiers
        See CLEARMODIFIERS

click [options] button
    Send mousedown followed by mouseup for the given button

    --clearmodifiers
        Clear modifiers before clicking. See CLEARMODIFIERS below.

    --window
        WINDOW - Specify a window to send a click to. See SENDEVENT below for caveats. Uses the current mouse position when generating the event.

mousedown [options] button
    Same as above, except only a mouse down is sent.

mouseup [options] button
    Same as above, except only a mouse up is sent.

getmouselocation [--shell]
    Outputs the x, y, and screen location of the mouse cursor. Screen numbers will be nonzero if you have multiple monitors and are not using Xinerama.

    --shell
        This makes getmouselocation output shell data you can eval. Example:

         % xdotool getmouselocation --shell
         X=880
         Y=443
         SCREEN=0

         % eval $(xdotool getmouselocation --shell)
         % echo $X,$Y
         714,324

WINDOW COMMANDS

search [options] somestring
    Search for windows with titles, names, or classes matching somestring. The output is line-delimited list of X window identifiers

    The options available are:

    --class
        Match against the window class

    --classname
        Match against the window classname

    --maxdepth N
        Set recursion/child search depth. Default is -1, meaning infinite. 0 means no depth, aka no results. If you only want toplevel windows, set maxdepth of 1.

    --name
        Match against the window name

    --onlyvisible
        Show only visible windows in the results.

    --pid PID
        Match windows that belong to a specific process id. This may not work for some X applications that do not set this metadata on its windows.

    --screen N
        Select windows only on a specific screen. Default is to search all screens. Only meaningful if you have multiple displays and are not using Xinerama.

    --title
        Match against the window title (what's displayed in the titlebar of the window)

    The default options are "--title --name --class"

getwindowfocus [-f]
    Prints the window id of the currently focused window.

    If the current window has no WM_CLASS property, we assume it is not a normal top-level window and traverse up the parents until we find a window with a WM_CLASS set and return that window id.

    If you really want the window currently having focus and don't care if it has a WM_CLASS setting, then use 'getwindowfocus -f'

windowsize [options] windowid width height
    Set the window size of the given window

    The options available are:

    --usehints
        Use window sizing hints (when available) to set width and height. This is useful on terminals for setting the size based on row/column of text rather than pixels.

    Example: To set a terminal to be 80x24 characters, you would use: "xdotool windowsize --usehints windowid 80 24"

windowmove windowid x y
    Move the window to the given position

windowfocus windowid
    Focus the window

windowmap window_id
    Map a window. In X11 terminology, mapping a window means making it visible on the screen.

windowraise window_id
    Raise the window to the top of the stack. This may not work on all window managers.

windowunmap window_id
    Unmap a window, making it no longer appear on your screen.

set_window [options] windowid
    Set properties about a window.

    Options:

    --name newname
        Set window WM_NAME (the window title, usually)

    --icon-name newiconname
        Set window WM_ICON_NAME (the window title when minimized, usually)

    --role newrole
        Set window WM_WINDOW_ROLE

    --classname newclassname
        Set window class name (not to be confused with window class)

    --class newclass
        Set window class (not to be confused with window class name)

DESKTOP AND WINDOW COMMANDS
These commands follow the EWMH standard. See the section "EXTENDED WINDOW MANAGER HINTS" for more information.

windowactivate windowid
    Activate the window. This command is different from windowfocus: if the window is on another desktop, we will switch to that desktop. It also uses a different method for bringing the window up. I recommend trying this command before using windowfocus, as it will work on more window managers.

getactivewindow
    Output the current active window. This command is often more reliable than getwindowfocus.

set_num_desktops number
    Changes the number of desktops or workspaces.

get_num_desktops
    Output the current number of desktops.

set_desktop desktop_number
    Change the current view to the specified desktop.

get_desktop
    Output the current desktop in view.

set_desktop_for_window window_id desktop_number
    Move a window to a different desktop.

get_desktop_for_window window_id
    Output the desktop currently containing the given window.

SCRIPTS
xdotool can read a list of commands via stdin or a file if you want. A script will fail when any command fails.

•   Read commands from a file:

     xdotool filename

•   Read commands from stdin:

     xdotool -

•   Read commands from a redirected file

     xdotool - < myfile

You can also write scripts that only execute xdotool. Example:

 #!/usr/local/bin/xdotool
 windowactivate $WINDOWID
 mousemove -window $WINDOWID 50 50
 click 1
 click 1

All commands are run as if you had typed 'xdotool <line>' via /bin/sh. This means any shell magic should work here, too, including the use of environment variables. For above, here's how you'd set the value of WINDOWID:

 % WINDOWID=1234 ./myscript

CLEARMODIFIERS
Any command taking the --clearmodifiers flag will attempt to clear any active input modifiers during the command and restore them afterwards.

For example, if you were to run this command:
 xdotool key a

The result would be 'a' or 'A' depending on whether or not you were holding the shift key on your keyboard. Often it is undesirable to have any modifiers active, so you can tell xdotool to clear any active modifiers.

The order of operations if you hold shift while running 'xdotool key --clearmodifiers a' is this:

1. Query for all active modifiers (finds shift, in this case)
2. Try to clear shift by sending 'key up' for the shift key
3. Runs normal 'xdotool key a'
4. Restore shift key by sending 'key down' for shift

The --clearmodifiers flag can currently clear of the following:

•   any key in your active keymap that has a modifier associated with it. (See xmodmap(1)'s 'xmodmap -pm' output)

•   mouse buttons (1, 2, 3, 4, and 5)

•   caps lock

SENDEVENT NOTES
If you are trying to send key input to a specific window, and it does not appear to be working, then it's likely your application is ignoring the events xdotool is generating. This is fairly common.

Sending keystrokes to a specific window uses a different API than simply typing to the active window. If you specify 'xdotool type --window 12345 hello' xdotool will generate key events and send them directly to window 12345. However, X11 servers will set a special flag on all events generated in this way (see XEvent.xany.send_event in X11's manual). Many programs observe this flag and reject these events.

Some programs can be configured to accept events even if they are generated by xdotool. Seek the documentation of your application for help.

Specific application notes (from the author's testing): * Firefox 3 seems to ignore all input when it does not have focus. * xterm can be configured while running with ctrl+leftclick, 'Allow SendEvents' * gnome-terminal appears to accept generated input by default.

EXTENDED WINDOW MANAGER HINTS
The following pieces of the EWMH standard are supported:

_NET_SUPPORTED
    Asks the window manager what is supported

_NET_CURRENT_DESKTOP
    Query and set the current desktop. Support for this enables these commands: "set_desktop", "get_desktop".

_NET_WM_DESKTOP
    Query and set what desktop a window is living in. Support for this enables these commands: "set_desktop_for_window", "get_desktop_for_window".

_NET_ACTIVE_WINDOW
    Allows you to query and set the active window by asking the window manager to bring it forward. Support for this enables these commands: "windowactivate", "getactivewindow".

SEE ALSO
xprop(1), xwininfo(1),

Project site: <http://www.semicomplete.com/projects/xdotool>

Google Code: <http://semicomplete.googlecode.com/>

CONTACT
Please send questions to xdotool-users@googlegroups.com. File bugs and feature requests at the following URL:

<http://code.google.com/p/semicomplete/issues/list>

Alternately, if you prefer email, feel free to file bugs by emailing the list. What works for you :)

AUTHOR
xdotool was written by Jordan Sissel.

This manual page was written originally by Daniel Kahn Gillmor <dkg@fifthhorseman.net> for the Debian project (but may be used by others). It is maintained by Jordan Sissel.