Skip to content

remoclip

remoclip (remote clipboard) is a small tool for providing copy and paste clipboard functionality in the CLI - with a special emphasis on allowing access to your local machine's clipboard when connected to remote systems. The package provides two CLI scripts: remoclip_server and remoclip.

remoclip relies on the pyperclip package to interface with the local clipboard on Linux, Mac, and Windows.

Warning

Please pay attention to these warnings in the documentation. Allowing remote access to your local machine's clipboard is dangerous if not properly secured. Use the security_token feature and keep its value secret.

Quick Start

Install with uv or pip: 

$ uv tool install remoclip
# alternative:
# pip install remoclip

Create a security token (optional but highly recommended): 

TOKEN=$(python3 -c "import secrets; print(secrets.token_hex(32))")
echo "security_token: $TOKEN" > ~/.remoclip.yaml

Run the server: 

$ remoclip_server

In a new shell, access your local clipboard: 

$ echo Hello from remoclip. | remoclip copy
Hello from remoclip.
$ remoclip paste
Hello from remoclip.

Add --strip (or -s) to remoclip copy when you need to remove trailing newline characters from the piped input before it reaches the clipboard.

Connect to a remote system: 

# first copy the config file so the remote client uses the security token
$ scp ~/.remoclip.yaml user@myremotehost:~
# remoclip's default port is 35612
$ ssh -R 35612:127.0.0.1:35612 user@myremotehost
user@myremotehost$ uv tool install remoclip
user@myremotehost$ remoclip paste
Hello from remoclip.
user@myremotehost$ echo Hello from $(hostname) | remoclip copy
Hello from myremotehost

Now, back on your local system, paste the contents of your clipboard somewhere. It should contain: 

Hello from myremotehost

You can also use remoclip paste (or remoclip p) and remoclip copy (or remoclip c) locally, similar to the macOS pbcopy and pbpaste commands.

If you want to avoid exposing a port on the remote system, Unix domain sockets are also supported:

$ echo "Hello from my local machine." | remoclip copy
Hello from my local machine.
$ ssh -R /tmp/remoclip.sock:127.0.0.1:35612 user@myremotehost
user@myremotehost$ echo -e "\nclient:\n\tsocket: /tmp/remoclip.sock" >> ~/.remoclip.yaml
user@myremotehost$ remoclip paste
Hello from my local machine.

Unfortunately, SSH does not automatically clean up the socket file when you disconnect your session. You'll need to delete it manually before you initiate a new connection with the same socket:

$ ssh user@myremote rm /tmp/remoclip-user.sock
$ ssh -R /tmp/remoclip-user.sock:127.0.0.1:35612 user@myremotehost

Documentation layout

  • Configuration describes the YAML settings used by both CLIs
  • Usage describes some common setups
  • Server documents the remoclip_server HTTP server
  • Client explains the remoclip client tool
  • Release History lists each released version