A clipboard manager written in Rust Programming Language.
Installation | Usage | Integration
Table of contents
- Copy/Paste plaintext
- Copy/Paste images
- Persistent clipboard contents
- Support for snippets
- Support for
X11 - Support for
Wayland(experimental) - Support for
macOS - Support for
gRPC- gRPC over
HTTP - gRPC over
Unix domain socket
- gRPC over
- Support for
D-Bus
-
Demonstration with Rofi
clipcat.webm
-
Use Rofi to select clip
-
Use dmenu to select clip
-
Use skim to select clip
Clipcat can be installed using various package managers on Linux.
Pre-built binaries can also be downloaded from the GitHub releases page.
Detailed instructions for installing Clipcat can be found here.
Clipcat uses a Client-Server architecture. There are two role types in this architecture: Server and Client.
The clipcat daemon runs as a background process and performs the following tasks:
- Watches for changes to the clipboard.
- Caches clipboard content.
- Inserts content into the clipboard.
- Acts as a gRPC server, waiting for remote procedure calls from clients.
Currently, clipcat supports the following windowing systems:
X11, the followingcrates are leveraged:Wayland(experimentally), the followingcrates are leveraged:
A clipcat client sends requests to the server for the following operations:
List: list the cached clips from server.Insert: replace the current content ofclipboardwith a clip.Remove: remove the cached clips from server.
| Program | Role Type | Comment |
|---|---|---|
clipcatd |
Server |
The clipcat server (daemon). |
clipcatctl |
Client |
The clipcat client providing a command line interface. |
clipcat-menu |
Client |
The clipcat client that calls a built-in finder or an external finder for selecting clips. |
- Setup configurations for
clipcat. Read configuration section for more details.
mkdir -p $XDG_CONFIG_HOME/clipcat
clipcatd default-config > $XDG_CONFIG_HOME/clipcat/clipcatd.toml
clipcatctl default-config > $XDG_CONFIG_HOME/clipcat/clipcatctl.toml
clipcat-menu default-config > $XDG_CONFIG_HOME/clipcat/clipcat-menu.toml- Start
clipcatdfor watching clipboard events.
# Show the usage. Please read the usage before doing any other operations.
clipcatd help
# Start and daemonize clipcatd. It will run in the background.
# You can use `pkill clipcatd` to stop it; a `SIGTERM` signal will be sent to clipcatd.
clipcatd
# Alternatively, you can start clipcatd but keep it in the foreground.
# You can press `Ctrl+C` in your terminal to stop it; a `SIGINT` signal will be sent to clipcatd.
clipcatd --no-daemon-
Copy arbitrary text or images from other processes using your mouse or keyboard.
-
You can run the following commands with
clipcatctlorclipcat-menu:
| Command | Comment |
|---|---|
clipcatctl list |
List cached clipboard history |
clipcatctl promote <id> |
Insert cached clip with <id> into the X11 clipboard |
clipcatctl remove [ids] |
Remove cached clips with [ids] from the server |
clipcatctl clear |
Clear cached clipboard history |
| Command | Comment |
|---|---|
clipcat-menu insert |
Insert a cached clip into the X11 clipboard |
clipcat-menu remove |
Remove cached clips from the server |
clipcat-menu edit |
Edit a cached clip with $EDITOR |
The following finders are supported by clipcat-menu:
| Program | Default Configuration File Path |
|---|---|
clipcatd |
$XDG_CONFIG_HOME/clipcat/clipcatd.toml |
clipcatctl |
$XDG_CONFIG_HOME/clipcat/clipcatctl.toml |
clipcat-menu |
$XDG_CONFIG_HOME/clipcat/clipcat-menu.toml |
Configuration for clipcatd
# Run as a traditional UNIX daemon.
daemonize = true
# Maximum number of clips in history.
max_history = 50
# File path for clip history.
# If this value is omitted, `clipcatd` will persist history in `$XDG_CACHE_HOME/clipcat/clipcatd-history`.
history_file_path = "/home/<username>/.cache/clipcat/clipcatd-history"
# File path for the PID file.
# If this value is omitted, `clipcatd` will place the PID file in `$XDG_RUNTIME_DIR/clipcatd.pid`.
pid_file = "/run/user/<user-id>/clipcatd.pid"
# Controls how often the program updates its stored value of the Linux primary selection.
# In the Linux environment, the primary selection automatically updates to reflect the currently highlighted text or object,
# typically updating with every mouse movement.
primary_threshold_ms = 5000
[log]
# Emit log messages to a log file.
# If this value is omitted, `clipcatd` will disable logging to a file.
file_path = "/path/to/log/file"
# Emit log messages to systemd-journald.
emit_journald = true
# Emit log messages to stdout.
emit_stdout = false
# Emit log messages to stderr.
emit_stderr = false
# Log level.
level = "INFO"
[watcher]
# Enable watching the X11/Wayland clipboard selection.
enable_clipboard = true
# Enable watching the X11/Wayland primary selection.
enable_primary = true
# Ignore clips that match any of the MIME types.
sensitive_mime_types = ["x-kde-passwordManagerHint"]
# Ignore text clips that match any of the provided regular expressions.
# The regular expression engine is powered by https://github.com/rust-lang/regex.
denied_text_regex_patterns = []
# Ignore text clips with a length less than or equal to `filter_text_min_length`, in characters (Unicode scalar value), not bytes.
filter_text_min_length = 1
# Ignore text clips with a length greater than `filter_text_max_length`, in characters (Unicode scalar value), not bytes.
filter_text_max_length = 20000000
# Enable or disable capturing images.
capture_image = true
# Ignore image clips with a size greater than `filter_image_max_size`, in bytes.
filter_image_max_size = 5242880
[grpc]
# Enable gRPC over HTTP.
enable_http = true
# Enable gRPC over Unix domain socket.
enable_local_socket = true
# Host address for gRPC.
host = "127.0.0.1"
# Port number for gRPC.
port = 45045
# Path for the Unix domain socket.
# If this value is omitted, `clipcatd` will place the socket in `$XDG_RUNTIME_DIR/clipcat/grpc.sock`.
local_socket = "/run/user/<user-id>/clipcat/grpc.sock"
[dbus]
# Enable D-Bus.
enable = true
# Specify the identifier for the current `clipcat` instance.
# The D-Bus service name will appear as "org.clipcat.clipcat.instance-0".
# If the identifier is not provided, the D-Bus service name will appear as "org.clipcat.clipcat".
identifier = "instance-0"
[desktop_notification]
# Enable desktop notifications.
enable = true
# Path for an icon; the given icon will be displayed in the desktop notification,
# if your desktop notification server supports showing an icon.
# If this value is not provided, the default value `accessories-clipboard` will be used.
icon = "/path/to/the/icon"
# Timeout duration in milliseconds.
# This sets the time from when the notification is displayed until it is closed by the notification server.
timeout_ms = 2000
# Define the length of long plaintext.
# If the length of plaintext is greater than or equal to `long_plaintext_length`,
# a desktop notification will be emitted.
# If this value is 0, no desktop notification will be emitted for long plaintext.
long_plaintext_length = 2000
# Snippets, only UTF-8 text is supported.
[[snippets]]
[snippets.Directory]
# Name of snippet.
name = "my-snippets"
# File path to the directory containing snippets.
path = "/home/user/snippets"
[[snippets]]
[snippets.File]
# Name of snippet.
name = "os-release"
# File path to the snippet.
path = "/etc/os-release"
[[snippets]]
[snippets.Text]
# Name of snippet.
name = "cxx-io-speed-up"
# Content of the snippet.
content = '''
int io_speed_up = [] {
std::ios::sync_with_stdio(false);
std::cin.tie(nullptr);
std::cout.tie(nullptr);
return 0;
}();
'''
[[snippets]]
[snippets.Text]
name = "rust-sieve-primes"
content = '''
fn sieve_primes(n: usize) -> Vec<usize> {
if n < 2 {
return Vec::new();
}
let root_n = f64::from(n as i32).sqrt().floor() as usize;
let mut is_prime = vec![true; n + 1];
for i in 2..=root_n {
if !is_prime[i] {
continue;
}
for j in ((i << 1)..=n).step_by(i) {
is_prime[j] = false;
}
}
is_prime
.into_iter()
.enumerate()
.skip(2)
.filter_map(|(i, x)| if x { Some(i) } else { None })
.collect()
}
'''Configuration for clipcatctl
# Server endpoint.
# `clipcatctl` connects to the server via a Unix domain socket if `server_endpoint` is a file path, such as:
# "/run/user/<user-id>/clipcat/grpc.sock".
# It connects via HTTP if `server_endpoint` is a URL, like: "http://127.0.0.1:45045".
server_endpoint = "/run/user/<user-id>/clipcat/grpc.sock"
[log]
# Emit log messages to a log file.
# Delete this line to disable logging to a file.
file_path = "/path/to/log/file"
# Emit log messages to systemd-journald.
emit_journald = true
# Emit log messages to stdout.
emit_stdout = false
# Emit log messages to stderr.
emit_stderr = false
# Log level.
level = "INFO"Configuration for clipcat-menu
# Server endpoint
# The `clipcat-menu` connects to the server via a Unix domain socket if `server_endpoint` is a file path, such as:
# "/run/user/<user-id>/clipcat/grpc.sock".
# It connects via HTTP if `server_endpoint` is a URL, like: "http://127.0.0.1:45045".
server_endpoint = "/run/user/<user-id>/clipcat/grpc.sock"
# The default finder to invoke when no "--finder=<finder>" option is provided.
finder = "rofi"
[log]
# Emit log messages to a log file.
# Delete this line to disable logging to a file.
file_path = "/path/to/log/file"
# Emit log messages to systemd-journald.
emit_journald = true
# Emit log messages to stdout.
emit_stdout = false
# Emit log messages to stderr.
emit_stderr = false
# Log level.
level = "INFO"
# Options for "rofi".
[rofi]
# Length of line.
line_length = 100
# Length of menu.
menu_length = 30
# Prompt for the menu.
menu_prompt = "Clipcat"
# Extra arguments to pass to `rofi`.
extra_arguments = ["-mesg", "Please select a clip"]
# Options for "dmenu".
[dmenu]
# Length of line.
line_length = 100
# Length of menu.
menu_length = 30
# Prompt for the menu.
menu_prompt = "Clipcat"
# Extra arguments to pass to `dmenu`.
extra_arguments = [
"-fn",
"SauceCodePro Nerd Font Mono-12",
"-nb",
"#282828",
"-nf",
"#ebdbb2",
"-sb",
"#d3869b",
"-sf",
"#282828",
]
# Customize your finder.
[custom_finder]
# External program name.
program = "fzf"
# Arguments for calling the external program.
args = []
Integrating with Zsh
For zsh users, it is useful to integrate clipcat with zsh.
Add the following commands to your zsh configuration file (~/.zshrc):
if type clipcat-menu >/dev/null 2>&1; then
alias clipedit=' clipcat-menu --finder=builtin edit'
alias clipdel=' clipcat-menu --finder=builtin remove'
bindkey -s '^\' "^Q clipcat-menu --finder=builtin insert ^J"
bindkey -s '^]' "^Q clipcat-menu --finder=builtin remove ^J"
fiIntegrating with i3 Window Manager
For i3 window manager users, it is useful to integrate clipcat with i3.
Add the following options to your i3 configuration file ($XDG_CONFIG_HOME/i3/config):
exec_always --no-startup-id clipcatd # start clipcatd at startup
set $launcher-clipboard-insert clipcat-menu insert
set $launcher-clipboard-remove clipcat-menu remove
bindsym $mod+p exec $launcher-clipboard-insert
bindsym $mod+o exec $launcher-clipboard-remove
NOTE: You can use rofi or dmenu as the default finder.
Integrating with LeftWM
For leftwm users, it is useful to integrate clipcat with leftwm.
Add the following keybindings to your leftwm configuration file ($XDG_CONFIG_HOME/leftwm/config.ron):
(
/* other configurations */
keybind: [
/* select clip from clipboard */
(command: Execute, value: "clipcat-menu insert", modifier: ["modkey"], key: "p"),
(command: Execute, value: "clipcat-menu remove", modifier: ["modkey"], key: "o"),
/* other configurations */
],
/* other configurations */
)NOTE: You can use rofi or dmenu as the default finder.
Add the following commands to your $XDG_CONFIG_HOME/leftwm/themes/current/up:
# other configurations
# Start clipcatd
clipcatd
# other configurationsAdd the following commands to your $XDG_CONFIG_HOME/leftwm/themes/current/down:
# other configurations
# Terminate clipcatd
pkill clipcatd
# other configurationsStarting clipcatd with systemd
Put the following snippet in $XDG_CONFIG_HOME/systemd/user/clipcat.service:
[Unit]
Description=Clipcat Daemon
PartOf=graphical-session.target
[Install]
WantedBy=graphical-session.target
[Service]
# NOTE: We assume that your `clipcatd` is located at `/usr/bin/clipcatd`.
ExecStartPre=/bin/rm -f %t/clipcat/grpc.sock
ExecStart=/usr/bin/clipcatd --no-daemon --replace
Restart=on-failure
Type=simple
Enable and start clipcat with the following commands:
systemctl --user daemon-reload
systemctl --user enable clipcat.service
systemctl --user start clipcat.service
systemctl --user status clipcat.service-
clipcatd: Theclipcatserver (daemon). -
clipcatctl: Theclipcatclient that provides a command line interface. -
clipcat-menu: Theclipcatclient that utilizes a built-in or external finder to select clips. -
clipcat-notify: A tool for monitoring clipboard events. It watches the clipboard and exits when a change is detected, returning an exit code of 0 for success and 1 for errors.
Note
clipcat-notify does not interact with clipcatd, clipcatctl, or clipcat-menu; it is simply a tool for monitoring the clipboard.
Clipcat is licensed under the GNU General Public License version 3. See LICENSE for more information.