WL-CLIPBOARD(1)

📦
version 2.3.0 · 7 versions
, in nixos 26.05, nixpkgs unstable, ubuntu stonking

💖 NAME 💖

okay so welcome, bestie — this is the manual page for wl-clipboard, from section 1 of the General Commands Manual (the header literally shouts its own name twice, man pages are so extra). 💅

wl-clipboard — Wayland copy and paste command line utilities.

that's it, that's the whole name section. two adorable little programs, wl-copy and wl-paste, doing copy/paste but on Wayland. no cap.

✨ SYNOPSIS ✨

here's the shape of it:

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

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

and ngl, only the most useful options are listed right there ↑ — the full list is further down, keep scrolling, you got this 👑

🌈 DESCRIPTION 🌈

wl-copy copies the given text to the Wayland clipboard. no text handed to it? then it copies data from its standard input instead. iconic.

wl-paste pastes data from the Wayland clipboard to its standard output. that's the whole job, and it eats every time. 💖

so is this text-only? bestie, NO. wl-copy and wl-paste are particularly optimized for plain text and other textual content formats, but they fully support content of arbitrary MIME types. periodt. here's how:

  • wl-copy automatically infers the type of the copied content by running xdg-mime(1) on it. glance at it, clock the format, done.
  • 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.

and if you're not satisfied with the type they picked, or you just don't want to rely on this implicit type inference at all? you can explicitly say which type to use with the --type option. problem solved, you're the main character now. ✨

🔥 OPTIONS 🔥

before we get to the list, one general vibe check: to parse options, wl-clipboard uses the getopt(3) library routines, whose features depend on the C library in use. so depending on your libc, it may be possible to do these two things:

  • specify -- as an argument on its own, so that no further arguments get parsed as options — which, yes, is exactly how you copy text containing words that start with the - sign 🫶
  • shorten long options to their unambiguous prefixes

now, the options themselves, one by one, no skipping (I would never):

  • -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 literally the point, it's 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. so, y'know, tradeoffs.
  • -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. squeaky clean ✨
  • -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. and 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. so smart.
  • -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 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. and honestly if you're on a single-seat system, there is little reason to use this option — it's giving very much "you don't need me bestie".
  • -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. no protocol, no watch, sorry.

  • --sensitive (for wl-copy) — hint that the data being copied contains passwords, keys, or other sensitive content. some clipboard managers may react by not persisting the copied data in the clipboard history. this corresponds to CLIPBOARD_STATE=sensitive (see below). 💜
  • -v, --version — display the version of wl-clipboard, plus some short info about its license.
  • -h, --help — display a short help message listing the available options.

that's the options, and there's still so much more coming, don't you dare close the tab —

🐛 REPORTING BUGS 🐛

Found a bug? Bestie, do not suffer in silence. Take it straight to:

https://github.com/bugaevc/wl-clipboard/issues

And when you file it, pleaaaase include two things, because the maintainers genuinely need them:

  • Which Wayland compositor you are using. Like, tell them the actual name. They can't debug a vibe, they need specifics. 💅
  • WAYLAND_DEBUG=1 debugging logs of wl-clipboard. Attach those. The full logs. All of them. Don't be shy, don't trim, just yeet the whole thing in there. 🔥
fr fr, a bug report with no compositor and no WAYLAND_DEBUG=1 logs is giving "it doesn't work" energy, and nobody can do anything with that. Do the logs. Your future self says thank you. 🫶

Copyright © 2018-2026 Sergey Bugaev.

License GPLv3+: GNU GPL version 3 or later — https://gnu.org/licenses/gpl.html.

Bestie this is free software: you are free to change it and redistribute it, no cap. Go off, remix it, share it, be the main character of your own fork. ✨

But — and listen — there is NO WARRANTY, to the extent permitted by law. None. Zero. Nada. It's giving "you're on your own and that's the deal". 😭

👀 SEE ALSO 👑

The og clipboard girlies. Go pay your respects. 🎀

okay and that's the whole page bestie!! 💖 This one came from wl-clipboard, dated 2026-03-22 — screenshot the date, cite it, and go copy something iconic. Periodt. 💅✨🦋

📦 where this page comes from