gem-hunterThis guide covers ~30 pro-tips for effectively using Gemini CLI for agentic coding
Gemini CLI is an open-source AI assistant that brings the power of Google's Gemini model directly into your terminal. It functions as a conversational, "agentic" command-line tool - meaning it can reason about your requests, choose tools (like running shell commands or editing files), and execute multi-step plans to help with your development workflow.
In practical terms, Gemini CLI acts like a supercharged pair programmer and command-line assistant. It excels at coding tasks, debugging, content generation, and even system automation, all through natural language prompts. Before diving into pro tips, let's quickly recap how to set up Gemini CLI and get it running.
GEMINI.md for Persistent ContextMCP Servers/restore as an Undo Button@ for Explicit Context! (Talk to Your Terminal)$PATH (and Tool Availability) for Stability/copy for Quick Clipboard CopyCtrl+C for Shell Mode and Exitingsettings.jsonGemini CLI GitHub ActionExtensionsInstallation: You can install Gemini CLI via npm. For a global install, use:
npm install -g @google/gemini-cli
Or run it without installing using npx:
npx @google/gemini-cli
Gemini CLI is available on all major platforms (it's built with Node.js/TypeScript). Once installed, simply run the gemini command in your terminal to launch the interactive CLI.
Authentication: On first use, you'll need to authenticate with the Gemini service. You have two options: (1) Google Account Login (free tier) - this lets you use Gemini 2.5 Pro for free with generous usage limits (about 60 requests/minute and 1,000 requests per day. On launch, Gemini CLI will prompt you to sign in with a Google account (no billing required. (2) API Key (paid or higher-tier access) - you can get an API key from Google AI Studio and set the environment variable GEMINI_API_KEY to use it.
API key usage can offer higher quotas and enterprise data‑use protections; prompts aren't used for training on paid/billed usage, though logs may be retained for safety.
For example, add to your shell profile:
export GEMINI_API_KEY="YOUR_KEY_HERE"
Basic Usage: To start an interactive session, just run gemini with no arguments. You'll get a gemini> prompt where you can type requests or commands. For instance:
$ gemini
gemini> Create a React recipe management app using SQLiteYou can then watch as Gemini CLI creates files, installs dependencies, runs tests, etc., to fulfill your request. If you prefer a one-shot invocation (non-interactive), use the -p flag with a prompt, for example:
gemini -p "Summarize the main points of the attached file. @./report.txt"This will output a single response and exit. You can also pipe input into Gemini CLI: for example, echo "Count to 10" | gemini will feed the prompt via stdin.
CLI Interface: Gemini CLI provides a rich REPL-like interface. It supports slash commands (special commands prefixed with / for controlling the session, tools, and settings) and bang commands (prefixed with ! to execute shell commands directly). We'll cover many of these in the pro tips below. By default, Gemini CLI operates in a safe mode where any action that modifies your system (writing files, running shell commands, etc.) will ask for confirmation. When a tool action is proposed, you'll see a diff or command and be prompted (Y/n) to approve or reject it. This ensures the AI doesn't make unwanted changes without your consent.
With the basics out of the way, let's explore a series of pro tips and hidden features to help you get the most out of Gemini CLI. Each tip is presented with a simple example first, followed by deeper details and nuances. These tips incorporate advice and insights from the tool's creators (e.g. Taylor Mullen) and the Google Developer Relations team, as well as the broader community, to serve as a canonical guide for power users of Gemini CLI.
Quick use-case: Stop repeating yourself in prompts. Provide project-specific context or instructions by creating a GEMINI.md file, so the AI always has important background knowledge without being told every time.
When working on a project, you often have certain overarching details - e.g. coding style guidelines, project architecture, or important facts - that you want the AI to keep in mind. Gemini CLI allows you to encode these in one or more GEMINI.md files. Simply create a .gemini folder (if not already present) in your project, and add a Markdown file named GEMINI.md with whatever notes or instructions you want the AI to persist. For example:
# Project Phoenix - AI Assistant - All Python code must follow PEP 8 style. - Use 4 spaces for indentation. - The user is building a data pipeline; prefer functional programming paradigms.
Place this file in your project root (or in subdirectories for more granular context). Now, whenever you run gemini in that project, it will automatically load these instructions into context. This means the model will always be primed with them, avoiding the need to prepend the same guidance to every prompt.
How it works: Gemini CLI uses a hierarchical context loading system. It will combine global context (from ~/.gemini/GEMINI.md, which you can use for cross-project defaults) with your project-specific GEMINI.md, and even context files in subfolders. More specific files override more general ones. You can inspect what context was loaded at any time by using the command:
/memory show
This will display the full combined context the AI sees. If you make changes to your GEMINI.md, use /memory refresh to reload the context without restarting the session.
Pro Tip: Use the /init slash command to quickly generate a starter GEMINI.md. Running /init in a new project creates a template context file with information like the tech stack detected, a summary of the project, etc.. You can then edit and expand that file. For large projects, consider breaking the context into multiple files and importing them into GEMINI.md with @include syntax. For example, your main GEMINI.md could have lines like @./docs/prompt-guidelines.md to pull in additional context files. This keeps your instructions organized.
With a well-crafted GEMINI.md, you essentially give Gemini CLI a "memory" of the project's requirements and conventions. This persistent context leads to more relevant responses and less back-and-forth prompt engineering.
Quick use-case: Speed up repetitive tasks by defining your own slash commands. For example, you could make a command /test:gen that generates unit tests from a description, or /db:reset that drops and recreates a test database. This extends Gemini CLI's functionality with one-liners tailored to your workflow.
Gemini CLI supports custom slash commands that you can define in simple configuration files. Under the hood, these are essentially pre-defined prompt templates. To create one, make a directory commands/ under either ~/.gemini/ for global commands or in your project's .gemini/ folder for project-specific commands. Inside commands/, create a TOML file for each new command. The file name format determines the command name: e.g. a file test/gen.toml defines a command /test:gen.
Let's walk through an example. Say you want a command to generate a unit test from a requirement description. You could create ~/.gemini/commands/test/gen.toml with the following content:
# Invoked as: /test:gen "Description of the test" description \= "Generates a unit test based on a requirement." prompt \= """ You are an expert test engineer. Based on the following requirement, please write a comprehensive unit test using the Jest framework. Requirement: {{args}} """
Now, after reloading or restarting Gemini CLI, you can simply type:
/test:gen "Ensure the login button redirects to the dashboard upon success"Gemini CLI will recognize /test:gen and substitute the {{args}} in your prompt template with the provided argument (in this case, the requirement). The AI will then proceed to generate a Jest unit test accordingly. The description field is optional but is used when you run /help or /tools to list available commands.
This mechanism is extremely powerful - effectively, you can script the AI with natural language. The community has created numerous useful custom commands. For instance, Google's DevRel team shared a set of 10 practical workflow commands (via an open-source repo) demonstrating how you can script common flows like creating API docs, cleaning data, or setting up boilerplate code. By defining a custom command, you package a complex prompt (or series of prompts) into a reusable shortcut.
Pro Tip: Custom commands can also be used to enforce formatting or apply a "persona" to the AI for certain tasks. For example, you might have a /review:security command that always prefaces the prompt with "You are a security auditor..." to review code for vulnerabilities. This approach ensures consistency in how the AI responds to specific categories of tasks.
To share commands with your team, you can commit the TOML files in your project's repo (under .gemini/commands directory). Team members who have Gemini CLI will automatically pick up those commands when working in the project. This is a great way to standardize AI-assisted workflows across a team.
Quick use-case: Suppose you want Gemini to interface with an external system or a custom tool that isn't built-in - for example, query a proprietary database, or integrate with Figma designs. You can do this by running a custom Model Context Protocol (MCP) server and plugging it into Gemini CLI. MCP servers let you add new tools and abilities to Gemini, effectively extending the agent.
Gemini CLI comes with several MCP servers out-of-the-box (for instance, ones enabling Google Search, code execution sandboxes, etc.), and you can add your own. An MCP server is essentially an external process (it could be a local script, a microservice, or even a cloud endpoint) that speaks a simple protocol to handle tasks for Gemini. This architecture is what makes Gemini CLI so extensible.
Examples of MCP servers: Some community and Google-provided MCP integrations include a Figma MCP (to fetch design details from Figma), a Clipboard MCP (to read/write from your system clipboard), and others. In fact, in an internal demo, the Gemini CLI team showcased a "Google Docs MCP" server that allowed saving content directly to Google Docs. The idea is that whenever Gemini needs to perform an action that the built-in tools can't handle, it can delegate to your MCP server.
How to add one: You can configure MCP servers via your settings.json or using the CLI. For a quick setup, try the CLI command:
gemini mcp add myserver --command "python3 my_mcp_server.py" --port 8080This would register a server named "myserver" that Gemini CLI will launch by running the given command (here a Python module) on port 8080. In ~/.gemini/settings.json, it would add an entry under mcpServers. For example:
"mcpServers": { "myserver": { "command": "python3", "args": ["-m", "my_mcp_server", "--port", "8080"], "cwd": "./mcp_tools/python", "timeout": 15000 } }
This configuration (based on the official docs) tells Gemini how to start the MCP server and where. Once running, the tools provided by that server become available to Gemini CLI. You can list all MCP servers and their tools with the slash command:
/mcp
This will show any registered servers and what tool names they expose.
Power of MCP: MCP servers can provide rich, multi-modal results. For instance, a tool served via MCP could return an image or a formatted table as part of the response to Gemini CLI. They also support OAuth 2.0, so you can securely connect to APIs (like Google's APIs, GitHub, etc.) via an MCP tool without exposing credentials. Essentially, if you can code it, you can wrap it as an MCP tool - turning Gemini CLI into a hub that orchestrates many services.
Default vs. custom: By default, Gemini CLI's built-in tools cover a lot (reading files, web search, executing shell commands, etc.), but MCP lets you go beyond. Some advanced users have created MCP servers to interface with internal systems or to perform specialized data processing. For example, you could have a database-mcp that provides a /query_db tool for running SQL queries on a company database, or a jira-mcp to create tickets via natural language.
When creating your own, be mindful of security: by default, custom MCP tools require confirmation unless you mark them as trusted. You can control safety with settings like trust: true for a server (which auto-approves its tool actions) or by whitelisting specific safe tools and blacklisting dangerous ones.
In short, MCP servers unlock limitless integration. They're a pro feature that lets Gemini CLI become a glue between your AI assistant and whatever system you need it to work with. If you're interested in building one, check out the official MCP guide and community examples.
Quick use-case: Keep important facts at your AI's fingertips by adding them to its long-term memory. For example, after figuring out a database port or an API token, you can do:
/memory add "Our staging RabbitMQ is on port 5673"This will store that fact so you (or the AI) don't forget it later. You can then recall everything in memory with /memory show at any time.
The /memory commands provide a simple but powerful mechanism for persistent memory. When you use /memory add <text>, the given text is appended to your project's global context (technically, it's saved into the global ~/.gemini/GEMINI.md file or the project's GEMINI.md. It's a bit like taking a note and pinning it to the AI's virtual bulletin board. Once added, the AI will always see that note in the prompt context for future interactions, across sessions.
Consider an example: you're debugging an issue and discover a non-obvious insight ("The config flag X_ENABLE must be set to true or the service fails to start"). If you add this to memory, later on if you or the AI are discussing a related problem, it won't overlook this critical detail - it's in the context.
Using /memory:
/memory add "<text>" - Add a fact or note to memory (persistent context). This updates the GEMINI.md immediately with the new entry.
/memory show - Display the full content of the memory (i.e. the combined context file that's currently loaded).
/memory refresh - Reload the context from disk (useful if you manually edited the GEMINI.md file outside of Gemini CLI, or if multiple people are collaborating on it).
Because the memory is stored in Markdown, you can also manually edit the GEMINI.md file to curate or organize the info. The /memory commands are there for convenience during conversation, so you don't have to open an editor.
Pro Tip: This feature is great for "decision logs." If you decide on an approach or rule during a chat (e.g., a certain library to use, or an agreed code style), add it to memory. The AI will then recall that decision and avoid contradicting it later. It's especially useful in long sessions that might span hours or days - by saving key points, you mitigate the model's tendency to forget earlier context when the conversation gets long.
Another use is personal notes. Because ~/.gemini/GEMINI.md (global memory) is loaded for all sessions, you could put general preferences or information there. For example, "The user's name is Alice. Speak politely and avoid slang." It's like configuring the AI's persona or global knowledge. Just be aware that global memory applies to all projects, so don't clutter it with project-specific info.
In summary, Memory Addition & Recall helps Gemini CLI maintain state. Think of it as a knowledge base that grows with your project. Use it to avoid repeating yourself or to remind the AI of facts it would otherwise have to rediscover from scratch.
Quick use-case: If Gemini CLI makes a series of changes to your files that you're not happy with, you can instantly roll back to a prior state. Enable checkpointing when you start Gemini (or in settings), and use the /restore command to undo changes like a lightweight Git revert. /restore rolls back your workspace to the saved checkpoint; conversation state may be affected depending on how the checkpoint was captured.
Gemini CLI's checkpointing feature acts as a safety net. When enabled, the CLI takes a snapshot of your project's files before each tool execution that modifies files. If something goes wrong, you can revert to the last known good state. It's essentially version control for the AI's actions, without you needing to manually commit to Git each time.
How to use it: You can turn on checkpointing by launching the CLI with the --checkpointing flag:
gemini --checkpointing
Alternatively, you can make it the default by adding to your config ("checkpointing": { "enabled": true } in settings.json). Once active, you'll notice that each time Gemini is about to write to a file, it says something like "Checkpoint saved."
If you then realize an AI-made edit is problematic, you have two options:
Run /restore list (or just /restore with no arguments) to see a list of recent checkpoints with timestamps and descriptions.
Run /restore <id> to rollback to a specific checkpoint. If you omit the id and there's only one pending checkpoint, it will restore that by default.
For example:
/restore
Gemini CLI might output:
0: [2025-09-22 10:30:15] Before running 'apply_patch'
1: [2025-09-22 10:45:02] Before running 'write_file'
You can then do /restore 0 to revert all file changes (and even the conversation context) back to how it was at that checkpoint. In this way, you can "undo" a mistaken code refactor or any other changes Gemini made.
What gets restored: The checkpoint captures the state of your working directory (all files that Gemini CLI is allowed to modify) and the workspace files (conversation state may also be rolled back depending on how the checkpoint was captured). When you restore, it overwrites files to the old version and resets the conversation memory to that snapshot. It's like time-traveling the AI agent back to before it made the wrong turn. Note that it won't undo external side effects (for example, if the AI ran a database migration, it can't undo that), but anything in the file system and chat context is fair game.
Best practices: It's a good idea to keep checkpointing on for non-trivial tasks. The overhead is small, and it provides peace of mind. If you find you don't need a checkpoint (everything went well), you can always clear it or just let the next one overwrite it. The development team recommends using checkpointing especially before multi-step code edits. For mission-critical projects, though, you should still use a proper version control (git) as your primary safety net - consider checkpoints as a convenience for quick undo rather than a full VCS.
In essence, /restore lets you use Gemini CLI with confidence. You can let the AI attempt bold changes, knowing you have an "OH NO" button to rewind if needed.
Quick use-case: Imagine you have a Google Doc or Sheet with some specs or data that you want the AI to use. Instead of copy-pasting the content, you can provide the link, and with a configured Workspace MCP server Gemini CLI can fetch and read it.
For example:
Summarize the requirements from this design doc: https://docs.google.com/document/d/<id>
Gemini can pull in the content of that Doc and incorporate it into its response. Similarly, it can read Google Sheets or Drive files by link.
How this works: These capabilities are typically enabled via MCP integrations. Google's Gemini CLI team has built (or is working on) connectors for Google Workspace. One approach is running a small MCP server that uses Google's APIs (Docs API, Sheets API, etc.) to retrieve document content when given a URL or ID. When configured, you might have slash commands or tools like /read_google_doc or simply an auto-detection that sees a Google Docs link and invokes the appropriate tool to fetch it.
For example, in an Agent Factory podcast demo, the team used a Google Docs MCP to save a summary directly to a doc - which implies they could also read the doc's content in the first place. In practice, you might do something like:
@https://docs.google.com/document/d/XYZ12345
Including a URL with @ (the context reference syntax) signals Gemini CLI to fetch that resource. With a Google Doc integration in place, the content of that document would be pulled in as if it were a local file. From there, the AI can summarize it, answer questions about it, or otherwise use it in the conversation.
Similarly, if you paste a Google Drive file link, a properly configured Drive tool could download or open that file (assuming permissions and API access are set up). Google Sheets could be made available via an MCP that runs queries or reads cell ranges, enabling you to ask things like "What's the sum of the budget column in this Sheet [link]?" and have the AI calculate it.
Setting it up: As of this writing, the Google Workspace integrations may require some tinkering (obtaining API credentials, running an MCP server such as the one described by Kanshi Tanaike, etc.). Keep an eye on the official Gemini CLI repository and community forums for ready-to-use extensions - for example, an official Google Docs MCP might become available as a plugin/extension. If you're eager, you can write one following guides on how to use Google APIs within an MCP server. It typically involves handling OAuth (which Gemini CLI supports for MCP servers) and then exposing tools like read_google_doc.
Usage tip: When you have these tools, using them can be as simple as providing the link in your prompt (the AI might automatically invoke the tool to fetch it) or using a slash command like /doc open <URL>. Check /tools to see what commands are available - Gemini CLI lists all tools and custom commands there.
In summary, Gemini CLI can reach out beyond your local filesystem. Whether it's Google Docs, Sheets, Drive, or other external content, you can pull data in by reference. This pro tip saves you from manual copy-paste and keeps the context flow natural - just refer to the document or dataset you need, and let the AI grab what's needed. It makes Gemini CLI a true knowledge assistant for all the information you have access to, not just the files on your disk.
(Note: Accessing private documents of course requires the CLI to have the appropriate permissions. Always ensure any integration respects security and privacy. In corporate settings, setting up such integrations might involve additional auth steps.)
Quick use-case: Instead of describing a file's content or an image verbally, just point Gemini CLI directly to it. Using the @ syntax, you can attach files, directories, or images into your prompt. This guarantees the AI sees exactly what's in those files as context. For example:
Explain this code to me: @./src/main.js
This will include the contents of src/main.js in the prompt (up to Gemini's context size limits), so the AI can read it and explain it.
This @ file reference is one of Gemini CLI's most powerful features for developers. It eliminates ambiguity - you're not asking the model to rely on memory or guesswork about the file, you're literally handing it the file to read. You can use this for source code, text documents, logs, etc. Similarly, you can reference entire directories:
Refactor the code in @./utils/ to use async/await.By appending a path that ends in a slash, Gemini CLI will recursively include files from that directory (within reason, respecting ignore files and size limits). This is great for multi-file refactors or analyses, as the AI can consider all relevant modules together.
Even more impressively, you can reference binary files like images in prompts. Gemini CLI (using the Gemini model's multimodal capabilities) can understand images. For example:
Describe what you see in this screenshot: @./design/mockup.pngThe image will be fed into the model, and the AI might respond with something like "This is a login page with a blue sign-in button and a header image," etc.. You can imagine the uses: reviewing UI mockups, organizing photos (as we'll see in a later tip), or extracting text from images (Gemini can do OCR as well).
A few notes on using @ references effectively:
File limits: Gemini 2.5 Pro has a huge context window (up to 1 million tokens), so you can include quite large files or many files. However, extremely large files might be truncated. If a file is enormous (say, hundreds of thousands of lines), consider summarizing it or breaking it into parts. Gemini CLI will warn you if a reference is too large or if it skipped something due to size.
Automatic ignoring: By default, Gemini CLI respects your .gitignore and .geminiignore files when pulling in directory context. So if you @./ a project root, it will not dump huge ignored folders (like node_modules) into the prompt. You can customize ignore patterns with .geminiignore similarly to how .gitignore works.
Explicit vs implicit context: Taylor Mullen (the creator of Gemini CLI) emphasizes using @ for explicit context injection rather than relying on the model's memory or summarizing things yourself. It's more precise and ensures the AI isn't hallucinating content. Whenever possible, point the AI to the source of truth (code, config files, documentation) with @ references. This practice can significantly improve accuracy.
Chaining references: You can include multiple files in one prompt, like:
Compare @./foo.py and @./bar.py and tell me differences.
The CLI will include both files. Just be mindful of token limits; multiple large files might consume a lot of the context window.
Using @ is essentially how you feed knowledge into Gemini CLI on the fly. It turns the CLI into a multi-modal reader that can handle text and images. As a pro user, get into the habit of leveraging this - it's often faster and more reliable than asking the AI something like "Open the file X and do Y" (which it may or may not do on its own). Instead, you explicitly give it X to work with.
Quick use-case: If a task at hand would benefit from a small script or utility, you can ask Gemini CLI to create that tool for you - right within your session. For example, you might say, "Write a Python script to parse all JSON files in this folder and extract the error fields." Gemini can generate the script, which you can then execute via the CLI. In essence, you can dynamically extend the toolset as you go.
Gemini CLI is not limited to its pre-existing tools; it can use its coding abilities to fabricate new ones when needed. This often happens implicitly: if you ask for something complex, the AI might propose writing a temporary file (with code) and then running it. As a user, you can also guide this process explicitly:
write_file tool to create the file. For instance:Generate a Node.js script that reads all '.log' files in the current directory and reports the number of lines in each.
Gemini CLI will draft the code, and with your approval, write it to a file (e.g. script.js). You can then run it by either using the ! shell command (e.g. !node script.js) or by asking Gemini CLI to execute it (the AI might automatically use run_shell_command to execute the script it just wrote, if it deems it part of the plan).