WL-CLIPBOARD(1) General Commands Manual WL-CLIPBOARD(1)
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 arbi-
trary 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 con-
taining 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 win-
dows 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 back-
ground; 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 con-
tent. 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 re-
quest 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 ex-
plicitly, 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 clip-
board 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 CLIP-
BOARD_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_con-
nect(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. Cur-
rently 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 ex-
plicit 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 visi-
bly 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 CLIP-
BOARD_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 CLIP-
BOARD_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 clip-
board tools are encouraged to implement the same protocol. Cur-
rently, 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 proto-
col, 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 pre-
vents 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 sur-
prise. 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 al-
ways 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/is-
sues>
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.
SEE ALSO
xclip(1), xsel(1), wl-clipboard-x11(1)
wl-clipboard 2023-04-22 WL-CLIPBOARD(1)
Generated by dwww version 1.16 on Sat Oct 3 07:35:54 CEST 2026.