clipse.mp4

Table of contents

• Why use clipse?
• Installation
• Set up
• Configuration
• All commands
• How it works
• Contributing
• FAQs

Release information

If moving to a new release of clipse please review the changelog.

About 📋

clipse is a configurable, TUI-based clipboard manager application written in Go with minimal dependency. Though the app is optimized for a Linux OS using a dedicated window manager, clipse can also be used on any Unix-based system. Simply install the package and bind the open command to get your desired clipboard behavior. Further instructions for setting this up can be found below.

Dependency info and libraries used

atotto/clipboard

This requires a standard system clipboard, something like one of the following:

• wl-clipboard
• xclip
• xsel
• termux-clipboard

go-ps

Does not require any additional dependency.

BubbleTea

Does not require any additional dependency.

Why use clipse?

1. Configurability 🧰

A customizable TUI allows you to easily match your system's theme. The app is based on your terminal's theme by default but is editable from a custom_theme.json file that gets created when the program is run for the first time. Some example themes (based on my terminal)...

Nord

Dracula

Gruvbox

An example custom_theme.json file:

{
    "useCustomTheme": true,
    "DimmedDesc": "#4C566A",
    "DimmedTitle": "#4C566A",
    "FilteredMatch": "#A3BE8C",
    "NormalDesc": "#81A1C1",
    "NormalTitle": "#B48EAD",
    "SelectedDesc": "#A3BE8C",
    "SelectedTitle": "#A3BE8C",
    "SelectedBorder": "#88C0D0",
    "SelectedDescBorder": "#88C0D0",
    "TitleFore": "#D8DEE9",
    "Titleback": "#3B4252",
    "StatusMsg": "#8FBCBB",
    "PinIndicatorColor": "#ff0000"
}

Simply leaving this file alone or setting the useCustomTheme value to false will give you a nice default theme...

You can also easily specify source config like custom paths and max history limit in the apps config.json file. For more information see Configuration section.

2. Usability ✨

Easily recall, add, and delete clipboard history via a smooth TUI experience built with Go's excellent BubbleTea library. A simple fuzzy finder, callable with the / key can easily match content from a theoretically unlimited amount of time in the past:

Items can be pinned using the p key and toggled using tab, these pinned items will be not be removed from your history unless explicitly deleted with backpace/x in the TUI or clipse -clear.

Content can also be added explicitly from the command-line using the -a or -c flags. This would allow you to easily pipe any CLI output directly into your history with commands like:

ls /home | clipse -a

clipse -a "a custom string value"

3. Efficiency 💥

Due to Go's inbuilt garbage collection system and the way the application is built, clipse is pretty selfless when it comes to CPU consumption and memory. The below image shows how little resources are required to run the background event listener used to continually update the history displayed in the TUI...

4. Versatility 🌐

The clipse binary, installable from the repository, can run on pretty much any Unix-based OS, though currently optimized for Linux. Being terminal-based also allows for easy integration with a window manager and configuration of how the TUI behaves. For example, binding a floating window to the clipse command as shown at the top of the page using Hyprland window manager on NixOs.

Note that working with image files will require one of the following dependencies to be installed on your system:

• Linux (X11) & macOS: xclip
• Linux (Wayland): wl-clipboard

Setup & installation 🏗️

See below for instructions on getting clipse installed and configured effectively.

Installation

Installing on NixOs

Due to how irregularly the stable branch of Nixpkgs is updated, you may find the unstable package is more up to date. The Nix package for clipse can be found here

Direct install

nix-env -iA nixpkgs.clipse # OS == NixOs
nix-env -f channel:nixpkgs -iA clipse # OS != NixOs

Nix shell

nix shell -p clipse

System package

environment.systemPackages = [
    pkgs.clipse
  ];

If building clipse from the unstable branch as a system package, I would suggest referencing this article for best practice. The derivation can also be built from source using the following:

{ lib
, buildGoModule
, fetchFromGitHub
}:

buildGoModule rec {
  pname = "clipse";
  version = "0.0.71";

  src = fetchFromGitHub {
    owner = "savedra1";
    repo = "clipse";
    rev = "v${version}";
    hash = "sha256-88GuYGJO5AgWae6LyMO/TpGqtk2yS7pDPS0MkgmJUQ4=";
  };

  vendorHash = "sha256-GIUEx4h3xvLySjBAQKajby2cdH8ioHkv8aPskHN0V+w=";

  meta = {
    description = "Useful clipboard manager TUI for Unix";
    homepage = "https://github.com/savedra1/clipse";
    license = lib.licenses.mit;
    mainProgram = "clipse";
    maintainers = [ lib.maintainers.savedra1 ];
  };
}

Installing on Arch

Shout out to mcdenkijin for creating the AUR package!

Installing with yay

yay -S clipse

Installing from pkg source

git clone https://aur.archlinux.org/clipse.git && cd clipse && makepkg -si

Installing with wget

Linux arm64

wget -c https://github.com/savedra1/clipse/releases/download/v0.0.6/clipse_0.0.71_linux_arm64.tar.gz -O - | tar -xz

Linux amd64

wget -c https://github.com/savedra1/clipse/releases/download/v0.0.71/clipse_0.0.71_linux_amd64.tar.gz -O - | tar -xz

Linux 836

wget -c https://github.com/savedra1/clipse/releases/download/v0.0.71/clipse_0.0.71_linux_836.tar.gz -O - | tar -xz

Darwin arm64

wget -c https://github.com/savedra1/clipse/releases/download/v0.0.71/clipse_0.0.71_darwin_arm64.tar.gz -O - | tar -xz

Darwin amd64

wget -c https://github.com/savedra1/clipse/releases/download/v0.0.71/clipse_0.0.71_darwin_amd64.tar.gz -O - | tar -xz

Installing with Go

go install github.com/savedra1/clipse@v0.0.71

Building from source

git clone https://github.com/savedra1/clipse

cd clipse

go mod tidy

go build -o clipse

Set up

As mentioned earlier, to get the most out of clipse you'll want to bind the two key commands to your systems config. The first key command is to open the clipboard history TUI:

clipse

The second command doesn't need to be bound to a key combination, but rather to the system boot to run the background listener on start-up:

clipse -listen  

The above command creates a nohup process of clipse --listen-shell, which if called on its own will start a listener in your current terminal session instead. If nohup is not supported on your system, you can use your preferred method of running clipse --listen-shell in the background instead.

Note: The following examples are based on bash/zsh shell environments. If you use something else like foot or fish, you may need to construct the command differently, referencing the relevant documentation.

Hyprland

Add the following lines to your Hyprland config file:

exec-once = clipse -listen                                                            # run listener on startup

windowrulev2 = float,class:(floating)                                                 # ensure you have defined a floating window class

bind = SUPER, V, exec,  <terminal name> --class floating -e <shell-env>  -c 'clipse'  # bind the open clipboard operation to a nice key. 

                                                                                      # Example: bind = SUPER, V, exec, alacritty --class floating -e zsh -c 'clipse'

Hyprland reference

i3

Add the following commands to your ~/.config/i3/config file:

exec --no-startup-id clipse -listen                                                           # run listener on startup

bindsym $mod+V exec --no-startup-id urxvt -e "$SHELL" -c "i3-msg 'floating enable' && clipse" # Bind floating shell with TUI selection to something nice 

i3 reference

Sway

Add the following config to your ~/.config/sway/config file:

exec clipse -listen                                                                                                                     # run the background listener on startup

bindsym $mod+V exec <terminal name> -e sh -c "swaymsg floating enable, move position center; swaymsg resize set 80ppt 80ppt && clipse"  # Bind floating shell with TUI selection to something nice

Sway reference

MacOs

The native terminal on MacOs will not close once the clipse program completes, even when using the -fc argument. You will therefore need to use a different terminal environment like Alacritty to achieve the "close on selection" effect. The bindings used to open the TUI will then need to be defined in your settings/window manager.

Other

Every system/window manager is different and hard to determine exactly how to achieve the more ‘GUI-like’ behavior. If using something not mentioned above, just refer to your systems documentation to find how to:

• Run the clipse -listen / clipse --listen-shell command on startup
• Bind the clipse command to a key that opens a terminal session (ideally in a window)

If you're not calling clipse with a command like exec <terminal name> -e sh -c and want to force the terminal window to close on selection of an item, use the -fc arg to pass in the $PPID variable so the program can force kill the shell session. EG clipse -fc $PPID. Note that the $PPID variable is not available in every terminal environment, like fish terminal where you'd need to use $fish_pid instead.

Configuration

The configuration capabilities of clipse will change as clipse evolves and grows. Currently, clipse supports the following configuration:

• Setting custom paths for:
  • The clipboard history file
  • The clipboard binaries directory (copied images and other binary data is stored in here)
  • The clipboard UI theme file
• Setting a custom max history limit
• Custom themes

clipse looks for a base config file in $CONFIG_DIR/clipse/config.json ($CONFIG_DIR being $XDG_DATA_HOME or $HOME/.config), and creates a default file if it does not find anything. The default config looks like this:

{
    "historyFile": "clipboard_history.json",
    "maxHistory": 100,
    "themeFile": "custom_theme.json",
    "tempDir": "tmp_files"
}

Note that all the paths provided (the theme, historyFile, and tempDir) are all relative paths. They are relative to the location of the config file that holds them. Thus, a file config.json at location $HOME/.config/clipse/config.json will have all relative paths defined in it relative to its directory of $HOME/.config/clipse.

Absolute paths starting with /, paths relative to the user home dir using ~, or any environment variables like $HOME and $XDG_CONFIG_HOME are also valid paths that can be used in this file instead.

All commands 💻

clipse is more than just a TUI. It also offers a number of CLI commands for managing clipboard content directly from the terminal.

# Operational commands 

clipse -a <arg>       # Adds <arg> directly to the clipboard history without copying to system clipboard (string

clipse -a             # Adds any standard input directly to the clipboard history without copying to the system clipboard.

                      # For example: echo "some data" | clipse -a

clipse -c <arg>       # Copy the <arg> to the system clipboard (string). This also adds to clipboard history if currently listening. 

clipse -c             # Copies any standard input directly to the system clipboard.

                      # For example: echo "some data" | clipse -c

clipse -p             # Prints the current clipboard content to the console. 

                      # Example: clipse -p > file.txt

# TUI management commands

clipse -fc $PPID      # Open Clipboard TUI in 'force kill' mode 

clipse -listen        # Run a background listener process

clipse --listen-shell # Run a listener process in the current terminal (useful for debugging)

clipse -help          # Display menu option

clipse -v             # Get version

clipse -clear         # Wipe all clipboard history and current system clipboard value

clipse keep           # Keep the TUI open after selecting an item to copy (useful for debugging)

clipse -kill          # Kill any existing background processes

clipse                # Open Clipboard TUI in persistent/debug mode

You can view the full list of key bind commands when in the TUI by hitting the ? key:

How it works 🤔

When the app is run for the first time it creates a /home/$USER/.config/clipse dir containing config.json, clipboard_history.json, custom_theme.json and a dir called tmp_files for storing image data. After the clipse -listen command is executed, a background process will be watching for clipboard activity and adding any changes to the clipboard_history.json file, unless a different path is specified in config.json.

The TUI that displays the clipboard history with the defined theme should then be called with the clipse command. Operations within the TUI are defined with the BubbleTea framework, allowing for efficient concurrency and a smooth UX. delete operations will remove the selected item from the TUI view and the storage file, select operations will copy the item to the systems clipboard and exit the program.

The maximum item storage limit defaults at 100 but can be customized to anything you like in the config.json file.

Contributing 🙏

I would love to receive contributions to this project and welcome PRs from anyone and everyone. The following is a list of example future enhancements I'd like to implement:

• Image previews in TUI view
• Pinned items
• Customisations for:
  • max history limit
  • config file paths
  • key bindings
• Auto-forget feature based on where the text was copied
• Multi-select feature for copying multiple items at once
• Categorized pinned items with potentially different tabs/views
• System paste option (building functionality to paste the chosen item directly into the next place of focus after the TUI closes)
• Packages for apt, dnf, brew etc
• Theme/config adjustments made available via CLI
• Better debugging / debug mode (eg clipse --debug / debug file / system alert on panic)
• Use of a GUI library such as fyne/GIO (only with minimal CPU cost)
• Cross compile binaries for wl-clipboard/xclip to remove dependency
• TUI / theming enhancements:
  • Menu theme
  • Filter theme
  • Clear TUI view on select and close (mirror close effect from q or esc)
• Private mode (eg clipse --pause 1 )

FAQ

• My terminal window does not close on selection, even when using clipse -fc $PPID - Some terminal environments reference system variables differently. For example, the fish terminal will need to use $fish_pid instead. To debug this error you can run echo $PPID to see what gets returned. The 'close on selection functionality is also not currently available for macOS as killing the terminals ppid does not close the window - it seems AppleScript is needed to achieve this.

• Is there risk of multiple parallel processes running? - No. The clipse command kills any existing TUI processes before opening up and the clipse -listen command kills any existing background listeners before starting a new one.

• High CPU usage? - When an image file has an irregular binary data pattern it can cause a lot of strain on the program when clipse reads its history file (even when the TUI is not open). If this happens, you will need to remove the image file from the TUI or buy using clipse -clear or clipse -clear-images to remove all files if you don't want to spend the time figuring out which one is causing the issue. See issue #33 for an example.

• My copied entries are not recorded when starting the clipse listener on boot with a systemd service - There may be a few ways around this but the workaround discovered in issue #41 was to use a .desktop file, stored in ~/.config/autostart/. Eg:

  [Desktop Entry]
  Name=clipse
  Comment=Clipse event listener autostart.
  Exec=/home/brayan/Applications/bin/clipse/clipse_0.0.71_linux_amd64/clipse --listen %f
  Terminal=false
  Type=Application