Hotkeys not working (macOS)

If Cmd+Shift+S (toggle sync) or Cmd+B (paste path) do nothing on macOS, the cause is almost always a missing macOS permission.

Check the PermissionBanner first

If any permission is missing, an amber banner appears at the top of the Clipshot window. Click the banner to open System Settings directly.

Grant permissions manually:

  1. System Settings → Privacy & Security → Input Monitoring
    • Click +, navigate to /Applications/Clipshot.app, and add it.
    • Required for: all global hotkeys (Cmd+Shift+S, Cmd+B).
  2. System Settings → Privacy & Security → Accessibility
    • Click +, navigate to /Applications/Clipshot.app, and enable the toggle.
    • Required for: the paste simulation step in Cmd+B.
  3. Restart Clipshot after granting either permission.

After an app update:

macOS invalidates TCC permission entries when the app binary changes. Clipshot detects this on startup and resets the stale entries automatically — you may see the permission prompt again after an update. Re-grant the permissions and restart.

Headless mode:

Permissions are only required in the desktop GUI. clipshot daemon (headless) does not need Input Monitoring or Accessibility.

No peers connected

Check these first:

  • make sure at least one other device is online
  • verify both devices use the same Group Token
  • open Settings → Account and confirm the portal is not badged Disconnected / Not configured (the connection state is also spelled out as Hub Status under Settings → Advanced → Diagnostics)
  • open Devices and use Add device (with no devices yet the empty state also offers Scan LAN, which opens the same dialog)
  • if you are on different networks, use Pair Code or the hub instead of LAN scan
  • if both devices share a VPN (Tailscale, WireGuard, ZeroTier), Clipshot detects VPN interfaces automatically — no relay or extra config needed

If needed, run:

clipshot doctor

Beyond the obvious binary/config/clipboard/daemon/peers/hub checks, doctor also reports External DNS (libc vs DoH fallback vs cached IP), Hub WS staleness, Home relay attach state, Endpoint workers liveness, Peer reachability, Projection contradictions, Peer removal convergence, Launchers, and Crash diagnostics — so a peer that looks online but never syncs usually has a warning here. The full list is in the CLI reference.

Sync paused

Signs:

  • the toggle button in the header reads Resume and is tinted amber
  • tray icon turns red (static red icon)
  • Home shows a Sync is paused strip under the status line

How to resume:

  • click Resume in the header
  • click Resume in the strip on Home
  • press the sync toggle hotkey (Cmd+Shift+S on macOS, Ctrl+Shift+S on Windows/Linux)
  • use Toggle Sync from the tray or Dock menu

Clipboard not syncing

Common causes:

  • no connected peers
  • sync is paused
  • Linux clipboard tools are missing
  • the copied item is larger than your max file size

Platform checks:

  • Linux X11: install xclip
  • Linux Wayland: install wl-clipboard
  • macOS: install pngpaste for reliable image syncing

Large files not arriving

Try this:

  • increase Settings → Sync → Max file size
  • adjust Settings → Advanced → Transfer timeouts
  • keep both devices online until the transfer finishes
  • retry a failed transfer from the feed on Home (a failed item you sent carries a Retry act)

A transfer looks stuck

What the feed on Home shows now (there is no separate Transfers page — /transfers opens Home):

  • one row per item and device, for the whole attempt — a drop mid-item does not start a second row; the row stays in progress while the sender resumes, and its byte count never goes backwards
  • for items of 8 MiB and more that resume is automatic (up to three times within the item’s time budget of 15 s + 5 s per MiB); a row that has not moved for longer than that budget is not going to move on its own
  • on the receiving device the row names whichever device finished the item
  • failed means the other device could not be reached at all — that is a link problem, not a transfer problem; the item will be offered again on reconnect, or use Retry
  • a row for a phone that is not moving usually means the phone is asleep: the Devices page shows it as Asleep, and it catches up when it wakes

Then run:

clipshot doctor

Its Peer reachability check tells the cases apart: a peer that is reachable but not syncing (outbound transport failing, quarantined), one that is responsive but busy (a receiver backlog — wait, do not reconnect), and a phone that is asleep (no action).

Phone did not receive the clipboard

On a phone an arrival is offered, not written: tap Copy / Copy path on the offer bar or on the Android notification, or bring Clipshot to the front (the newest offer is applied if it is newer than your own last copy). To send from the phone use Share → Clipshot; the phone’s own clipboard is never read. See Phones and tablets.

A group path arrived as text (Universal Clipboard)

After a share, your iPhone/iPad holds the item’s group path (~/.clipshot/sync/<name>) on its pasteboard, and Apple’s Universal Clipboard may carry that text to your Mac; the Mac’s daemon recognises a lone group path as a reference to a file every node already has and does not broadcast it (the text stays on the Mac clipboard for you to paste). A path typed inside a sentence is ordinary text and still syncs.

Peer shows ‘Limited’

This means the device exists, but your current Lite plan cannot keep it active.

What to do:

  • remove or disconnect an old device
  • click Activate on the device you want to use now
  • or upgrade to Pro

If a device that WAS in your Pro group suddenly shows all its peers as Limited/Offline while sync still works, it has switched groups (clipshot doctor → Projection names the hidden peers): restore the group token in Settings → Sign in / switch group, or re-pair with that device generating the code — a restart changes nothing.

Where are logs

Useful places to check:

  • Linux service logs:
clipshot service logs
journalctl --user -u clipshot -n 200
  • Linux service status:
systemctl --user status clipshot
  • macOS launch agent logs from the installer:
~/Library/Logs/clipshot.log
~/Library/Logs/clipshot.error.log

Data & config paths

Settings: ~/.config/clipshot/settings.toml

This is the main settings file on Linux and in the installer-based setup.

On some platforms, Clipshot may use the OS-equivalent config directory for the same file.

Sync files: ~/.clipshot/sync/

This folder stores synced files and clipboard assets.

Peers: ~/.config/clipshot/peers.toml

This file stores known/saved peers.

HMAC secret: ~/.config/clipshot/hmac_secret

This secret is used to validate Clipshot share links.

Iroh not starting (no peers connecting)

If you see Cannot connect to iroh peer: iroh not started in logs, check that enable_iroh is not set to false in your settings.toml. The default is true — if the field is missing, iroh starts normally. Only set it explicitly if you want to disable iroh transport.

# settings.toml — remove this line or set to true
enable_iroh = true

Back to top

Clipshot — P2P clipboard sync across your devices.

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