eXtended PasteBoard Copy — a drop-in enhancement for macOS pbcopy that supports images.
pbcopy only handles text. xpbc automatically detects whether stdin contains image data and copies it to the clipboard as an image. For plain text, it behaves exactly like pbcopy.
# Copy an image to the clipboard
cat screenshot.png | xpbc
# Copy text (same as pbcopy)
echo "hello" | xpbc
# Paste with Cmd+V in any appcurl -fsSL https://raw.githubusercontent.com/chigichan24/xpbc/main/Scripts/install.sh | bashTo install to a custom directory:
curl -fsSL https://raw.githubusercontent.com/chigichan24/xpbc/main/Scripts/install.sh | bash -s -- /your/custom/pathThe default install directory is ~/.local/bin.
Requires Swift 6.0+ and macOS 13+.
git clone https://github.com/chigichan24/xpbc.git
cd xpbc
make install PREFIX=~/.localxpbc [-pboard {general|ruler|find|font}] [--no-validate] [--help] [--version]
Pipe any data into xpbc via stdin. It automatically detects the format and copies accordingly.
# Images — detected by magic bytes, copied as native format
cat photo.jpg | xpbc
cat document.pdf | xpbc
cat icon.webp | xpbc
# Text — anything that isn't a recognized image format
echo "some text" | xpbc
git diff | xpbc
curl -s https://example.com | xpbc
# Select a specific pasteboard
echo "search term" | xpbc -pboard find| Format | Detection |
|---|---|
| PNG | 8-byte signature |
| JPEG | 3-byte signature |
| GIF | 6-byte signature (87a/89a) |
| TIFF | 4-byte signature (LE/BE) |
| BMP | 2-byte signature |
| WebP | RIFF + WEBP markers |
| HEIC | ftyp + heic brand |
| AVIF | ftyp + avif brand |
| %PDF signature |
Anything that doesn't match a known image signature is copied as text.
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Known error (empty input, input too large, invalid argument, validation failure, pasteboard write failure) |
| 2 | Unexpected error |
| Flag | Description |
|---|---|
-pboard NAME |
Target pasteboard: general (default), ruler, find, or font |
--no-validate |
Skip structural validation of image headers |
-h, --help |
Print usage |
-v, --version |
Print version |
make build # Release build (host architecture)
make build-universal # Release build (arm64 + x86_64)
make test # Run tests
make clean # Clean build artifactsxpbc is designed as a raw-bytes passthrough. It never decodes or renders image data — it only inspects the first few bytes (magic bytes) to determine the format, then writes the raw bytes directly to NSPasteboard. This eliminates exposure to image decoder vulnerabilities (e.g., CVE-2021-30860, CVE-2023-41064).
- No use of
NSImage,CGImageSource, or any image decoding API - Input size is capped at 100 MB (read in 64 KB chunks to prevent OOM)
- stdin-only input (no file path arguments, no path traversal risk)
- Written in memory-safe Swift with no
Unsafepointer usage - Structural validation of image headers is enabled by default (use
--no-validateto skip)
xpbc does not guarantee the safety of clipboard contents. While structural validation checks that image headers are well-formed, it cannot detect:
- Crafted exploit payloads — A structurally valid image (valid headers, correct dimensions) can still contain malicious data that exploits vulnerabilities in the application where you paste it (e.g., heap overflows in image decoders like libwebp, ImageIO).
- Decompression bombs — An image with valid headers but compressed data that expands to an extreme size, causing the paste target to crash with out-of-memory.
- PDF active content — While xpbc blocks PDFs containing known dangerous keywords (
/JS,/JavaScript,/OpenAction,/AA,/Launch), obfuscated or novel techniques may bypass this check.
Do not pipe untrusted data (e.g., curl <untrusted-url> | xpbc) without understanding the risk. The clipboard contents will be processed by whatever application you paste into, and xpbc cannot protect against vulnerabilities in those applications.
See docs/architecture.md for design details.
MIT