TL;DR: Recent Gemini CLI builds paste clipboard images with Ctrl+V (Windows builds also added Alt+V): the image is saved into .gemini-clipboard/, shown as [image #N], and turned into a file reference on submit. When paste fails, and it does on WSL, over SSH, and on some macOS setups, the @ file syntax always works: @screenshots/bug.png attaches the file directly.

How paste actually works in Gemini CLI

When clipboard paste works, Gemini CLI does something sensible under the hood: it writes the clipboard image to a .gemini-clipboard/ folder in your project, shows a clean [image #N] placeholder in your prompt, and converts it to a file reference when you submit. So even the “paste” path is really the file path, automated.

That’s worth knowing because it tells you what the universal fallback is.

The @ syntax: the method that always works

Gemini CLI attaches files with @:

the header is clipped on mobile, look at @screenshots/bug.png and fix it

Tab completion works on the path. This reads the file straight off disk, so it doesn’t care about your terminal, your clipboard, tmux, or whether you’re SSH’d into another machine (as long as the file exists there). Every clipboard trick below is a convenience layer over this.

Platform by platform

Windows (native). Ctrl+V pastes clipboard images in current builds, and newer Windows builds added Alt+V as a dedicated image-paste key, the same escape hatch Claude Code uses. If Ctrl+V inserts nothing or garbage text, try Alt+V, then fall back to @.

WSL2. This is where it breaks. Your screenshot lives on the Windows clipboard and the WSL clipboard bridge is unreliable, so paste inside a WSL session often fails silently. The reliable move: get the image onto disk and reference it with @ (a path under /mnt/c/... works). This is the same boundary that plagues Claude Code image paste in WSL, same cause, same workaround.

macOS. Ctrl+V (not Cmd+V) in most terminals. Paste support here has regressed between versions before, so if it stops working after an update, don’t debug your terminal for an hour: @ the file and move on.

Linux. Clipboard paste needs the right helper installed: wl-paste on Wayland, xclip on X11. No helper, no paste. The @ syntax needs neither.

SSH. Never. The clipboard doesn’t cross the wire; the file must exist on the remote machine. Every remote workflow that works is here, and they all apply to Gemini CLI unchanged.

> Snip. Hotkey. Path pasted.

Invoke turns the clipboard image into a PNG on disk and pastes the file path into your terminal — one hotkey, works in Hyper, Wezterm, Windows Terminal, and WSL2. It's also the fastest way to dictate prompts to Claude Code. Free for 7 days, then $49 once.

Fix this for good →

Quick answers

Can Gemini CLI see images? Yes, it’s multimodal: screenshots, mockups, diagrams, photos, attached by paste or @ reference.

Where do pasted images go? Into .gemini-clipboard/ in your project. You can delete the folder freely, or gitignore it (you probably should).

Paste shows text garbage instead of [image #N]. Your terminal pasted the clipboard as text before Gemini CLI saw it. Try Alt+V on Windows, or use @.

Is this the same problem as Claude Code’s “no image found in clipboard”? Same family. Terminals and clipboard boundaries fail the same way for every CLI agent; here’s the general map.

The one-hotkey version

The pattern across every platform: when in doubt, get the image on disk and reference the path. That save-and-locate step is the annoying part, so Invoke does it in one press: snip with Win+Shift+S, hit the image hotkey, and the PNG is saved with its path pasted into your terminal, ready for an @ reference or any CLI agent. Add push-to-talk dictation on top and the whole prompt, words and image, takes a few seconds. $49 once, local Whisper on your GPU. Free 7-day trial.