Gemini CLI reference

Show version info. Share this information when filing issues.

Manage local and remote subagents.

sub-commands: list, reload (alias refresh), enable, disable, config

Open a dialog that lets you change the authentication method.

File an issue about Gemini CLI; the text after /bug becomes the headline. Configurable via advanced.bugCommand.

Alias for /resume, exposing the same session browser and checkpoint subcommands.

sub-commands: debug, delete <tag>, list, resume <tag>, save <tag>, share [filename]

Clear the conversation context and start a new session, also clearing the terminal screen and scrollback.

Manage custom slash commands loaded from .toml files.

sub-commands: list, reload

Replace the entire chat context with a summary to save tokens.

Copies the last output produced by Gemini CLI to your clipboard.

Manage workspace directories for multi-directory support.

alias: /dir; sub-commands: add, show

Open Gemini CLI documentation in your browser.

Open a dialog for selecting supported editors.

Manage extensions.

sub-commands: config, disable, enable, explore, install, link, list, restart, uninstall, update

Display help information about Gemini CLI, including available commands.

alias: /?

Manage hooks that intercept and customize behavior at lifecycle events.

sub-commands: disable-all, disable <hook-name>, enable-all, enable <hook-name>, list (show, panel)

Manage IDE integration.

sub-commands: disable, enable, install, status

Analyzes the current directory and generates a tailored GEMINI.md context file.

Manage configured MCP servers; list is the default action.

sub-commands: auth, desc, disable, enable, list (ls), reload, schema

Manage hierarchical instructional memory loaded from GEMINI.md files.

sub-commands: list, refresh, reload, show, inbox

Manage model configuration.

sub-commands: manage, set

Manage folder trust settings and other permissions.

sub-commands: trust

Switch to read-only Plan Mode and view the current plan; an optional goal is submitted immediately.

sub-commands: copy; disable via general.plan.enabled

Manage policies; list shows all active policies grouped by mode.

sub-commands: list

Display the Privacy Notice and select data-collection consent.

Exit Gemini CLI. --delete also permanently deletes the current session's history and temporary files.

alias: /exit; flags: --delete

Restore project files to the state before a tool ran; lists checkpoints when run without an ID. Requires checkpointing.

Navigate backward through conversation history, optionally reverting chat state and file changes.

shortcut: press Esc twice

Browse and resume auto-saved sessions and manage manual chat checkpoints.

alias: /chat; sub-commands: list, save <tag>, resume <tag> (load), delete <tag>, share [filename], debug

Open the settings editor to view and modify settings with validation.

Toggle the background shells view for long-running processes.

alias: /bashes

Set up GitHub Actions to triage issues and review PRs with Gemini.

Manage Agent Skills.

sub-commands: disable <name>, enable <name>, list [all] [nodesc], link <path> [--scope user|workspace], reload (refresh)

Display detailed statistics for the current session.

sub-commands: session (default), model, tools

Configure terminal keybindings for multiline input (VS Code, Cursor, Windsurf).

Open a dialog to change the visual theme.

Display the list of currently available tools.

sub-commands: desc (descriptions), nodesc (nodescriptions)

Open the Gemini Code Assist upgrade page. Only available when logged in with Google.

Toggle vim mode with NORMAL and INSERT modes; the preference persists in ~/.gemini/settings.json.

In-session status panel for local Gemma model routing.

Inject file content into the prompt (directories are passed for the model to inspect); git-ignored files excluded by default.

escape spaces with a backslash

Run a shell command (bash, or powershell.exe on Windows); a lone ! toggles shell mode. Sets GEMINI_CLI=1 in the subprocess.

Run in debug mode with verbose logging. Open the debug console with F12 to see the additional logging.

boolean; default: false

Show CLI version number and exit.

Show help information about command-line arguments.

Model to use for this session. Accepts aliases (auto, pro, flash, flash-lite) or concrete model names.

string; default: auto

Prompt text, appended to stdin input if provided. Forces non-interactive mode.

string

Execute the prompt and continue in interactive mode. Cannot be used when piping input from stdin.

string

Start Gemini in a new git worktree; a name is generated if none is given. Requires experimental.worktrees: true.

string (optional name)

Run in a sandboxed environment for safer execution.

boolean; default: false

Trust the current workspace for this session, skipping the folder trust check.

boolean; default: false

Approval mode for tool execution: default prompts, auto_edit auto-approves edit tools, yolo auto-approves all, plan is read-only. Cannot be combined with --yolo.

string; choices: default, auto_edit, yolo, plan; default: default

Deprecated. Auto-approve all actions; use --approval-mode=yolo instead.

boolean; default: false

Starts the agent in Agent Client Protocol (ACP) mode, JSON-RPC over stdio for IDE and tool integrations.

boolean

Start in ACP mode. Experimental feature.

boolean

Run in Zed editor integration mode. Experimental feature.

boolean

Allowed MCP server names for the session (comma-separated or multiple flags).

array

Deprecated; use the Policy Engine instead. Tools allowed to run without confirmation.

array

List of extensions to use; all are enabled if omitted. Use -e none to disable all extensions.

array

List all available extensions and exit.

boolean

Resume a previous session by "latest", index number, or session UUID; defaults to "latest".

string

List available sessions for the current project and exit.

boolean

Delete a session by index number or full session UUID.

string

Additional workspace directories (comma-separated or multiple flags). 5 directories can be added at maximum.

array

Enable screen reader mode for accessibility.

boolean

Output format for non-interactive mode.

string; choices: text, json, stream-json; default: text

Path to a file with fake model responses for testing.

string (path)

Path to a file to record model responses for testing.

string (path)

Supplemental admin policy path; ignored if .toml policy files exist in the standard system location.

string (path)

Positional prompt. Defaults to interactive mode in a TTY; use -p/--prompt for non-interactive execution.

string (variadic)

Configuration scope: user (~/.gemini/settings.json) or project (.gemini/settings.json).

user or project; default: "project"

Transport type for the server.

stdio, sse, http; default: "stdio"

The git ref (branch, tag, or commit) to install.

Update to the latest version.

Install an extension from a GitHub URL or local path.

<source> [--ref <ref>] [--auto-update] [--pre-release] [--consent] [--skip-settings]

Uninstall one or more extensions.

<name...>

List all installed extensions.

Update an extension, or all extensions with --all.

<name> | --all

Re-enable a disabled extension.

<name> [--scope user|workspace]

Disable an extension entirely or for a specific workspace.

<name> [--scope user|workspace]

Symlink a local development directory into the extensions directory.

<path>

Create a new extension from a built-in template (for example mcp-server, context, custom-commands).

<path> [template]

Validate extension structure.

<path>

Update an extension's settings.

<name> [setting] [--scope <scope>]

Add an MCP server to user or project settings.json. Options: -s/--scope, -t/--transport, -e/--env, -H/--header, --timeout, --trust, --description, --include-tools, --exclude-tools.

[options] <name> <commandOrUrl> [args...]

List configured MCP servers with configuration and connection status. Has no flags.

Delete a server from the mcpServers object in settings.json.

<name> [-s, --scope]

Re-enable a disabled MCP server; --session applies only to this session.

<name> [--session]

Temporarily disable an MCP server without removing its configuration.

<name> [--session]

List all discovered agent skills.

Install a skill from Git, a path, or a file.

<source> [--scope] [--path] [--consent]

Link local agent skills via symlink.

<path>

Uninstall an agent skill.

<name> [--scope user|workspace]

Enable an agent skill, or all skills with --all.

<name> | --all

Disable an agent skill, or all skills with --all.

<name> | --all

Trust the current folder, so stdio MCP servers are tested and shown as Connected.

Full local Gemma routing install (binary, model, settings, server start). Flags: --port, --no-start, --force, --skip-model.

[--port] [--no-start] [--force] [--skip-model]

Health check showing what is installed and running.

Start the LiteRT server (auto-starts on CLI launch by default).

Stop the LiteRT server.

Tail the server logs to see routing requests live.

Cancel the current request or quit the CLI when input is empty.

default keys: Ctrl+C

Exit the CLI when the input buffer is empty.

default keys: Ctrl+D

Start reverse search through history.

default keys: Ctrl+R

Insert a newline without submitting.

default keys: Ctrl+Enter, Cmd/Win+Enter, Alt+Enter, Shift+Enter, Ctrl+J

Queue the current prompt to run after the current task finishes.

default keys: Tab

Open the current prompt or the plan in an external editor.

default keys: Ctrl+G, Ctrl+Shift+G

Toggle the debug console for detailed error information.

default keys: F12

Toggle the full TODO list.

default keys: Ctrl+T

Toggle YOLO (auto-approval) mode for tool calls.

default keys: Ctrl+Y

Cycle approval modes: default, auto_edit, plan (plan skipped when the agent is busy).

default keys: Shift+Tab

Clear the terminal screen and redraw the UI (keeps conversation context).

default keys: Ctrl+L

Toggle Markdown rendering.

default keys: Alt+M

Toggle current background shell visibility.

default keys: Ctrl+B

Pressed twice quickly: clear the input if not empty, otherwise browse and rewind previous interactions.

Toggle the shortcuts panel above the input.

Default approval mode for tool execution. YOLO can only be enabled via the command line.

enum; default: "default"; values: "default", "auto_edit", "plan"

Enable Vim keybindings.

boolean; default: false

Enable session checkpointing for recovery.

boolean; default: false; restart required

Enable Plan Mode for read-only safety during planning.

boolean; default: true; restart required

Automatically delete chats older than this period (e.g. "30d", "7d", "24h", "1w").

string; default: "30d"

The color theme for the UI.

string; default: undefined

The Gemini model to use for conversations.

string; default: undefined

Maximum user/model/tool turns to keep in a session; -1 means unlimited.

number; default: -1

Fraction of context usage at which to trigger context compression.

number; default: 0.5; restart required

Name of the context file or files to load into memory.

string | string[]; default: undefined

Legacy full-process sandbox: boolean, profile path, or command (e.g. "docker", "podman", "lxc", "windows-native").

string; default: undefined; restart required

Tool names that bypass the confirmation dialog.

array; default: undefined; restart required

Tool names to exclude from discovery.

array; default: undefined; restart required

Whether Folder trust is enabled.

boolean; default: true; restart required

Disable YOLO mode, even if enabled by a flag.

boolean; default: false; restart required

Environment variables to exclude from project context.

array; default: ["DEBUG", "DEBUG_MODE"]

Enable automated Git worktree management for parallel work.

boolean; default: false; restart required

Enable Agent Skills.

boolean; default: true; restart required

Canonical toggle for the hooks system; when disabled, no hooks run.

boolean; default: true; restart required

Hooks that run before tool execution. Other events: AfterTool, BeforeAgent, AfterAgent, Notification, SessionStart, SessionEnd, PreCompress, BeforeModel, AfterModel, BeforeToolSelection.

array; default: []

Named MCP server config. Fields: command, args, env, cwd, url (SSE), httpUrl, headers, timeout, trust, description, includeTools, excludeTools.

object; precedence httpUrl > url > command

Telemetry settings: enabled, traces, target, otlpEndpoint, otlpProtocol, otlpHeaders, logPrompts, outfile, useCollector, useCliAuth.

target: local|gcp (default local); otlpEndpoint default http://localhost:4317; otlpProtocol grpc|http (default grpc)

If true, disallows YOLO mode and "Always allow" options.

boolean; default: false

Your API key for the Gemini API.

Specifies the default Gemini model, overriding the hardcoded default.

If "true", trusts the current workspace for the session, bypassing the folder trust check.

"true"

Overrides the default location of trustedFolders.json.

path

Manually specifies the IDE process PID for integration, overriding auto-detection.

PID

Root directory for user-level configuration and storage; a .gemini folder is created inside it.

path; default: user home

Custom label included in the User-Agent header for API traffic reporting.

string

Overrides the path of the system defaults settings file.

path

Overrides the path of the system settings (override) file.

path

Google Cloud API key; required for Vertex AI express mode.

Google Cloud Project ID; required for Code Assist or Vertex AI.

Google Cloud location (for example us-central1); required for Vertex AI non-express mode.

Path to your Google Application Credentials JSON file.

string (path)

API version for Gemini API requests, overriding the SDK default.

Overrides the Gemini API base URL (gemini-api-key auth); must be HTTPS unless localhost.

URL

Overrides the Vertex AI base URL (vertex-ai auth); must be HTTPS unless localhost.

URL

Google Cloud Project ID for telemetry in Google Cloud.

true or 1 enables telemetry; overrides telemetry.enabled. Related overrides: GEMINI_TELEMETRY_TRACES_ENABLED, _TARGET, _OTLP_ENDPOINT, _OTLP_PROTOCOL, _OTLP_HEADERS, _LOG_PROMPTS, _OUTFILE, _USE_COLLECTOR, _USE_CLI_AUTH.

true/1

Alternative to the sandbox setting; enables sandboxing.

true, false, docker, podman, sandbox-exec, runsc, lxc, or a custom command

Custom container image to use for sandboxing.

image name

Builds a custom sandbox image from .gemini/sandbox.Dockerfile.

1

Comma-separated from:to:opts mounts giving the sandbox access outside the workspace; opts defaults to ro.

from:to:opts list

Custom flags injected into the docker or podman command.

string

Switches the macOS Seatbelt (sandbox-exec) profile.

permissive-open (default), permissive-proxied, restrictive-open, restrictive-proxied, strict-open, strict-proxied, or a custom <profile_name>

Replaces the built-in system prompt with a Markdown file; true/1 uses ./.gemini/system.md, other strings are paths.

true/1, false/0, or a path

Writes the built-in system prompt to a file for review; true/1 writes ./.gemini/system.md.

true/1 or a path

true or 1 enables verbose debug logging; excluded from project .env files by default.

true/1

Set to any value to disable all color output.

any value

Customizes the title of the CLI.

string

Endpoint for the code assist server, for development and testing.

URL

Set to 1 in subprocesses run via ! or shell mode so scripts can detect Gemini CLI.

1

Hook environment: absolute path to the project root. Hooks also get GEMINI_PLANS_DIR, GEMINI_SESSION_ID, GEMINI_CWD and CLAUDE_PROJECT_DIR (alias).

Set to 1 to make Node.js use the system certificate store (corporate TLS fix); alternative is NODE_EXTRA_CA_CERTS.

1

User settings file; applies to all sessions for the current user.

Project settings file; overrides user settings and system defaults.

System defaults file (lowest precedence). macOS: /Library/Application Support/GeminiCli/system-defaults.json; Windows: C:\ProgramData\gemini-cli\system-defaults.json.

System settings file that overrides all other settings files. macOS and Windows equivalents under GeminiCli / ProgramData.

.env is searched from the cwd up to project root or home, then ~/.env. Variables from .gemini/.env are never excluded.

Central store of folder trust decisions.

JSON array of {command, key|keys} entries; prefix a command with - to unbind.

Default hierarchical context file (global ~/.gemini/GEMINI.md plus project files); name configurable via context.fileName.

Excludes files and directories from Gemini CLI tools, similar to .gitignore.

Custom command .toml files; project commands override user commands with the same name.

User skills (alias ~/.agents/skills/) and workspace skills directories.

User-tier policy files. Admin tier: /etc/gemini-cli/policies (Linux); workspace tier currently disabled.

Extension manifest in ~/.gemini/extensions/<name>/ (name, version, mcpServers, contextFileName, excludeTools, settings).

Stores MCP server enablement state.

Custom sandbox Dockerfile, built when BUILD_SANDBOX is set.