AUTOCUTSEL(1)

NAME
autocutsel - synchronize X selections and the cutbuffer

SYNOPSIS
autocutsel [-selection selection_name] [-cutbuffer number] [-debug] [-verbose] [-fork] [-pause milliseconds] [-buttonup] [-mouseonly] [-encoding charset] [--help] [--version]

DESCRIPTION
autocutsel tracks changes in the server's cutbuffer and clipboard selection. When the clipboard is changed, it updates the cutbuffer. When the cutbuffer is changed, it owns the clipboard selection. The cutbuffer and clipboard selection are always synchronized.

On Wayland (detected automatically via WAYLAND_DISPLAY), the X11 cutbuffer does not exist. In this case autocutsel synchronizes selections directly: changes in the monitored selection are forwarded to the target selection without a cutbuffer intermediary. See WAYLAND SUPPORT below.

This is useful for VNC sessions where Windows VNC clients synchronize the Windows clipboard with the cutbuffer but not with the selections.

OPTIONS

-selection, -select, -sel, -s name
    Specify which selection to use. Default is CLIPBOARD.

-cutbuffer, -cut, -c number
    Specify which cutbuffer to use. Default is 0. This option has no effect on Wayland, where the cutbuffer is not used.

-debug, -d
    Print debugging information.

-verbose, -v
    Be more verbose. Reports the version and announces synchronizations.

-fork, -f
    Run as a daemon in the background.

-pause, -p milliseconds
    Set the polling interval in milliseconds. Default is 500.

-buttonup
    Only read the selection when mouse button 1 is not pressed. This may help with applications like OpenOffice Writer that have trouble when the selection is requested before the mouse button is released.

-mouseonly
    Synchronize PRIMARY to CLIPBOARD only when text is selected with the mouse. Keyboard-based selections (e.g. Shift+Arrow) are ignored. This prevents accidental clipboard overwrites in text editors where keyboard selection would otherwise replace the clipboard content.

    Only a single instance is needed — unlike the traditional setup which requires two instances (one for CLIPBOARD, one for PRIMARY), the -mouseonly option handles both selections in a single process. Typical usage:

    autocutsel -selection PRIMARY -mouseonly

    This option uses libinput to detect mouse button releases and works on both X11 and Wayland (via XWayland). It requires libinput and libudev.

    Note: The -mouseonly option requires read access to input devices (/dev/input/*). The user running autocutsel must be a member of the input group:

    sudo usermod -aG input $USER

    A re-login is required for the group change to take effect.

-encoding, -e charset
    Convert clipboard text between UTF-8 and the specified character encoding using iconv. This is useful for VNC sessions where the VNC client uses a legacy encoding (e.g. ISO-8859-1, WINDOWS-1252) for the cutbuffer.

    When this option is set, text received from the X selection (UTF-8) is converted to the specified encoding before storing, and text served to requesting applications is converted back to UTF-8. Without this option, no encoding conversion is performed.

    autocutsel -encoding WINDOWS-1252

    Run iconv -l to list available encodings.

--help
    Print usage information and exit. Does not require an X display.

--version
    Print version information and exit. Does not require an X display.

EXAMPLES
Synchronize the CLIPBOARD selection with the cutbuffer (default):

    autocutsel

Synchronize the PRIMARY selection with the cutbuffer:

    autocutsel -selection PRIMARY

Sync PRIMARY to CLIPBOARD on mouse selection only (single instance):

    autocutsel -selection PRIMARY -mouseonly

Synchronize with encoding conversion for a VNC session using Windows-1252:

    autocutsel -encoding WINDOWS-1252

INSTANCE MANAGEMENT
autocutsel automatically prevents multiple instances for the same selection. If an instance monitoring the same selection is already running, additional invocations will print a message to stderr and exit. This makes it safe to place autocutsel in .bashrc or .xinitrc without spawning duplicate processes.

Different selections can still be monitored concurrently (e.g. one instance for CLIPBOARD and one for PRIMARY).

SYSTEMD
autocutsel can be run as a systemd user service. A template unit (autocutsel@.service) and example configuration files are provided in contrib/systemd/. Each instance reads its options from ~/.config/autocutsel/<instance>.args.

Install the service:

If installed from an RPM package, the service file is already at /usr/lib/systemd/user/autocutsel@.service. Just create the configuration:

    mkdir -p ~/.config/autocutsel
    cp /usr/share/doc/autocutsel/examples/mouseonly.args ~/.config/autocutsel/

For manual installation:

    mkdir -p ~/.config/autocutsel ~/.config/systemd/user
    cp contrib/systemd/autocutsel@.service ~/.config/systemd/user/
    cp contrib/systemd/mouseonly.args ~/.config/autocutsel/

Available example configurations:

mouseonly.args
    Sync PRIMARY to CLIPBOARD on mouse selection only (recommended, single instance).

clipboard.args
    Sync CLIPBOARD with the cutbuffer (traditional setup, use together with primary.args).

primary.args
    Sync PRIMARY with the cutbuffer (traditional setup, use together with clipboard.args).

Enable a single mouseonly instance (recommended):

    systemctl --user daemon-reload
    systemctl --user enable --now autocutsel@mouseonly

Or enable the traditional two-instance setup:

    systemctl --user daemon-reload
    systemctl --user enable --now autocutsel@clipboard autocutsel@primary

View logs with: journalctl --user -u 'autocutsel@*'

The service file includes systemd hardening options (sandboxing via PrivateUsers, ProtectHome, ProtectSystem, NoNewPrivileges, etc.). The service uses ConditionEnvironment=DISPLAY to only start when an X11 display is available.

Compatibility: The systemd service works on GNOME (since 3.34) and KDE Plasma (since 5.25) on both X11 and Wayland. XFCE and standalone window managers do not activate graphical-session.target by default and require manual setup.

WAYLAND SUPPORT
autocutsel automatically detects Wayland sessions by checking the WAYLAND_DISPLAY environment variable. On Wayland the X11 cutbuffer does not exist, so autocutsel switches to direct selection sync: instead of storing values in the cutbuffer, it directly owns the target selection.

When monitoring PRIMARY (the recommended setup on Wayland), changes are synced directly to CLIPBOARD. When monitoring CLIPBOARD, changes are synced to PRIMARY.

Typical Wayland usage (single instance):

    autocutsel -selection PRIMARY

This also works with -buttonup and -encoding. The -cutbuffer option is ignored on Wayland since no cutbuffer is involved. The -mouseonly option already used direct selection sync and continues to work as before.

SEE ALSO
cutsel(1)

AUTHORS
Originally written by Michael Witrant <mike@lepton.fr>.
Original repository: https://github.com/sigmike/autocutsel

The -mouseonly option was added in this fork: https://github.com/Pihaar/autocutsel

LICENSE
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.