On machines without a desktop session, Clipshot runs in CLI mode.

Starting the daemon

Start the background sync daemon:

clipshot daemon --port 19231

Useful optional flags include:

  • --peers — comma-separated list of peer addresses (host:port)
  • --port — P2P port (default 19231)
  • --paused — start with sync paused
  • --http-port — HTTP API port (default 15282). This flag only changes the port: in daemon mode the HTTP REST API always starts (src/cli/daemon_entry.rs, http_port.unwrap_or(runtime_defaults::HTTP_PORT)), so the API is on whether or not you pass the flag. It binds 127.0.0.1 and is unauthenticated — keep it localhost-only and do not override the bind with CLIPSHOT_HTTP_BIND=0.0.0.0 on an untrusted network.
  • --force — run even if a GUI instance is active (the primary Windows daemon deployment flag)
  • --password — password for incoming peer connections
  • --iroh — enable iroh transport (QUIC + NAT traversal; requires the iroh feature)
  • --hub-url
  • --group-token
  • --relay-url

Pairing via CLI

Generate a 6-digit pair code on this device:

clipshot pair
#   Pair code: 482 917
#   Valid for 5 minutes.
#
#   Waiting for other device.......
#   ✓ Device connected!
#   ✓ Confirmation digits: 7392
#     (verify they match on both devices)

The CLI polls for the other device to join (up to 5 minutes). Once connected, 4 confirmation digits are displayed — compare them to verify no MITM.

Join with a code from another device:

clipshot pair 482917
#   ✓ Pair join accepted
#   ✓ Confirmation digits: 7392

No account required; pair works via Portal relay or local mDNS automatically. The CLI communicates with the running daemon via DaemonClient IPC (localhost HTTP API).

Note: clipshot pair still accepts the legacy --local and --addr flags for backwards compatibility with older guides, but they are deprecated no-ops in pair-v2 — they are parsed and ignored. The single 6-digit code flow above already covers both LAN and internet pairing, so neither flag is needed.

Account setup via CLI

Set up a new account without a pair code. This creates a session on the portal, opens your browser for login or registration (Google OAuth supported), and polls until you authorize the device. The group token is saved automatically.

clipshot setup

If you already have a group token, clipshot setup tells you so and exits. To switch groups, use clipshot pair CODE instead.

Useful commands

Generate a share link for this node:

clipshot share-uri
clipshot share-uri --port 19231 --ttl 3600 --name mybox
clipshot share-uri --password   # mark the node as password-protected in the URI

--ttl is the link lifetime in seconds. The default is 1800 (30 minutes) and the accepted range is 1..86400 (up to 24 hours); values outside it are rejected by clap. --port defaults to 19231. --name sets the node name (defaults to the hostname or a random name). --password is a flag (default off) that includes the password requirement in the generated link, so the joining device knows an auth code is needed. The URI carries the expiry plus an HMAC signature, so an expired link cannot be used even if it leaks.

Add a peer from a Clipshot link:

clipshot add-uri 'clipshot://node/...'

Copy text back to your local terminal clipboard over SSH:

clipshot push "hello"

Show recent sync history:

clipshot history
clipshot history --filter images --limit 10

Filters: all, files, images, text. Default limit is 20 (the HTTP API default is 100; the CLI uses a smaller default for terminal readability).

Check for or install updates:

clipshot update
clipshot update --check

clipshot update checks clipshot.cc for a newer release matching your platform. With --check it only reports availability without installing.

Other useful CLI commands:

clipshot status
clipshot pause
clipshot resume
clipshot toggle
clipshot doctor
clipshot doctor --fix
clipshot list-peers
clipshot add-peer alice 192.168.1.5:19231
clipshot remove-peer alice
clipshot retry-transfer /path/to/file

clipshot doctor runs read-only environment checks. Adding --fix repairs detected environment issues (disables a wrong/duplicate service and fixes autostart) instead of only reporting them; an intentional --force daemon service is left untouched.

The full check list (run_all_checks() in src/doctor/mod.rs), in output order:

Check What it verifies
Binary the running binary and its version
Config config file presence and parseability
Clipboard platform clipboard tooling (xclip / wl-clipboard / pngpaste)
Sync dir ~/.clipshot/sync/ exists and is writable
Daemon a daemon is running and reachable
Peers configured peers and their connection state
Peer reachability per-peer verdict from health-Pong freshness; mesh-only (indirect) liveness warns rather than fails
Launchers systemd/launchd unit audit — stale debug-binary autostart, duplicate units, missing restart caps (reported, never auto-applied without --fix)
Crash diagnostics collected crash evidence (backtraces, breadcrumbs, heartbeat witness)
Hub portal portal configuration and reachability
External DNS libc / DoH-fallback / IP-cache probe matrix; warns when system DNS is broken and the hub is running on the DoH fallback, or when only an unverified cached IP is left
Hub WS hub WebSocket staleness — a connection that is nominally up but no longer fresh
Home relay relay attach state; warns when the relay is configured but stuck connecting
Endpoint workers iroh endpoint worker liveness (dead-worker detection)
Projection contradictions between the daemon’s own projections (e.g. “reachable but not syncing”)
Peer removal pending remove-intents and stale local tombstones that have not converged

Settings management

View or change settings from the command line:

clipshot config show
clipshot config get listen_port
clipshot config set max_file_size_mb 100

Note the asymmetry with peers: config has only show, get, and set — there is no clipshot config list. Use clipshot config show to print all current settings. (peers, by contrast, does have a list subcommand.)

Manage saved peers:

clipshot peers list
clipshot peers add bob 10.0.0.5:19231
clipshot peers remove 10.0.0.5:19231

Legacy SSH/SCP commands

Clipshot retains several legacy commands from its original SSH/SCP-based clipboard sharing design. These still work but are not the primary workflow:

# Send clipboard image to a remote server via SCP
clipshot send user@server
clipshot send user@server:/custom/path

# Save clipboard image to a local file
clipshot save                        # saves into the default directory /tmp/clipshot
clipshot save --dir ~/screenshots     # override the output directory
clipshot save --copy-path            # copy the path to the clipboard instead of printing it
clipshot save --watch                # auto-save images and replace with path
clipshot save --watch --interval 250 # watch-mode poll interval in ms (default 500, range 1..3600000)

# Bidirectional clipboard sync with a remote machine
clipshot sync user@server
clipshot sync user@server --daemon

# Run as sync agent (stdin/stdout protocol, used by remote side)
clipshot agent

For most users, the P2P daemon with clipshot pair is the recommended approach.

Shell completions

Generate completion scripts for your shell:

clipshot completions bash > ~/.local/share/bash-completion/completions/clipshot
clipshot completions zsh > ~/.zfunc/_clipshot
clipshot completions fish > ~/.config/fish/completions/clipshot.fish

systemd / launchd auto-start

Install Clipshot as a background service that starts on boot:

clipshot service install --port 19231 --http-port 15282

Manage it with:

clipshot service status
clipshot service logs
clipshot service uninstall

Note: uninstall is a subcommand of service, not a standalone top-level command. Use clipshot service uninstall (not clipshot uninstall) to remove the service and stop the daemon.

Notes:

  • Linux uses a systemd user service (~/.config/systemd/user/clipshot.service) with Restart=always and loginctl enable-linger
  • macOS uses a launchd agent (~/Library/LaunchAgents/cc.clipshot.daemon.plist) with RunAtLoad and KeepAlive
  • the one-line installer sets this up automatically (skip with --no-autostart)
  • a PID lock (~/.config/clipshot/daemon.lock) prevents duplicate daemon instances
  • auto-start is enabled by default — toggle it in Settings or with clipshot service uninstall

Back to top

Clipshot — P2P clipboard sync across your devices.

This site uses Just the Docs, a documentation theme for Jekyll.