Provided by: xdotool_3.20160805.1-4_amd64
xdotool - command-line X11 automation tool
xdotool cmd args... Notation: Some documentation uses [window] to denote an optional window argument. This case means that the argument, if not present, will default to "%1". See "WINDOW STACK" for what "%1" means.
xdotool lets you programmatically (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.
key [options] keystroke [keystroke ...] Options: --window window Send keystrokes to a specific window id. You can use "WINDOW STACK" references like "%1" and "%@" here. If there is a window stack, then "%1" is the default, otherwise the current window is used. See also: "SENDEVENT NOTES" and "WINDOW STACK" --clearmodifiers Clear modifiers before sending keystrokes. See CLEARMODIFIERS below. --delay milliseconds Delay between keystrokes. Default is 12ms. 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. With respect to "COMMAND CHAINING", this command consumes the remainder of the arguments or until a new xdotool command is seen, because no xdotool commands are valid keystrokes. 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 Example: Send ctrl+l and then BackSpace as separate keystrokes: xdotool key ctrl+l BackSpace Example: Send ctrl+c to all windows matching title 'gdb' (See "COMMAND CHAINING") xdotool search --name gdb key ctrl+c keydown [options] keystroke Same as above, except only keydown (press) events are sent. keyup keystroke Same as above, except only keyup (release) events are sent. type [options] something to type Options: --window windowid Send keystrokes to a specific window id. See "SENDEVENT NOTES" below. The default, if no window is given, depends on the window stack. If the window stack is empty the current window is typed at using XTEST. Otherwise, the default is "%1" (see "WINDOW STACK"). --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. With respect to "COMMAND CHAINING", this command consumes the remainder of the arguments and types them. That is, no commands can chain after 'type'. Example: to type 'Hello world!' you would do: xdotool type 'Hello world!'
mousemove [options] x y OR 'restore' Move the mouse to the specific X and Y coordinates on the screen. You can move the mouse to the previous location if you specify 'restore' instead of an X and Y coordinate. Restoring only works if you have moved previously in this same command invocation. Further, it does not work with the --window option. For example, to click the top-left corner of the screen and move the mouse to the original position before you moved it, use this: xdotool mousemove 0 0 click 1 mousemove restore --window WINDOW Specify a window to move relative to. Coordinates 0,0 are at the top left of the window you choose. "WINDOW STACK" references are valid here, such as %1 and %@. Though, using %@ probably doesn't make sense. --screen SCREEN Move the mouse to the specified screen to move to. This is only useful if you have multiple screens and ARE NOT using Xinerama. The default is the current screen. If you specify --window, the --screen flag is ignored. --polar Use polar coordinates. This makes 'x' an angle (in degrees, 0-360, etc) and 'y' the distance. Rotation starts at 'up' (0 degrees) and rotates clockwise: 90 = right, 180 = down, 270 = left. The origin defaults to the center of the current screen. If you specify a --window, then the origin is the center of that window. --clearmodifiers See CLEARMODIFIERS --sync After sending the mouse move request, wait until the mouse is actually moved. If no movement is necessary, we will not wait. This is useful for scripts that depend on actions being completed before moving on. Note: We wait until the mouse moves at all, not necessarily that it actually reaches your intended destination. Some applications lock the mouse cursor to certain regions of the screen, so waiting for any movement is better in the general case than waiting for a specific target. mousemove_relative [options] x y Move the mouse x,y pixels relative to the current position of the mouse cursor. --polar Use polar coordinates. This makes 'x' an angle (in degrees, 0-360, etc) and 'y' the distance. Rotation starts at 'up' (0 degrees) and rotates clockwise: 90 = right, 180 = down, 270 = left. --sync After sending the mouse move request, wait until the mouse is actually moved. If no movement is necessary, we will not wait. This is useful for scripts that depend on actions being completed before moving on. Note that we wait until the mouse moves at all, not necessarily that it actually reaches your intended destination. Some applications lock the mouse cursor to certain regions of the screen, so waiting for any movement is better in the general case than waiting for a specific target. --clearmodifiers See CLEARMODIFIERS click [options] button Send a click, that is, a mousedown followed by mouseup for the given button with a short delay between the two (currently 12ms). Buttons generally map this way: Left mouse is 1, middle is 2, right is 3, wheel up is 4, wheel down is 5. --clearmodifiers Clear modifiers before clicking. See CLEARMODIFIERS below. --repeat REPEAT Specify how many times to click. Default is 1. For a double-click, use '--repeat 2' --delay MILLISECONDS Specify how long, in milliseconds, to delay between clicks. This option is not used if the --repeat flag is set to 1 (default). --window WINDOW Specify a window to send a click to. See "SENDEVENT NOTES" below for caveats. Uses the current mouse position when generating the event. The default, if no window is given, depends on the window stack. If the window stack is empty the current window is typed at using XTEST. Otherwise, the default is "%1" (see "WINDOW STACK"). mousedown [options] button Same as click, except only a mouse down is sent. mouseup [options] button Same as click, except only a mouse up is sent. getmouselocation [--shell] Outputs the x, y, screen, and window id 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 WINDOW=16777250 % eval $(xdotool getmouselocation --shell) % echo $X,$Y 714,324 behave_screen_edge [options] where command ... Bind an action to events when the mouse hits the screen edge or corner. Options are: --delay MILLISECONDS Delay in milliseconds before running the command. This allows you to require a given edge or corner to be held for a short period before your command will run. If you leave the edge or corner before the delay expires then the time will reset. --quiesce MILLISECONDS Delay in milliseconds before the next command will run. This helps prevent accidentally running your command extra times; especially useful if you have a very short --delay (like the default of 0). Event timeline * Mouse hits an edge or corner. * If delay is nonzero, the mouse must stay in this edge or corner until delay time expires. * If still in the edge/corner, trigger. * If quiesce is nonzero, then there is a cool-down period where the next trigger cannot occur Valid 'where' values are: left top-left top top-right right bottom-left bottom bottom-right Examples: # Activate google-chrome when you move the mouse to the bottom-left corner: xdotool behave_screen_edge bottom-left \ search --class google-chrome windowactivate # Go to the next workspace (right). Known to work in GNOME (metacity and compiz) xdotool behave_screen_edge --delay 500 bottom-right key XF86Forward # Activate firefox and do a web search in a new tab for text in your clipboard xdotool behave_screen_edge --delay 1000 top-left \ search --classname Navigator \ windowactivate --sync key --delay 250 ctrl+t ctrl+k ctrl+v Return
DESKTOP AND WINDOW COMMANDS
These commands follow the EWMH standard. See the section "EXTENDED WINDOW MANAGER HINTS" for more information. windowactivate [options] [window] 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. If no window is given, %1 is the default. See "WINDOW STACK" and "COMMAND CHAINING" for more details. --sync After sending the window activation, wait until the window is actually activated. This is useful for scripts that depend on actions being completed before moving on. getactivewindow Output the current active window. This command is often more reliable than getwindowfocus. The result is saved to the window stack. See "WINDOW STACK" for more details. set_num_desktops number Changes the number of desktops or workspaces. get_num_desktops Output the current number of desktops. get_desktop_viewport [--shell] Report the current viewport's position. If --shell is given, the output is friendly to shell eval. Viewports are sometimes used instead of 'virtual desktops' on some window managers. A viewport is simply a view on a very large desktop area. set_desktop_viewport x y Move the viewport to the given position. Not all requests will be obeyed - some windowmangers only obey requests that align to workspace boundaries, such as the screen size. For example, if your screen is 1280x800, you can move to the 2nd workspace by doing: xdotool set_desktop_viewport 1280 0 set_desktop [options] desktop_number Change the current view to the specified desktop. --relative Use relative movements instead of absolute. This lets you move relative to the current desktop. get_desktop Output the current desktop in view. set_desktop_for_window [window] desktop_number Move a window to a different desktop. If no window is given, %1 is the default. See "WINDOW STACK" and "COMMAND CHAINING" for more details. get_desktop_for_window [window] Output the desktop currently containing the given window. Move a window to a different desktop. If no window is given, %1 is the default. See WINDOW STACK and "COMMAND CHAINING" for more details.
exec [options] command [...] Execute a program. This is often useful when combined with behave_screen_edge to do things like locking your screen. Options: --sync Block until the child process exits. The child process exit status is then passed to the parent process (xdotool) which copies it. Examples: # Lock the screen when the mouse sits in the top-right corner xdotool behave_screen_edge --delay 1000 top-right \ exec gnome-screensaver-command --lock # Substitute 'xscreensaver-command -lock' if you use that program. # The following will fail to move the mouse because we use '--sync' and # /bin/false exits nonzero: xdotool exec --sync /bin/false mousemove 0 0 # This succeeds, though, since we do not use --sync on the exec command. xdotool exec /bin/false mousemove 0 0 sleep seconds Sleep for a specified period. Fractions of seconds (like 1.3, or 0.4) are valid, here.
xdotool can read a list of commands via stdin or a file if you want. A script will fail when any command fails. Truthfully, 'script' mode isn't fully fleshed out and may fall below your expectations. If you have suggestions, please email the list or file a bug (See CONTACT). Scripts can use positional arguments (Represented by $1, $2, ...) and environment variables (like $HOME or $WINDOWID). Quoting arguments should work as expected. Scripts are processed for parameter and environment variable expansion and then run as if you had invoked xdotool with the entire script on one line (using COMMAND CHAINING). • 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 search --onlyvisible --classname $1 windowsize %@ $2 $3 windowraise %@ windowmove %1 0 0 windowmove %2 $2 0 windowmove %3 0 $3 windowmove %4 $2 $3 This script will take all windows matched by the classname query given by arg1 ($1) and sizes/moves them into a 2x2 grid with windows sized by the 2nd and 3rd parameters. Here's an example usage: % ./myscript xterm 600 400 Running it like this will take 4 visible xterms, raise them, and move them into a 2x2 tile grid with each window 600x400 pixels in size.
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
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. It is important to note that for key and mouse events, we only use XSendEvent when a specific window is targeted. Otherwise, we use XTEST. 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.
Certain commands (search, getactivewindow, getwindowfocus) will find windows for you. These results generally printed to stdout, but they are also saved to memory for future use during the lifetime of the xdotool process. See "COMMAND CHAINING" for more information. The only modifications support for the window stack are to replace it. That is, two of two sequential searches, only the last one's results will be the window stack.
xdotool supports running multiple commands on a single invocation. Generally, you'll start with a search command (see "WINDOW STACK") and then perform a set of actions on those results. To query the window stack, you can use special notation "%N" where N is a number or the '@' symbol. If %N is given, the Nth window will be selected from the window stack. Generally you will only want the first window or all windows. Note that the order of windows in the window stack corresponds to the window stacking order, i.e. the bottom-most window will be reported first (see XQueryTree(3)). Thus the order of the windows in the window stack may not be consistent across invocations. The notation described above is used as the "window" argument for any given command. For example, to resize all xterms to 80x24: xdotool search --class xterm -- windowsize --usehints %@ 80 24 Resize move the current window: xdotool getactivewindow windowmove 0 0 In all cases, the default window argument, if omitted, will default to "%1". It is obviously an error if you omit the window argument and the window stack is empty. If you try to use the window stack and it is empty, it is also an error. To activate the first firefox window found: xdotool search --class firefox windowactivate These would error: xdotool windowactivate xdotool windowactivate %1 xdotool windowactivate %@ When xdotool exits, the current window stack is lost. Additionally, commands that modify the "WINDOW STACK" will not print the results if they are not the last command. For example: # Output the active window: % xdotool getactivewindow 20971533 # Output the pid of the active window, but not the active window id: % xdotool getactivewindow getwindowpid 4686
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". _NET_WM_PID This feature is application dependent, not window-manager dependent. Query the PID owning a given window. Support for this enables these commands: "getwindowpid".
xdotool (and libxdo) will try to function under all circumstances. However, there may be some cases where functionality is not provided by your X server or by your window manager. In these cases, xdotool will try to detect and tell you if an action requires a feature not currently supported by your system. For window-manager specific features, see "EXTENDED WINDOW MANAGER HINTS". XTEST If your X server does not support XTEST, then some typing and mouse movement features may not work. Specifically, typing and mouse actions that act on the "current window" (window 0 in libxdo) are unlikely to work. In most cases, XTEST is a feature you can enable on your X server if it is not enabled by default. You can see the list of supported X extensions by typing 'xdpyinfo' and looking the text 'number of extensions: ...'
Typing unusual symbols under non-us keybindings is known to occasionally send the wrong character.
xprop(1), xwininfo(1), Project site: <http://www.semicomplete.com/projects/xdotool> Source code and Issues: <https://github.com/jordansissel/xdotool> EWMH specification: <http://standards.freedesktop.org/wm-spec/wm-spec-1.3.html>
Please send questions to email@example.com. File bugs and feature requests at the following URL: <https://github.com/jordansissel/xdotool/issues> Alternately, if you prefer email, feel free to file bugs by emailing the list. What works for you :)
xdotool was written by Jordan Sissel. This manual page was written originally by Daniel Kahn Gillmor <firstname.lastname@example.org> for the Debian project (but may be used by others). It is maintained by Jordan Sissel. Patches, ideas, and other contributions by many, nice folks. See the CHANGELIST file for who provided what. 2018-06-11 XDOTOOL(1)