❯ the loop
claude-code codex-cli cursor-cli gemini-cli
> esc

Gemini CLI / terminal reference

Built from Google's official docs as of 11 July 2026 (Gemini CLI ~v0.50.0). Click any command to copy it. The docs ship in the repo — google-gemini/gemini-cli/docs is the source of truth, and inside a session /help lists what your build actually has.

Cheat sheet Cookbook Changes

Launch

Everything you can type before you're in a session.

npm install -g @google/gemini-cliInstall. gemini update keeps it current.
geminiStart the interactive REPL in the current directory.
gemini "query"Positional prompt: query and continue interactively.
gemini -p "query"Non-interactive. Runs the query, prints, exits. The scripting entry point.
gemini -i "query"Execute the prompt, then stay in interactive mode.
cat file | geminiProcess piped content. -p text is appended to stdin input if both are given.
gemini -r "latest" ["query"]Resume the most recent session, optionally with a new prompt. Also takes an index number or session UUID.
gemini --list-sessionsList saved sessions for this project and exit. Sessions are project-scoped.
gemini --delete-session <n>Delete a session by index number from --list-sessions.
gemini updateUpdate to the latest version.
gemini -v | -hVersion / help.

no matches in this section

CLI flags

Session shape

--prompt, -p | --prompt-interactive, -iNon-interactive / execute-then-stay-interactive.
--resume, -r <latest|n|uuid>Resume a previous session: "latest", an index number, or a session ID.
--worktree, -w [name]Start in a new git worktree; the name is generated if omitted. Requires experimental.worktrees: true in settings.
--include-directories a,bAdditional workspace directories (comma-separated or repeated flags).
--sandbox, -sRun tool execution in a sandboxed environment.
--skip-trustTrust the current workspace for this session, skipping the folder trust check.

Model

--model, -m <alias|name>Model to use. Default auto.
auto | proResolve to gemini-2.5-pro, or the Gemini 3 preview model when preview features are enabled.
flash | flash-litegemini-2.5-flash (fast, balanced) / gemini-2.5-flash-lite (fastest, simple tasks).

Approvals & extensions

--approval-mode <mode>Tool approval mode: default, auto_edit, yolo, plan.
--yolo, -yDeprecated. Auto-approve all actions — use --approval-mode=yolo instead.
--allowed-toolsDeprecated. Tools that run without confirmation — the docs point to the Policy Engine instead.
--allowed-mcp-server-namesRestrict which MCP servers load (comma-separated or repeated).
--extensions, -e | --list-extensions, -lChoose which extensions load (default: all) / list them and exit.

Output & debugging

--output-format, -o text|json|stream-jsonOutput shape for headless runs.
--debug, -dVerbose debug logging.
--screen-readerScreen reader mode for accessibility.
--experimental-acpStart in ACP mode. Experimental.

no matches in this section

Session & history

Typed inside the REPL. Sessions auto-save as you chat — no manual saving required.

Conversation

/clearClear the terminal screen and scrollback. Ctrl+L does the same.
/compressReplace the whole chat context with a summary to reclaim tokens.
/copyCopy the last output to the clipboard. Needs pbcopy/xclip/clip; OSC 52 over SSH.
/stats [session|model|tools]Session statistics: duration, tool calls, token counts, quota.
/shellsToggle the background shells view for long-running processes. Alias /bashes.
/quit [--delete]Exit. --delete also permanently removes this session's history and temp files. Alias /exit.

Resume, rewind, restore

/resumeInteractive session browser: / searches content, x deletes, Enter resumes. Alias /chat.
/resume save <tag> | resume <tag> | list | delete <tag>Manual tagged checkpoints inside a session. Saved per-project under ~/.gemini/tmp/<hash>/.
/resume share [file.md|file.json]Export the conversation to Markdown or JSON.
/rewindWalk back through interactions; revert chat, code changes, or both. Shortcut: Esc Esc.
/restore [checkpoint]Revert project files to the snapshot taken before a tool ran. Requires checkpointing enabled in settings; no arg lists checkpoints.

Context & memory

/memory show | refresh | listInspect or reload the hierarchical GEMINI.md context.
/initAnalyze the current directory and generate a starter GEMINI.md.
/directory add <p1>,<p2> | showAdd workspace directories mid-session. Alias /dir; disabled in restrictive sandboxes.

no matches in this section

Approval modes & plan mode

Cycle with Shift+Tab, set at launch with --approval-mode, or persist via /settings.

defaultPrompt before tool execution.
auto_editAuto-approve edits; other tools still prompt.
planRead-only research mode. Skipped in the Shift+Tab cycle while the agent is busy.
yoloAuto-approve everything. Toggle with Ctrl+Y; the enter_plan_mode tool is unavailable in this mode.

Plan mode

/plan [goal]Switch to Plan Mode, optionally submitting the goal immediately. View the current plan if one exists.
/plan copyCopy the approved plan to the clipboard.
gemini --approval-mode=planLaunch straight into Plan Mode.
Allowed in plan modeRead/search tools, research subagents, read-only MCP tools, activate_skill; writes only to .md plan files in the plans directory.
Ctrl+XWhile a plan is presented: open it in an external editor to edit or comment collaboratively.
Approving a planExits Plan Mode and starts implementation. Or exit any time via Shift+Tab or by asking to stop planning.

no matches in this section

MCP, extensions & subagents

MCP servers

gemini mcp add <name> <command>Add a stdio MCP server. --transport http <url> for HTTP, --env KEY=value, --scope user, --include-tools t1,t2.
gemini mcp list | remove <name>List configured servers / remove one.
/mcp [list|desc|schema]In-session server + tool listing, with descriptions or full schemas.
/mcp auth <server>Run an OAuth flow; with no name, lists servers that support OAuth.
/mcp enable | disable <server> | reloadToggle servers or re-discover their tools.

Extensions

gemini extensions install <git-url|path>Install from a repo or local path. --ref <branch> pins, --auto-update opts in.
gemini extensions list | update <name>|--all | uninstall <name>Inventory and lifecycle.
gemini extensions new <path> | link <path> | validate <path>Scaffold from a template / symlink for development / check structure.
/extensions [list|enable|disable|update|restart|explore]The same management, in-session.

Subagents

/agents list | enable <name> | disable <name>Manage local and remote subagents (built-in, ~/.gemini/agents, .gemini/agents).
/agents config <name>Dialog for a subagent's model, temperature, and execution limits.
/agents reloadRescan agent directories and reload the registry. Alias refresh.

no matches in this section

Skills & custom commands

Skills follow the agentskills.io standard: on-demand expertise the model activates with your consent. Custom commands are .toml prompt shortcuts.

Agent skills

/skills list [all] [nodesc]Discovered skills and status. all includes built-ins.
/skills enable | disable <name>Defaults to user scope; --scope workspace for project-level.
/skills link <path> [--scope user|workspace]Link skills from a local directory.
/skills reloadRefresh discovery across all tiers. Alias refresh.
gemini skills install <git|path> [--consent] [--path <subdir>]Install from the terminal; --consent skips the security confirmation.
gemini skills list --all | uninstall <name> [--scope]Terminal-side inventory and removal.
Discovery tiersBuilt-in → extension → user (~/.gemini/skills/) → workspace (.gemini/skills/); the .agents/skills/ alias wins within a tier.

Custom commands (.toml)

~/.gemini/commands/test.tomlGlobal command /test. Project commands in .gemini/commands/ override same-named user commands.
git/commit.toml → /git:commitSubdirectories namespace with a colon.
prompt = "…" / description = "…"prompt is required; description shows in /help and defaults to filename-derived text.
{{args}}Injected raw in prompt text, but shell-escaped inside !{…} blocks to prevent command injection.
!{grep -r {{args}} .}Shell blocks run and inline their output; the CLI confirms the exact command first.
/commands list | reloadSee every .toml source / pick up changes without restarting.

no matches in this section

Config & environment

In-session

/settingsSettings editor with validation — the safe way to edit .gemini/settings.json.
/theme | /editorPick the color theme / the external editor.
/vimToggle vim editing (NORMAL/INSERT, counts, dd/cw/. etc.). Persists to ~/.gemini/settings.json.
/auth | /privacySwitch authentication method / review the privacy notice and data-collection consent.
/permissions trust [dir]Manage folder trust settings.
/policies listActive policy-engine rules, grouped by mode.
/hooks [list|enable|disable <name>|enable-all|disable-all]Manage lifecycle hooks.
/model manage | set <name> [--persist]Model dialog / direct switch.
/tools [desc]List available tools, optionally with the full descriptions the model sees.
/ide [status|install|enable|disable]IDE integration.
/terminal-setupConfigure multiline-input keybindings for VS Code, Cursor, Windsurf.
/about | /docs | /bug <headline> | /helpVersion info / open docs / file a GitHub issue / command help.
/setup-githubGitHub Actions for issue triage and PR review with Gemini.

Environment variables

GEMINI_API_KEY | GOOGLE_API_KEYGemini API key / Google Cloud key (Vertex AI express mode). Loaded from .env files, nearest first, then ~/.env.
GOOGLE_CLOUD_PROJECT [+ GOOGLE_CLOUD_LOCATION]Required for Code Assist or Vertex AI.
GEMINI_MODELDefault model override.
GEMINI_SANDBOX=true|docker|podman|<cmd>Sandbox method; SEATBELT_PROFILE picks the macOS profile (permissive-open default, strict-open, …).
GEMINI_CLI_TRUST_WORKSPACE=trueTrust the workspace for the session — useful in CI.
GEMINI_SYSTEM_MD [+ GEMINI_WRITE_SYSTEM_MD]Replace the built-in system prompt from a file / dump the current one for review.
NO_COLOR | CLI_TITLE | DEBUGDisable color / retitle the CLI / verbose logging (DEBUG is ignored in project .env; use .gemini/.env).

no matches in this section

Keyboard & input

Press ? on an empty prompt for the shortcuts panel. Rebind anything in ~/.gemini/keybindings.json (VS Code-style; prefix - unbinds).

Input prefixes

/Slash commands: built-ins plus your custom .toml commands.
@path/to/file-or-dirInject file or directory contents into the prompt, git-aware filtered. Escape spaces: @My\ Docs/file.txt.
!cmd · ! aloneRun one shell command / toggle shell mode. Subprocesses see GEMINI_CLI=1.

Control

EscDismiss dialogs or cancel the current focus.
Esc EscClear the prompt — or, when it's empty, open rewind.
Shift+TabCycle approval modes: default → auto-edit → plan.
Ctrl+YToggle YOLO auto-approval.
Ctrl+C / Ctrl+DCancel the request, quit when input is empty / exit on an empty buffer.
TabQueue a message while the agent works; also accepts suggestions. Tab Tab toggles minimal vs full UI.
Ctrl+Enter / Shift+Enter / Ctrl+J / \ + EnterInsert a newline without submitting.
Ctrl+GOpen the prompt (or a presented plan) in your external editor.
Ctrl+RReverse-search prompt history. Ctrl+P/Ctrl+N step through it.
Ctrl+VPaste, including images, from the clipboard.
Ctrl+OExpand/collapse content blocks and [Pasted Text: …] placeholders.
Ctrl+TToggle the full TODO list.
Ctrl+BToggle visibility of the current background shell; Tab/Shift+Tab move focus between shell and Gemini.
Ctrl+SToggle mouse mode (scrolling and clicking).
Alt+MToggle Markdown rendering.
F12Debug console with keystroke logging — see exactly what your terminal sends.
Space (hold)Push-to-talk in Voice Mode.
Ctrl+Z / Ctrl+Shift+ZUndo / redo in the input field. Ctrl+Z suspends the CLI when not editing.

no matches in this section

Headless & scripting

Triggered by -p or any non-TTY environment.

gemini -p "query" -o jsonSingle JSON object: response, stats, optional error.
gemini -p "query" -o stream-jsonJSONL event stream: init, message, tool_use, tool_result, error, result.
exit codes0 success · 1 general/API error · 42 input error · 53 turn limit exceeded.
GEMINI_CLI_TRUST_WORKSPACE=true gemini -p …Skip the folder-trust prompt in CI.

no matches in this section

File map

~/.gemini/settings.jsonUser settings, all projects.
.gemini/settings.jsonProject settings — override user settings; commit them.
/etc/gemini-cli/settings.jsonSystem overrides (admin); system-defaults.json sits below everything. macOS: /Library/Application Support/GeminiCli/.
GEMINI.mdHierarchical instructional context: global, project and ancestors, subdirectories. /memory show inspects the merge.
.gemini/.envProject env vars, always loaded (plain .env files skip DEBUG etc.).
~/.gemini/keybindings.jsonKeybinding overrides, VS Code-style.
~/.gemini/commands/ · .gemini/commands/Custom .toml commands, user and project scope.
~/.gemini/skills/ · .gemini/skills/Skill tiers; .agents/skills/ alias is tool-interoperable and wins within a tier.
~/.gemini/agents/ · .gemini/agents/Subagent definitions, rescanned by /agents reload.
~/.gemini/tmp/<hash>/chats/Auto-saved sessions, per project. Retention defaults to 30 days.
~/.gemini/history/<hash>Shadow git repo holding checkpoint snapshots — never touches your own repo.
.gemini/sandbox-macos-<name>.sbCustom macOS Seatbelt profiles; .gemini/sandbox.Dockerfile for containers.

no matches in this section