Gemini CLI

CLI

Google

Google's open-source AI agent that brings the power of Gemini directly into your terminal.

MCP

Supported

MCP servers configured under the mcpServers key in settings.json. Supports stdio, SSE, and Streamable HTTP transports, OAuth (including Google credentials and service-account impersonation), tool filtering, and the gemini mcp CLI for managing entries.

Verified 2026-07-12Docs

Transportsstdiossehttp

Authoauthheadersgoogle-credentialsservice-account-impersonation

Config files

Path	Scope	Format	Key
`.gemini/settings.json`	Project	json	mcpServers
`~/.gemini/settings.json`	Global	json	mcpServers

Fields

Field	Type	Description
`command`	string	Path to the executable for stdio transport. One of command, url, or httpUrl is required.
`args`	string[]	Command-line arguments for stdio transport.
`url`	string	SSE endpoint URL (e.g. http://localhost:8080/sse).
`httpUrl`	string	Streamable HTTP endpoint URL.
`headers`	record<string, string>	Custom HTTP headers when using url or httpUrl.
`env`	record<string, string>	Environment variables for the server process. Supports $VAR_NAME / ${VAR_NAME} expansion (and %VAR_NAME% on Windows).
`cwd`	string	Working directory for stdio transport.
`timeout`	number	Request timeout in milliseconds (default 600,000 = 10 minutes).
`trust`	boolean	When true, bypasses all tool call confirmations for this server. Default false.
`includeTools`	string[]	Allowlist of tool names to expose from this server.
`excludeTools`	string[]	Denylist of tool names; takes precedence over includeTools.
`authProviderType`	string	Authentication provider for remote servers.
`oauth`	{ enabled?, clientId?, clientSecret?, authorizationUrl?, tokenUrl?, scopes?, redirectUri?, tokenParamName?, audiences? }	OAuth configuration for remote servers; endpoints are auto-discovered when omitted.
`targetAudience`	string	OAuth client ID allowlisted on an IAP-protected app (service account impersonation).
`targetServiceAccount`	string	Google Cloud service account email to impersonate (service account impersonation).

Capabilities

ToolsSupported

PromptsSupported

ResourcesSupported

RootsInformation missing

ElicitationInformation missing

SamplingInformation missing

Examples

Local stdio server

{
  "mcpServers": {
    "pythonTools": {
      "command": "python",
      "args": ["-m", "my_mcp_server", "--port", "8080"],
      "env": { "API_KEY": "$EXTERNAL_API_KEY" },
      "timeout": 15000
    }
  }
}

Remote HTTP server with headers

{
  "mcpServers": {
    "httpServerWithAuth": {
      "httpUrl": "http://localhost:3000/mcp",
      "headers": { "Authorization": "Bearer your-api-token" },
      "timeout": 5000
    }
  }
}

•MCP tools get a fully qualified name mcp_{serverName}_{toolName}; avoid underscores in server names so policy rules parse correctly.
•The mcp settings object (mcp.allowed / mcp.excluded) globally allow- or deny-lists servers by name.
•Manage servers without editing JSON via gemini mcp add/list/remove/enable/disable; per-server enablement is stored in ~/.gemini/mcp-server-enablement.json.
•OAuth tokens are stored in ~/.gemini/mcp-oauth-tokens.json and refreshed automatically.
•Sensitive host environment variables (patterns like *TOKEN*, *SECRET*, *KEY*) are redacted from server processes unless explicitly listed in env.
•MCP server instructions (from the initialize result) are appended to the system prompt.

Skills

Supported

Agent Skills based on the agentskills.io open standard: SKILL.md directories discovered from built-in, extension, user, and workspace tiers, activated by the model via the activate_skill tool with user consent.

Verified 2026-07-12Docs

Invokeautomatic (activate_skill tool)/skills list

Config files

Path	Scope	Format	Key
`.gemini/skills/<name>/SKILL.md` Workspace skills, shared with the team via version control.	Project	markdown	—
`.agents/skills/<name>/SKILL.md` Interoperable alias; takes precedence over .gemini/skills/ within the workspace tier.	Project	markdown	—
`~/.gemini/skills/<name>/SKILL.md` User skills, available across all projects.	Global	markdown	—
`~/.agents/skills/<name>/SKILL.md` Interoperable alias; takes precedence over ~/.gemini/skills/ within the user tier.	Global	markdown	—

Fields

Field	Type	Description
`name`*	string	Unique skill identifier; should match the directory name.
`description`*	string	How Gemini decides when to use the skill. Be specific about tasks and trigger keywords.

Examples

SKILL.md

---
name: code-reviewer
description:
  Expertise in reviewing code changes for correctness, security, and style. Use
  when the user asks to "review" their code or a PR.
---

# Code Reviewer Instructions

1. **Analyze**: Review the provided code for logical errors and style violations.
2. **Review**: Use the bundled `scripts/review.js` utility to perform an automated check.
3. **Feedback**: Provide constructive feedback.

•Discovery precedence (lowest to highest): built-in, extension, user, workspace. Within a tier the .agents/skills/ alias wins over .gemini/skills/.
•Only skill name and description are injected into the system prompt; the SKILL.md body loads on activation (progressive disclosure).
•Activation grants the model read access to the skill's directory (scripts/, references/, assets/).
•Manage with /skills list|link|enable|disable|reload in-session, or gemini skills list|install|uninstall|link from the terminal.
•Toggle the feature with the skills.enabled setting (default true).

Rules

Supported

Hierarchical GEMINI.md context files loaded from the global, workspace, and just-in-time (per-directory) tiers, concatenated and sent with every prompt. Supports @file.md imports and configurable file names (e.g. AGENTS.md).

Verified 2026-07-12Docs

Config files

Path	Scope	Format	Key
`GEMINI.md` Found in workspace directories and their parents; subdirectory files load just-in-time when tools access them.	Project	markdown	—
`~/.gemini/GEMINI.md` Default instructions for all projects.	Global	markdown	—

Fields

Field	Type	Description
`context.fileName`	string \| string[]	settings.json option that overrides the context file name(s), e.g. ["AGENTS.md", "CONTEXT.md", "GEMINI.md"].

Examples

Project GEMINI.md

# Project: My TypeScript Library

## General Instructions

- When you generate new TypeScript code, follow the existing coding style.
- Ensure all new functions and classes have JSDoc comments.

## Imports

@./components/instructions.md

Use AGENTS.md as the context file

{
  "context": {
    "fileName": ["AGENTS.md", "GEMINI.md"]
  }
}

•Load order: ~/.gemini/GEMINI.md, then GEMINI.md files found in workspace directories and their parents, then just-in-time files discovered when tools touch a directory.
•Compose instructions with @./path/file.md imports (relative or absolute paths); see the memory import processor docs.
•Rename or add context file names via the context.fileName setting, e.g. ["AGENTS.md", "GEMINI.md"].
•Inspect and reload with /memory show and /memory reload.
•The experimental Auto Memory feature (experimental.autoMemory) mines past sessions and proposes memory patches for review via /memory inbox.

Hooks

Supported

Synchronous shell commands that run at lifecycle events across the agent loop, configured under the hooks key in settings.json. Hooks communicate via JSON on stdin/stdout and can inject context, rewrite tool arguments, block actions, mock model responses, or filter tools.

Verified 2026-07-12Docs

EventsSessionStartSessionEndBeforeAgentAfterAgentBeforeModelAfterModelBeforeToolSelectionBeforeToolAfterToolPreCompressNotification

Config files

Path	Scope	Format	Key
`.gemini/settings.json`	Project	json	hooks
`~/.gemini/settings.json`	Global	json	hooks
`/etc/gemini-cli/settings.json` System settings (Linux). Windows: C:\ProgramData\gemini-cli\settings.json; macOS: /Library/Application Support/GeminiCli/settings.json.	Enterprise	json	hooks

Fields

Field	Type	Description
`matcher`	string	Regex (tool events) or exact string (lifecycle events) filtering when the hook group fires.
`sequential`	boolean	Run hooks in this group one after another instead of in parallel.
`hooks[].type`*	"command"	Execution engine. Currently only "command" is supported.
`hooks[].command`*	string	Shell command to execute. Receives event JSON on stdin.
`hooks[].name`	string	Friendly name for logs and the /hooks commands.
`hooks[].timeout`	number	Execution timeout in milliseconds (default 60000).
`hooks[].description`	string	Brief explanation of the hook's purpose.

Examples

Security check before file writes

{
  "hooks": {
    "BeforeTool": [
      {
        "matcher": "write_file|replace",
        "hooks": [
          {
            "name": "security-check",
            "type": "command",
            "command": "$GEMINI_PROJECT_DIR/.gemini/hooks/security.sh",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}

•Exit code 0 parses stdout as JSON (preferred, including intentional denies); exit code 2 blocks the action with stderr as the reason; other codes warn and continue.
•Matchers are regexes for tool events (e.g. "write_.*") and exact strings for lifecycle events; "*" or "" matches all.
•Settings precedence: project (.gemini/settings.json) over user (~/.gemini/settings.json) over system (/etc/gemini-cli/settings.json) over extensions.
•Project hooks are fingerprinted; a changed name or command is treated as a new untrusted hook and re-confirmed.
•Hooks receive GEMINI_PROJECT_DIR, GEMINI_SESSION_ID, GEMINI_CWD env vars (plus CLAUDE_PROJECT_DIR as a compatibility alias).
•Manage via /hooks panel, /hooks enable/disable; toggle the system with hooksConfig.enabled.

Commands

Supported

Custom slash commands defined as TOML files under .gemini/commands/. Subdirectories create namespaced names (git/commit.toml becomes /git:commit). Prompts support {{args}} injection, !{...} shell execution, and @{...} file embedding.

Verified 2026-07-12Docs

Invoke/command-name/namespace:command-name

Config files

Path	Scope	Format	Key
`.gemini/commands/<name>.toml` Project commands; subdirectories namespace the command name with colons.	Project	toml	—
`~/.gemini/commands/<name>.toml` User commands, available in every project.	Global	toml	—

Fields

Field	Type	Description
`prompt`*	string	The prompt sent to the model when the command runs. Single or multi-line.
`description`	string	One-line description shown in the /help menu. Generated from the filename if omitted.

Examples

Commit message from staged diff

# In: <project>/.gemini/commands/git/commit.toml
# Invoked via: /git:commit

description = "Generates a Git commit message based on staged changes."
prompt = """
Please generate a Conventional Commit message based on the following git diff:

!{git diff --staged}
"""

•Project commands override user commands of the same name.
•{{args}} is injected raw in the prompt body and shell-escaped inside !{...} blocks; without {{args}}, the full invocation is appended to the prompt.
•!{...} shell blocks require user confirmation before execution; @{...} embeds file content or directory listings (multimodal for images/PDF).
•Run /commands reload to pick up TOML changes without restarting; /commands list shows all command files.
•MCP server prompts also surface as slash commands (see the MCP surface).

Settings

Supported

Layered settings.json files (system defaults, user, project, system overrides) organized into category objects like general, ui, model, context, tools, security, mcp, and hooksConfig. Editable in-session with the /settings dialog.

Verified 2026-07-12Docs

Config files

Path	Scope	Format	Key
`.gemini/settings.json` Project settings; override user settings and system defaults.	Project	json	—
`~/.gemini/settings.json` User settings for all sessions.	Global	json	—
`/etc/gemini-cli/settings.json` System overrides beating all other files (Linux). Windows: C:\ProgramData\gemini-cli\settings.json; macOS: /Library/Application Support/GeminiCli/settings.json.	Enterprise	json	—
`/etc/gemini-cli/system-defaults.json` System-wide defaults with the lowest precedence (Linux); Windows and macOS analogues exist.	Enterprise	json	—

Fields

Field	Type	Description
`general`	object	General behavior: vimMode, defaultApprovalMode (default \| auto_edit \| plan), enableAutoUpdate, session retention, plan mode.
`model`	object	Model selection and session behavior: name, maxSessionTurns, compressionThreshold.
`context`	object	Context loading: fileName (GEMINI.md alternatives), discoveryMaxDirs, fileFiltering (.gitignore/.geminiignore handling).
`mcpServers`	record<string, object>	MCP server definitions (see the MCP surface).
`mcp`	{ serverCommand?, allowed?, excluded? }	Global MCP rules: allow/deny lists of server names.
`hooks`	object	Lifecycle hook configuration (see the Hooks surface).
`hooksConfig`	{ enabled?: boolean, notifications?: boolean }	Canonical toggle and UI indicators for the hooks system.
`skills`	{ enabled?: boolean }	Toggle for Agent Skills (default true).
`tools`	object	Tool behavior: sandbox paths and network access, shell options, useRipgrep, output truncation.
`security`	object	Security controls: folderTrust, disableYoloMode, always-allow behavior, extension allowlists, environment variable redaction.
`ui`	object	Terminal UI: theme switching, footer, banner, accessibility, rendering options.
`experimental`	object	Experimental flags such as autoMemory, worktrees, voiceMode, and modelSteering.

Examples

Project settings

{
  "general": { "defaultApprovalMode": "auto_edit" },
  "context": { "fileName": ["AGENTS.md", "GEMINI.md"] },
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@github/github-mcp-server"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_PERSONAL_ACCESS_TOKEN" }
    }
  }
}

•Precedence (low to high): defaults, system defaults file, user, project, system settings file, environment variables, command-line arguments.
•String values may reference environment variables with $VAR_NAME, ${VAR_NAME}, or ${VAR_NAME:-default} syntax.
•A hosted JSON schema is available at schemas/settings.schema.json in the repository for editor validation.
•System paths can be overridden with GEMINI_CLI_SYSTEM_SETTINGS_PATH and GEMINI_CLI_SYSTEM_DEFAULTS_PATH.