A single CLI clipboard tool for both X11 and Wayland, with one identical
command interface. It captures process output to the clipboard and serves the
clipboard back to process input, and adds a composed add (append) operation
that neither display server provides natively.
One binary with six faces, dispatched on argv[0] (the BusyBox pattern):
| Command | Action | TTY echo |
|---|---|---|
cpclip |
stdin (or TEXT) → clipboard (replace) |
yes |
cpadd |
stdin (or TEXT) → clipboard (append) |
yes |
cppaste |
clipboard → stdout | — |
cpclear |
empty the clipboard | — |
cuclip |
stdin (or TEXT) → clipboard (replace) |
never |
cuadd |
stdin (or TEXT) → clipboard (append) |
never |
"TTY echo" means stdin is mirrored to stdout when stdout is a terminal.
Downloads the latest release, verifies its SHA-256, and installs system-wide
(wget -qO- … | sh works too):
curl -fsSL https://raw.githubusercontent.com/clicraft/cpclip/main/install.sh | shIt installs into /usr/local (using sudo only for that step):
/usr/local/bin/cpclipplus thecpadd,cppaste,cpclear,cuclip,cuaddsymlinks/usr/local/share/man/man1/cp*.1
/usr/local/bin is on the default PATH, so cpclip works immediately.
Per-user, no sudo — install into ~/.local by setting PREFIX on the
piped shell (note the placement, so the variable reaches the script, not curl):
curl -fsSL https://raw.githubusercontent.com/clicraft/cpclip/main/install.sh | PREFIX=$HOME/.local shPin a specific version with CPCLIP_VERSION=v0.1.1.
Download a .deb / .rpm / .apk from a
Release and install it with your
package manager — it resolves the libx11 / libxfixes / libwayland-client
runtime dependencies for you.
make # builds cpclip + the cpadd/cppaste/cpclear symlinks
make test # runs the test matrix on whatever backends are available
sudo make install # installs to /usr/local (override with PREFIX= and DESTDIR=)echo "hello" | cpclip # copy text to the clipboard
cppaste # paste it back
cpclear # empty the clipboardcpclip and cpadd mirror stdin to stdout only when stdout is a terminal,
so you see the output and copy it at the same time:
make 2>&1 | cpclip # prints the build output and copies itWhen stdout is not a terminal (pipe, redirection, script), the mirror is suppressed automatically — nothing extra reaches the next stage:
make 2>&1 | cpclip | wc -l # copies silently; wc counts what actually went throughBecause the mirror only fires when stdout is a TTY, redirecting stdout is enough to silence it:
make 2>&1 | cpclip > /dev/null # copy silently, discard stdout
make 2>&1 | cpclip > build.log # copy and also save to a file
make 2>&1 | cpclip > build.log 2>&1 # same, stderr to the log tooRedirect stderr to suppress backend error messages (e.g. when the clipboard is unavailable and you don't want noise):
echo hi | cpclip 2>/dev/nullcuclip and cuadd never echo, regardless of whether stdout is a terminal.
Use them when the intent is "copy only" and pass-through would be surprising
— in shell functions, scripts, or keybindings where fd state is unpredictable:
echo hi | cuclip # always silent
echo more | cuadd # append, always silentThey accept the same flags as their cp* counterparts (-t, -f, --maxmem,
--separator, --backend), and all shell redirections work the same way.
Build up a clipboard entry from several commands, then paste it all at once:
git rev-parse HEAD | cpclip # first line — replaces the clipboard
date | cpadd # appended with a newline separator
uname -a | cpadd # appended again
cppaste # paste all three linesCustom separator:
printf 'foo' | cpclip
printf 'bar' | cpadd --separator ' | '
cppaste -n # → foo | barcppaste # appends a newline if the content lacks one
cppaste -n # byte-exact: no trailing newline added
cppaste -n > image.png # save binary clipboard content to a file
cppaste -t text/html # request a specific MIME type--backend auto (the default) picks Wayland when $WAYLAND_DISPLAY is set,
else X11 when $DISPLAY is set. Force one with --backend x11|wayland|null.
- X11 — Xlib + XFixes; owns the
CLIPBOARDselection, serves the MIME set, and handles arbitrarily large payloads via the INCR protocol (both directions). - Wayland —
ext-data-control(no input serial or surface needed; whatwl-copyuses). The backgrounded owner runs the required dispatch loop. - null — an in-process file-backed fake for testing the wiring.
X11 and Wayland have no system-owned clipboard buffer: the copying process is
the storage. So the copy/append commands fork a background owner that serves the bytes on
demand (the parent returns only once the child confirms ownership), while
cppaste is a clean one-shot read. A running clipboard manager copies from
the new owner and provides persistence after it exits.
Because that owner holds the whole payload in memory, a single copy/append
is capped at 10 MiB by default (this is a text tool). Raise or remove it with
--maxmem — e.g. --maxmem 200M, or --maxmem 0 to disable the cap.
See doc/DESIGN.md for the architecture and
doc/IMPLEMENTATION.md for the phased build.
libx11, libxfixes, libwayland-client, plus wayland-scanner and a C11
compiler. The ext-data-control protocol XML is vendored in protocol/, so the
build does not depend on the system wayland-protocols version.
Primary/secondary selections, clipboard history/watch mode, macOS/Windows.
GPL-2.0-or-later. See LICENSE.