Skip to content
clicraftPublic

About

CLI clipboard tool for X11 and Wayland (copy, paste, add, clear)

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

cpclip

CI Tests License Built with Claude Code

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.

Install

One-liner (recommended)

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 | sh

It installs into /usr/local (using sudo only for that step):

  • /usr/local/bin/cpclip plus the cpadd, cppaste, cpclear, cuclip, cuadd symlinks
  • /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 sh

Pin a specific version with CPCLIP_VERSION=v0.1.1.

Native package

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.

From source

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=)

Usage

Copy and paste

echo "hello" | cpclip       # copy text to the clipboard
cppaste                      # paste it back
cpclear                      # empty the clipboard

TTY pass-through

cpclip 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 it

When 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 through

Redirecting stdout and stderr

Because 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 too

Redirect stderr to suppress backend error messages (e.g. when the clipboard is unavailable and you don't want noise):

echo hi | cpclip 2>/dev/null

Silent copy with cuclip / cuadd

cuclip 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 silent

They accept the same flags as their cp* counterparts (-t, -f, --maxmem, --separator, --backend), and all shell redirections work the same way.

Append

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 lines

Custom separator:

printf 'foo' | cpclip
printf 'bar' | cpadd --separator ' | '
cppaste -n                   # → foo | bar

Paste options

cppaste                      # 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

Backends

--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 CLIPBOARD selection, 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; what wl-copy uses). The backgrounded owner runs the required dispatch loop.
  • null — an in-process file-backed fake for testing the wiring.

How it works

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.

Dependencies

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.

Not supported

Primary/secondary selections, clipboard history/watch mode, macOS/Windows.

License

GPL-2.0-or-later. See LICENSE.

About

CLI clipboard tool for X11 and Wayland (copy, paste, add, clear)

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages