Language: English | Italiano

See also: Security Policy (EN) · Politica di Sicurezza (IT)

Paste images from your clipboard directly into the terminal as file paths — ready for any CLI coding assistant.

Press a keyboard shortcut, and the clipboard image is saved as a temporary file with its path automatically typed into the active terminal window.

CLI coding assistants like Claude Code, Aider, Gemini CLI, and others accept image files as input but have no native way to paste images from the system clipboard. This tool bridges that gap: copy an image, press the shortcut, and the file path is typed into the terminal — ready to send.

Works with any CLI tool that accepts file paths as input.

# 1. Copy an image (screenshot, browser image, etc.)
# 2. Focus on the terminal running your coding assistant
# 3. Press Ctrl+Shift+V
# 4. The path gets typed automatically:

/tmp/paste_image_20260309_143022_a1b2c3.png

The filename includes a timestamp and a random suffix generated by mktemp for security and uniqueness.

• Global GNOME keyboard shortcut (configurable)
• Automatic image type detection (PNG/JPEG)
• Secure atomic file creation via mktemp with 0600 permissions
• Window focus management (remembers which terminal had focus)
• Desktop notifications for success and errors (with zenity fallback)
• Automatic cleanup of temporary files older than 7 days
• Log rotation with race-condition-safe writes via flock
• Cross-distro dependency installation (apt/dnf/pacman)
• Version flag support (--version, -v)
• Comprehensive test suite (50+ test cases)
• ShellCheck validated code

Supported image formats: PNG, JPEG.

git clone https://github.com/user/cli-image-paste.git
cd cli-image-paste
bash install.sh

The installer handles everything:

1. Detects and installs missing dependencies (xclip, xdotool, libnotify-bin)
2. Copies the script to ~/.local/bin/paste-image
3. Adds ~/.local/bin to your PATH if needed
4. Configures a GNOME global keyboard shortcut (default: Ctrl+Shift+V)
5. Verifies the gsd-media-keys service is running

You'll be prompted to choose a custom shortcut or accept the default.

All dependencies are installed automatically during setup. If you prefer manual installation:

# Ubuntu/Debian
sudo apt install xclip xdotool libnotify-bin

# Fedora
sudo dnf install xclip xdotool libnotify

# Arch
sudo pacman -S xclip xdotool libnotify

1. Copy an image to your clipboard (screenshot, right-click > copy image, etc.)
2. Focus on the terminal where your coding assistant is running
3. Press the shortcut (default: Ctrl+Shift+V)
4. The image is saved and its path is typed into the terminal
5. Press Enter to send it to the coding assistant

paste-image            # Run the script directly
paste-image --version  # Show version
paste-image -v         # Show version (short form)

During installation you can choose a custom shortcut. After installation, change it with:

gsettings set org.gnome.settings-daemon.plugins.media-keys.custom-keybinding:/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/paste-image/ binding "<Control><Alt>v"

Modifier key format: <Control>, <Shift>, <Alt>, <Super>.

You can also change it from Settings > Keyboard > Shortcuts > Custom Shortcuts.

Note: Ctrl+Shift+V is the default paste shortcut in most Linux terminals. If this causes conflicts, choose a different shortcut (e.g. <Control><Alt>v).

The following constants can be edited directly in ~/.local/bin/paste-image:

Logs are stored at ~/.local/state/paste-image/paste_image.log (or $XDG_STATE_HOME/paste-image/ if set).

• Format: [YYYY-MM-DD HH:MM:SS] message
• Automatic rotation at 500 lines (keeps last 250)
• Race-condition-safe writes using flock
• Contains timestamps and file paths only (no clipboard content)

bash uninstall.sh

This removes:

• The script from ~/.local/bin/paste-image
• The GNOME keyboard shortcut
• PATH modifications from .bashrc and .zshrc
• Log directory (~/.local/state/paste-image/)
• Temporary files in /tmp/paste_image_*

System dependencies are intentionally left installed (they may be used by other programs). Temporary files older than 7 days are cleaned automatically on each invocation; newer ones are removed on system reboot.

• Make sure the terminal has focus when you press the shortcut
• Verify X11 is in use: echo $XDG_SESSION_TYPE should return x11
• Try running paste-image manually to see error output

• Make sure you copied an actual image (not text or a file)
• Some applications don't copy images to the system clipboard

The GNOME service that handles custom shortcuts (gsd-media-keys) may not be running:

# Check if it's active
pgrep -x gsd-media-keys

# If it returns nothing, restart it
systemctl --user start org.gnome.SettingsDaemon.MediaKeys.target

If the problem persists:

• Verify the shortcut is registered: gsettings get org.gnome.settings-daemon.plugins.media-keys custom-keybindings
• Check for conflicts with other system shortcuts

• Increase TYPING_DELAY in the script configuration (default: 0.1 seconds)
• Some terminal emulators may need a longer delay for xdotool to work correctly

cli-image-paste/
├── paste-image          # Main script
├── install.sh           # Installation script
├── uninstall.sh         # Uninstallation script
├── README.md            # Documentation (English)
├── README.it.md         # Documentation (Italian)
├── SECURITY.md          # Security policy (English)
├── SECURITY.it.md       # Security policy (Italian)
├── LICENSE              # MIT License
├── .gitignore           # Git exclusion rules
├── .shellcheckrc        # ShellCheck linter configuration
├── tests/               # Test suite
│   ├── run_tests.sh         # Test runner
│   ├── test_framework.sh    # Custom test framework
│   ├── test_paste_image.sh  # Main script tests
│   ├── test_install.sh      # Installation tests
│   └── test_uninstall.sh    # Uninstallation tests
└── docs/                # Documentation

bash tests/run_tests.sh

The test suite includes 50+ test cases covering:

• Main script functionality (18 tests): dependency checks, clipboard handling, MIME type detection, mktemp security, file cleanup, notifications, version flag
• Installation flow (12 tests): dependency installation, PATH configuration, gsettings array manipulation, shortcut conflict detection, idempotency
• Uninstallation flow (7 tests): script removal, gsettings cleanup, PATH cleanup

Tests use mocked system utilities for safe execution without requiring actual X11 or GNOME.

Static analysis with ShellCheck:

shellcheck paste-image install.sh uninstall.sh

All scripts pass ShellCheck validation with zero warnings.

• X11 only — not compatible with Wayland (would require wl-paste + ydotool)
• GNOME only — automatic shortcut configuration uses gsettings
• Terminal must have focus when the shortcut is pressed
• Only PNG and JPEG images are supported

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Make sure all tests pass (bash tests/run_tests.sh)
4. Make sure ShellCheck passes (shellcheck paste-image install.sh uninstall.sh)
5. Commit your changes and open a pull request

For information about security considerations and how to report vulnerabilities, see SECURITY.md.

This project is licensed under the MIT License.