cliphist

Clipboard history “manager” for Wayland

• Write clipboard changes to a history file.
• Recall history with dmenu, rofi, wofi (or whatever other picker you like).
• Both text and images are supported.
• Clipboard is preserved byte-for-byte.
  • Leading/trailing whitespace, no whitespace, or newlines are preserved.
  • Won’t break fancy editor selections like Vim wordwise, linewise, or block mode.
• No concept of a picker, only pipes.

Requires Go, wl-clipboard, and xdg-utils (for MIME inference by wl-copy when no type is supplied).

Install

• You could try using your distro's repos if it's available there.
• Or stick a static binary from the releases page somewhere in your $PATH.
• Or just install it from source with Go and $ go install go.senan.xyz/cliphist@latest.

Usage

Listen for clipboard changes

$ wl-paste --watch cliphist store
This will listen for changes on your primary clipboard and write them to the history.
Call it once per session - for example, in your Sway config.

store reads CLIPBOARD_TYPE from wl-paste --watch (requires wl-clipboard PR #297, merged after v2.3.0). Older wl-clipboard versions leave MIME types unknown.

Select an old item

$ cliphist list | dmenu | cliphist decode | wl-copy
Bind it to something nice on your keyboard.

List metadata

cliphist list -fields id,mime,preview
cliphist list -fields id,format
cliphist list -fields id,timestamp
cliphist list -fields mime 123
cliphist -db-path /some/db list -fields id,timestamp
cliphist list -h

list emits TSV without a header, newest first. -fields selects columns in the requested order; the default is id,preview. An optional ID selects one entry. Unknown fields and missing IDs are errors.

Delete an old item

$ cliphist list | dmenu | cliphist delete
Or else query manually: $ cliphist delete-query "secret item".

Clear database

$ cliphist wipe.

Expire old entries

Run this from a timer to delete entries older than 30 days:

cliphist wipe -older-than 720h

The duration is a Go duration, so days must be given in hours. Entries stored before cliphist tracked timestamps count as older than any cutoff.

Compact database

$ cliphist compact.

Picker examples

exec wl-paste --watch cliphist store
bindsym Mod1+p exec cliphist list | wofi -S dmenu | cliphist decode | wl-copy

FAQ

# fzf
cliphist list | fzf -d $'\t' --with-nth 2 | cliphist decode | wl-copy

# rofi
cliphist list | rofi -dmenu -display-columns 2 | cliphist decode | wl-copy

# fuzzel
cliphist list | fuzzel --dmenu --with-nth 2 | cliphist decode | wl-copy

# wofi
# It kind of works but breaks with quotes in the original selection. I recommend not trying to hide the column with wofi.
cliphist list | wofi --dmenu --pre-display-cmd "echo '%s' | cut -f 2" | cliphist decode | wl-copy

wl-paste --type text --watch cliphist store
wl-paste --type image --watch cliphist store

Packaging

Demo

https://user-images.githubusercontent.com/6832539/230513908-b841fffe-d7d5-46c2-b29f-28b3e91daa74.mp4

Configuration

cliphist can be optionally configured to extend the default functionality. Global options can be provided with a CLI argument, environment variable, or config file key. Global CLI flags go before the command. The command-local list -fields flag is CLI-only; environment variables and config keys cannot change the output fields.

For example, the option max-items, can be set via the CLI as -max-items 100, as an environment variable CLIPHIST_MAX_ITEMS=100, or in the config file as max-items 100.

If you choose to use the config file, the default location is $XDG_CONFIG_HOME/cliphist/config. The format is a text file with one option per line, where each line is <key> <value>. For example:

# example cliphist config
max-items 1000
max-dedupe-search 200

The list of available options is: