skill-paste-image-to-file-tool

name	skill-paste-image-to-file-tool
description	Save clipboard images to numbered PNGs

When to use

• When saving multiple screenshots to files quickly
• When capturing clipboard images with incremental naming
• When batch-saving images from clipboard

paste-image-to-file-tool Skill

Purpose

This skill provides access to the paste-image-to-file-tool CLI tool that watches the clipboard for images and saves them as numbered PNG files (1.png, 2.png, ...) in the current directory.

When to Use This Skill

Use this skill when:

• Saving screenshots or clipboard images to files
• Batch capturing images with auto-incrementing filenames
• Need to save multiple images quickly without naming each one

Do NOT use this skill for:

• Image editing or manipulation
• Converting image formats
• Working with existing image files

CLI Tool: paste-image-to-file-tool

Installation

git clone https://github.com/dnvriend/paste-image-to-file-tool.git
cd paste-image-to-file-tool
uv tool install .

Prerequisites

• Python 3.14+
• uv package manager
• macOS (uses clipboard access)

Quick Start

# Auto mode (default) - polls clipboard, saves new images
paste-image-to-file-tool

# Manual mode - press Enter to save current clipboard
paste-image-to-file-tool -m

# With verbose logging
paste-image-to-file-tool -v

Progressive Disclosure

📖 Core Commands (Click to expand)

Main Command - Save Clipboard Images

Watches clipboard for images and saves them with incremental filenames.

Usage:

paste-image-to-file-tool [OPTIONS]

Options:

Option	Description
-a, --auto	Auto mode: poll clipboard, save on change (default)
-m, --manual	Manual mode: press Enter to save clipboard image
-v, --verbose	Increase verbosity: -v=INFO, -vv=DEBUG, -vvv=TRACE
--telemetry	Enable OpenTelemetry tracing
--version	Show version and exit
--help	Show help message

Examples:

# Auto mode - polls clipboard every 0.5s
cd ~/screenshots
paste-image-to-file-tool
# Output:
# waiting for paste (auto mode, Ctrl+C to stop)
# writing 1.png
# waiting for paste
# writing 2.png

# Manual mode - press Enter to capture
paste-image-to-file-tool -m
# Output:
# waiting for paste (manual mode, press Enter to save, Ctrl+C to stop)
# <Enter>
# writing 1.png
# waiting for paste

# With verbose logging
paste-image-to-file-tool -vv

Behavior:

• Saves images in current directory
• Continues from next available number if files exist (e.g., if 1.png exists, starts at 2.png)
• Auto mode detects clipboard changes via image hash comparison
• Press Ctrl+C to stop

---

completion - Shell Completion

Generate shell completion scripts for bash, zsh, or fish.

Usage:

paste-image-to-file-tool completion generate SHELL

Examples:

# Generate for bash
eval "$(paste-image-to-file-tool completion generate bash)"

# Generate for zsh
eval "$(paste-image-to-file-tool completion generate zsh)"

# Generate for fish
paste-image-to-file-tool completion generate fish > \
    ~/.config/fish/completions/paste-image-to-file-tool.fish

⚙️ Advanced Features (Click to expand)

Multi-Level Verbosity Logging

Control logging detail with progressive verbosity levels. All logs output to stderr.

Flag	Level	Output
(none)	WARNING	Errors and warnings only
-v	INFO	+ High-level operations
-vv	DEBUG	+ Detailed info, image hashes
-vvv	TRACE	+ Library internals

Examples:

# INFO - see operations
paste-image-to-file-tool -v
# [INFO] Starting paste watcher in /Users/you/screenshots

# DEBUG - see detailed info
paste-image-to-file-tool -vv
# [INFO] Starting paste watcher in /Users/you/screenshots
# [DEBUG] Initial clipboard has image, hash: abc123
# [DEBUG] Saved image to /Users/you/screenshots/1.png

---

OpenTelemetry Observability

Enable tracing for observability.

# Via CLI flag
paste-image-to-file-tool --telemetry

# Via environment variable
export OTEL_ENABLED=true
paste-image-to-file-tool

🔧 Troubleshooting (Click to expand)

Common Issues

Issue: Command not found

# Verify installation
paste-image-to-file-tool --version

# Reinstall if needed
cd paste-image-to-file-tool
uv tool install . --reinstall

Issue: No image in clipboard

• Ensure you've copied an image (screenshot or Cmd+C on image)
• Text in clipboard is ignored
• Try -vv flag to see debug info

Issue: Files not saving

• Check write permissions in current directory
• Try with -vv to see detailed errors
• Ensure you're in the directory where you want files saved

Getting Help

paste-image-to-file-tool --help

Exit Codes

• 0: Success (stopped with Ctrl+C)
• 1: Error (permission denied, invalid options)

Best Practices

1. Use auto mode for rapid capture: Just copy screenshots, they save automatically
2. Use manual mode for selective capture: Control exactly when to save
3. Check existing files first: Tool continues numbering from next available
4. Use verbose mode for debugging: -vv shows clipboard state

Resources

• GitHub: https://github.com/dnvriend/paste-image-to-file-tool