wsl-clip

Smart Clipboard Bridge for WSL2

wsl-clip is a clipboard utility that bridges Linux (WSL2) and Windows. It detects content types to provide the appropriate clipboard format:

• Text: Copies clean, safe text (pasted into editors).
• Images: Copies the bitmap (pasted into Slack/Paint).
• Files: Copies the file object (pasted into Explorer/Outlook).
• Paths: Copies the translated Windows path (pasted into File Dialogs).

It is designed to be a drop-in replacement for clip.exe with added intelligence and safety features.

Architecture & Features

• Smart Detection: Analyzes file headers (magic bytes) and extensions to distinguish between text, images (PNG, JPG), and binary assets (PDF, ZIP, 3D models).
• Streaming (Low Memory): Uses a buffered reader to process text line-by-line. This allows piping large logs (e.g., cat huge.log | wsl-clip) without loading the entire file into memory.
• Sanitization:
  • Pastejacking Protection: Strips potentially dangerous hidden control characters.
  • ANSI Stripping: Automatically removes terminal color codes from piped output.
  • Line Endings: Options to normalize to Windows (CRLF) or preserve Linux (LF) endings.
• Bridge Mode (Experimental): TCP/UDP listener stubs for future clipboard forwarding; bridge connect currently sends a small test payload.

Installation

From Source

Requires a Rust toolchain.

git clone https://github.com/yourusername/wsl-clip
cd wsl-clip
just build
# Or: cargo install --path .

Ensure ~/.cargo/bin is in your $PATH.

Usage

1. Smart Mode (Default)

The tool attempts to infer the best format based on the input file.

# Copy an image (Bitmap)
wsl-clip screenshot.png

# Copy a PDF (File Object)
wsl-clip invoice.pdf

# Copy source code (Text)
wsl-clip src/main.rs

# Copy multiple files (File Object Drop List)
wsl-clip *.png

2. Text Piping

Reads from standard input. Useful for capturing command output.

# Copy directory listing (ANSI colors stripped by default)
ls -la --color | wsl-clip

# Copy with Markdown wrapping
wsl-clip src/lib.rs --code

3. Explicit Modes

Force a specific behavior to override detection.

# Force copy as a file object (e.g., to attach a source file to an email)
wsl-clip file src/main.rs

# Force copy as an image
wsl-clip img logo.png

# Copy the translated Windows path string (e.g., "\\wsl.localhost\..."')
wsl-clip path document.pdf

4. Bridge (TCP/UDP Transport, Experimental)

Experimental stub commands; bridge connect currently sends a fixed test payload rather than piping real data.

Listener (Host):

# Listen on TCP localhost:8121
wsl-clip bridge listen --mode tcp --bind 127.0.0.1:8121

Client (Container/Remote):

# Send clipboard data to the listener
wsl-clip bridge connect --mode tcp --to 127.0.0.1:8121

See wsl-clip bridge listen --daemon-help for background daemon options.

Configuration Flags

Development

Testing

The project includes unit tests and integration tests. The integration tests use a mock environment to simulate clipboard operations without affecting the system clipboard.

# Run all tests
just test
# Or
# cargo test

Project Structure

• wsl-clip: Thin CLI wrapper.
• wsl_clip_core: Core logic library (crate: wsl-clip-core, module path: wsl_clip_core).

License

MIT