Installing Gemini CLI and writing GEMINI.md: getting started with a free Google account
Install Google's Gemini CLI, sign in with a Google account or API key, run your first task, and learn where GEMINI.md lives, how it is loaded, and how to check it with /memory.
Contents
Gemini CLI is Google's open-source coding agent for the terminal. Its standout feature is that a personal Google account is enough to start using it for free, within rate limits.
This article walks through installation, sign-in and the first task, then explains GEMINI.md, the file that tells Gemini CLI about your project.
KEY POINT
What you will learn
- Installation and sign-in with a Google account or API key
- Where GEMINI.md lives, how it is loaded, and how to inspect it
- A GEMINI.md template you can adapt
Requirements
| Item | Detail |
|---|---|
| Node.js | 20 or later |
| OS | macOS, Linux, Windows |
| Account | Personal Google account (free tier), a Gemini API key, or Google Cloud (Vertex AI) |
Installation
# global install with npm
npm install -g @google/gemini-cli
# or Homebrew on macOS / Linux
brew install gemini-cli
# or MacPorts on macOS
sudo port install gemini-cli
# or try it without installing
npx @google/gemini-cliThe official README lists four routes: npm, Homebrew, MacPorts and Anaconda. Homebrew covers Linux as well as macOS.
gemini --versionSigning in
Run gemini in your project directory. The first start asks how you want to authenticate.
cd path/to/project
gemini| Method | Notes |
|---|---|
| Google account | Browser sign-in. A personal account gets the free tier |
| Gemini API key | Issued in Google AI Studio; set GEMINI_API_KEY |
| Vertex AI | Through a Google Cloud project; for organizations |
# using an API key
export GEMINI_API_KEY="your-key"First task
Explain the structure of this repository and how to run the testsGemini CLI reads files and runs commands as needed, asking before it changes files or executes commands. Choosing "always allow" skips the prompt for that kind of action for the rest of the session.
Useful commands during a session:
| Command | What it does |
|---|---|
/help | List commands |
/memory show | Show the loaded GEMINI.md content |
/memory refresh | Reload GEMINI.md |
/tools | List available tools |
/mcp | MCP server status |
/stats | Token usage |
/clear | Clear the screen and history |
GEMINI.md: role and locations
Gemini CLI looks for GEMINI.md at start-up and treats it as project context, the same role CLAUDE.md plays for Claude Code and AGENTS.md for Codex.
| Location | Purpose |
|---|---|
~/.gemini/GEMINI.md | Personal preferences for all projects |
GEMINI.md at the repository root | Shared project rules |
GEMINI.md in a subdirectory | Extra rules loaded when working in that directory |
The files are concatenated; /memory show displays the result.
用語解説
context.fileName: Set fileName inside the context object in settings.json to make Gemini CLI read a different file name, such as AGENTS.md. Useful when you want to share one context file with Codex.
A GEMINI.md template
# Project overview
Django + React internal tool. Backend in `backend/`, frontend in `frontend/`.
## Commands
- Backend tests: `cd backend && pytest`
- Frontend tests: `cd frontend && npm test`
- Lint: `cd backend && ruff check .` / `cd frontend && npm run lint`
- Dev server: `docker compose up`
## Conventions
- Python: type hints required; no `Any`
- React: function components only; use the existing Zustand store for state
- API schemas live in `backend/api/schemas/`; regenerate frontend types with the generator
## Do not modify
- Existing files under `backend/migrations/`
- `frontend/src/generated/`
## Workflow
- Read related tests before changing code
- Present a plan before changes spanning several files
- Include the commands you ran and their results in the completion report/init generates a first draft from the project. Trim anything the README already says and keep only the agreements you cannot see in the code, the same approach as in How to write CLAUDE.md.
Saving notes during a session
/memory add <text> appends the text to your user-level GEMINI.md. Anything you keep repeating is worth saving this way so it carries over to the next session.
Summary
- Install with
npm install -g @google/gemini-cli, rungemini, sign in with a Google account - GEMINI.md is merged from
~/.gemini/, the repository root and subdirectories - Check what is loaded with
/memory show; reload with/memory refresh - Generate a draft with
/init, then keep it to commands, conventions, no-go areas and workflow
FAQ
- Is Gemini CLI really free?
- Signing in with a personal Google account gives you a free tier with per-minute and per-day request limits. For heavier or commercial use, switch to an API key or Vertex AI.
- Can I install Gemini CLI with Homebrew?
- Yes. The official README lists brew install gemini-cli for macOS and Linux. To pick a release channel (preview, latest or nightly) you need the npm tags instead.
- Where does GEMINI.md go?
- Global preferences in ~/.gemini/GEMINI.md, shared project rules at the repository root, and directory-specific rules in that directory.
- How do I see which GEMINI.md files are loaded?
- Run /memory show during a session. After editing, /memory refresh reloads them.
Questions & answers
Q. Gemini CLI says a node_modules path "resolves outside the allowed workspace directories" when I run list_directory on it, but it is inside my project. Why?
The message does not describe the actual cause, which is why changing your workspace configuration does not help.
The error reads:
Path not in workspace: Attempted path "/home/you/node_modules" resolves outside
the allowed workspace directoriesIt says the path is outside the workspace, but the reported case is a node_modules directory inside the project. Tracing the source, the reporter found that any path containing a node_modules, .git or .env segment is blocked unconditionally, after which the workspace containment check returns false and the tool falls back to the "outside workspace" message. That is the reporter's analysis, not documented behaviour.
Adding directories to the workspace will not fix it, because the cause is different. The documented way to add directories exists for directories genuinely outside your workspace:
gemini --include-directories ../lib,../docsIf you need the agent to look at a dependency's contents, the options today are:
| Approach | What to do |
|---|---|
| Don't pass the path | Ask about the dependency's implementation and let the model locate it |
| Copy the file in | Copy the specific file into your working directory first |
The same message can also mean what it says
If you see this error for a path that contains none of node_modules, .git or .env, it is literally outside the workspace, and --include-directories is the fix. Whether those three names appear in the path is how you tell the two cases apart.
Note that v0.65.0 optimised ignore filtering and enabled subtree pruning (PR #29582). That is a file-discovery speed change, not a fix for this error. For the rest of that release, see Gemini CLI v0.65 enforces read-only settings in untrusted folders.
Q. Gemini CLI's sandbox fails with EACCES during builds when I run it under rootless podman.
Rootless podman uses a user namespace by default, so the UID inside the container does not map directly to your host UID. Bind-mounted files then become unwritable, and tools that recreate build directories — node-gyp, for one — fail with EACCES.
Gemini CLI provides a hook for passing arbitrary flags to the container runtime. The documentation states that for container-based sandboxing you can inject custom flags into the docker or podman command using the SANDBOX_FLAGS environment variable. Multiple flags are space-separated.
The podman flag that lines the UIDs up is --userns=keep-id:
export GEMINI_SANDBOX=podman
export SANDBOX_FLAGS="--userns=keep-id"
gemini --sandboxIf you also hit mount permission errors on a system with SELinux enabled (Fedora and relatives), add the flag the documentation gives as its example:
export SANDBOX_FLAGS="--userns=keep-id --security-opt label=disable"One caveat: --userns=keep-id is a podman flag, and the example the Gemini CLI documentation shows is --security-opt label=disable. --userns=keep-id itself does not appear in the official docs — what is documented is the SANDBOX_FLAGS mechanism for passing runtime flags through.
GEMINI_SANDBOX accepts true, docker, podman, sandbox-exec, runsc and lxc. Use --security-opt label=disable only where you need it, since it turns off SELinux labeling.
Primary sources
This article was drafted by AI from official documentation and reviewed by the site operator before publishing. Found a mistake? Let us know via the contact page.