skip to content

Gemini CLI

Google's open-source terminal agent: GEMINI.md context files, built-in tools, MCP servers and extensions, sandboxing and trusted folders. Interviewers set it beside Claude Code and Codex.

part ofAI coding toolsread it →
on this pageshow

explore

questions

6

In Gemini CLI 0.62.0, which GEMINI.md files reach the model, in what order, and how do you see exactly what it received?

level: middleimportance: must knowfreq 14%

answer

  1. home, repository, then touched folders
  2. upward walk stops at the .git root
  3. concatenated, never overridden
  4. /memory show versus /memory list
  5. context.fileName and @file.md imports

basics

~20 s

Gemini CLI concatenates ~/.gemini/GEMINI.md, the GEMINI.md files from the launch directory up to the repository root, and files found later in folders a tool touches. /memory show prints the combined text; /memory list prints the paths.

solid answer

~40 s

At 0.62.0 Gemini CLI builds one block of instructions from every context file it finds. First the global `~/.gemini/GEMINI.md`; then, walking upward from the directory you launched in, every `GEMINI.md` up to the first directory holding `.git` (the `context.memoryBoundaryMarkers` setting), ordered root to leaf; then, just in time, any `GEMINI.md` in a folder a tool reads or writes. Nothing overrides anything: the files are concatenated with their paths as separators and sent with every prompt. `/memory show` prints exactly that text, `/memory list` prints the file paths, and `/memory reload` (alias `refresh`) re-scans after you edit one. `@./file.md` imports another Markdown file inline, and `context.fileName` changes or extends the names it looks for, for example to read `AGENTS.md` too.

code

json · 6 lines
json
{
  "context": {
    "fileName": ["AGENTS.md", "GEMINI.md"],
    "memoryBoundaryMarkers": [".git"]
  }
}

go deeper

for a junior

Know that ~/.gemini/GEMINI.md and the repository's GEMINI.md are both read, and that /memory show prints what the model gets.

for a middle

Explain the three tiers - global, the upward walk to the .git root, just-in-time folders - and that the files are concatenated rather than overriding each other.

for a senior

Debug a missing instruction methodically: /memory list for paths, /memory show for text, the boundary marker for files above the root, and /memory reload after edits.

for a principal

Decide how a team splits guidance between global, root and nested files, and whether context.fileName should standardise on AGENTS.md alongside GEMINI.md across repositories.

## What a GEMINI.md file is A **context file** is a Markdown file of instructions that Gemini CLI, Google's open-source terminal agent, reads and sends to the model with every prompt. Its default name is `GEMINI.md` (the constant in the source is `DEFAULT_CONTEXT_FILENAME`). It carries project conventions, commands to run, style rules or a persona. It is **guidance the model reads**, not configuration the CLI enforces: a rule in it can still be ignored, which is why permissions live elsewhere (approval modes, policies, settings). ## Where Gemini CLI 0.62.0 looks The CLI assembles context from three tiers, in this order: 1. **Global** - `~/.gemini/GEMINI.md`, your personal defaults for every project. 2. **Workspace** - starting at the directory you launched in, the CLI walks **upward** and collects every context file it finds, stopping at the project root: the first directory that contains a `.git` marker. Files are ordered from the root down, so the repository-wide file comes before a nested one. The marker list is the setting `context.memoryBoundaryMarkers` (default `[".git"]`; an empty list disables the parent walk). A `GEMINI.md` sitting above the repository root - say in `~/work` - is outside that walk. 3. **Just in time** - when a tool reads or writes something in a directory, the CLI scans that directory and its ancestors, up to the same ceiling, for context files it has not loaded yet and adds them. A component's own `GEMINI.md` therefore arrives the first time the agent touches that component, not at startup. Installed **extensions** can contribute a context file as well (`contextFileName` in `gemini-extension.json`, or a `GEMINI.md` in the extension directory). ## Concatenation, not override Every file found is **concatenated**, with separators that name each file's path, and the result travels with each prompt. No file replaces another. | Situation | What the model receives | |---|---| | Global and repository files both say how to format commits | Both texts, global first | | A nested `GEMINI.md` contradicts the root one | Both texts; the model has to reconcile them | | A `GEMINI.md` in `~/work`, above a repository with `.git` | Not loaded by the workspace walk | | A sub-folder file the agent has not touched yet | Not loaded yet; it arrives just in time | The practical consequence: write the general rule once, put only genuinely local rules in nested files, and avoid two files that disagree, because there is no precedence rule to settle it for you. The CLI footer shows how many context files are loaded, a quick sign that a file you expected is missing. ## Seeing what the model received - `/memory show` - prints the **full concatenated text** currently loaded. This is the answer to "what did the model actually get?" - `/memory list` - prints the **paths** of the context files in use, which tells you which files loaded but not what they say. - `/memory reload` (alias `/memory refresh`) - re-scans and reloads every context file, for when you edited one mid-session. - `/init` - analyses the project and creates a tailored `GEMINI.md` to start from. ## Imports and renaming A large file can be split with **imports**: a line such as `@./docs/testing.md` or `@../shared/style-guide.md` pulls that Markdown file's content in at that point. Relative and absolute paths work, imported files may import others, circular imports are detected and stopped, the import-processor page gives a default maximum depth of five levels, and an `@` inside a code block or inline code span is ignored. The setting `context.fileName` takes a string or an array of names. Setting it to `["AGENTS.md", "GEMINI.md"]` makes the CLI treat both names as context files at every tier, so a repository that already keeps an `AGENTS.md` does not need a duplicate. ## Mistakes that show up in practice - Expecting the closest file to win and deleting shared rules from it: both files are sent, so the model sees the contradiction. - Debugging with `/memory list` and concluding the instructions are fine: it lists paths, not content. - Putting team rules in a `GEMINI.md` above the repository root and wondering why teammates never get them. - Editing `GEMINI.md` mid-session and forgetting `/memory reload`. - Treating a sentence in `GEMINI.md` as a security control; it is a request to the model, not a permission.

  • A rule lives in services/billing/GEMINI.md, and Gemini CLI was launched at the repository root. When does the model see it?
    Not at startup: the workspace walk goes upward from the launch directory, so it never descends into `services/billing`. The file is loaded just in time, the first time a tool reads or writes something in that folder, and from then on it is part of the concatenated context. `/memory list` shows whether it has been picked up yet.
  • How do you share one style guide between several GEMINI.md files without copying it?
    Keep the guide in its own Markdown file and import it with a line such as `@../shared/style-guide.md` in each `GEMINI.md`. The import processor inlines its content, handles nested imports, stops circular ones and ignores `@` inside code blocks. `/memory show` confirms the guide's text actually arrived.

  • The closest GEMINI.md overrides the global one, so only one file is sent.
  • Gemini CLI reads only the GEMINI.md in the directory you launched from.
  • /memory list shows the instructions the model is actually receiving.
  • The file must be called GEMINI.md; the name cannot be changed.
  • An @file.md line is only a link the model may open later.
  • A GEMINI.md anywhere above the repository is always loaded.

Assumes Gemini CLI 0.62.0: the .git-bounded upward walk, just-in-time loading and /memory list / reload (alias refresh) are as defined in that release's source.

open as a page

In Gemini CLI 0.62.0, what does each --approval-mode value - default, auto_edit, yolo and plan - let the agent do without asking?

level: juniorimportance: should knowfreq 10%

basics

~10 s

Gemini CLI's default mode runs reads and searches but asks before edits and shell commands; auto_edit also approves file edits; yolo approves tool calls wholesale; plan is read-only apart from writing its Markdown plan.

open as a page

A release job runs `gemini -p "update CHANGELOG.md from the commits since the last tag"` with Gemini CLI 0.62.0 and changes nothing - why, and what do you change?

level: seniorimportance: should knowfreq 7%

basics

~10 s

Headless runs cannot ask, so write_file, replace and run_shell_command are denied in the default mode, and the untrusted checkout forces that mode anyway. Trust it with --skip-trust and pick --approval-mode=auto_edit or a policy rule.

open as a page

You open an unfamiliar cloned repository in Gemini CLI 0.62.0 and choose Don't trust - what does safe mode switch off, and what still works?

level: seniorimportance: should knowfreq 6%

basics

~20 s

Safe mode ignores the repository's .gemini/settings.json and .env, connects no MCP servers, loads no custom commands, blocks extension installs and forces the default approval mode, so edits and commands ask. The agent can still read code.

open as a page

A team of forty developers is standardising on Gemini CLI 0.62.0 - which sign-in should they use, and how do you stop anyone using a different one?

level: principalimportance: should knowfreq 3%

basics

~10 s

For company code, use corporate Google accounts on a Code Assist Standard or Enterprise licence with GOOGLE_CLOUD_PROJECT set, or Vertex AI under the company project; enforce it with security.auth.enforcedType in the system settings file.

open as a page

In Gemini CLI, when do you declare an MCP server under mcpServers in settings.json, and when do you ship it inside an extension instead?

level: middleimportance: nice to knowfreq 5%

basics

~20 s

Use mcpServers in user or project settings.json for a server one person or one repository needs. Package it in an extension when it travels with context, commands or policies across repositories; a same-named settings.json entry wins.

open as a page