Cliphoard

Cliphoard is a small, local-only, keyboard-first clipboard history utility for Linux/X11.

The core is implemented in Rust with SQLite persistence and TOML configuration. The default build intentionally keeps the GTK/X11 desktop integration behind the gui feature so the data model and persistence tests can run on machines without GTK development libraries.

Build and install from source

From the repository root, copy/paste this complete block:

sudo apt update
sudo apt install cargo rustc dpkg-dev libgtk-4-dev libdbus-1-dev libx11-dev libxfixes-dev libxtst-dev pkg-config
cargo build --release --features gui
packaging/build-deb.sh
sudo apt install ./target/cliphoard_0.1.0_amd64.deb

The last command installs the package. Start Cliphoard from the desktop menu, the tray, or with cliphoard.

Install from a .deb

You can send target/cliphoard_0.1.0_amd64.deb to another Debian/Ubuntu/Mint user. They can install it with:

sudo apt install ./cliphoard_0.1.0_amd64.deb

If apt is unavailable, use:

sudo dpkg -i ./cliphoard_0.1.0_amd64.deb
sudo apt-get install -f

The package installs the cliphoard command, desktop launcher, icon, and automatic startup entry. It does not install a system-wide daemon.

Uninstall and disable autostart

For a package installed with apt install ./cliphoard_*.deb or dpkg -i, remove it with:

sudo apt remove cliphoard

If the package manager says it cannot find the package, check how the binary was installed and remove the registered Debian package directly:

dpkg -S "$(command -v cliphoard)"
sudo dpkg -r cliphoard

To keep Cliphoard installed but disable automatic startup for your user:

mkdir -p ~/.config/autostart
printf '%s\n' '[Desktop Entry]' 'Hidden=true' > ~/.config/autostart/io.cliphoard.Cliphoard.desktop

To remove the local history, configuration, and logs as well:

rm -rf ~/.local/share/cliphoard ~/.config/cliphoard ~/.local/state/cliphoard

The final command permanently deletes Cliphoard’s local data. Stop Cliphoard from the tray menu first.

Development

cargo test
cargo run -- --diagnostics

To build the desktop application on Debian/Ubuntu, install the native dependencies first:

sudo apt install cargo rustc libgtk-4-dev libpango1.0-dev libdbus-1-dev libx11-dev libxfixes-dev libxtst-dev pkg-config
cargo run --features gui

The repository also includes an isolated Docker build that installs all build headers, runs tests, compiles the GTK/X11 backend, and creates an installable .deb:

docker build -t cliphoard-builder .
docker run --rm -v "$PWD/target:/out" cliphoard-builder

The resulting package declares its runtime libraries, so Debian/Ubuntu users can install it with sudo apt install ./target/cliphoard_0.1.0_amd64.deb and the package manager will resolve GTK/X11 runtime dependencies automatically.

Once installed, Cliphoard runs as a background process. Ctrl+Alt+V opens the popup, and cliphoard --show requests it without keeping the invoking shell blocked. On Cinnamon, a StatusNotifier tray icon provides another way to open the popup when the desktop panel exposes tray icons. The tray menu also has Quit Cliphoard, which stops background recording and exits the process.

Runtime files follow XDG conventions:

  • database: ~/.local/share/cliphoard/cliphoard.db
  • configuration: ~/.config/cliphoard/config.toml
  • log state: ~/.local/state/cliphoard/

On first start, Cliphoard asks for a passphrase. The history database is encrypted with SQLCipher and the passphrase is never stored. If an older plaintext history is found, Cliphoard asks before migrating it and keeps the original as a .plaintext-backup, then offers to remove that plaintext backup. Removing it deletes the file entry; it cannot erase copies already made by backups, snapshots, or the filesystem.

The full product contract is in .agents/BIBLE.md.

Description
No description provided
Readme 305 KiB
2026-09-27 19:20:01 +00:00
Languages
Rust 99%
Shell 0.7%
Dockerfile 0.3%