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 until you remove that backup yourself.
The full product contract is in .agents/BIBLE.md.