Gemini CLI complete guide: monorepo agents and API routing

Quick answer: what Gemini CLI is and how monorepos fit in

Gemini CLI is a terminal-based coding agent from Google, distributed as an npm package. You point it at a repository, give it a task in plain language, and it reads files, runs shell commands, and edits code inside an approval loop, the same broad shape as Claude Code or Codex CLI. The part that trips people up is not the chat loop, it is configuration: how auth works, how the agent decides what context to load in a large repository, and what happens when you want to compare its output against a different model. For a single small repo, defaults are fine. For a monorepo with several packages or services, three things need a decision before the agent is useful day to day: which auth mode you are on (free Google login versus a billed API key), how GEMINI.md files stack across nested directories, and how far the agent's tool access reaches by default. This guide walks through all three, then covers what it takes to run the same coding task through a different model when you want a second opinion or a cheaper pass.

Install, authenticate, and layer GEMINI.md across packages

Installation is one line: `npm install -g @google/gemini-cli`, or run it without installing via `npx @google/gemini-cli`. The first launch asks you to authenticate, and this choice matters more than any flag you will set later. Signing in with a personal Google account puts you on Google's free consumer tier, which is the fastest way to try the tool but ties usage to one person's login, shared across every terminal and every repo that person opens Gemini CLI in. Setting a `GEMINI_API_KEY` environment variable instead switches billing to the metered Gemini API: every project can carry its own key, usage shows up per key in Google's console, and there is no shared quota to collide with a teammate's session. Enterprises can also point the CLI at Vertex AI with service account credentials, which is the path that keeps billing inside an existing Google Cloud project. For context, Gemini CLI follows the same pattern as CLAUDE.md in Claude Code: a file named `GEMINI.md` gets read and concatenated starting from your home directory, then the project root, then the current working directory, so a rule written once at the top applies everywhere below it. In a monorepo this maps cleanly onto the folder structure. Put shared conventions, coding style, and commit message format in one `GEMINI.md` at the repo root, then drop a short package-specific file inside `packages/api/GEMINI.md` or `services/worker/GEMINI.md` with that package's build command, test command, and any local quirks. The agent picks up both automatically the moment you run it from inside that package.

Worked example: what a monorepo task actually costs

Cost tracks input tokens, because every agent turn resends the system prompt, the loaded GEMINI.md files, every file read so far, and prior tool output. A quick single-package fix stays small. A refactor that touches several packages in one session grows the window fast, and a full monorepo audit that walks every package in sequence is the expensive end of the range. The table below prices three task sizes using Gemini 3.1 Pro Preview, at Google's official per-token rate and at the same model's rate through an OpenAI-compatible gateway. Treat the token counts as illustrative planning numbers, not a spec; your repo size, file lengths, and how many turns the agent needs will move the real figure up or down.

Where monorepo setups go wrong

Most of these failures show up as slow sessions or context overflows rather than hard errors, which is why they survive so long in otherwise careful teams.

• Shared free-tier logins collide. Google account auth ties quota to one person, so two engineers on the same login competing for the same daily allowance looks like random slowdowns, not a billing problem.
• A root GEMINI.md that tries to cover every package gets vague fast. Once it grows past general conventions, most of it is irrelevant to whichever package the agent is actually working in, and it still gets billed as input on every call.
• Default tool access is broad. Without scoping, an agent invoked from the repo root can read, run, and edit across every package, not just the one you meant to touch, which is exactly the wrong default for a shared monorepo.
• Switching from Google login to an API key changes the billing basis silently. Teams that move to `GEMINI_API_KEY` for team use sometimes do not realize usage stopped being free until the first invoice.
• MCP servers configured once in the global settings file load into every session in every repo you open, so a server you added for one project quietly adds its tool schema, and its token cost, to unrelated work elsewhere.

Gemini CLI vs Claude Code vs Codex CLI

All three tools are the same shape: an npm-installed terminal agent, a project-level markdown file for standing instructions, and an approval loop for shell and file operations. Where they differ is auth defaults and how tightly the vendor couples the agent to its own model family.

Fixes that make a monorepo setup usable

Apply these in order; the first two usually recover most of the lost speed before you touch anything else.

• Keep the root GEMINI.md short and cross-cutting. Move anything package-specific, build commands, test runners, local env notes, into that package's own GEMINI.md.
• Scope tool access per workspace. Use the coreTools and excludeTools settings to keep an agent invoked in one package from running shell commands meant for another.
• Move a team off shared Google logins once usage is a daily habit. A GEMINI_API_KEY per project makes cost visible and stops one person's quota from throttling everyone else.
• Turn off MCP servers you are not using in the current repo. Every configured server rides along as tool-definition tokens on every call, whether the agent needs it or not.
• For CI or scheduled monorepo sweeps, script the call yourself against an OpenAI-compatible endpoint rather than depending on one vendor being reachable. Routing a routine sweep through APIsRouter and falling back to a second model if the first errors keeps a sequential audit from stalling on one provider's outage or quota limit.
• Log the package touched, model, tokens, and cost per task. A full monorepo sweep is the profile most likely to become the most expensive job in your CI without anyone noticing until the bill arrives.

Scoping settings and scripting a fallback call

A per-package `.gemini/settings.json` is where the coreTools and excludeTools scoping from above actually lives, alongside any MCP servers that package needs. Gemini CLI has no native OpenAI-compatible provider option; that capability is an open feature request on the project, and the base-URL override it does expose (GEMINI_BASE_URL) only redirects Gemini-dialect traffic, which is how translation proxies like LiteLLM hook in for those willing to run one. The simpler path for a fallback or comparison call is a separate script, not a CLI flag: point it at an OpenAI-compatible `/v1` endpoint, keep the same prompt, and swap the model field to try claude-sonnet-5, gpt-5.3-codex-spark, or a budget model like deepseek-v4-flash for a low-cost pass over the same package.

{
  "contextFileName": "GEMINI.md",
  "coreTools": ["ReadFile", "WriteFile", "Grep", "ShellTool(pnpm test)"],
  "excludeTools": ["ShellTool(rm)", "ShellTool(git push)"],
  "mcpServers": {
    "repo-docs": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./docs"]
    }
  }
}

FAQ