Ubuntu Manpage: wl-clipboard - Wayland copy and paste command line utilities

NAME

       wl-clipboard - Wayland copy and paste command line utilities

SYNOPSIS

       wl-copy [--primary] [--type mime/type] [text...]

       wl-paste [--primary] [--type mime/type]

       Only the most useful options are listed here; see below for the full list.

DESCRIPTION

       wl-copy  copies  the  given  text  to the Wayland clipboard.  If no text is given, wl-copy
       copies data from its standard input.

       wl-paste pastes data from the Wayland clipboard to its standard output.

       Although wl-copy and wl-paste are particularly optimized for plain text and other  textual
       content formats, they fully support content of arbitrary MIME types. wl-copy automatically
       infers the type of the copied content by running xdg-mime(1) on  it.  wl-paste  tries  its
       best  to pick a type to paste based on the list of offered MIME types and the extension of
       the file it's pasting into. If you're not satisfied with the type they pick or don't  want
       to  rely  on this implicit type inference, you can explicitly specify the type to use with
       the --type option.

OPTIONS

To parse options, wl-clipboard uses the getopt(3) library routines, whose features depend
on the C library in use. In particular, it may be possible to specify -- as an argument on
its own to prevent any further arguments from getting parsed as options (which lets you
copy text containing words that start with the - sign), and to shorten long options to
their unambiguous prefixes.

-p, --primary
Use the "primary" clipboard instead of the regular clipboard.

-o, --paste-once (for wl-copy)
Only serve one paste request and then exit. Unless a clipboard manager specifically
designed to prevent this is in use, this has the effect of clearing the clipboard
after the first paste, which is useful for copying sensitive data such as
passwords. Note that this may break pasting into some clients that expect to be
able to paste multiple times, in particular pasting into XWayland windows is known
to break when this option is used.

-f, --foreground (for wl-copy)
By default, wl-copy forks and serves data requests in the background; this option
overrides that behavior, causing wl-copy to run in the foreground.

-c, --clear (for wl-copy)
Instead of copying anything, clear the clipboard so that nothing is copied.

-n, --trim-newline (for wl-copy)
Do not copy the trailing newline character if it is present in the input file.

-n, --no-newline (for wl-paste)
Do not append a newline character after the pasted clipboard content. This option
is automatically enabled for non-text content types and when using the --watch
mode.

-t mime/type, --type mime/type
Override the automatically selected MIME type. For wl-copy this option controls
which type wl-copy will offer the content as. For wl-paste it controls which of the
offered types wl-paste will request the content in. In addition to specific MIME
types such as image/png, wl-paste also accepts generic type names such as text and
image which make it automatically pick some offered MIME type that matches the
given generic name.

-s seat-name, --seat seat-name
Specify which seat wl-copy and wl-paste should work with. Wayland natively supports
multi-seat configurations where each seat gets its own mouse pointer, keyboard
focus, and among other things its own separate clipboard. The name of the default
seat is likely default or seat0, and additional seat names normally come from the
udev(7) property ENV{WL_SEAT}. You can view the list of the currently available
seats as advertised by the compositor using the weston-info(1) tool. If you don't
specify the seat name explicitly, wl-copy and wl-paste will pick a seat
arbitrarily. If you are using a single-seat system, there is little reason to use
this option.

-l, --list-types (for wl-paste)
Instead of pasting the selection, output the list of MIME types it is offered in.

-w command..., --watch command... (for wl-paste)
Instead of pasting once and exiting, continuously watch the clipboard for changes,
and run the specified command each time a new selection appears. The spawned
process can read the clipboard contents from its standard input. wl-paste also
sets the CLIPBOARD_STATE variable in the environment of the spawned processes (see
below).

This mode requires a compositor that supports the wlroots data-control protocol.

-v, --version
Display the version of wl-clipboard and some short info about its license.

-h, --help
Display a short help message listing the available options.

ENVIRONMENT

WAYLAND_DISPLAY
Specifies what Wayland server wl-copy and wl-paste should connect to. This is the
same environment variable that you pass to other Wayland clients, such as graphical
applications, that connect to this Wayland server. It is normally set up
automatically by the graphical session and the Wayland compositor. See
wl_display_connect(3) for more details.

WAYLAND_DEBUG
When set to 1, causes the wayland-client(7) library to log every interaction wl-
copy and wl-paste make with the Wayland compositor to stderr.

CLIPBOARD_STATE
Set by wl-paste for the spawned command in --watch mode. Currently the following
possible values are defined:

CLIPBOARD_STATE=data
Indicates that the clipboard contains data that the spawned command can read
from its standard input. This is the most common case.

CLIPBOARD_STATE=nil
Indicates that the clipboard is empty. In this case the spawned command's
standard input will be attached to /dev/null. Note that this is subtly
different from the clipboard containing zero-sized data (which can be
achieved, for instance, by running wl-copy < /dev/null).

CLIPBOARD_STATE=clear
Indicates that the clipboard is empty because of an explicit clear request,
such as after running wl-copy --clear. As for nil, the command's standard
input will be attached to /dev/null.

CLIPBOARD_STATE=sensitive
Indicates that the clipboard contains sensitive data such as a password or a
key. It is probably best to avoid visibly displaying or persistently saving
clipboard contents.

Any client programs implementing the CLIPBOARD_STATE protocol are encouraged to
implement proper support for all the values listed above, as well as to fall back
to some sensible behavior if CLIPBOARD_STATE is unset or set to some unrecognized
value (this is to leave the design space open for future extensions). However, the
currently existing Wayland clipboard protocols don't let wl-clipboard identify the
cases where clear and sensitive values should be set, so currently wl-clipboard
only ever sets CLIPBOARD_STATE to data or nil.

The CLIPBOARD_STATE protocol was intentionally designed to not be specific to
either wl-clipboard or Wayland; in fact, other clipboard tools are encouraged to
implement the same protocol. Currently, the SerenityOS paste(1) utility is known to
implement the same CLIPBOARD_STATE protocol.

FILES

       /etc/mime.types
              If present, read by wl-paste to infer the MIME type to paste in based on  the  file
              name extension of its standard output.

BUGS

Unless the Wayland compositor implements the wlroots data-control protocol, wl-clipboard
has to resort to using a hack to access the clipboard: it will briefly pop up a tiny
transparent surface (window). On some desktop environments (in particular when using
tiling window managers), this can cause visual issues such as brief flashing. In some
cases the Wayland compositor doesn't give focus to the popup surface, which prevents wl-
clipboard from accessing the clipboard and manifests as a hang.

There is currently no way to copy data in multiple MIME types, such as multiple image
formats, at the same time.
See <https://github.com/bugaevc/wl-clipboard/issues/71>.

wl-clipboard is not always able to detect that a MIME type is textual, which may break
pasting into clients that expect textual formats, not application/something. The
workaround, same as for all format inference issues, is to specify the desired MIME type
explicitly, such as wl-copy --type text/plain.

wl-copy --clear and wl-copy --paste-once don't always interact well with clipboard
managers that are overeager to preserve clipboard contents.

Applications written using the GTK 3 toolkit copy text with "\r\n" (also known as CR LF)
line endings, which takes most other software by surprise. wl-cipboard does nothing to
rectify this. The recommended workaround is piping wl-paste output through dos2unix(1)
when pasting from a GTK 3 application.
See <https://gitlab.gnome.org/GNOME/gtk/-/issues/2307>.

When trying to paste content copied with wl-copy, wl-copy does not check whether the
requested MIME type is among those it has offered, and always provides the same data in
response.

EXAMPLES

       Copy a simple text message:
              $ wl-copy Hello world!

       Copy a message starting with dashes:
              wl-copy -- --long

       Copy the list of files in ~/Downloads:
              $ ls ~/Downloads | wl-copy

       Copy an image:
              $ wl-copy < ~/Pictures/photo.png

       Copy the previous command:
              $ wl-copy "!!"

       Paste to a file, without appending a newline:
              $ wl-paste -n > clipboard.txt

       Sort clipboard contents:
              $ wl-paste | sort | wl-copy

       Upload clipboard contents to a pastebin on each change:
              $ wl-paste --watch nc paste.example.org 5555

AUTHOR

       Written by Sergey Bugaev.

REPORTING BUGS

       Report wl-clipboard bugs to <https://github.com/bugaevc/wl-clipboard/issues>
       Please  make  sure  to  mention  which  Wayland  compositor  you  are  using,  and  attach
       WAYLAND_DEBUG=1 debugging logs of wl-clipboard.

COPYRIGHT

       Copyright  ©  2018-2023  Sergey  Bugaev.   License  GPLv3+:  GNU  GPL  version  3 or later
       <https://gnu.org/licenses/gpl.html>.
       This is free software: you are free to change and redistribute it.  There is NO  WARRANTY,
       to the extent permitted by law.