xdotool

Retrieve the X-Windows window ID of the running Firefox window(s)

$ xdotool search --onlyvisible --name [firefox]

$ xdotool click [3]

$ xdotool getactivewindow

$ xdotool windowfocus --sync [12345]

$ xdotool type --delay [500] "Hello world"

$ xdotool key [KP_Enter]

xdotool [--window <WINDOW>] [--delay <MILLISECONDS>] <COMMAND> [COMMAND_OPTIONS]

xdotool typically takes a command followed by its specific options and arguments. Global options like --window and --delay can precede the command.

--window
    Specifies the window to operate on. WINDOW can be a window ID, "focus" for the currently focused window, "active" for the active window, or "root" for the root window.

--delay
    Sets a delay (in milliseconds) before executing a command.

help
    Displays a list of available commands and their usage.

version
    Prints the xdotool version information.

mousemove
    Moves the mouse cursor to absolute screen coordinates X and Y.

mousemove_relative
    Moves the mouse cursor relative to its current position by X and Y.

click
    Simulates a mouse click. BUTTON is typically 1 (left), 2 (middle), 3 (right), 4 (scroll up), or 5 (scroll down).

mousedown
    Presses down a mouse button.

mouseup
    Releases a mouse button.

key
    Simulates key presses. KEYNAME can be a single key (e.g., "a", "control", "Return") or a sequence (e.g., "control+c").

type
    Types a string of text, character by character.

getmouselocation
    Prints the current mouse coordinates and screen information.

windowfocus
    Brings the specified window into focus.

windowactivate
    Activates (raises and focuses) the specified window.

windowmove
    Moves the specified window to screen coordinates X and Y.

windowsize
    Resizes the specified window to WIDTH and HEIGHT.

windowminimize
    Minimizes the specified window.

windowmaximize
    Maximizes the specified window.

windowrestore
    Restores the specified window from a minimized or maximized state.

getactivewindow
    Prints the ID of the currently active window.

getwindowfocus
    Prints the ID of the window currently in focus.

getwindowname
    Prints the name (title) of the specified window.

search
    Searches for windows based on criteria like name, class, or PID, and prints their IDs. Common options include --name, --class, --pid.

sleep
    Pauses execution for the specified number of SECONDS.

xdotool is a powerful command-line tool designed to simulate keyboard input and mouse activity, and to perform various window management tasks in the X11 graphical environment. It interacts directly with the X server, allowing users to automate repetitive actions, create custom keyboard shortcuts, test applications, or manage windows from scripts. Its capabilities include moving and resizing windows, bringing windows to the foreground, sending arbitrary key presses or entire strings of text, and simulating mouse clicks and movements. By providing a programmatic interface to X11 interactions, xdotool becomes an essential utility for system administrators, developers, and power users looking to enhance their productivity through automation. It is commonly used in shell scripts for tasks like automating browser interactions, setting up development environments, or creating complex desktop workflows.

• X11 Dependency: xdotool works exclusively with the X Window System. It is not compatible with Wayland directly, requiring an XWayland compatibility layer to function in Wayland environments.
• Security Risk: As it can simulate user input, xdotool can be a security risk if misused or run with elevated privileges in untrusted scripts.
• Window ID Volatility: Window IDs are not persistent across sessions or even during some window manager operations, which can complicate long-running scripts.
• Timing Issues: Scripts may encounter race conditions if they don't account for delays in application response times, requiring careful use of the --delay option or the sleep command.
• Keyboard Layout: Key presses are interpreted based on the current X keyboard layout, which can lead to unexpected results if layouts change.

The --window and --delay options are global and can be used before any xdotool command. --window allows you to specify a target window for commands that would otherwise operate on the focused or active window. --delay introduces a pause before the command executes, useful for giving applications time to respond.

Many xdotool commands accept a WINDOW argument. Besides numerical window IDs, xdotool supports special keywords like "focus" (current input focus), "active" (active window according to window manager), and "root" (the root window). The search command is invaluable for programmatically finding window IDs based on properties like title, class, or PID.

For the key command, xdotool supports standard X keysym names (e.g., Control_L, Alt_R, Return, BackSpace) in addition to single characters. Multiple keys can be combined with + (e.g., control+shift+a).

xdotool was initially developed by Jordan S. Hubbard and released in the mid-2000s as a successor or alternative to older X11 automation tools like `xte` and `xmacro`. It quickly gained popularity due to its robust feature set, ease of use, and ability to handle complex X11 interactions, including window management which was less comprehensively covered by its predecessors. Its design focused on providing a flexible and scriptable interface, making it a staple for Linux desktop automation and testing. Continuous development has ensured its compatibility with modern X11 environments, solidifying its position as a go-to tool for X11 scripting.

xwininfo(1), xprop(1), xev(1), wmctrl(1), DISPLAY(7)