clipboard

Documentation

Overview

Package clipboard pushes a text payload onto the host's system clipboard. Two transports are tried in tandem:

• OSC 52 — an ANSI escape that asks the terminal emulator itself to update the clipboard. Honored by iTerm2, kitty, WezTerm, Alacritty, Ghostty, recent xterm, and tmux (with `allow-passthrough`). Crucially, it works over SSH because the escape travels back through the same TTY the user is sitting in.
• Native shellout — pbcopy / wl-copy / xclip / xsel / clip.exe. Covers the terminals that don't honor OSC 52 (macOS Terminal.app, Warp). Does NOT work over SSH; runs on the remote host.

Code ported verbatim from the maintainer's secguard prototype (./secguard/main.go), with one refinement: OSC 52 is emitted to the supplied io.Writer (caller passes stderr or /dev/tty) instead of stdout, so it never leaks into piped output like `--json | jq`.

Index

• func EmitOSC52(w io.Writer, payload string) error
• func NativeCopy(payload string) error
• type Result
  • func Copy(w io.Writer, payload string) Result
  • func (r Result) MethodLabel() string

Functions

func EmitOSC52

func EmitOSC52(w io.Writer, payload string) error

EmitOSC52 writes an OSC 52 escape sequence to w that places payload on the system clipboard of the terminal emulator on the other end of w. Caller controls the destination: stderr keeps the escape out of redirected stdout; /dev/tty bypasses any redirection entirely.

func NativeCopy

func NativeCopy(payload string) error

NativeCopy shells out to the platform clipboard tool. Returns nil on success. The Linux branch tries wl-copy → xclip → xsel in order, matching what's typically installed on Wayland / X11 hosts.

Types

type Result

type Result struct {
	OSC52  bool
	Native bool
}

Result reports which transports succeeded for a single Copy call. OSC52 is true when the escape sequence was written to the supplied io.Writer without error (the terminal may still ignore it, but that's invisible to us). Native is true when the platform tool exited zero. Both can be true; at least one is expected on a supported environment.

func Copy

func Copy(w io.Writer, payload string) Result

Copy emits the OSC 52 escape to w *and* invokes the native tool, returning a Result that records which transports succeeded. Caller decides what to do when both fail (e.g. headless Linux without wl-clipboard / xclip / xsel installed AND a terminal that ignores OSC 52).

func (Result) MethodLabel

func (r Result) MethodLabel() string

MethodLabel summarizes which transports succeeded as a short string for user-facing hints. Returns "" when neither succeeded so callers can branch on the empty case.