1WL-CLIPBOARD(1) General Commands Manual WL-CLIPBOARD(1)
2
6 wl-clipboard - Wayland copy and paste command line utilities
7
9 wl-copy [--primary] [--type mime/type] [text...]
10 wl-paste [--primary] [--type mime/type]
12 Only the most useful options are listed here; see below for the full
14 list.
15
17 wl-copy copies the given text to the Wayland clipboard. If no text is
18 given, wl-copy copies data from its standard input.
19 wl-paste pastes data from the Wayland clipboard to its standard output.
21 Although wl-copy and wl-paste are particularly optimized for plain text
23 and other textual content formats, they fully support content of arbi‐
24 trary MIME types. wl-copy automatically infers the type of the copied
25 content by running xdg-mime(1) on it. wl-paste tries its best to pick a
26 type to paste based on the list of offered MIME types and the extension
27 of the file it's pasting into. If you're not satisfied with the type
28 they pick or don't want to rely on this implicit type inference, you
29 can explicitly specify the type to use with the --type option.
30
32 To parse options, wl-clipboard uses the getopt(3) library routines,
33 whose features depend on the C library in use. In particular, it may be
34 possible to specify -- as an argument on its own to prevent any further
35 arguments from getting parsed as options (which lets you copy text con‐
36 taining words that start with the - sign), and to shorten long options
37 to their unambiguous prefixes.
38 -p, --primary
40 Use the "primary" clipboard instead of the regular clipboard.
41 -o, --paste-once (for wl-copy)
43 Only serve one paste request and then exit. Unless a clipboard
44 manager specifically designed to prevent this is in use, this
45 has the effect of clearing the clipboard after the first paste,
46 which is useful for copying sensitive data such as passwords.
47 Note that this may break pasting into some clients that expect
48 to be able to paste multiple times, in particular pasting into
49 XWayland windows is known to break when this option is used.
50 -f, --foreground (for wl-copy)
52 By default, wl-copy forks and serves data requests in the back‐
53 ground; this option overrides that behavior, causing wl-copy to
54 run in the foreground.
55 -c, --clear (for wl-copy)
57 Instead of copying anything, clear the clipboard so that nothing
58 is copied.
59 -n, --trim-newline (for wl-copy)
61 Do not copy the trailing newline character if it is present in
62 the input file.
63 -n, --no-newline (for wl-paste)
65 Do not append a newline character after the pasted clipboard
66 content. This option is automatically enabled for non-text con‐
67 tent types and when using the --watch mode.
68 -t mime/type, --type mime/type
70 Override the automatically selected MIME type. For wl-copy this
71 option controls which type wl-copy will offer the content as.
72 For wl-paste it controls which of the offered types wl-paste
73 will request the content in. In addition to specific MIME types
74 such as image/png, wl-paste also accepts generic type names such
75 as text and image which make it automatically pick some offered
76 MIME type that matches the given generic name.
77 -s seat-name, --seat seat-name
79 Specify which seat wl-copy and wl-paste should work with. Way‐
80 land natively supports multi-seat configurations where each seat
81 gets its own mouse pointer, keyboard focus, and among other
82 things its own separate clipboard. The name of the default seat
83 is likely default or seat0, and additional seat names normally
84 come from the udev(7) property ENV{WL_SEAT}. You can view the
85 list of the currently available seats as advertised by the com‐
86 positor using the weston-info(1) tool. If you don't specify the
87 seat name explicitly, wl-copy and wl-paste will pick a seat ar‐
88 bitrarily. If you are using a single-seat system, there is lit‐
89 tle reason to use this option.
90 -l, --list-types (for wl-paste)
92 Instead of pasting the selection, output the list of MIME types
93 it is offered in.
94 -w command..., --watch command... (for wl-paste)
96 Instead of pasting once and exiting, continuously watch the
97 clipboard for changes, and run the specified command each time a
98 new selection appears. The spawned process can read the clip‐
99 board contents from its standard input. wl-paste also sets the
100 CLIPBOARD_STATE variable in the environment of the spawned pro‐
101 cesses (see below).
102 This mode requires a compositor that supports the wlroots data-
104 control protocol.
105 -v, --version
107 Display the version of wl-clipboard and some short info about
108 its license.
109 -h, --help
111 Display a short help message listing the available options.
112
114 WAYLAND_DISPLAY
115 Specifies what Wayland server wl-copy and wl-paste should con‐
116 nect to. This is the same environment variable that you pass to
117 other Wayland clients, such as graphical applications, that con‐
118 nect to this Wayland server. It is normally set up automatically
119 by the graphical session and the Wayland compositor. See wl_dis‐
120 play_connect(3) for more details.
121 WAYLAND_DEBUG
123 When set to 1, causes the wayland-client(7) library to log every
124 interaction wl-copy and wl-paste make with the Wayland composi‐
125 tor to stderr.
126 CLIPBOARD_STATE
128 Set by wl-paste for the spawned command in --watch mode. Cur‐
129 rently the following possible values are defined:
130 CLIPBOARD_STATE=data
132 Indicates that the clipboard contains data that the
133 spawned command can read from its standard input. This is
134 the most common case.
135 CLIPBOARD_STATE=nil
137 Indicates that the clipboard is empty. In this case the
138 spawned command's standard input will be attached to
139 /dev/null. Note that this is subtly different from the
140 clipboard containing zero-sized data (which can be
141 achieved, for instance, by running wl-copy < /dev/null).
142 CLIPBOARD_STATE=clear
144 Indicates that the clipboard is empty because of an ex‐
145 plicit clear request, such as after running wl-copy
146 --clear. As for nil, the command's standard input will be
147 attached to /dev/null.
148 CLIPBOARD_STATE=sensitive
150 Indicates that the clipboard contains sensitive data such
151 as a password or a key. It is probably best to avoid vis‐
152 ibly displaying or persistently saving clipboard con‐
153 tents.
154 Any client programs implementing the CLIPBOARD_STATE protocol
156 are encouraged to implement proper support for all the values
157 listed above, as well as to fall back to some sensible behavior
158 if CLIPBOARD_STATE is unset or set to some unrecognized value
159 (this is to leave the design space open for future extensions).
160 However, the currently existing Wayland clipboard protocols
161 don't let wl-clipboard identify the cases where clear and sensi‐
162 tive values should be set, so currently wl-clipboard only ever
163 sets CLIPBOARD_STATE to data or nil.
164 The CLIPBOARD_STATE protocol was intentionally designed to not
166 be specific to either wl-clipboard or Wayland; in fact, other
167 clipboard tools are encouraged to implement the same protocol.
168 Currently, the SerenityOS paste(1) utility is known to implement
169 the same CLIPBOARD_STATE protocol.
170
172 /etc/mime.types
173 If present, read by wl-paste to infer the MIME type to paste in
174 based on the file name extension of its standard output.
175
177 Unless the Wayland compositor implements the wlroots data-control pro‐
178 tocol, wl-clipboard has to resort to using a hack to access the clip‐
179 board: it will briefly pop up a tiny transparent surface (window). On
180 some desktop environments (in particular when using tiling window man‐
181 agers), this can cause visual issues such as brief flashing. In some
182 cases the Wayland compositor doesn't give focus to the popup surface,
183 which prevents wl-clipboard from accessing the clipboard and manifests
184 as a hang.
185 There is currently no way to copy data in multiple MIME types, such as
187 multiple image formats, at the same time.
188 See <https://github.com/bugaevc/wl-clipboard/issues/71>.
189 wl-clipboard is not always able to detect that a MIME type is textual,
191 which may break pasting into clients that expect textual formats, not
192 application/something. The workaround, same as for all format inference
193 issues, is to specify the desired MIME type explicitly, such as wl-copy
194 --type text/plain.
195 wl-copy --clear and wl-copy --paste-once don't always interact well
197 with clipboard managers that are overeager to preserve clipboard con‐
198 tents.
199 Applications written using the GTK 3 toolkit copy text with "\r\n" (al‐
201 so known as CR LF) line endings, which takes most other software by
202 surprise. wl-cipboard does nothing to rectify this. The recommended
203 workaround is piping wl-paste output through dos2unix(1) when pasting
204 from a GTK 3 application.
205 See <https://gitlab.gnome.org/GNOME/gtk/-/issues/2307>.
206 When trying to paste content copied with wl-copy, wl-copy does not
208 check whether the requested MIME type is among those it has offered,
209 and always provides the same data in response.
210
212 Copy a simple text message:
213 $ wl-copy Hello world!
214 Copy a message starting with dashes:
216 wl-copy -- --long
217 Copy the list of files in ~/Downloads:
219 $ ls ~/Downloads | wl-copy
220 Copy an image:
222 $ wl-copy < ~/Pictures/photo.png
223 Copy the previous command:
225 $ wl-copy "!!"
226 Paste to a file, without appending a newline:
228 $ wl-paste -n > clipboard.txt
229 Sort clipboard contents:
231 $ wl-paste | sort | wl-copy
232 Upload clipboard contents to a pastebin on each change:
234 $ wl-paste --watch nc paste.example.org 5555
235
237 Written by Sergey Bugaev.
238
240 Report wl-clipboard bugs to <https://github.com/bugaevc/wl-clip‐
241 board/issues>
242 Please make sure to mention which Wayland compositor you are using, and
243 attach WAYLAND_DEBUG=1 debugging logs of wl-clipboard.
244
246 Copyright © 2018-2023 Sergey Bugaev. License GPLv3+: GNU GPL version 3
247 or later <https://gnu.org/licenses/gpl.html>.
248 This is free software: you are free to change and redistribute it.
249 There is NO WARRANTY, to the extent permitted by law.
250
252 xclip(1), xsel(1), wl-clipboard-x11(1)
253wl-clipboard 2023-04-22 WL-CLIPBOARD(1)