Gemini CLI Config Generator

Gemini CLI config generator: write ~/.gemini/settings.json and GEMINI.md correctly

Google's Gemini CLI reads a single JSON settings file at ~/.gemini/settings.json, and a per-project context file named GEMINI.md. This generator writes both from a short form, updating live as you change options. Everything happens in the browser — the tool is a client-side component with no upload step, so your project details stay on your machine.

The first thing worth stating plainly, because it is the most common source of a wasted hour: your API key does not go in settings.json. Gemini CLI takes it from the GEMINI_API_KEY environment variable, or from a .env file in ~/.gemini/. The generator reflects this by putting the key export in the install strip at the top of the tool rather than anywhere in the generated JSON — which also means the settings file it produces is safe to commit to a dotfiles repository.

Install, and the two commands the tool gives you

The key comes from Google AI Studio. Put the export in your shell profile so it survives new terminals, or write it into ~/.gemini/.env if you would rather keep it out of your shell history and process environment for every other program you run.

The five keys the settings.json tab can write

The output is a flat JSON object. Two keys are always present, two are conditional, and one nested object appears only if you select MCP servers:

The model picker offers gemini-2.5-pro (the default, and the strongest of the four), gemini-2.5-flash for speed, and gemini-2.0-flash and gemini-2.0-flash-exp for the previous generation. Model ids are exact strings; the picker exists so you never have to remember whether the separator is a dot or a hyphen.

Choosing between the four models

All four ids in the picker are valid values for the model key; the choice is about what you are doing, not about syntax.

• gemini-2.5-pro — the default here, and what you want for multi-file reasoning, refactors and anything where a wrong answer costs more than a slow one.
• gemini-2.5-flash — the fast tier. Good for repetitive edits, commit messages, and long sessions where latency compounds.
• gemini-2.0-flash — the previous generation's fast model. Reach for it if you have a workflow already tuned against its behaviour.
• gemini-2.0-flash-exp — the experimental build of that model. Treat it as unstable and do not pin a team config to it.

The theme key sits in the same file and takes dark, light or auto. It only affects how the CLI renders in your terminal, so it is worth setting once and forgetting — auto follows your terminal's own preference where that can be detected.

fallbackEnabled and sandbox: the two behaviour toggles

fallbackEnabled is on by default in the form and writes "fallbackEnabled": true. It means that when you hit a rate or quota limit on Pro, the CLI drops to Flash rather than failing your turn. For interactive work this is almost always what you want — a slightly weaker answer beats a dead session mid-task. Turn it off when reproducibility matters more than continuity, for instance when you are benchmarking output quality and a silent model swap would corrupt the comparison.

sandbox writes "sandbox": true and makes the CLI run tool calls inside a container. This one has a prerequisite the tool states in its own help text: it needs Docker or Podman available on the machine. If neither is installed, turning it on will not sandbox anything — it will just fail to start the sandbox. Install a container runtime first, then enable it. Note that Gemini CLI's sandbox is a single boolean, not the graded posture some other agents expose; there is no in-between setting to reach for here.

MCP servers, including the one that is not a subprocess

When you select servers, they land under an mcpServers object inside the same settings.json — there is no separate MCP file to manage. The generator knows four: Filesystem, GitHub, Context7 and Playwright.

Three of them are stdio servers, launched as local subprocesses through npx -y: Filesystem as @modelcontextprotocol/server-filesystem scoped to ., Context7 as @upstash/context7-mcp, and Playwright as @playwright/mcp@latest. Each is a command plus an args array.

GitHub is deliberately different, and this is the detail most worth knowing. Rather than spawning a local process, it is configured as a remote HTTP server:

"github": { "httpUrl": "https://api.githubcopilot.com/mcp/", "headers": { "Authorization": "Bearer $GITHUB_TOKEN" } }

That means no npm package is downloaded and nothing runs on your machine for GitHub access — the CLI talks to GitHub's hosted MCP endpoint and authenticates with a bearer token. Two consequences follow. First, the shape is httpUrl and headers, not command and args; if you are copying an entry from another agent's config you cannot reuse a stdio block here. Second, the token is written as $GITHUB_TOKEN for shell expansion rather than embedded, so export it before starting the CLI. An unset variable expands to an empty bearer token, which fails as an authentication error rather than a configuration error — a misleading symptom worth recognising.

Worked example: Flash with one MCP server

Choose gemini-2.5-flash, the light theme, leave fallback on, leave sandbox off, and tick Context7. The tab shows:

{ "theme": "light", "model": "gemini-2.5-flash", "fallbackEnabled": true, "mcpServers": { "context7": { "command": "npx", "args": ["-y", "@upstash/context7-mcp"] } } }

Note what is absent: no sandbox key, because a false toggle writes nothing rather than writing false, and no API key anywhere. Both are intentional. A settings file that only names what you changed is easier to diff and easier to reason about a year later.

GEMINI.md is the filename — it is not CLAUDE.md or AGENTS.md

The second tab writes GEMINI.md to your repository root. Getting the filename right is not a detail: Gemini CLI looks for GEMINI.md, and a well-written context file saved as CLAUDE.md or AGENTS.md is simply not read. If you work across several agents in the same repository you will end up with more than one of these files, and keeping them in sync is a real maintenance cost worth being deliberate about — one canonical file plus thin per-agent pointers is usually less painful than three full copies drifting apart.

The template is built deterministically from four fields: project name, primary stack, package manager and test command. It produces a Project block, a Commands block covering install, dev, test, build and lint derived from your package manager, a Conventions section about matching surrounding code and keeping changes focused, and a Guardrails section about secrets and destructive actions. The package-manager control only appears for Node.js, Next.js and "Other" stacks — it is hidden for Python, Go, Rust, Java and Ruby, where the concept does not map cleanly. Leave the test command empty and it falls back to <pm> test.

The optional in-browser AI, and where it does not apply

Below the GEMINI.md tab — and nowhere else in this tool — there is a collapsed AI panel. Describe your project in a paragraph and a small model rewrites the context file around your actual specifics: the migration that must run before tests, the generated directory nobody should hand-edit, the framework quirk that keeps costing you a review cycle. A template can state your commands; it cannot know those things.

It runs entirely in your browser over WebGPU using a compact model such as Qwen2.5 1.5B or Llama 3.2 1B. Nothing downloads until you open the panel and explicitly ask, your description never leaves the device, and the model is unloaded when you navigate away. If your browser does not support WebGPU the panel says so and the deterministic template is unaffected. Generated output replaces the tab contents with a visible "revert to template" link, so you can always get the plain version back.

The settings.json tab has no AI involvement at all. That is the right split: a settings file is a small set of exact keys where a generated guess is worse than a picker, and a context file is prose where a model genuinely helps.

Gemini CLI setup problems and their real causes

• Authentication fails despite a correct settings file. The key is not in that file by design. Check echo $GEMINI_API_KEY in the same shell that launches the CLI.
• The sandbox toggle appears to do nothing. Docker or Podman is not installed or not running. The setting is a request, not an implementation.
• The GitHub MCP server returns auth errors. $GITHUB_TOKEN is unset or lacks scope. Because it is a remote HTTP server, failures surface as HTTP errors rather than a process that failed to start.
• An MCP entry copied from another agent does not work. Gemini nests servers under mcpServers inside settings.json; Claude Code uses a separate .mcp.json and Codex uses TOML tables. The inner block often transfers, the surrounding file never does.
• Invalid JSON after hand-editing. A trailing comma is the usual culprit. Regenerate from the form rather than patching by hand.
• GEMINI.md seems ignored. Check the filename and that it is at the repository root, then check its length — it is loaded every session, so a long one dilutes the few rules you actually care about.

Every tab has copy and download buttons, and Reset returns the form and any AI-tailored file to defaults.