LaoHandDeveloper Cheatsheet

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.

AI CLI·55 commands·Last updated 2026-08-05
gemini-cligeminigoogleaicliagentCoding Agent

Typical Use Case

Gemini CLI is best for long-context work: a 2M-token window lets it read whole-repo source/docs for cross-file refactors, architecture analysis, and large batch edits most conversational tools cannot handle. For daily coding, use the interactive terminal to edit code and run tests; for long sessions or repo-wide tasks, put build/test commands in GEMINI.md so every session auto-loads team conventions. Headless via -p -o json feeds one-shot reviews and docgen into scripts or CI. It also connects to your own models (local or custom endpoints) and MCP/extensions — a good fit for teams that want model control and refuse vendor lock-in.

Install & Auth 6

npm install -g @google/gemini-cli
Install globally via npm (Node 20+ required)
gemini --version
Verify install and show version
gemini
First run triggers browser OAuth sign-in
gemini --auth-method=api-key
Switch to API-key auth
export GEMINI_API_KEY="your-key"
Set API key env var (servers/CI)
export GOOGLE_GENAI_USE_VERTEXAI=true
Enterprise / Vertex AI auth

Run Modes 8

gemini
Launch the interactive TUI agent (default)
gemini "Refactor the user-auth module"
Launch the TUI seeded with a prompt
gemini -p "Explain this function"
Headless mode: print and exit (--prompt)
gemini -i "Implement the cache first"
Seed a prompt then stay interactive (--prompt-interactive)
gemini mcp
Manage MCP servers
gemini extensions
Manage Gemini CLI extensions
gemini skills
Manage agent skills (install/link/list)
gemini gemma
Local Gemma model routing (setup/start/stop/status)

Global Flags 15

gemini -m gemini-2.5-pro "task"
Override the model for one invocation (-m/--model)
gemini -y "Refactor the whole module"
Auto-approve all actions (--yolo; prefer --approval-mode=yolo)
gemini --approval-mode plan "Explore architecture"
Read-only plan mode (default/auto_edit/yolo/plan)
gemini -w feat/login
Run in a fresh git worktree (--worktree)
gemini -s
Run tool calls in the configured sandbox (Docker/Podman)
gemini --skip-trust
Trust the current workspace for this session only
gemini --checkpointing
Enable per-edit snapshots, restorable via /restore
gemini -r latest
Resume the previous session (--resume, latest or index)
gemini --list-sessions
Print sessions for the current project and exit
gemini --delete-session 2
Delete a session by index
gemini --include-directories ../backend,../frontend
Add directories to the workspace map
gemini -o json "task"
Output format text/json/stream-json (json for scripting)
gemini -e context7
Restrict the active extension set (--extensions)
gemini -l
List installed extensions and exit (--list-extensions)
gemini --debug
Verbose debug logging (--debug/-d)

Session Slash Commands 14

/help
List all available commands
/model
Switch the active model (Pro/Flash, etc.)
/context
Show current conversation token usage
/compress
Summarize the conversation to free context (past 2M)
/clear
Reset the conversation
/save
Save the conversation to a checkpoint
/restore
Resume a saved conversation
/yolo
Skip all confirmation prompts (use with caution)
/mcp list
List configured MCP servers
/tools
List all available tools
/init
Generate a GEMINI.md for the project
/memory list
View loaded context files
/memory refresh
Reload GEMINI.md without restarting
/quit
Exit

MCP & Extensions 7

gemini mcp add <name> <url>
Add an MCP server
gemini mcp remove <name>
Remove an MCP server
gemini mcp list
List MCP servers
gemini mcp enable <name>
Enable an MCP server
gemini mcp disable <name>
Disable an MCP server
gemini extensions install <name>
Install a Gemini CLI extension
gemini mcp add --url https://example.com/mcp
Add an HTTP MCP server

GEMINI.md & Config 5

echo "Build: make build\nTest: go test ./..." > GEMINI.md
Write GEMINI.md at repo root, auto-loaded each session
@./docs/architecture.md
Inject a file/directory into the prompt with @
!git status
Run a shell command directly inside Gemini with !
echo ".env\nnode_modules/" > .geminiignore
Keep the agent away from secrets and large dirs
cat ~/.gemini/settings.json
Inspect user-level config (model/MCP/tool perms)

Command Examples

Headless run with JSON output for scripts

gemini -p -o json "对比当前代码与最近一次 tag 的 API 差异"

-p 非交互即跑即退，-o json 再配 --save 可把结果落盘，是 CI 自动化的常用组合。

Output

（模型只输出结构化 JSON 供下游脚本消费，例如新增/删除的接口清单与风险提示）

One-shot quick question

gemini "帮我解释这个函数的递归逻辑"

与 -p 相比，无参数的非交互调用同样即跑即退，无需进入 TUI。

Output

（直接在当前终端返回回答后退出，适合查文档片段与做单次决策）

Bootstrap project memory

/init echo "Build: make build\nTest: go test ./..." > GEMINI.md /memory refresh

GEMINI.md 每次会话自动加载，把项目约定沉淀其中可显著减少重复提示；敏感文件用 .geminiignore 排除。

Output

（/init 生成 GEMINI.md 骨架，补充构建/测试命令后 refresh 立刻生效，无需重启会话）

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 json` with --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.

Related Cheatsheets

6 related cheatsheets

Claude Code CLI Cheatsheet - Anthropic AI Coding Agent Full ReferenceFull command reference for Claude Code, Anthropic terminal AI coding agent: install & auth, -p print mode and session resume, --permission-mode/--worktree, dev slash commands, MCP server management, and @ file references, all flags matching official docs.Codex CLI Cheatsheet - OpenAI Terminal Coding Agent Full ReferenceCommand reference for OpenAI Codex CLI, the Rust-built terminal coding agent: install & auth, interactive and non-interactive codex exec, session management, model & config, sandbox and approval modes, MCP, and Codex Cloud.Cursor Editor CLI Cheatsheet - AI Editor Command Line & Agent FlagsCommand-line and Cursor Agent reference for Cursor, the VS Code-based AI editor: opening files/folders, window management, diff compare, extension management, rendering & performance, remote dev, debugging, cursor-agent non-interactive calls, and git core.editor integration.Aider Cheatsheet - Open-Source Terminal AI Pair Programming Full ReferenceCommand reference for Aider, the open-source Apache 2.0 terminal AI pair programmer (100+ models, auto git commits): install, model & reasoning, files & context, chat modes, Git & run, session tools, and advanced usage.OpenCode CLI Cheatsheet - Open-Source TUI AI Coding Agent Full ReferenceCommand reference for OpenCode, the open-source Claude Code-style TUI terminal AI coding agent: launch & resume, CLI flags, session and subcommands (agent/auth/github/mcp/run/serve/web), and interactive slash commands.Goose CLI Cheatsheet - Block / Linux Foundation AAIF Agent Full ReferenceCommand reference for Goose, the open-source general-purpose terminal AI agent (Rust, Apache-2.0, 15+ providers, 70+ MCP extensions; orig. Block, now Linux Foundation AAIF): sessions, runtime, configure, extensions, and diagnostics, including goose session/run/configure/cook/doctor and --resume.

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