stash/README.md

Stash

Wayland clipboard "manager" with fast persistent history and multi-media support. Stores and previews clipboard entries (text, images) on the command line.

Features
Installation | Usage
Tips and Tricks

Features

Stash is a feature-rich, yet simple clipboard management utility with many features such as but not limited to:

• Automatic MIME detection for stored entries
• Fast persistent storage using SQLite
• List, search, decode, delete, and wipe clipboard history with ease
• Backwards compatible with Cliphist TSV format
  • Import clipboard history from TSV (e.g., from cliphist list)
• Image preview (shows dimensions and format)
• Deduplication and entry limit control
• Text previews with customizable width
• Automatic clipboard monitoring with stash watch
• Sensitive clipboard filtering via regex (see below)

See usage section for more details.

Installation

With Nix

Nix is the recommended way of downloading Stash. You can install it using Nix flakes using nix profile add if on non-nixos or add Stash as a flake input if you are on NixOS.

{
  # Add Stash to your inputs like so
  inputs.stash.url = "github:notashelf/stash";

  outputs = { /* ... */ };
}

Then you can get the package from your flake input, and add it to your packages to make stash available in your system.

{inputs, pkgs, ...}: let
  stashPkg = inputs.stash.packages.${pkgs.stdenv.hostPlatform}.stash;
in {
  environment.systemPackages = [stashPkg];

  # Additionally feel free to add the Stash package in `systemd.packages` to
  # automatically run the Stash watch daemon, which will watch your primary
  # clipboard for changes and persist them.
  systemd.packages = [stashPkg];
}

You can also run it one time with nix run

nix run github:notashelf/stash -- watch # start the watch daemon

Without Nix

You can also install Stash on any of your systems without using Nix. New releases are made when a version gets tagged, and are available under GitHub Releases. To install Stash on your system without Nix, eiter:

• Download a tagged release from GitHub Releases for your platform and place the binary in your $PATH. Instructions may differ based on your distribution, but generally you want to download the built binary from releases and put it somewhere like /usr/bin.

• Build and install from source with Cargo:

  cargo install --git https://github.com/notashelf/stash
  

Usage

Command interface is only slightly different from Cliphist. In most cases, it will be as simple as replacing cliphist with stash in your commands, aliases or scripts.

Note

It is not a priority to provide 1:1 backwards compatibility with Cliphist. While the interface is almost identical, Stash chooses to build upon Cliphist's design and extend existing design choices. See Migrating from Cliphist for more details.

Store an entry

echo "some clipboard text" | stash store

List entries

stash list

Decode an entry by ID

stash decode --input "1234"

Delete entries matching a query

stash delete --type query --arg "some text"

Delete multiple entries by ID (from a file or stdin)

stash delete --type id < ids.txt

Wipe all entries

stash wipe

Watch clipboard for changes and store automatically

stash watch

This runs a daemon that monitors the clipboard and stores new entries automatically. This is designed as an alternative to shelling out to wl-paste --watch inside a Systemd service or XDG autostart. You may find a premade Systemd service in vendor/. Packagers are encouraged to vendor the service unless adding their own.

Options

Some commands take additional flags to modify Stash's behavior. See each commands --help text for more details. The following are generally standard:

• --db-path <path>: Custom database path
• --max-items <N>: Maximum number of entries to keep (oldest trimmed)
• --max-dedupe-search <N>: Deduplication window size
• --preview-width <N>: Text preview max width for list
• --version: Print the current version and exit

Sensitive Clipboard Filtering

Stash can be configured to avoid storing clipboard entries that match a sensitive pattern, using a regular expression. This is useful for preventing accidental storage of secrets, passwords, or other sensitive data. You don't want sensitive data ending up in your persistent clipboard, right?

The filter can be configured in one of two ways:

• Environment variable: Set STASH_SENSITIVE_REGEX to a valid regex pattern. If clipboard text matches, it will not be stored.

• Systemd LoadCredential: If running as a service, you can provide a regex pattern via a credential file. For example, add to your stash.service:

  LoadCredential=clipboard_filter:/etc/stash/clipboard_filter
  

  The file /etc/stash/clipboard_filter should contain your regex pattern (no quotes). This is done automatically in the vendored Systemd service. Remember to set the appropriate file permissions if using this option.

The service will check the credential file first, then the environment variable. If a clipboard entry matches the regex, it will be skipped and a warning will be logged.

Example regex to block common password patterns:

• (password|secret|api[_-]?key|token)[=: ]+[^\s]+

Tips & Tricks

Migrating from Cliphist

Stash was designed to be a drop-in replacement for Cliphist, with only minor improvements. If you are migrating from Cliphist, here are a few things you should know.

• Most Cliphist commands have direct equivalents in Stash. For example, cliphist store -> stash store, cliphist list -> stash list, etc.
• Cliphist uses delete-query; in Stash, you must use stash delete --type query --arg "your query".
• Both Cliphist and Stash support deleting by ID, including from stdin or a file.
• Stash respects the STASH_CLIPBOARD_STATE environment variable for sensitive/clear entries, just like Cliphist. The STASH_ prefix is added for granularity, you must update your scripts.
• You can export your Cliphist history to TSV and import it into Stash (see below).
• Stash supports text and image previews, including dimensions and format.
• Stash adds a watch command to automatically store clipboard changes. This is an alternative to wl-paste --watch cliphist list. You can avoid shelling out and depending on wl-paste as Stash implements it through wl-clipboard-rs crate.

TSV Export and Import

Both Stash and Cliphist support TSV format for clipboard history. You can export from Cliphist and import into Stash, or use Stash to export TSV for interoperability.

Export TSV from Cliphist:

cliphist list --db ~/.cache/cliphist/db > cliphist.tsv

Import TSV into Stash:

stash import < cliphist.tsv

Export TSV from Stash:

stash list > stash.tsv

Import TSV into Cliphist:

cliphist --import < stash.tsv

More Tricks

Here are some other tips for Stash that are worth documenting. If you have figured out something new, e.g. a neat shell trick, feel free to add it here!

1. You may use stash list to view your clipboard history in an interactive TUI. This is obvious if you have ever ran the command, but here are some things that you might not have known.

   • stash list displays the TUI only if the user is in an interactive TTY. E.g. if it's a Bash script, stash list will output TSV.
   • You can change the format with --format to e.g. JSON but you can also force a TSV format inside an interactive session with --format tsv.
   • stash list displays the mime type for newly recorded entries, but it will not be able to display them for entries imported by Cliphist since Cliphist never made a record of this data.

2. You can pipe cliphist list --db ~/.cache/cliphist/db to stash import --type tsv to mimic importing from STDIN.

   cliphist list --db ~/.cache/cliphist/db | stash import