Prompting Gemini CLI Well

Gemini CLI (@google/gemini-cli, current stable v0.46.0, released 2026-06-10) is a terminal agent over a Gemini model with a 1,000,000-token context window. This guide shows how to prompt it: how to place context for that window, when to inject files explicitly with @ vs let the agent explore, how to use GEMINI.md, multimodal inputs, Plan Mode, and the headless surface that turns any prompt into a script.

Place context first, the ask last

Google's prompt-design guidance for large contexts is explicit: "When providing large amounts of context (e.g., documents, code), supply all the context first. Place your specific instructions or questions at the very end of the prompt," then bridge with a phrase like "Based on the information above…". Two more documented habits raise hit rate: give clear, specific instructions, and include few-shot examples with consistent formatting ("prompts without few-shot examples are likely to be less effective"; mismatched example formats produce mismatched output).

Explicit context: the @ command

@<path> injects file or directory content into the current prompt: it runs the read_many_files tool and inserts the content before sending your turn. Position is flexible (@README.md What is this? and What is this? @README.md both work), but for large injections put the instruction last per the placement rule. A bare directory like @src/ is recursive (it pulls that directory and all subdirectories). Git-aware filtering is on by default — node_modules/, dist/, .env, and .git/ are excluded (tunable via context.fileFiltering), and a .geminiignore file is also respected. A lone @ with no path passes the query through unchanged.

Multimodal: images, PDFs, sketches

The read_file tool supports text, images, audio, and PDF, so referencing a supported asset by path injects it as multimodal input the model can see. Google's README lists "Generate new apps from PDFs, images, or sketches using multimodal capabilities," and the official walkthrough has the agent visually analyze .png files and rename them by content (photo1.png → yellow_flowers.png). The mechanism is identical to text @: reference the asset by path, put the instruction last.

Standing context: GEMINI.md

GEMINI.md is the default context file the CLI concatenates and sends with every prompt. Load order: (1) global ~/.gemini/GEMINI.md; (2) workspace files in your configured directories and their parents; (3) just-in-time files discovered in a directory when a tool touches it. The footer shows how many context files are loaded. Use it for standing rules — build/test commands, conventions, hard "never do this" constraints — and modularize large files with @file.md imports. Override the filename(s) via context.fileName in settings.json (e.g. ["AGENTS.md", "CONTEXT.md", "GEMINI.md"]).

The same prompt, headless

Gemini CLI enters headless mode automatically in a non-TTY environment, or whenever you pass a query with -p / --prompt. gemini -p "query" runs non-interactively and prints to stdout; cat file | gemini processes piped stdin. Crucially, -p appends to stdin rather than replacing it, so git diff | gemini -p "Write a commit message for these changes" feeds the diff and your instruction together. For machine-readable output, --output-format json (-o json) returns one { response, stats, error? } object — extract clean text with jq -r '.response'. stream-json emits newline-delimited events (init, message, tool_use, tool_result, error, result).