clippy

README

Clippy 📎

Copy files from your terminal that actually paste into GUI apps. No more switching to Finder.

macOS only - built specifically for the Mac clipboard system.

Why Clippy?

pbcopy copies file contents, but GUI apps need file references. When you pbcopy < image.png, you can't paste it into Slack or email - those apps expect files, not raw bytes. Your only option is to leave the terminal and drag files from Finder.

Clippy bridges this gap by detecting what you want and using the right clipboard format:

# Copy files as references (for pasting into GUI apps)
clippy report.pdf         # ⌘V into any app - uploads the file
clippy *.jpg             # Multiple files at once

# Copy piped/streamed data as files
curl -s https://picsum.photos/300 | clippy       # Download → clipboard as file
cat archive.tar.gz | clippy                      # Pipe → paste as file

# Smart detection for text files
clippy notes.txt          # Copies text content
echo "Hello" | clippy     # Works like pbcopy for piped text

Stay in your terminal. Copy anything. Paste anywhere.

Key Features

• Smart detection: Automatically decides whether to copy content or file references
• File support: clippy document.pdf copies the PDF as a file (not its raw content)
• Multiple files: clippy *.jpg copies all JPGs as file references
• Binary streaming: Pipe images/PDFs and paste them as files in other apps
• Text handling: Text files are copied as content, just like pbcopy
• Automatic cleanup: Temporary files from piped data are cleaned up intelligently
• Library support: Use clippy as a Go library in your own applications
• Companion tool: Includes pasty for intelligent pasting from clipboard

Installation

Homebrew (Recommended)

brew install neilberkman/clippy/clippy

Build from Source

# Clone and build
git clone https://github.com/neilberkman/clippy.git
cd clippy
go build -o clippy ./cmd/clippy
sudo mv clippy /usr/local/bin/

# Or use go install
go install github.com/neilberkman/clippy/cmd/clippy@latest

Usage

Basic Usage

# Copy a file
clippy myfile.txt           # Text content
clippy photo.jpg            # File reference

# Pipe data
echo "Hello, World!" | clippy
cat image.png | clippy

Flags

clippy --verbose file.txt   # Show success messages
clippy -v file.txt          # Short version
clippy --help               # Show usage and examples
clippy -h                   # Short version
clippy --version            # Show version information

Configuration

Create ~/.clippy.conf for persistent settings:

# Enable verbose output by default
verbose = true

# Disable automatic cleanup of temporary files
cleanup = false

# Use custom directory for temporary files
temp_dir = /path/to/custom/temp

Features

Smart Detection

• Text files (.txt, .md, code files) → copies actual text
• Binary files (images, PDFs, zips) → copies as file reference
• Works with both file arguments and piped input

Silent by Default

• No output unless --verbose flag is used
• Perfect for scripts and automation
• Errors still shown on stderr

Automatic Cleanup

• Temporary files created for piped binary data are managed automatically
• Background process scans for orphaned temp files on each run
• Checks if temp files are still referenced in clipboard before removal
• Non-blocking - cleanup happens while main operation proceeds

How It Works

1. File Mode (when you pass a filename):

   • Detects MIME type using content analysis (not just file extension)
   • Text files → reads content, copies as text
   • Other files → copies file path reference

2. Stream Mode (when you pipe data):

   • Detects MIME type from content
   • Text data → copies as text
   • Binary data → saves to temp file, copies reference

3. MIME Type Detection:

   • Uses content-based detection, not file extensions
   • Anything with MIME type text/* is treated as text
   • This means .log, .conf, .json, etc. are correctly identified as text
   • Binary files are identified by their actual content (e.g., PNG magic bytes)

Examples

# Copy code file as text
clippy main.go

# Copy PDF as file reference
clippy report.pdf

# Copy command output
ls -la | clippy

# Copy image from curl
curl -s https://picsum.photos/300 | clippy

# Silent operation for scripts
clippy data.txt && echo "Copied!"

# Verbose mode to see what happened
clippy -v recording.mp4

Pasty - Intelligent Clipboard Pasting

Pasty is clippy's companion tool for intelligent pasting from the clipboard:

# Paste clipboard content to stdout
pasty

# Paste to a specific file
pasty output.txt

# Paste with verbose output
pasty -v

# Copy files from clipboard to directory
pasty /path/to/destination/

How it works:

• Text content: Pastes directly to stdout or file
• File references: Lists file paths or copies files to destination
• Smart detection: Automatically handles text vs file clipboard content

Examples:

# Copy some text and paste it
echo "Hello World" | clippy
pasty  # Outputs: Hello World

# Copy a file and paste to directory
clippy document.pdf
pasty ~/Desktop/  # Copies document.pdf to ~/Desktop/

# Copy a file and list its path
clippy image.png
pasty  # Outputs: /path/to/image.png

Testing

# Run tests
go test -v ./...

Using as a Library

Clippy can be used as a Go library in your own applications:

go get github.com/neilberkman/clippy

High-Level API

import "github.com/neilberkman/clippy"

// Smart copy - automatically detects text vs binary files
err := clippy.Copy("document.pdf")

// Copy multiple files as references
err := clippy.CopyMultiple([]string{"image1.jpg", "image2.png"})

// Copy text content
clippy.CopyText("Hello, World!")

// Copy data from reader (handles text/binary detection)
reader := strings.NewReader("Some content")
err := clippy.CopyData(reader)

// Copy from stdin
err := clippy.CopyData(os.Stdin)

// Get clipboard content
text, ok := clippy.GetText()
files := clippy.GetFiles()

Low-Level Clipboard API

import "github.com/neilberkman/clippy/pkg/clipboard"

// Direct clipboard operations
clipboard.CopyText("Hello")
clipboard.CopyFile("/path/to/file.pdf")
clipboard.CopyFiles([]string{"/path/to/file1.jpg", "/path/to/file2.png"})

// Read clipboard
text, ok := clipboard.GetText()
files := clipboard.GetFiles()

The high-level API provides the same smart detection and temp file management as the CLI tool, while the low-level API gives you direct access to clipboard operations without any automatic behavior.

Alternatives

gcopy

gcopy is a cross-platform clipboard tool that also works with files. Key differences:

• Cross-platform: gcopy works on Linux/Windows, clippy is macOS-only
• Implementation: clippy uses native macOS APIs, gcopy uses AppleScript
• File handling: clippy copies file references (like Finder), gcopy copies file contents - this makes clippy work for pasting images/PDFs into apps, while gcopy doesn't
• Multiple files: clippy supports *.jpg, gcopy handles one file at a time
• Cleanup: clippy auto-cleans temp files, gcopy doesn't

Choose gcopy if you need cross-platform support. Choose clippy for better macOS integration and multi-file support.

Why "Clippy"?

Because it's a helpful clipboard assistant that knows what you want to do! 📎

License

MIT

Documentation

Overview

Package clippy provides smart clipboard operations for macOS. It automatically detects whether to copy file content or file references based on MIME type detection.

Example

package main

import (
	"fmt"
	"log"
	"strings"

	"github.com/neilberkman/clippy"
)

func main() {
	// Copy text to clipboard
	clippy.CopyText("Hello, World!")

	// Copy a file (text files copy content, others copy reference)
	err := clippy.Copy("document.pdf")
	if err != nil {
		log.Fatal(err)
	}

	// Copy multiple files
	err = clippy.CopyMultiple([]string{"image1.jpg", "image2.png"})
	if err != nil {
		log.Fatal(err)
	}

	// Copy from a reader (e.g., from a download)
	reader := strings.NewReader("Some text content")
	err = clippy.CopyData(reader)
	if err != nil {
		log.Fatal(err)
	}

	// Get clipboard content
	if text, ok := clippy.GetText(); ok {
		fmt.Printf("Clipboard text: %s\n", text)
	}

	// Get files from clipboard
	files := clippy.GetFiles()
	for _, file := range files {
		fmt.Printf("File in clipboard: %s\n", file)
	}
}

Index

• func Copy(path string) error
• func CopyData(reader io.Reader) error
• func CopyDataWithTempDir(reader io.Reader, tempDir string) error
• func CopyMultiple(paths []string) error
• func CopyText(text string)
• func GetFiles() []string
• func GetText() (string, bool)

Examples

• Package
• Copy
• CopyText
• GetText

Functions

func Copy

func Copy(path string) error

Copy intelligently copies a file to clipboard. Text files copy their content, binary files copy file references.

Example

package main

import (
	"log"

	"github.com/neilberkman/clippy"
)

func main() {
	// Copy a single file intelligently
	err := clippy.Copy("report.pdf")
	if err != nil {
		log.Printf("Failed to copy file: %v", err)
	}
}

func CopyData

func CopyData(reader io.Reader) error

CopyData copies data from a reader to clipboard. Text data is copied as text, binary data is saved to a temp file.

func CopyDataWithTempDir

func CopyDataWithTempDir(reader io.Reader, tempDir string) error

CopyDataWithTempDir is like CopyData but allows specifying a custom temp directory.

func CopyMultiple

func CopyMultiple(paths []string) error

CopyMultiple copies multiple files to clipboard as file references.

func CopyText

func CopyText(text string)

CopyText copies text content to clipboard.

Example

package main

import (
	"github.com/neilberkman/clippy"
)

func main() {
	// Copy text to clipboard
	clippy.CopyText("Hello from clippy library!")
}

func GetFiles

func GetFiles() []string

GetFiles returns file paths from clipboard.

func GetText

func GetText() (string, bool)

GetText returns text content from clipboard.

Example

package main

import (
	"fmt"

	"github.com/neilberkman/clippy"
)

func main() {
	// Get text from clipboard
	if text, ok := clippy.GetText(); ok {
		fmt.Printf("Clipboard contains: %s\n", text)
	} else {
		fmt.Println("No text in clipboard")
	}
}