skill-paste-image-to-file-tool

What this skill does

# 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

```bash
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](https://github.com/astral-sh/uv) package manager
- macOS (uses clipboard access)

### Quick Start

```bash
# 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

<details>
<summary><strong>📖 Core Commands (Click to expand)</strong></summary>

### Main Command - Save Clipboard Images

Watches clipboard for images and saves them with incremental filenames.

**Usage:**
```bash
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:**
```bash
# 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:**
```bash
paste-image-to-file-tool completion generate SHELL
```

**Examples:**
```bash
# 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
```

</details>

<details>
<summary><strong>⚙️ Advanced Features (Click to expand)</strong></summary>

### 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:**
```bash
# 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.

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

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

</details>

<details>
<summary><strong>🔧 Troubleshooting (Click to expand)</strong></summary>

### Common Issues

**Issue: Command not found**
```bash
# 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

```bash
paste-image-to-file-tool --help
```

</details>

## 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