Gemini CLI with GEMINI.md: Examples and Best Practices

Google’s Gemini CLI is an open-source AI agent that works inside your terminal. It can inspect a codebase, explain code, edit files, run commands, research a problem, and help plan or implement multi-step changes.

The quality of that work depends heavily on context. A short prompt may explain the immediate task, but it rarely captures your architecture, coding conventions, verification requirements, safety boundaries, and product decisions. GEMINI.md gives Gemini CLI that durable project context.

Update: Gemini CLI is still maintained, but Google changed who can access it through Google-account authentication. Since June 18, 2026, Gemini CLI has stopped serving requests for individual free, Google AI Pro, and Google AI Ultra accounts. Individual users should migrate to Antigravity CLI or use Gemini CLI with a Gemini API key. Gemini Code Assist Standard and Enterprise licenses, Google Cloud access, and API-key authentication remain supported. See Google’s official deprecation notice before choosing your setup.

Should you use Gemini CLI or Antigravity CLI?

The answer now depends on how you authenticate:

Antigravity CLI retains the main workflow concepts from Gemini CLI, including context files, skills, subagents, hooks, and Model Context Protocol (MCP) servers. It is not a perfect one-to-one replacement, however. Some paths and configuration formats have changed. I cover the important differences later in this article.

Installing Gemini CLI in 2026

According to the current Gemini CLI installation guide, the recommended runtime is Node.js 20 or newer. Google lists macOS 15+, Windows 11 24H2+, and Ubuntu 20.04+ among its recommended environments.

Install the stable release with npm:

npm install -g @google/gemini-cli

On macOS or Linux, you can also use Homebrew:

brew install gemini-cli

If you only want to try it without installing it globally:

npx @google/gemini-cli

Verify your installation:

gemini --version

Gemini CLI publishes stable, preview, and nightly release channels. Use the stable channel unless you have a specific reason to test unreleased features. At the time of this update, the latest documented stable release is v0.52.0, released July 22, 2026. Check the release page rather than copying that version number into scripts, because releases change frequently.

Authenticating Gemini CLI

For individual users, the most direct supported option is now a Gemini API key from Google AI Studio.

On macOS or Linux:

export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
gemini

On Windows PowerShell:

$env:GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
gemini

Select Use Gemini API key when prompted. Do not commit the key to Git, place it inside GEMINI.md, or paste it into an AI conversation.

Organizations can also authenticate through Gemini Code Assist licenses or Vertex AI. The authentication documentation explains the required Google Cloud project, location, Application Default Credentials, and service-account options.

What is GEMINI.md?

GEMINI.md is Gemini CLI’s default context file. It contains durable instructions that should apply across sessions, such as:

• What the product does and who it serves.
• The languages, frameworks, and package manager in use.
• Important folders and architectural boundaries.
• Coding, content, and design-system conventions.
• Commands used to test or validate changes.
• Actions that require confirmation.
• Files, data, or systems that should not be accessed.
• The expected format for plans, explanations, or handoffs.

It is better understood as an instruction layer than as magical memory. Gemini CLI adds the loaded content to the model’s context, but the instructions do not guarantee correctness. You still need tests, type checking, reviews, permissions, and appropriate tool restrictions.

How hierarchical context works

Gemini CLI can combine instructions from several levels:

1. Global context: ~/.gemini/GEMINI.md contains preferences that apply across projects.
2. Project context: A GEMINI.md at the repository root contains shared project instructions.
3. Nested context: A GEMINI.md inside a subdirectory can add instructions for that part of the codebase.

For example:

~/.gemini/GEMINI.md
projects/my-app/GEMINI.md
projects/my-app/src/components/GEMINI.md

This lets you keep broad preferences global while placing framework, package, or component rules close to the code they govern.

Inside Gemini CLI, use these commands to inspect the active context:

/memory list
/memory show
/memory refresh

• /memory list shows the context files currently in use.
• /memory show displays their combined content.
• /memory refresh reloads the files after you edit them.

These commands are documented in the current Gemini CLI command reference.

You can use filenames other than GEMINI.md

GEMINI.md is the default, but it is no longer the only option. Gemini CLI’s current configuration supports one filename or a list of filenames through context.fileName in settings.json.

For example, a team working with several coding agents can configure Gemini CLI to read existing instruction files:

{
  "context": {
    "fileName": ["AGENTS.md", "CONTEXT.md", "GEMINI.md"]
  }
}

This can reduce duplicated instructions, but be careful with conflicts. If multiple files say different things, it may become unclear which rule should win. Keep one source of truth for each type of decision and inspect the combined context with /memory show.

See Google’s current guide to providing context with GEMINI.md for configuration details.

A practical root GEMINI.md example

A useful context file should be specific enough to guide work without trying to document the entire organization.

# Project: Loanchy

Loanchy is a loan-management web application. This repository contains the
customer application and its Firebase integration.

## Technology

- Next.js with the App Router
- TypeScript in strict mode
- Tailwind CSS and shadcn/ui
- Firebase Authentication and Firestore
- npm for package management

## Important folders

- `src/app`: routes and layouts
- `src/components`: reusable interface components
- `src/lib`: shared utilities and Firebase configuration
- `src/features`: domain-specific workflows

## Implementation rules

- Prefer the smallest change that solves the requested problem.
- Reuse existing components and design tokens before adding new ones.
- Do not introduce a dependency without explaining why it is needed.
- Preserve loading, empty, error, disabled, and success states.
- Never open, print, or modify `.env` files or credentials.
- Ask before changing authentication, database rules, or deployment settings.

## Verification

Before presenting work as complete:

1. Run `npm run typecheck`.
2. Run the tests related to the changed feature.
3. Run `npm run build` for routing or configuration changes.
4. Report any check that could not be completed.

This example tells the agent what matters, where to look, what requires caution, and how completion is verified. It does not include generic advice that the agent already knows.

Add focused instructions for a subdirectory

If your frontend and backend need different rules, avoid turning the root file into a long collection of exceptions. Place narrower instructions inside the relevant directory.

For example, src/components/GEMINI.md could contain:

# Component instructions

- Use existing design tokens; do not hardcode colors or spacing values.
- Every interactive element must be keyboard accessible.
- Reuse the shared Button, Field, Dialog, and Toast components.
- Include loading, empty, error, disabled, and destructive states where relevant.
- Do not describe an interface as accessible without testing it.

The root file still provides product and repository context, while the nested file describes the additional rules for component work.

Import shared instructions

Large projects can split reusable guidance into smaller documents and import them with @path syntax:

# Project instructions

@./docs/architecture.md
@./docs/testing-guidelines.md
@./docs/design-system-rules.md

## Project-specific constraints

- Ask before changing public APIs.
- Keep database migrations backward compatible.

Gemini CLI supports relative and absolute imports. Prefer relative paths for repository-owned documentation so that the project remains portable across machines.

Do not import every document in the repository. Excessive, stale, or contradictory context can make results worse and consumes space that could be used for the actual task.

Use the real Plan Mode

Older workflows sometimes tried to simulate planning by writing “do not edit anything” inside GEMINI.md. Gemini CLI now has a native Plan Mode with tool restrictions for read-only research and planning.

Start a session in Plan Mode:

gemini --approval-mode=plan

Or enter it during a session:

/plan investigate the authentication failure and propose a fix

You can also use Shift+Tab to cycle through approval modes. Native Plan Mode is safer and clearer than relying only on prompt text because it restricts the tools available to the agent while it investigates.

GEMINI.md can still define what a good plan should contain—for example, risks, affected files, test strategy, and rollback considerations—but it should not pretend to be the security boundary.

Choose models through /model

Avoid hardcoding one model as “the Gemini CLI model.” Availability changes by account, release channel, and product configuration.

Use:

/model

The current model-selection documentation recommends an Auto option for most work, Pro for more complex reasoning, and Flash or Flash-Lite when speed is more important. You can also start the CLI with --model, but the selected model does not necessarily control models used by subagents.

This is why static benchmark tables age poorly. Evaluate the model and CLI version you actually use on representative tasks, and record the version and date when publishing comparisons.

Security: instructions are not permissions

Writing “never access secrets” in GEMINI.md is useful guidance, but it does not technically prevent access. Treat it as one layer in a broader safety setup.

Practical safeguards include:

• Keep secrets outside the repository and out of context files.
• Review commands and diffs before approving them.
• Use Plan Mode for investigation before implementation.
• Enable Trusted Folders so untrusted projects cannot automatically load powerful workspace configuration.
• Use sandboxing to restrict filesystem and command access.
• Give MCP servers and external tools the minimum access they need.
• Do not auto-approve destructive commands, deployments, purchases, messages, or permission changes.
• Treat content fetched from websites, issues, documents, and repositories as untrusted input.

Before trusting a repository, inspect its .gemini configuration, hooks, commands, skills, and MCP definitions. Project files can change how the agent behaves.

Best practices for GEMINI.md

Keep instructions verifiable

“Write high-quality code” is subjective. “Run npm run typecheck and the related tests before completion” describes observable behavior.

Explain the reason behind unusual rules

An agent is more likely to apply a constraint correctly when it understands the boundary. For example: “Do not rename these event properties because the mobile clients consume them.”

Separate shared and personal context

Commit team-approved project rules to the repository. Keep personal preferences and private notes in the appropriate user-level or private memory location.

Keep context close to the work

Use the root file for shared product and repository decisions. Use nested context files for specialized packages or directories.

Document tests and completion criteria

List the commands that prove a change works. Tell the agent to distinguish successful checks from checks it could not run.

Include important negative boundaries

Call out sensitive data, generated files, deployment systems, migrations, public APIs, or folders that must not be changed casually.

Review the loaded context

Run /memory list and /memory show. A perfectly written file does nothing if it is not being loaded.

Remove stale instructions

Update context files when frameworks, commands, ownership, or architecture change. Old instructions can be worse than missing instructions because they look authoritative.

Prefer concise context over a documentation dump

Link or import only what is relevant. More context is not automatically better context.

Treat agent mistakes as diagnostic signals

Repeated mistakes can reveal unclear naming, missing tests, conflicting documentation, or an architecture that is difficult for both agents and new teammates to understand.

Migrating GEMINI.md to Antigravity CLI

Google’s migration guide says Antigravity CLI continues to read workspace GEMINI.md and AGENTS.md files, along with the global ~/.gemini/GEMINI.md. Existing context documents therefore do not need to be rewritten solely because of the migration.

On its first launch, Antigravity CLI can detect legacy Gemini CLI configuration and offer migration options. You can also import Gemini extensions as Antigravity plugins:

agy plugin import gemini

Check these differences after migration:

For remote MCP connections, Antigravity CLI uses serverUrl rather than the legacy url or httpUrl keys. Automatic migration handles many configurations, but you should verify context, skills, plugins, hooks, and MCP connections individually rather than assuming complete parity.

Final checklist

Before relying on a GEMINI.md setup, confirm that:

• The file describes the product and repository accurately.
• Important folders and boundaries are documented.
• The package manager and verification commands are current.
• Sensitive information is not included.
• Destructive or external actions require approval.
• Nested files do not contradict root instructions.
• Imported files exist and remain relevant.
• /memory list shows the expected files.
• /memory show contains the expected combined instructions.
• Security relies on permissions, trust, sandboxing, and review—not prompt text alone.

GEMINI.md is most effective when it functions as a concise operating guide for the repository. It should help the agent understand the product, make appropriate tradeoffs, respect boundaries, and verify its work. Keep it specific, inspect what is actually loaded, and update it whenever the project or toolchain changes.

Official references

• Gemini CLI installation
• Gemini CLI authentication
• Project context with GEMINI.md
• Memory management
• Gemini CLI command reference
• Gemini CLI Plan Mode
• Gemini CLI model selection
• Google’s Gemini Code Assist deprecation notice
• Migrating from Gemini CLI to Antigravity CLI