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/licens‐
       es/gpl.html>.
       This is free software: you are free to change and redistribute it.  There is NO WARRANTY, to  the  extent
       permitted by law.