Gemini CLI Cheatsheet - Google Terminal AI Agent Full Reference
Gemini CLI is Google open-source terminal AI agent (Apache 2.0) for developers who need very long context and want the model to edit code autonomously against their own models; its 2M-token window fits whole-repository refactoring and analysis. Long context, forkable self-hosting, and GEMINI.md project memory set it apart. This sheet covers install/auth, headless automation (-p -o json), and MCP/extensions.
Typical Use Case
For engineers putting Gemini CLI into daily development and automation pipelines. Six lines map to six situations: installation and authentication, run modes including the interactive TUI and headless -p, global flags, session slash commands, MCP and extension management, and the GEMINI.md project memory. The engineering practice that pays off most is writing build and test commands into GEMINI.md and using .geminiignore to keep secrets and large directories out of context, running automation with approval mode yolo plus JSON output, and using /compress and checkpoints to keep long tasks alive.
Install & Auth 6
npm install -g @google/gemini-cligemini --versiongeminigemini --auth-method=api-keyexport GEMINI_API_KEY="your-key"export GOOGLE_GENAI_USE_VERTEXAI=trueRun Modes 8
geminigemini "Refactor the user-auth module"gemini -p "Explain this function"gemini -i "Implement the cache first"gemini mcpgemini extensionsgemini skillsgemini gemmaGlobal Flags 15
gemini -m gemini-2.5-pro "task"gemini -y "Refactor the whole module"gemini --approval-mode plan "Explore architecture"gemini -w feat/logingemini -sgemini --skip-trustgemini --checkpointinggemini -r latestgemini --list-sessionsgemini --delete-session 2gemini --include-directories ../backend,../frontendgemini -o json "task"gemini -e context7gemini -lgemini --debugSession Slash Commands 14
/help/model/context/compress/clear/save/restore/yolo/mcp list/tools/init/memory list/memory refresh/quitMCP & Extensions 7
gemini mcp add <name> <url>gemini mcp remove <name>gemini mcp listgemini mcp enable <name>gemini mcp disable <name>gemini extensions install <name>gemini mcp add --url https://example.com/mcpGEMINI.md & Config 5
echo "Build: make build\nTest: go test ./..." > GEMINI.md@./docs/architecture.md!git statusecho ".env\nnode_modules/" > .geminiignorecat ~/.gemini/settings.jsonParameter matrix
| Parameter | Effect | Example |
|---|---|---|
npm install -g @google/gemini-cli | Installs globally via npm (requires Node 20+). | npm install -g @google/gemini-cli |
gemini --version | Verifies the install and prints the version. | gemini --version |
gemini (first run) | Triggers a browser OAuth login. | gemini |
--auth-method=api-key | Switches to API key authentication. | gemini --auth-method=api-key |
GEMINI_API_KEY | Sets the API key environment variable (for servers/CI). | export GEMINI_API_KEY="your-key" |
GOOGLE_GENAI_USE_VERTEXAI=true | Enables the Vertex AI authentication method. | export GOOGLE_GENAI_USE_VERTEXAI=true |
gemini "refactor the user-auth module" | Starts the TUI with an initial prompt. | gemini "refactor the user-auth module" |
gemini -p "explain this function" | Headless mode: run then print and exit. | gemini -p "explain this function" |
gemini -i "implement caching first" | Seeds the prompt then stays interactive. | gemini -i "implement caching first" |
gemini -m gemini-2.5-pro | Overrides the model for this call. | gemini -m gemini-2.5-pro "task" |
gemini -y | Auto-approves all actions (now recommended to use --approval-mode=yolo instead). | gemini -y "refactor the whole module" |
--approval-mode plan | Read-only planning mode (default/auto_edit/yolo/plan). | gemini --approval-mode plan "explore the architecture" |
gemini -w feat/login | Runs in a separate git worktree. | gemini -w feat/login |
gemini -s | Runs tool calls inside a configured sandbox (Docker/Podman). | gemini -s |
gemini --skip-trust | Trusts the current workspace for this session. | gemini --skip-trust |
gemini --checkpointing | Enables per-edit snapshots, recoverable with /restore. | gemini --checkpointing |
gemini -r latest | Resumes the previous session (latest or an index). | gemini -r latest |
gemini --list-sessions | Lists the sessions for the current project then exits. | gemini --list-sessions |
gemini --delete-session 2 | Deletes a session by index. | gemini --delete-session 2 |
--include-directories | Adds extra directories to the workspace mapping. | gemini --include-directories ../backend,../frontend |
gemini -o json | Output format text/json/stream-json. | gemini -o json "task" |
gemini -e context7 | Limits the set of extensions loaded this session. | gemini -e context7 |
gemini -l | Lists installed extensions then exits. | gemini -l |
gemini --debug | Prints verbose debug logs. | gemini --debug |
/help | Lists all available commands. | /help |
/model | Switches the active model. | /model |
/context | Shows current conversation token usage. | /context |
/compress | Summarizes the conversation to free up context. | /compress |
/clear / /save / /restore | Reset the conversation / save a checkpoint / restore a session. | /save |
/yolo | Skips all confirmation prompts (use with caution). | /yolo |
/mcp list / /tools | List MCP servers / available tools. | /mcp list |
/init | Generates a GEMINI.md for the project. | /init |
/memory list / /memory refresh | Show loaded context / reload GEMINI.md. | /memory refresh |
gemini mcp add <name> <url> | Adds an MCP server. | gemini mcp add --url https://example.com/mcp |
gemini mcp remove / enable / disable | Remove / enable / disable an MCP server. | gemini mcp disable <name> |
gemini mcp list | Lists MCP servers. | gemini mcp list |
gemini extensions install <name> | Installs a CLI extension. | gemini extensions install <name> |
gemini skills | Manage agent skills (install/link/list). | gemini skills |
echo "build: make build" > GEMINI.md | Writes project memory that is auto-loaded every session. | echo "build: make build\ntest: go test ./..." > GEMINI.md |
@./docs/architecture.md | Injects file/directory contents into the prompt. | @./docs/architecture.md how is this architecture implemented? |
!git status | Runs a shell command directly inside the session. | !git status |
.geminiignore | Keeps the agent away from secrets and large directories. | echo ".env\nnode_modules/" > .geminiignore |
cat ~/.gemini/settings.json | Inspects user-level config (model/MCP/tool permissions). | cat ~/.gemini/settings.json |
Common pitfalls
SymptomThe agent keeps reading .env or searching inside node_modules, wasting time every session with a risk of leaking secrets.
CauseThe agent scans the whole workspace by default, and nothing told it which paths to ignore.
FixAdd a .geminiignore at the project root listing .env, node_modules/, and other sensitive or redundant directories to narrow the workspace mapping.
SymptomMidway through a session the agent repeats conclusions it already gave, slows down, or gets truncated.
CauseThe accumulated tokens are approaching the context limit, squeezing out earlier content and shrinking the model's usable space.
FixCheck the current usage with /context and run /compress to summarize and shrink the history; for long multi-day tasks save a checkpoint with /save and resume with /restore next time.
SymptomA -p run in a script hangs on some step because no one can approve it in a non-interactive environment.
CauseIn the default approval mode tool calls wait for human confirmation, but a headless -p session has no terminal to respond.
FixFor unattended runs specify --approval-mode=yolo explicitly (clearer than -y), and first validate feasibility with --approval-mode plan in read-only mode.
SymptomThe agent modified several files on the current branch and the only way to discard them is manual git recovery.
CauseIt ran directly in the main working tree without checkpointing enabled, so rollback depends entirely on version control.
FixRun with --checkpointing so /restore can roll back, or add -w feat/xxx to work in a separate git worktree and leave the main branch untouched.
SymptomYou want the agent to consult a design doc and it says the file is missing or just makes things up.
CauseThe file is outside the workspace mapping, or it is not referenced explicitly in the prompt.
FixInject it explicitly at the start of the prompt with @./docs/architecture.md; for files outside the workspace add them with --include-directories.
SymptomYou edited GEMINI.md but the agent behaves the same, still following the old conventions.
CauseContext files are loaded at session start, so new content on disk does not take effect automatically.
FixRun /memory refresh to reload, or /memory list to confirm which files are actually loaded right now.
SymptomWith several MCP servers attached startup is noticeably slower and the tool list is too long to find the one you want.
CauseEvery MCP server and extension registers in the session, so the tool count balloons.
FixUse gemini mcp disable to turn off servers you do not need, or -e to limit the extensions loaded this session, and check /tools for what is actually available.
SymptomRuns on CI or a server fail with an auth error while an interactive local login works fine.
CauseYour machine uses browser OAuth credentials, but a headless environment has neither a browser nor a credentials file.
FixFor CI use gemini --auth-method=api-key and export GEMINI_API_KEY beforehand; inside a company you can use GOOGLE_GENAI_USE_VERTEXAI=true to go through Vertex AI.
Troubleshooting
1Confirm the install and authentication are ready.
gemini --version; gemini --auth-method=api-keyGetting output from --version means the global install worked and PATH is in effect. Then set API key auth and export GEMINI_API_KEY to verify the credential path in a headless environment.
2Explore the architecture read-only with no changes allowed.
gemini --approval-mode plan "explore the architecture"In plan mode the agent only reads and analyzes, never edits. Use it to map the project structure first, then switch to default or auto_edit once the task is viable — this avoids hard-to-revert changes from the outset.
3Unattended automated invocation.
gemini -p "task" -o json --approval-mode=yolo-p exits as soon as it finishes, -o json emits machine-parsable output for scripts, and --approval-mode=yolo removes manual confirmation. Together they are the basic CI integration shape; pair with --checkpointing beforehand to keep a way back.
4Manage context usage and keep long tasks alive.
/context → /compress → /saveStart with /context to see current token usage; when nearing the limit run /compress to summarize history and free space; at milestones use /save to store a checkpoint and /restore to continue next time, avoiding restating the background from scratch.
5Check the actual state of MCP and extensions.
gemini mcp list; gemini -l; /mcp list and /tools inside the sessionAn empty list means nothing is configured; if entries are listed but tools cannot be found, use /tools inside the session to confirm they actually registered (a config existing does not mean it is loaded this session).
6Bake project conventions into the memory file.
echo "build: make build\ntest: go test ./..." > GEMINI.md; /memory refreshAfter writing, reload with /memory refresh (or use /memory list to confirm it loaded). Every later session then reads these commands automatically, so the agent need not be told again each time.
7Isolate dangerous operations and keep a rollback path.
echo ".env\nnode_modules/" > .geminiignore; gemini -w feat/login --checkpointing.geminiignore keeps the agent away from secrets and large directories; -w runs in a separate git worktree and --checkpointing keeps edit snapshots, so even an undesirable change can be fully reverted.
Command Examples
Headless run with JSON output for scripts
gemini -p -o json "diff the current code against the API of the most recent tag"-p runs and exits without interaction; combining -o json with --save writes the result to disk — a common combo for CI automation.
Output
(The model emits only structured JSON for downstream scripts, e.g. a list of added/removed endpoints with risk notes.)
One-shot quick question
gemini "help me explain the recursion logic of this function"Compared with -p, a no-argument non-interactive call also runs and exits, without entering the TUI.
Output
(It answers in the current terminal and exits, good for checking doc snippets and making a one-off decision.)
Bootstrap project memory
/init
echo "Build: make build\nTest: go test ./..." > GEMINI.md
/memory refreshGEMINI.md is auto-loaded every session; capturing project conventions there sharply cuts repeated prompting, and sensitive files are excluded via .geminiignore.
Output
(/init creates a GEMINI.md skeleton; after adding build/test commands, refresh takes effect immediately with no session restart.)
Common Pitfalls
- A 2M-long context loads fast, but first-pass latency grows as you stuff in many files — configure GEMINI.md and .geminiignore so node_modules, logs, and other bulk files stay out of context.
- -p headless runs exit immediately with no human to approve file edits and command execution; scope allowed actions in config rather than defaulting to full write access.
- GEMINI.md conventions are auto-followed every session, so editing it or dependencies changes future behavior; use .geminiignore to keep .env-style secrets out of memory files.
- Custom model endpoints may not support all native abilities (e.g., tools, long context); verify behavior consistency in a controlled repo before production.
Tips
- The personal Google account free tier is 1000 requests/day and it is open-source/forkable — the default choice for long-context (2M) and self-hosted use.
- For headless automation use
gemini -p -o jsonwith --approval-mode=yolo (preferred over the deprecated -y) for unattended tasks. - Write build/test commands into GEMINI.md; Gemini auto-loads it each session — more stable than repeating prompts. Use .geminiignore to block .env etc.
- Past the 2M ceiling use /compress to keep going; use /save + /restore to preserve sessions across days.
FAQ
How do I run Gemini CLI headless in CI?
Use -p (--prompt) print mode: it runs the task, prints the result and exits instead of entering the TUI. Supply GEMINI_API_KEY in the environment rather than relying on a local login. For planning jobs add --approval-mode plan to stay read-only, so the agent cannot unexpectedly modify files or run commands on CI.
What is each --approval-mode value for?
plan is read-only and good for exploring an architecture before touching anything. default pauses for confirmation on sensitive actions, which suits day-to-day work. auto_edit permits file edits automatically but still confirms critical operations, and is the usual mode for coding. yolo approves everything and carries the most risk — keep it for disposable containers or one-off environments.
What if the conversation outgrows the context window?
Check /context to see current token usage, and when you approach the limit run /compress to summarize the conversation and continue — it can carry you past the 2M ceiling. To start completely fresh, /clear resets the conversation. When switching to an unrelated task, /clear is cleaner than continuing in the same thread, since leftover context skews the new result.
What do GEMINI.md and .geminiignore do?
GEMINI.md sits at the project root and is loaded automatically on every session, which is where you put conventions such as "build with make build, test with go test ./..." so the agent stops guessing. .geminiignore excludes files it should not read — .env and node_modules/ in particular — keeping secrets out of the context and large directories from slowing responses.
How can I keep Gemini CLI changes out of my current branch?
Use -w / --worktree with a branch name: it creates a fresh git worktree and runs there, isolating the agent's edits from your current working tree so your branch stays clean. Diff or merge when you are done. This is the safest approach for trying several approaches in parallel or for large agent-driven rewrites.
Official References
Each command links to its official documentation below, so you can verify the latest usage and read deeper.
Maintained by LaoHand
Publicly updated on Aug 5, 2026, continuously proofread against official docs.
Contact Us
Wrong command or description? Send us corrections, business inquiries or product feedback by email.
Contact Us