Gemini CLI Cheatsheet - Google Terminal AI Agent Full Reference

SymptomThe agent edited files in the repository while you only wanted it to read the code.

CauseApproval mode was default or yolo, so every tool call was accepted without prompting.

FixRelaunch with --approval-mode plan for exploration, and add .geminiignore entries so the paths you never want touched are outside the map.

SymptomThe agent refuses to act or answers as if it cannot see the project files.

CauseThe session was started from a directory above the repository root, so the workspace map contains no source files.

Fixcd into the project root before launching, and use --include-directories when the relevant code sits in a sibling directory.

SymptomEdits are applied to a branch you did not want to touch, or uncommitted work conflicts with the run.

CauseThe worktree flag was not used and the agent committed or rewrote files in the active checkout.

FixStart the session with -w feat/name to get an isolated worktree, and keep uncommitted changes stashed before the run.

SymptomCI output cannot be parsed because the answer contains commentary around the JSON.

CauseThe output format defaults to text, so the model wraps its answer in prose.

FixPass -o json (or stream-json for incremental output) and parse the response field instead of scraping stdout.

SymptomA long conversation stops accepting new instructions and replies to a truncated history.

CauseThe conversation exceeded the context window, so the earliest turns were dropped.

FixRun /compress to summarise the history, /save to checkpoint it, and use -r latest to resume in a fresh session.

SymptomThe same instruction is obeyed over and over despite /compress, or an edit is reverted on the next turn.

CauseThe project rules in GEMINI.md were not reloaded, so the agent is working from the older instructions.

FixRun /memory refresh, or confirm with /memory list that the expected context files are actually loaded.

SymptomTool calls fail inside the sandbox with a permission error on an otherwise writable path.

CauseThe sandbox container maps only the workspace directory, so any other path resolves outside the sandbox.

FixAdd the needed directory with --include-directories, or drop -s for a run where direct host access is acceptable.

Symptom在 CI / 服务器上跑时报认证错误，本机交互登录却正常

Cause本机走的是浏览器 OAuth 凭据，而无头环境没有浏览器也没有凭据文件。

FixCI 场景改用 gemini --auth-method=api-key 并预先 export GEMINI_API_KEY；企业内可用 GOOGLE_GENAI_USE_VERTEXAI=true 走 Vertex AI。