clipush

clipush reads an image or file reference from the local clipboard, uploads it to a remote host via scp, and replaces the clipboard contents with the resulting remote file path. The next paste drops a path the remote tool can read directly off disk.

It shells out to the system ssh and scp binaries. All SSH configuration (~/.ssh/config aliases, Tailscale hostnames, ProxyCommand, identity files, agent forwarding) is inherited transparently — clipush handles no credentials.

Requirements

• Go 1.22+
• ssh and scp on PATH
• Clipboard tool for the local OS:

OS	Tool
Linux (Wayland)	wl-clipboard (wl-paste, wl-copy)
Linux (X11)	xclip
macOS	pngpaste (brew install pngpaste)
Windows	PowerShell (built-in)

Run clipush doctor to check which tools are present.

Quick Start

go build -o clipush .
sudo mv clipush /usr/local/bin/

See available SSH hosts:

clipush hosts

Add a profile:

clipush add home --host meeseekbox-01 --dir ~/clip-images --default

Copy a screenshot or file, then push:

clipush          # uses the default profile
clipush dev      # uploads via "dev" and makes it the new default

Paste into the remote SSH session. The clipboard holds the absolute remote path.

Subcommands

Command	Description
clipush [profile] [flags]	Read clipboard, upload, write remote path back to clipboard. Naming a profile makes it the new default.
clipush add <name> --host <alias> [flags]	Add or update a profile.
clipush remove <name>	Delete a profile.
clipush use <name>	Switch the default profile without pushing.
clipush list	Show configured profiles (* marks the default).
clipush hosts	List Host aliases from ~/.ssh/config.
clipush history [--limit N] [--all] [clear]	Show recent transfers or clear the log.
clipush doctor	Check that required tools are installed.
clipush version	Print version.

Flags

Flag	Default	Description
--host	(required for add)	SSH host alias from ~/.ssh/config
--dir	~/clip-images	Remote directory to upload into
--at	false	Prefix the path with @ (Claude Code file-reference syntax)
--quote	false	Wrap the path in double quotes
--keep	false	Keep the local temp file after upload
--profile	(none)	Explicit profile name (alternative to positional form)
--config	~/.config/clipush/config	Config file path

Environment variables

Variable	Description
CLIPUSH_HOST	SSH host to use when no profile or --host is given
CLIPUSH_REMOTE_DIR	Remote directory when no profile or --dir is given

Clipboard sources

clipush checks clipboard sources in priority order:

1. File references (Nautilus, Dolphin, Finder). Copied files are uploaded under their original names. Multiple files copied at once produce multiple space-separated paths.

2. Raw image bytes (screenshot tools). Written to a temp file named clip-<timestamp>.<ext>, uploaded, then deleted unless --keep is set.

Config file

~/.config/clipush/config is a hand-editable INI-style file:

default = home

[home]
host = meeseekbox-01
remote_dir = ~/clip-images
at_syntax = false
quote = false
keep = false

[dev]
host = dev-server
remote_dir = /tmp/clip
at_syntax = true
quote = false
keep = false

History

Every push is logged to ~/.config/clipush/history.jsonl (one JSON object per line).

clipush history            # last 20 transfers
clipush history --limit 50 # last 50
clipush history --all      # everything
clipush history clear      # wipe the log

Limitations

• macOS multi-file Finder copies use a best-effort AppleScript path; copy one file at a time if it returns nothing usable.
• clipush hosts does not follow Include directives in ~/.ssh/config.

Development

go test ./...  # run all tests
go build ./... # compile

License

MIT

Inspiration

clipssh by Samuel Lawrentz — the original shell-script tool that proved this workflow. clipush is a Go reimplementation with profiles, multi-file support, sticky defaults, and platform-native clipboard handling.