# Gemini CLI Google's open-source AI agent that brings the power of Gemini directly into your terminal. Schema: 1.0 · Data: ee5de863c30bdbe4fe7dd3e07c7e22ea9bf4ab2248dbc7c35cdbf60bc28be1db ## Configuration ### MCP Status: 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. - project: `.gemini/settings.json` (json) — key: mcpServers - global: `~/.gemini/settings.json` (json) — key: mcpServers - `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 — Custom HTTP headers when using url or httpUrl. - `env`: record — 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. Values: dynamic_discovery, google_credentials, service_account_impersonation - `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). - transports: stdio, sse, http - auth: oauth, headers, google-credentials, service-account-impersonation - Tools: supported - Prompts: supported — Server prompts become slash commands, e.g. /poem-writer --title="...". - Resources: supported — Discovered at startup and referenced in chat with @server://resource/path. - Roots: missing — Not documented in the official MCP docs. - Elicitation: missing — Not documented in the official MCP docs. - Sampling: missing — Not documented in the official MCP docs. - 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. Local stdio server ```json { "mcpServers": { "pythonTools": { "command": "python", "args": ["-m", "my_mcp_server", "--port", "8080"], "env": { "API_KEY": "$EXTERNAL_API_KEY" }, "timeout": 15000 } } } ``` Remote HTTP server with headers ```json { "mcpServers": { "httpServerWithAuth": { "httpUrl": "http://localhost:3000/mcp", "headers": { "Authorization": "Bearer your-api-token" }, "timeout": 5000 } } } ``` Source: https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md Checked: 2026-07-12 ### Skills Status: 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. - project: `.gemini/skills//SKILL.md` (markdown) — Workspace skills, shared with the team via version control. - project: `.agents/skills//SKILL.md` (markdown) — Interoperable alias; takes precedence over .gemini/skills/ within the workspace tier. - global: `~/.gemini/skills//SKILL.md` (markdown) — User skills, available across all projects. - global: `~/.agents/skills//SKILL.md` (markdown) — Interoperable alias; takes precedence over ~/.gemini/skills/ within the user tier. - `name`: string (required) — Unique skill identifier; should match the directory name. - `description`: string (required) — How Gemini decides when to use the skill. Be specific about tasks and trigger keywords. - invocation: automatic (activate_skill tool), /skills list - 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). SKILL.md ```markdown --- 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. ``` Source: https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/skills.md Checked: 2026-07-12 ### Rules Status: 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). - project: `GEMINI.md` (markdown) — Found in workspace directories and their parents; subdirectory files load just-in-time when tools access them. - global: `~/.gemini/GEMINI.md` (markdown) — Default instructions for all projects. - `context.fileName`: string | string[] — settings.json option that overrides the context file name(s), e.g. ["AGENTS.md", "CONTEXT.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. Project GEMINI.md ```markdown # 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 ```json { "context": { "fileName": ["AGENTS.md", "GEMINI.md"] } } ``` Source: https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/gemini-md.md Checked: 2026-07-12 ### Hooks Status: 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. - project: `.gemini/settings.json` (json) — key: hooks - global: `~/.gemini/settings.json` (json) — key: hooks - enterprise: `/etc/gemini-cli/settings.json` (json) — key: hooks — System settings (Linux). Windows: C:\ProgramData\gemini-cli\settings.json; macOS: /Library/Application Support/GeminiCli/settings.json. - `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" (required) — Execution engine. Currently only "command" is supported. - `hooks[].command`: string (required) — 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. - events: SessionStart, SessionEnd, BeforeAgent, AfterAgent, BeforeModel, AfterModel, BeforeToolSelection, BeforeTool, AfterTool, PreCompress, Notification - 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. Security check before file writes ```json { "hooks": { "BeforeTool": [ { "matcher": "write_file|replace", "hooks": [ { "name": "security-check", "type": "command", "command": "$GEMINI_PROJECT_DIR/.gemini/hooks/security.sh", "timeout": 5000 } ] } ] } } ``` Source: https://github.com/google-gemini/gemini-cli/blob/main/docs/hooks/index.md Checked: 2026-07-12 ### Commands Status: 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. - project: `.gemini/commands/.toml` (toml) — Project commands; subdirectories namespace the command name with colons. - global: `~/.gemini/commands/.toml` (toml) — User commands, available in every project. - `prompt`: string (required) — 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. - invocation: /command-name, /namespace:command-name - 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). Commit message from staged diff ```toml # In: /.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} """ ``` Source: https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/custom-commands.md Checked: 2026-07-12 ### Settings Status: 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. - project: `.gemini/settings.json` (json) — Project settings; override user settings and system defaults. - global: `~/.gemini/settings.json` (json) — User settings for all sessions. - enterprise: `/etc/gemini-cli/settings.json` (json) — System overrides beating all other files (Linux). Windows: C:\ProgramData\gemini-cli\settings.json; macOS: /Library/Application Support/GeminiCli/settings.json. - enterprise: `/etc/gemini-cli/system-defaults.json` (json) — System-wide defaults with the lowest precedence (Linux); Windows and macOS analogues exist. - `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 — 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. - 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. Project settings ```json { "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" } } } } ``` Source: https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/settings.md Checked: 2026-07-12 ## Search, browser & identification Not researched. Unknown does not mean unsupported.