ydotool

Start the ydotool daemon in the background

$ ydotoold

$ ydotool click 0xC0

$ ydotool click 0xC1

$ ydotool key 56:1 62:1 62:0 56:0

ydotool [OPTIONS] COMMAND [ARGUMENTS...]

Common Command Examples:
ydotool type <text>
ydotool click <button>
ydotool key <key>
ydotool mousemove <x> <y>

type <text>
    Simulate typing a given string of text on the console.

click <button>
    Simulate a mouse button click (e.g., 1 for left, 2 for middle, 3 for right).

mousemove <x> <y>
    Move the mouse cursor by a specified relative X and Y offset.

mousemove_to <x> <y>
    Move the mouse cursor to a specified absolute X and Y position.

keydown <key>
    Simulate pressing a specific key down without releasing it.

keyup <key>
    Simulate releasing a specific key previously held down.

key <key> [<delay>]
    Simulate pressing and then immediately releasing a specific key, optionally with a delay.

sleep <seconds>
    Pause execution for a specified number of seconds.

exec <command> [<args...>]
    Execute an external command.

status
    Display the status of the ydotoold daemon.

monitor
    Monitor and display input events from the virtual devices managed by ydotool.

command <raw_command>
    Execute raw commands directly via the ydotoold daemon (advanced usage).

-d, --debug
    Enable debug logging for more verbose output from ydotool and its daemon.

-u, --user <user>
    Specify a user to run ydotool commands as, typically when the daemon is run as root.

ydotool is a command-line utility designed for simulating keyboard and mouse input events on the Linux console and framebuffer. Unlike tools such as xdotool which operate within the X Window System, ydotool functions independently of a graphical server, making it ideal for automation in environments like embedded systems, kiosks, or headless servers. It achieves this by interacting with the uinput kernel module, which allows user-space programs to create virtual input devices. Through these virtual devices, ydotool can inject a wide range of input events, including typing text, clicking mouse buttons, moving the cursor, and simulating key presses and releases. For ydotool to operate, the uinput kernel module must be loaded, and the user or its associated daemon (ydotoold) typically requires read/write access to /dev/uinput, often managed via specific udev rules or by running with elevated privileges.

• Requires the uinput kernel module to be loaded on the system.
• Demands appropriate permissions to /dev/uinput for ydotool or its daemon (ydotoold) to create virtual devices, often requiring root privileges or specific udev rules.
• Primarily designed for use within the Linux console or framebuffer environment, not directly compatible with X11 or Wayland display servers.
• Can potentially interfere with normal user input if used improperly or maliciously.
• The key names used with key, keydown, keyup commands must correspond to Linux kernel input event codes.

ydotool commands typically communicate with a background daemon process named ydotoold. This daemon is responsible for managing the virtual uinput device creation and actual event injection. Running ydotoold, often as root or via a systemd service with appropriate permissions, allows unprivileged users to send commands to ydotool without needing direct access to /dev/uinput for every single action.

For non-root users to utilize ydotool, it is common practice to set up udev rules. These rules can modify the permissions of the /dev/uinput device node (e.g., setting its group ownership to a dedicated 'uinput' group) and ensure that users belonging to that group have read and write access. This allows ydotoold to start and manage input without requiring root privileges for the client commands.

ydotool emerged from the need for a command-line input automation tool in environments where a traditional X Window System (or later Wayland) server is not present or desired. While xdotool served this purpose for graphical desktops, a solution was required for embedded systems, kiosks, and bare-metal Linux console applications. By leveraging the kernel's uinput module, ydotool provides a direct interface to inject events into the kernel's input subsystem, allowing for low-level, server-independent input simulation. Its development addressed this specific gap, providing robust scripting capabilities for non-graphical Linux systems.

xdotool(1), libinput-debug-events(1), evtest(1)