Gemini CLI cheat sheet
The stuff you actually need. Updated 2026-03-14.
🚀 Get productive in 30 seconds
- 1. Install: npm i -g @google/gemini-cli or brew install gemini-cli
- 2. Authenticate with a Google account or export GEMINI_API_KEY, then run gemini
- 3. Use gemini -p "summarize this repo" for one-shot tasks and plain gemini for the full TUI
- 4. Hit /plan for read-only planning, /tools to inspect available tools, and /model set gemini-2.5-pro --persist if you want a stronger default model
- 5. If you are touching untrusted code, start with gemini -s or set tools.sandbox in ~/.gemini/settings.json
// daily_workflows
The things you'll actually do every day.
Fast one-shot repo question
headlessqafastAsk a direct question without opening the interactive UI.
gemini -p "Explain the auth flow in this repo" Structured output for scripts
automationjsonciUse JSON output so shell scripts can parse the answer, token stats, and tool usage.
gemini -p "Generate release notes from git log" --output-format json | jq -r '.response' Plan before changing code
planningsaferead-onlySwitch to read-only planning mode to inspect a codebase and draft a sequence of edits.
gemini
# then run: /plan Use extra directories as context
monorepocontextworkspaceBring sibling packages or docs into the workspace context without moving directories.
gemini --include-directories ../docs,../packages/shared Run in ACP mode
acpintegrationagentsUse Agent Communication Protocol mode when integrating Gemini CLI into agentic tooling or orchestrators.
gemini --acp "analyze this repository and return a task plan" ⚡ power_moves
Stuff most people don't know about.
Create reusable slash commands
Store repeatable prompts in ~/.gemini/commands or .gemini/commands as TOML files, including file injection and shell output injection.
mkdir -p .gemini/commands/git && $EDITOR .gemini/commands/git/commit.toml Turns recurring prompts like commit writing, code review, and changelog updates into one-command muscle memory.
Bundle capabilities with extensions
Install extensions that package custom commands, MCP servers, prompt context, and tool exclusions.
gemini extensions install https://github.com/gemini-cli-extensions/security Best way to share team workflows or add specialized commands without manually copying config files.
Enable browser automation when text tools are not enough
Turn on the experimental browser_agent and optionally a visual model for UI-driving tasks.
# configure ~/.gemini/settings.json with agents.overrides.browser_agent.enabled=true Useful for sites or flows where DOM text extraction alone is insufficient and you need accessibility-tree or visual browser control.
Use MCP servers for custom tools
Connect stdio, SSE, or HTTP MCP servers via mcpServers in settings.json and selectively include or exclude tools.
# add mcpServers in ~/.gemini/settings.json, then use /mcp list Lets Gemini talk to internal APIs, docs search, issue trackers, or bespoke local tooling without patching the CLI itself.
Prefer sandbox plus plan mode on risky repos
Combine read-only planning with sandboxed execution for safer exploration of unfamiliar or untrusted projects.
gemini -s
# then run: /plan Reduces the chance of accidental edits or shell damage while still letting you explore deeply.
🔥 common_gotchas
Save yourself 30 minutes of debugging.
The browser agent is not available by default.
Enable experimental agents and explicitly enable browser_agent in settings before expecting browser automation to work.
Custom commands that use !{...} can surprise you with shell execution.
Remember Gemini CLI asks for confirmation, keep commands simple, and use argument placeholders carefully because shell blocks escape arguments differently than raw prompt text.
OAuth MCP auth needs a real browser on the local machine.
Do not expect /mcp auth to succeed from a headless box without local browser/redirect support; authenticate from a local desktop session instead.
Project and user settings merge across multiple layers.
Check ~/.gemini/settings.json, .gemini/settings.json, env vars, and CLI args when behavior feels inconsistent because later layers override earlier ones.
Sandboxing can break commands that need broader filesystem or network access.
Switch to a more permissive seatbelt profile, use a container image with needed tools preinstalled, or temporarily disable sandboxing for the exact task.
Subagents are experimental and operate more aggressively than normal flows.
Treat them as advanced tooling, enable only when needed, and understand the current docs warn they can run in a YOLO-like confirmation model.
📋 cli_flags
----prompt, --p Run headless with a one-shot prompt instead of opening the interactive TUI.
Automation, CI, shell scripts, and fast single questions.
gemini -p "Review this diff for security issues"
----model, --m Choose the Gemini model for the current run.
Switch between speed and capability depending on task size.
gemini -m gemini-2.5-flash
----output-format Select response format such as text or json for headless runs.
Pipe results into jq or other tooling.
gemini -p "Summarize this changelog" --output-format json
----include-directories Add extra directories to the workspace context.
Monorepos and adjacent-docs workflows.
gemini -p "Compare code and docs" --include-directories ../docs,../sdk
----all-files, --a Include all files in context for the current run.
Broad codebase analysis when you want maximal context.
gemini -p "Find dead code" -a
----sandbox, --s Enable sandboxing for tool execution; can use built-in or configured sandbox backends.
Safer operation on untrusted code or risky commands.
gemini -s -p "run tests and explain failures"
----yolo, --y Auto-approve actions.
Fast local workflows when you intentionally want fewer approval prompts.
gemini -p "apply the obvious fix" --yolo
----approval-mode Set approval behavior, including auto_edit and plan-oriented modes.
Tuning how interactive or hands-off tool execution should be.
gemini -p "refactor this module" --approval-mode auto_edit
----acp Run in ACP mode; this replaced the older experimental ACP flag name.
Agent-to-agent integrations and external orchestration.
gemini --acp "inspect the repo and emit a plan"
----debug, --d Enable debug logging for troubleshooting.
Diagnosing auth, sandbox, tool, and transport problems.
gemini -d -p "why is this MCP server failing" / commands
/plan Switch to Plan Mode, a read-only mode for exploring and drafting changes safely.
💡 Great first move in unfamiliar repos; pair it with sandboxing for extra safety.
/model set Switch the current model, optionally persisting the choice.
💡 Use flash for quick sweeps, then pro for final reasoning-heavy passes.
/mcp List, authenticate, enable, disable, and refresh configured MCP servers.
💡 If a tool disappears after config changes, try /mcp refresh.
/extensions Manage installed extensions from within the CLI.
💡 Extension changes usually require a restart to affect active sessions.
/commands reload Reload custom slash commands from user, project, MCP prompt, and extension sources.
💡 Use this after editing .toml command files instead of restarting.
/memory refresh Reload hierarchical GEMINI.md memory and context files.
💡 Useful after updating GEMINI.md or adding context directories.
/resume Browse and resume prior sessions or manage manual checkpoints.
💡 All chats are auto-saved, so use this liberally instead of manually recreating context.
/skills List, enable, disable, and reload Agent Skills.
💡 If a skill folder exists but does not appear, run /skills reload.
💡 pro_tips
- › For automation, prefer --output-format json so you get both the response and usage/tool stats in one payload.
- › Use /plan before giving a broad refactor prompt; it tends to produce cleaner decompositions and fewer accidental edits.
- › Put team conventions in GEMINI.md and refresh memory instead of re-pasting long instructions each session.
- › Use project-scoped custom commands in .gemini/commands for workflows you want teammates to share through git.
- › When an MCP server exposes many tools, filter aggressively with includeTools or excludeTools to avoid wasting context.
⚙️ configuration
model.name Default Gemini model for conversations.
default: unset / provider default
recommended: gemini-2.5-pro for deeper coding work, or gemini-2.5-flash for speed-first sessions
tools.sandbox Enable sandboxing and optionally specify the sandbox backend such as docker.
default: unset
recommended: true or "docker" for risky repos and untrusted code
context.includeDirectories Additional directories to include in workspace context.
default: []
recommended: Add sibling packages or docs in monorepos instead of copying files around
tools.allowed Allowlist trusted tools or shell command prefixes that bypass confirmation.
default: unset
recommended: Only allow low-risk repetitive commands like git status or npm test
mcpServers Define stdio, SSE, or streamable HTTP MCP servers and per-server trust, headers, filters, and timeouts.
default: {}
recommended: Keep trust=false by default and include only the tools you actually need
experimental.enableAgents Enables experimental subagent support.
default: false
recommended: Enable only if you actively need subagents and understand the current safety tradeoffs
agents.overrides.browser_agent.enabled Turns on the browser automation agent.
default: false
recommended: true only when you need browser-driven tasks and have a supported Chrome setup
telemetry.enabled Controls telemetry logging and metrics collection.
default: provider-dependent / feature default
recommended: Review and set explicitly in team or enterprise environments