Gemini CLI Best Practices: GEMINI.md, Extensions and Approval Modes

The short version: sign in with a Gemini API key, Vertex AI or an organisation’s Code Assist licence, because personal Google sign-in has ended. Keep GEMINI.md short and layered, and split it with @ imports. Install extensions only from sources you have read, and pin them. Start in the default approval mode, use plan mode for anything large, and keep YOLO for a sandbox. Turn on checkpointing and trusted folders, both of which are off by default. And in GitHub, use Google’s run-gemini-cli action with an API key or Workload Identity Federation rather than a personal account. Each habit is below, with the setting that makes it stick.

1. Sign in the way that still works

Most older guides start with “choose Sign in with Google”. For personal accounts that no longer works. Google’s Code Assist deprecation notice↗ (opens in a new tab) says that from 18 June 2026 the Login with Google option stopped working for Gemini Code Assist for individuals and the Google AI Pro and Ultra tiers, in the IDE extensions and in Gemini CLI, and points those users to the Antigravity family of products. The Gemini CLI sign-in page carries a matching notice that for the unpaid tier and Google One users, Gemini CLI was replaced by Antigravity CLI on that date. Code Assist Standard and Enterprise licences are unchanged.

• Working alone: a Gemini API key from Google AI Studio, set as GEMINI_API_KEY, then choose “Use Gemini API key” when Gemini starts.
• On Google Cloud: Vertex AI, with GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION set and credentials from gcloud, a service account or a Google Cloud API key.
• In a company with a Code Assist Standard or Enterprise licence: Sign in with Google still works for that account, with a Google Cloud project set.
• In scripts and CI: an API key or Vertex AI, never an interactive sign-in.

Keep the key in your shell profile or a secret manager, not in a project’s .env that might be committed. How Gemini CLI now relates to Code Assist is in Gemini CLI vs Gemini Code Assist.

2. Keep GEMINI.md layered and short

Google’s GEMINI.md documentation↗ (opens in a new tab) describes three layers, all concatenated and sent with every prompt: a global ~/.gemini/GEMINI.md, files in your workspace folders and their parents, and files found just in time when a tool opens a folder further down. Use each layer for what it is for.

• Global: a few lines about you, such as British spelling or “never push”. Everything here is paid for in every session of every project.
• Project root: how to build, test and lint, the folder layout, and the rules the whole team follows.
• Subfolders: rules that apply only there, such as the migration conventions in db/. They load only when Gemini works in that folder.
• /memory show prints exactly what was sent; /memory reload re-reads the files after you edit them.

When the root file grows, split it with imports. A line of the form @path/to/file.md pulls another Markdown file in, with relative or absolute paths:

# Orders service

Build with npm run build. Test with npm test before saying a task is done.

@./docs/agents/architecture.md
@./docs/agents/testing.md
@../shared/style-guide.md

If the repository already keeps its rules in AGENTS.md for other agents, add it to context.fileName in settings.json, for example ["AGENTS.md", "GEMINI.md"], instead of copying it. How the different agents’ files compare is in AI context files compared.

3. Treat extensions like dependencies

An extension can bundle prompts, MCP servers, custom commands, themes, hooks, subagents and skills, which means it can change what Gemini does and what it can reach. The extension reference↗ (opens in a new tab) covers the commands:

gemini extensions install https://github.com/<owner>/<repo> --ref v1.2.0
gemini extensions list
gemini extensions update <name>            # or --all
gemini extensions disable <name> --scope workspace
gemini extensions uninstall <name>
gemini extensions link ./my-extension      # develop one locally

• Read the repository’s gemini-extension.json before installing. It lists the MCP servers the extension starts, its context file and any tools it excludes.
• Pin with --ref to a tag or commit, and add --auto-update only for sources you trust to stay trustworthy.
• An MCP server you define in settings.json wins over an extension’s server of the same name, and extensions cannot set trust on their servers.
• Disable an extension per workspace where it is not needed, rather than carrying every extension into every project.

4. Pick the approval mode per task

Gemini CLI has four approval modes. default asks before tools that change things, auto_edit approves file edits but still asks about other actions, plan is read-only until you approve a plan, and yolo approves everything. Shift+Tab cycles the first three during a session; YOLO is only set on the command line with --approval-mode=yolo.

• Unfamiliar code, or anything touching data or infrastructure: default, and read each command before approving it.
• A change you have already agreed in detail: auto_edit, with checkpointing on so any edit can be undone.
• Anything bigger than a single file: plan first. How plan mode works, and where its plans are saved, is in Gemini CLI plan mode.
• yolo: only inside a sandbox or a throwaway CI runner, never on the machine that holds your keys.

5. Sandbox anything unattended

Sandboxing is off until you turn it on. The sandbox documentation↗ (opens in a new tab) gives three switches in order of precedence: the -s or --sandbox flag, the GEMINI_SANDBOX variable, and tools.sandbox in settings.json. The method depends on your platform: macOS Seatbelt, Docker or Podman anywhere, a native Windows sandbox, gVisor (runsc) on Linux for the strongest isolation, and LXC on Linux as an experiment. Seatbelt’s default profile keeps writes inside the project but allows reads and network access; stricter profiles are chosen with SEATBELT_PROFILE.

{
  "tools": { "sandbox": "docker" },
  "general": { "checkpointing": { "enabled": true } }
}

With a container sandbox, your project folder is mounted at the same absolute path inside it, so commands behave as they would on your machine while the rest of the system stays out of reach.

6. Turn on checkpoints and trusted folders

Checkpointing is off by default, and it is the cheapest safety net Gemini CLI has. Once general.checkpointing.enabled is set, as above, the checkpointing page↗ (opens in a new tab) says Gemini snapshots your project into a shadow Git repository under ~/.gemini/history/<project_hash> before any approved edit, along with the conversation and the tool call it was about to make. /restore lists the checkpoints, and /restore <name> puts the files and the conversation back. Your own Git repository is not touched. The old --checkpointing flag was removed in 0.11.0, so older guides that use it will fail.

Trusted folders is also off by default. Set security.folderTrust.enabled to true in your user settings and Gemini asks before loading a new folder’s configuration. An untrusted folder runs in a safe mode: its .gemini/settings.json and .env files are not loaded, its MCP servers do not connect, its custom commands are skipped, and tools are not auto-approved. That matters most for repositories you cloned but did not write.

7. Gemini CLI GitHub examples

Google publishes a GitHub Action, run-gemini-cli↗ (opens in a new tab), with ready-made workflows for pull request review, issue triage, a general assistant you call with @gemini-cli in a comment, and a dispatcher that routes those requests. The quickest setup is /setup-github inside a Gemini CLI session, which adds the workflows to the repository; the README also lists them under examples/workflows to copy by hand. After that, @gemini-cli /review on a pull request or @gemini-cli /triage on an issue runs them.

name: gemini-summary
on:
  pull_request:
    types: [opened]
permissions:
  contents: read
jobs:
  summarise:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - id: gemini
        uses: google-github-actions/run-gemini-cli@v0
        with:
          gemini_api_key: ${{ secrets.GEMINI_API_KEY }}
          prompt: Summarise what this pull request changes, in five bullet points.
      - run: echo "$SUMMARY" >> "$GITHUB_STEP_SUMMARY"
        env:
          SUMMARY: ${{ steps.gemini.outputs.summary }}

• Store the key as a repository secret named GEMINI_API_KEY. On Google Cloud, the README recommends Workload Identity Federation instead of a long-lived key.
• Give the job the narrowest permissions block that works, and add pull-requests: write only to the jobs that comment.
• Pin the action and the CLI version (gemini_cli_version) so a new release does not change behaviour mid-week.
• A GEMINI.md at the repository root is read in the Action too, so review rules written once apply in the terminal and in CI.

For your own scripts outside the Action, gemini -p "..." --output-format json returns one object with the answer in response, and stream-json returns events line by line. Exit code 0 is success, 1 a general or API error, 42 an input error and 53 a turn limit.

8. Keep the plan and the outcome somewhere shared

Gemini’s to-do list and plan files live with one session on one machine. The task they belong to, and what happened to it, should outlive both. fenbs connects as an MCP server under mcpServers in settings.json with httpUrl set to https://fenbs.ai/api/mcp, and /mcp auth fenbs signs in through the browser; a CI job uses a token issued by hand under Settings, with a name, scopes and an optional expiry. Gemini can then read a task, write the approved plan into it, move it through To Do, Next Up, In Progress and Completed, and set its test status, each change recorded in History under the assistant’s name. The GEMINI.md lines that make that routine are in Gemini CLI plan mode, and the setup is on Gemini CLI on fenbs.