YDOTOOL(1)

NAME

ydotool - command-line /dev/uinput automation tool

SYNOPSIS

ydotool cmd args [ , cmd args ... ]

ydotool cmd --help

DESCRIPTION

ydotool lets you programmatically (or manually) simulate keyboard input and mouse activity, etc. It does this by writing directly to /dev/uinput so it generally needs to run as root.

It's possible to chain multiple commands together, separated by a comma between two spaces.

Currently implemented command(s):

type
    Type a string
key
    Press keys
mousemove
    Move mouse pointer to absolute position
click
    Click on mouse buttons
recorder
    Record/replay input events
sleep
    sleep for a while

KEYBOARD COMMANDS
key [--up] [--down] [--next-delay <ms>] [--key-delay <ms>] [--repeat <times>] [--repeat-delay <ms>] <key sequence>

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

    Options:

    --up
        Only keyup

    --down
        Only keydown

    --delay <ms>
        Delay before starting to output keystrokes. Default 100ms.

    --key-delay <ms>
        Delay time between keystrokes. Default 12ms.

    --repeat <times>
        Times to repeat the key sequence.

    --repeat-delay <ms>
        Delay time between repetitions. Default 0ms.

    Generally, any valid name from /usr/include/linux/input-event-codes.h will work. Multiple keys are separated by '+'.

    Each key sequence can be any number of modifiers and keys, separated by plus (+)

    For example: alt+r Alt+F4 CTRL+alt+f3 aLT+1+2+3 ctrl+Backspace

    Since we are emulating keyboard input, combinations like Shift+# is invalid because typing a `#' involves pressing Shift and 3.

    Example: Switch to tty1:
        ydotool key ctrl+alt+f1

    Example: Close a window in graphical environment:
        ydotool key Alt+F4

type [--next-delay <ms>] [--key-delay <ms>] [--texts arg] [--file <filepath>] "texts"

    Types text as if you had typed it on the keyboard.

    Options:

    --next-delay <ms>
        Delay before starting typing. Default 100ms.

    --key-delay <ms>
        Delay time between keystrokes. Default 12ms.

    --texts arg
        Texts to type

    --file <filepath>
        Specify a file, the contents of which will be typed as if passed as an argument. The filepath may also be '-' to read from stdin.

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

MOUSE COMMANDS

mousemove <x> <y>
    Move the mouse to the specific relative X and Y coordinates on the screen.

    Options: --absolute
        Use absolute position

    Example: to move the cursor to absolute coordinates (100,100):
        ydotool mousemove --absolute 100 100

click [--next-delay <ms>] button
    Send a click. Buttons are: left, right or middle

    Options:

    --next-delay <ms>
        Delay before click. Default 100ms.

    --up
        Only mouseup

    --down
        Only mousedown

    --buttons <arg>
        Buttons to press (left, right, middle)

    Example: Mouse middle click:
        ydotool click middle

recorder [--record <devices>] [--replay <input files>] [--display] [--duration <ms>] [--devices <path>] [--file <path>]

    Options:

    --record <devices>
        Devices to record from. Default is all, including non-keyboard devices.

    --replay <input files>
        The record file can't be replayed on an architecture with different endianness.

    --display
        Display

    --duration <ms>
        Record duration. Otherwise use SIGINT to stop recording.

    --devices <path>
        Devices, separated by comma, to record from. Default is all devices (default: "")

    --file <path>
        File to record to / replay from

AUTHOR

ydotool was written by ReimuNotMoe.

This man page by bob.hepple@gmail.com

BUGS

When ydotool(1) runs and creates a virtual input device, it will take some time for your graphical environment (eg X11/Wayland) to recognize and enable the virtual input device. (Usually done by udev)

If the delay is too short, the virtual input device may not be recognized & enabled by the graphical environment in time.

In order to solve this problem, there is a persistent background service, ydotoold(1), to hold a persistent virtual device, and accept input from ydotool(1). When ydotoold(1) is unavailable, ydotool(1) will work without it.

LICENCE
AGPLv3

SEE ALSO

ydotoold(8)

Project site: <https://github.com/ReimuNotMoe/ydotool>