{"id":166650,"date":"2026-04-17T14:05:11","date_gmt":"2026-04-17T11:05:11","guid":{"rendered":"https:\/\/computingforgeeks.com\/install-configure-gemini-cli\/"},"modified":"2026-06-15T19:01:05","modified_gmt":"2026-06-15T16:01:05","slug":"install-configure-gemini-cli","status":"publish","type":"post","link":"https:\/\/computingforgeeks.com\/install-configure-gemini-cli\/","title":{"rendered":"Gemini CLI on Linux, macOS, and Windows (Agent Setup)"},"content":{"rendered":"<p>Gemini CLI is Google&#8217;s open-source AI agent for the terminal. It ships the full Gemini 3 model, a 1 million token context window, and a generous free tier (60 requests per minute, 1,000 per day) behind a single <code>gemini<\/code> binary. Free Google-account access to that tier ends on 18 June 2026 (see the migration section below); paid API keys and Vertex AI credentials are unaffected. The current stable release arrived in April 2026, with weekly preview drops on Tuesdays and nightly builds at 00:00 UTC.<\/p>\n\n<p><strong>Before you start:<\/strong> Google is retiring the hosted Gemini CLI on 18 June 2026 for free, Google AI Pro, and Google AI Ultra accounts and moving them to the <a href=\"https:\/\/computingforgeeks.com\/install-antigravity-cli-linux-macos-windows\/\" target=\"_blank\" rel=\"noreferrer noopener\">Antigravity CLI<\/a>. The install steps below still run, and a paid API key or Vertex AI credentials keep the <code>gemini<\/code> binary working past that date, but if you plan to sign in with a free Google account, read <a href=\"#migrate-antigravity\">Migrating to Antigravity CLI<\/a> first so you do not set up a tool that stops answering within days.<\/p>\n\n<p>This guide installs Gemini CLI on macOS, Linux, and Windows, walks through the three authentication modes, wires up agent skills, adds a Model Context Protocol (MCP) server, configures <code>settings.json<\/code>, and runs real headless queries. Every command and every piece of output below was executed on a live box.<\/p>\n\n<p><em>Updated in June 2026 for the Antigravity CLI transition. The install itself was tested in April 2026 on macOS 26.3 (Apple Silicon) and Rocky Linux 10.1 (x86_64) with Gemini CLI 0.38.1 and Node.js 25.9.0.<\/em><\/p>\n\n<h2 class=\"wp-block-heading\" id=\"migrate-antigravity\">Migrating to Antigravity CLI<\/h2>\n\n<p>On 18 June 2026 Google switches off the hosted Gemini CLI backend for free users, Google AI Pro, Google AI Ultra, and Gemini Code Assist for individuals. After that date a plain Google sign-in stops returning responses, and Google moves those tiers to the Antigravity CLI, a closed-source Go binary called <code>agy<\/code> announced at Google I\/O on 19 May 2026. Decide which path you want before you install anything below.<\/p>\n\n<p>The Gemini CLI is not being deleted. The repository stays open source under Apache 2.0 and the <code>gemini<\/code> binary keeps running. Only the free Google-account quota ends, which leaves two honest paths:<\/p>\n\n<ul class=\"wp-block-list\">\n<li><strong>Stay on Gemini CLI with a paid key.<\/strong> Authentication method 2 (Gemini API key) or method 3 (Vertex AI) in this guide keeps your Gemini CLI access uninterrupted past 18 June. Gemini Code Assist Standard and Enterprise licences, and Gemini Enterprise Agent Platform API keys, are unaffected too.<\/li>\n<li><strong>Move to Antigravity CLI.<\/strong> If you only have a free Google account, install <code>agy<\/code> and sign in with that same account. Agent Skills, hooks, subagents, and extensions (now called plugins) carry over, though Antigravity applies its own usage limits in place of the old per-day request quota.<\/li>\n<\/ul>\n\n<p>Installing the Antigravity CLI on Linux or macOS takes one command:<\/p>\n\n\n<pre class=\"wp-block-code code\"><code>curl -fsSL https:\/\/antigravity.google\/cli\/install.sh | bash\nagy --version<\/code><\/pre>\n\n\n<p>On Windows, run <code>irm https:\/\/antigravity.google\/cli\/install.ps1 | iex<\/code> in PowerShell. The full install, the OAuth cache path, and the &#8220;Illegal instruction&#8221; fix on older VMs are covered in our <a href=\"https:\/\/computingforgeeks.com\/install-antigravity-cli-linux-macos-windows\/\" target=\"_blank\" rel=\"noreferrer noopener\">Antigravity CLI install guide<\/a>, and Google&#8217;s <a href=\"https:\/\/developers.googleblog.com\/an-important-update-transitioning-gemini-cli-to-antigravity-cli\/\" target=\"_blank\" rel=\"noreferrer noopener\">official transition notice<\/a> has the per-tier breakdown and migration FAQ.<\/p>\n\n\n<script type=\"application\/ld+json\">\n{\n  \"@context\": \"https:\/\/schema.org\",\n  \"@type\": \"HowTo\",\n  \"name\": \"Install and Configure Gemini CLI\",\n  \"description\": \"Install Gemini CLI on macOS, Linux, and Windows. Configure auth, slash commands, skills, and MCP servers with real tested examples.\",\n  \"totalTime\": \"PT20M\",\n  \"tool\": [\n    {\"@type\": \"HowToTool\", \"name\": \"Node.js 20 or newer\"},\n    {\"@type\": \"HowToTool\", \"name\": \"Terminal (macOS Terminal, GNOME Terminal, or PowerShell)\"},\n    {\"@type\": \"HowToTool\", \"name\": \"Google Account, Gemini API key, or Vertex AI credentials\"}\n  ],\n  \"step\": [\n    {\"@type\": \"HowToStep\", \"name\": \"Recent changes worth noting\", \"text\": \"The current Gemini CLI ships TerminalBuffer mode to stop flicker, compact tool output, context-aware policy approvals, and a memory service for skill extraction. The upcoming 0.39.0 preview adds a \/memory inbox for skill review and subagent architecture.\"},\n    {\"@type\": \"HowToStep\", \"name\": \"Prerequisites\", \"text\": \"Node.js 20 or newer, macOS 15+ or Windows 11 24H2+ or Ubuntu 20.04+, 4 GB RAM minimum, an internet connection, and a Google Account or API key.\"},\n    {\"@type\": \"HowToStep\", \"name\": \"Set reusable shell variables\", \"text\": \"Export GEMINI_API_KEY, GEMINI_MODEL, and GEMINI_AGENT at the top of your session so later commands reference the variables instead of repeating literals.\"},\n    {\"@type\": \"HowToStep\", \"name\": \"Install Gemini CLI\", \"text\": \"Use npm install -g @google\/gemini-cli on any platform, or brew install gemini-cli on macOS\/Linux, or sudo port install gemini-cli on MacPorts, or npx @google\/gemini-cli for a throwaway run.\"},\n    {\"@type\": \"HowToStep\", \"name\": \"Choose an authentication mode\", \"text\": \"Pick between Google Sign-in OAuth (60 rpm, 1000 rpd free), a Gemini API key from aistudio.google.com\/apikey (1000 rpd free), or Vertex AI for enterprise workloads.\"},\n    {\"@type\": \"HowToStep\", \"name\": \"Run your first query\", \"text\": \"Start interactive mode with gemini or run a headless prompt with gemini -p 'your prompt here'.\"},\n    {\"@type\": \"HowToStep\", \"name\": \"Learn the slash commands\", \"text\": \"Use \/help, \/chat, \/memory, \/tools, \/mcp, \/skills, \/auth, \/theme, \/compress, \/stats, \/bug, \/quit and others to control the session.\"},\n    {\"@type\": \"HowToStep\", \"name\": \"Manage agent skills\", \"text\": \"Use gemini skills list, gemini skills install <source>, gemini skills enable <name>, and gemini skills disable <name>.\"},\n    {\"@type\": \"HowToStep\", \"name\": \"Add MCP servers\", \"text\": \"Use gemini mcp add --scope user <name> <command> to wire up Model Context Protocol servers like Context7, GitHub, or filesystem.\"},\n    {\"@type\": \"HowToStep\", \"name\": \"Configure settings.json\", \"text\": \"Edit ~\/.gemini\/settings.json for user-wide config or .gemini\/settings.json for project-wide config. Fields include model.name, ui.theme, security.auth.selectedType, tools.allowed, mcpServers, and telemetry.\"},\n    {\"@type\": \"HowToStep\", \"name\": \"Write a GEMINI.md context file\", \"text\": \"Use \/init or create GEMINI.md at the project root to give Gemini persistent context about the codebase.\"},\n    {\"@type\": \"HowToStep\", \"name\": \"Use non-interactive mode in scripts\", \"text\": \"Pass -p for headless prompts and --output-format json or stream-json for structured output suitable for CI pipelines.\"},\n    {\"@type\": \"HowToStep\", \"name\": \"Pick a release channel\", \"text\": \"Use npm install -g @google\/gemini-cli@latest for stable, @preview for weekly preview, or @nightly for daily main-branch builds.\"}\n  ]\n}\n<\/script>\n\n\n<h2 class=\"wp-block-heading\">Recent changes worth noting<\/h2>\n\n<p>The current release line is where Gemini CLI graduated from a useful terminal shim to a full <a href=\"https:\/\/computingforgeeks.com\/claude-code-cheat-sheet\/\" target=\"_blank\" rel=\"noreferrer noopener\">Claude Code<\/a> competitor. That line landed in April 2026 and shipped four changes that matter day-to-day:<\/p>\n\n<ul>\n<li><strong>TerminalBuffer mode<\/strong>, which finally kills the flicker that older releases had on long agent turns.<\/li>\n<li><strong>Compact tool output<\/strong> as the default rendering, so multi-tool plans do not bury your prompt in JSON.<\/li>\n<li><strong>Context-aware policy approvals<\/strong>, letting you approve a tool once for a folder instead of re-prompting on every file.<\/li>\n<li><strong>Memory service<\/strong> that extracts reusable patterns from sessions for later skills.<\/li>\n<\/ul>\n\n<p>Later patch releases follow the same branch. Next up on the preview track is a <code>\/memory inbox<\/code> command for reviewing extracted skills, and a refactored subagent architecture that matches what <a href=\"https:\/\/computingforgeeks.com\/claude-code-cheat-sheet\/\" target=\"_blank\" rel=\"noreferrer noopener\">Claude Code<\/a> and <a href=\"https:\/\/computingforgeeks.com\/setup-opencode-ai-coding-agent\/\" target=\"_blank\" rel=\"noreferrer noopener\">OpenCode<\/a> now offer.<\/p>\n\n<h2 class=\"wp-block-heading\">Prerequisites<\/h2>\n\n<p>Three hard requirements, one soft one.<\/p>\n\n<ul>\n<li><strong>Node.js 20 or newer.<\/strong> Gemini CLI ships as an npm package, so Node is the runtime. Check with <code>node --version<\/code>.<\/li>\n<li><strong>A supported operating system.<\/strong> macOS 15 Sequoia or later (Intel and Apple Silicon), Windows 11 24H2 or later, or Ubuntu 20.04 \/ Debian 12 \/ Rocky Linux 10 or later.<\/li>\n<li><strong>4 GB RAM<\/strong> for casual use, 16 GB or more if you plan to keep multiple sessions and a sandbox container running.<\/li>\n<li><strong>One of three credentials<\/strong>: a personal Google Account (free tier), a Gemini API key from <a href=\"https:\/\/aistudio.google.com\/apikey\" target=\"_blank\" rel=\"noreferrer noopener\">Google AI Studio<\/a>, or Vertex AI credentials if you are on Google Cloud.<\/li>\n<\/ul>\n\n<h2 class=\"wp-block-heading\">Step 1: Set reusable shell variables<\/h2>\n\n<p>Most of the commands below take a model name, an approval mode, and (on some platforms) an API key. Export them once so later steps paste as-is.<\/p>\n\n\n<pre class=\"wp-block-code code\"><code>export GEMINI_API_KEY=\"your-api-key-here\"\nexport GEMINI_MODEL=\"gemini-2.5-pro\"\nexport GEMINI_AGENT=\"claude-code\"\nexport GEMINI_APPROVAL=\"auto_edit\"<\/code><\/pre>\n\n\n<p>Confirm the values landed before touching anything that spends requests:<\/p>\n\n\n<pre class=\"wp-block-code code\"><code>echo \"Key:     ${GEMINI_API_KEY:0:10}...\"\necho \"Model:   ${GEMINI_MODEL}\"\necho \"Agent:   ${GEMINI_AGENT}\"\necho \"Approve: ${GEMINI_APPROVAL}\"<\/code><\/pre>\n\n\n<p>Values hold only in the current shell. Re-export after reconnecting over SSH or opening a new tab. Persist them by appending the same lines to <code>~\/.zshrc<\/code>, <code>~\/.bashrc<\/code>, or Windows <code>$PROFILE<\/code>.<\/p>\n\n<h2 class=\"wp-block-heading\">Step 2: Install Gemini CLI on macOS<\/h2>\n\n<p>Three paths on Apple Silicon or Intel Macs. Pick whichever matches your package manager.<\/p>\n\n\n<pre class=\"wp-block-code code\"><code># Option A: npm (recommended for control over release channel)\nnpm install -g @google\/gemini-cli\n\n# Option B: Homebrew\nbrew install gemini-cli\n\n# Option C: MacPorts\nsudo port install gemini-cli<\/code><\/pre>\n\n\n<p>On a fresh Mac with Node 25 the npm install completes in about 23 seconds. Verify the binary lands in your PATH:<\/p>\n\n\n<pre class=\"wp-block-code code\"><code>gemini --version<\/code><\/pre>\n\n\n<p>You should see a version string matching the latest stable release. If you need a one-off run without installing, <code>npx @google\/gemini-cli<\/code> downloads and runs the package without polluting your global npm tree.<\/p>\n\n\n<figure class=\"wp-block-image size-large\"><img decoding=\"async\" src=\"https:\/\/computingforgeeks.com\/wp-content\/uploads\/2026\/04\/wm-gemini-cli-install-api-key-macos.png\" alt=\"Install Gemini CLI via npm on macOS, set GEMINI_API_KEY, and run a headless prompt\" title=\"\"><\/figure>\n\n\n<p>Those are the same three steps you will run on Linux and Windows, just with different package managers.<\/p>\n\n<h2 class=\"wp-block-heading\">Step 3: Install Gemini CLI on Linux<\/h2>\n\n<p>Same npm package works across Rocky Linux 10, Ubuntu 24.04, Debian 13, and Fedora 42. Homebrew on Linux also works if you already use it:<\/p>\n\n\n<pre class=\"wp-block-code code\"><code># Rocky Linux 10, AlmaLinux 10, Fedora 42\nsudo dnf install -y nodejs\nsudo npm install -g @google\/gemini-cli\n\n# Ubuntu 24.04, Debian 13\nsudo apt install -y nodejs npm\nsudo npm install -g @google\/gemini-cli\n\n# Homebrew on Linux\nbrew install gemini-cli<\/code><\/pre>\n\n\n<p>If the distro-shipped Node is older than 20, install Node 20 or 22 from NodeSource first. That version requirement is enforced at startup, not at install time, so <code>npm install -g<\/code> will succeed but the first <code>gemini<\/code> call will fail with a version error.<\/p>\n\n<p>For restricted environments where Node cannot be installed globally, Anaconda provides a hermetic path:<\/p>\n\n\n<pre class=\"wp-block-code code\"><code>conda create -y -n gemini_env -c conda-forge nodejs\nconda activate gemini_env\nnpm install -g @google\/gemini-cli<\/code><\/pre>\n\n\n<p>Docker is also a valid install target. Google publishes a sandbox image at <code>us-docker.pkg.dev\/gemini-code-dev\/gemini-cli\/sandbox:0.1.1<\/code>, which is the one the CLI itself uses when you pass <code>--sandbox<\/code>.<\/p>\n\n<h2 class=\"wp-block-heading\">Step 4: Install Gemini CLI on Windows<\/h2>\n\n<p>On Windows 11 24H2 or newer, open an elevated PowerShell prompt and run:<\/p>\n\n\n<pre class=\"wp-block-code code\"><code>npm install -g @google\/gemini-cli\ngemini --version<\/code><\/pre>\n\n\n<p>Windows does not ship Homebrew or MacPorts, so npm is the primary path. If your corporate policy blocks global npm installs, Docker Desktop plus the published sandbox image is a supported fallback:<\/p>\n\n\n<pre class=\"wp-block-code code\"><code>docker run --rm -it us-docker.pkg.dev\/gemini-code-dev\/gemini-cli\/sandbox:0.1.1<\/code><\/pre>\n\n\n<p>Set the API key via PowerShell rather than plain <code>export<\/code>:<\/p>\n\n\n<pre class=\"wp-block-code code\"><code>$env:GEMINI_API_KEY = \"your-api-key-here\"\ngemini<\/code><\/pre>\n\n\n<p>Persist the variable with <code>[System.Environment]::SetEnvironmentVariable('GEMINI_API_KEY', 'your-key', 'User')<\/code> if you want it to survive a reboot.<\/p>\n\n<h2 class=\"wp-block-heading\">Step 5: Choose an authentication mode<\/h2>\n\n<p>Gemini CLI supports three credential sources, and they have very different quotas.<\/p>\n\n<table>\n<thead><tr><th>Mode<\/th><th>Setup<\/th><th>Free tier<\/th><th>Best for<\/th><\/tr><\/thead>\n<tbody>\n<tr><td>Google Sign-in (OAuth)<\/td><td>Launch <code>gemini<\/code> and choose &#8220;Sign in with Google&#8221;<\/td><td>60 requests\/minute, 1,000\/day on Gemini 3 with 1M context<\/td><td>Individual developers, laptops with a browser<\/td><\/tr>\n<tr><td>Gemini API key<\/td><td>Export <code>GEMINI_API_KEY<\/code> from <a href=\"https:\/\/aistudio.google.com\/apikey\" target=\"_blank\" rel=\"noreferrer noopener\">aistudio.google.com\/apikey<\/a><\/td><td>1,000 requests\/day across Flash and Pro<\/td><td>CI pipelines, servers without browsers<\/td><\/tr>\n<tr><td>Vertex AI<\/td><td>Export <code>GOOGLE_CLOUD_PROJECT<\/code>, <code>GOOGLE_CLOUD_LOCATION<\/code>, and either ADC, a service account key, or <code>GOOGLE_GENAI_USE_VERTEXAI=true<\/code><\/td><td>Usage-based billing, no daily cap<\/td><td>Enterprise teams, compliance workloads<\/td><\/tr>\n<\/tbody>\n<\/table>\n\n<p>For OAuth, just launch the CLI and follow the browser flow. Credentials cache locally so subsequent runs skip the prompt.<\/p>\n\n\n<pre class=\"wp-block-code code\"><code>gemini<\/code><\/pre>\n\n\n<p>For API key auth, export the key and optionally the model:<\/p>\n\n\n<pre class=\"wp-block-code code\"><code>export GEMINI_API_KEY=\"your-api-key-here\"\ngemini -m \"${GEMINI_MODEL}\"<\/code><\/pre>\n\n\n<p>If you already set <code>GOOGLE_API_KEY<\/code> in your environment (for example because another Google SDK needs it), Gemini CLI picks that up and prints a one-line notice that it used <code>GOOGLE_API_KEY<\/code> instead of <code>GEMINI_API_KEY<\/code>. Unset one or the other if you want to force a specific source.<\/p>\n\n<p>For Vertex AI, the ADC path is the cleanest:<\/p>\n\n\n<pre class=\"wp-block-code code\"><code>export GOOGLE_CLOUD_PROJECT=\"my-gcp-project\"\nexport GOOGLE_CLOUD_LOCATION=\"us-central1\"\ngcloud auth application-default login\ngemini<\/code><\/pre>\n\n\n<p>Unset any lingering <code>GOOGLE_API_KEY<\/code> or <code>GEMINI_API_KEY<\/code> first, because the CLI prefers a direct key over ADC when both are present.<\/p>\n\n<h2 class=\"wp-block-heading\">Step 6: Run your first query<\/h2>\n\n<p>Two modes. Interactive is the default. Non-interactive is for scripts.<\/p>\n\n<p>Start an interactive session in your current directory:<\/p>\n\n\n<pre class=\"wp-block-code code\"><code>cd ~\/code\/my-project\ngemini<\/code><\/pre>\n\n\n<p>The session reads every <code>GEMINI.md<\/code> file it finds walking up from the current directory, adds the whole workspace to context (bounded by the nearest <code>.git<\/code> by default), and drops you at a prompt.<\/p>\n\n<p>For a one-shot query from a shell script or CI job, pass <code>-p<\/code>:<\/p>\n\n\n<pre class=\"wp-block-code code\"><code>gemini -p \"Summarise the last 10 commits in one paragraph\"<\/code><\/pre>\n\n\n<p>Structured output is available via <code>--output-format json<\/code> (one JSON document at the end) or <code>--output-format stream-json<\/code> (newline-delimited events during the run, useful for progress bars). Add <code>--include-directories ..\/lib,..\/docs<\/code> when the relevant context lives outside the current tree.<\/p>\n\n<h2 class=\"wp-block-heading\">Step 7: Learn the slash commands<\/h2>\n\n<p>Inside an interactive session, slash commands control state. Type <code>\/help<\/code> or <code>\/?<\/code> for the full list. The ones you will actually use:<\/p>\n\n<table>\n<thead><tr><th>Command<\/th><th>Purpose<\/th><\/tr><\/thead>\n<tbody>\n<tr><td><code>\/auth<\/code><\/td><td>Switch between OAuth, API key, and Vertex AI without restarting.<\/td><\/tr>\n<tr><td><code>\/chat save &lt;name&gt;<\/code> and <code>\/chat list<\/code><\/td><td>Save named conversations, resume with <code>\/resume &lt;name&gt;<\/code>.<\/td><\/tr>\n<tr><td><code>\/compress<\/code><\/td><td>Summarise history when the session grows long. Cheaper than starting over.<\/td><\/tr>\n<tr><td><code>\/memory add &lt;note&gt;<\/code> and <code>\/memory show<\/code><\/td><td>Manage persistent project memory.<\/td><\/tr>\n<tr><td><code>\/init<\/code><\/td><td>Generate a starter <code>GEMINI.md<\/code> from the current codebase.<\/td><\/tr>\n<tr><td><code>\/tools<\/code> and <code>\/tools desc<\/code><\/td><td>List built-in tools (file ops, shell, web fetch, Google Search).<\/td><\/tr>\n<tr><td><code>\/mcp list<\/code> and <code>\/mcp auth &lt;server&gt;<\/code><\/td><td>Inspect and authenticate MCP servers.<\/td><\/tr>\n<tr><td><code>\/skills enable &lt;name&gt;<\/code><\/td><td>Turn an agent skill on or off.<\/td><\/tr>\n<tr><td><code>\/plan<\/code><\/td><td>Switch to read-only plan mode before a risky change.<\/td><\/tr>\n<tr><td><code>\/rewind<\/code> (Esc Esc)<\/td><td>Step backward through history without losing state.<\/td><\/tr>\n<tr><td><code>\/stats session<\/code><\/td><td>See tokens used, cache hits, and model breakdown.<\/td><\/tr>\n<tr><td><code>\/theme<\/code><\/td><td>Pick a color scheme (GitHub, Dracula, etc.).<\/td><\/tr>\n<tr><td><code>\/bug \"&lt;summary&gt;\"<\/code><\/td><td>File a GitHub issue straight from the CLI.<\/td><\/tr>\n<\/tbody>\n<\/table>\n\n<p>Two special prefixes matter as much as the slash commands themselves. Start any line with <code>@<\/code> to inject a file or directory into the prompt (<code>@src\/main.ts fix the race condition<\/code>), and with <code>!<\/code> to shell out without leaving the session (<code>!git log --oneline -5<\/code>).<\/p>\n\n<p>For the full reference covering every CLI flag, all slash commands, keyboard shortcuts, custom TOML commands, the MCP server flag matrix, sandbox and checkpointing, plus real session captures, see the <a href=\"https:\/\/computingforgeeks.com\/gemini-cli-cheat-sheet\/\" target=\"_blank\" rel=\"noreferrer noopener\">Gemini CLI cheat sheet<\/a>.<\/p>\n\n<h2 class=\"wp-block-heading\">Step 8: Manage agent skills from the CLI<\/h2>\n\n<p>Skills are markdown-based capability packs following the <a href=\"https:\/\/agentskills.io\/\" target=\"_blank\" rel=\"noreferrer noopener\">Agent Skills open standard<\/a>. Gemini CLI discovers them in five locations, in precedence order:<\/p>\n\n<ol>\n<li>Workspace: <code>.agents\/skills\/<\/code> then <code>.gemini\/skills\/<\/code><\/li>\n<li>User: <code>~\/.agents\/skills\/<\/code> then <code>~\/.gemini\/skills\/<\/code><\/li>\n<li>Extensions bundled with installed CLI extensions<\/li>\n<\/ol>\n\n<p>The full skill lifecycle is exposed as <code>gemini skills<\/code> subcommands:<\/p>\n\n\n<pre class=\"wp-block-code code\"><code>gemini skills list\ngemini skills list --all\ngemini skills install https:\/\/github.com\/google-gemini\/gemini-skills\ngemini skills install .\/path\/to\/local\/skill\ngemini skills link .\/path\/to\/skill-in-development\ngemini skills enable &lt;name&gt;\ngemini skills disable &lt;name&gt; --scope user\ngemini skills uninstall &lt;name&gt; --scope user<\/code><\/pre>\n\n\n<p>If you already installed the <a href=\"https:\/\/computingforgeeks.com\/install-android-cli-linux-macos-windows\/\" target=\"_blank\" rel=\"noreferrer noopener\">Android CLI<\/a>, <code>android init<\/code> dropped an <code>android-cli<\/code> skill into <code>~\/.agents\/skills\/<\/code>, and Gemini CLI picks it up automatically. On the test Mac used for this guide that looks like this:<\/p>\n\n\n<figure class=\"wp-block-image size-large\"><img decoding=\"async\" src=\"https:\/\/computingforgeeks.com\/wp-content\/uploads\/2026\/04\/wm-gemini-cli-skills-list-install.png\" alt=\"Gemini CLI skills list and skills subcommand help on macOS\" title=\"\"><\/figure>\n\n\n<p>A skill conflict warning is not an error. It just means Gemini picked up the same skill from two discovery paths and is using the higher-precedence one. Either uninstall the duplicate or enable only the version you want with <code>gemini skills enable &lt;name&gt; --scope user<\/code>.<\/p>\n\n<p>Inside an interactive session, the same operations are available via <code>\/skills list<\/code>, <code>\/skills enable &lt;name&gt;<\/code>, and <code>\/skills reload<\/code>.<\/p>\n\n<h2 class=\"wp-block-heading\">Step 9: Add MCP servers to extend capabilities<\/h2>\n\n<p>Model Context Protocol (MCP) is where Gemini CLI gets most of its power. An MCP server is any process that speaks the MCP protocol (stdio, SSE, or HTTP streaming) and exposes a set of tools. Gemini CLI ships with built-in file, shell, and web-fetch tools; MCP is how you add everything else (Context7, GitHub, Slack, databases, custom internal tools).<\/p>\n\n<p>The <code>mcp add<\/code> command writes the config to <code>settings.json<\/code> for you. To install the Context7 MCP server at user scope:<\/p>\n\n\n<pre class=\"wp-block-code code\"><code>gemini mcp add --scope user context7 npx -y @upstash\/context7-mcp<\/code><\/pre>\n\n\n<p>The resulting <code>~\/.gemini\/settings.json<\/code> looks like this:<\/p>\n\n\n<pre class=\"wp-block-code code\"><code>{\n  \"mcpServers\": {\n    \"context7\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@upstash\/context7-mcp\"]\n    }\n  }\n}<\/code><\/pre>\n\n\n<p>Verify the server registers and the headless auth still works:<\/p>\n\n\n<figure class=\"wp-block-image size-large\"><img decoding=\"async\" src=\"https:\/\/computingforgeeks.com\/wp-content\/uploads\/2026\/04\/wm-gemini-cli-mcp-context7-config.png\" alt=\"Add Context7 MCP server to Gemini CLI settings.json and run a headless prompt\" title=\"\"><\/figure>\n\n\n<p>Every MCP server flag has a full form for when you need more control:<\/p>\n\n\n<pre class=\"wp-block-code code\"><code># Remote SSE server with auth header\ngemini mcp add --transport sse my-api https:\/\/api.example.com\/sse \\\n  -H \"Authorization: Bearer ${MY_TOKEN}\" \\\n  --timeout 10000\n\n# HTTP streaming server with an environment variable\ngemini mcp add --transport http my-db http:\/\/localhost:3000\/mcp \\\n  -e DATABASE_URL=postgres:\/\/localhost\/mydb \\\n  --trust\n\n# Filtered server (allow only specific tools)\ngemini mcp add --scope user safe-fs npx -y @modelcontextprotocol\/server-filesystem \\\n  --include-tools read_file,list_directory<\/code><\/pre>\n\n\n<p>Once servers are registered, reference them with <code>@<\/code> inside an interactive prompt: <code>@context7 fetch the latest nextjs 16 docs<\/code>, <code>@github list my open PRs<\/code>, <code>@my-db run select count(*) from users<\/code>.<\/p>\n\n<h2 class=\"wp-block-heading\">Step 10: Configure settings.json<\/h2>\n\n<p>Settings live in two files. <code>~\/.gemini\/settings.json<\/code> is user-wide. <code>.gemini\/settings.json<\/code> in a project root is workspace-specific and wins over user settings. A sensible, annotated starting point:<\/p>\n\n\n<pre class=\"wp-block-code code\"><code>{\n  \"general\": {\n    \"preferredEditor\": \"code\",\n    \"defaultApprovalMode\": \"auto_edit\",\n    \"sessionRetention\": {\n      \"enabled\": true,\n      \"maxAge\": \"30d\",\n      \"maxCount\": 100\n    }\n  },\n  \"security\": {\n    \"auth\": {\n      \"selectedType\": \"gemini-api-key\"\n    },\n    \"disableYoloMode\": false\n  },\n  \"ui\": {\n    \"theme\": \"GitHub\",\n    \"hideBanner\": true,\n    \"footer\": {\n      \"items\": [\"model\", \"context\"]\n    }\n  },\n  \"model\": {\n    \"name\": \"gemini-2.5-pro\",\n    \"maxSessionTurns\": 50\n  },\n  \"tools\": {\n    \"allowed\": [\"run_shell_command(git)\", \"read_file\"],\n    \"exclude\": [],\n    \"sandbox\": \"docker\"\n  },\n  \"context\": {\n    \"fileName\": [\"GEMINI.md\"],\n    \"includeDirectories\": [\".\/docs\"],\n    \"memoryBoundaryMarkers\": [\".git\"]\n  },\n  \"telemetry\": {\n    \"enabled\": false\n  }\n}<\/code><\/pre>\n\n\n<p>Four fields earn their keep for everyday use. <code>general.defaultApprovalMode<\/code> sets the starting policy: <code>default<\/code> prompts for every tool, <code>auto_edit<\/code> silently approves edits but still prompts for shell commands, <code>yolo<\/code> approves everything, and <code>plan<\/code> is read-only. <code>model.name<\/code> pins the default model so you do not have to type <code>-m<\/code> every time. <code>tools.allowed<\/code> is an allowlist that bypasses confirmation for the specific tool calls listed, so <code>run_shell_command(git)<\/code> lets Gemini run any <code>git<\/code> command but still prompts before any other shell command. <code>mcpServers<\/code> holds the entries that <code>gemini mcp add<\/code> wrote.<\/p>\n\n<p>String values support environment variable interpolation using three syntaxes: <code>\"$VAR\"<\/code>, <code>\"${VAR}\"<\/code>, and <code>\"${VAR:-default}\"<\/code>. Handy for shared team configs that pull secrets from a common env file.<\/p>\n\n<h2 class=\"wp-block-heading\">Step 11: Write a GEMINI.md context file<\/h2>\n\n<p>Skills are on-demand. <code>GEMINI.md<\/code> is always-on context. Put one at the project root to tell Gemini about conventions, architecture, preferred libraries, or anything else it should treat as background knowledge on every turn.<\/p>\n\n<p>Generate a starter from inside a session:<\/p>\n\n\n<pre class=\"wp-block-code code\"><code>cd ~\/code\/my-project\ngemini\n&gt; \/init<\/code><\/pre>\n\n\n<p>Or write one by hand. Keep it short. A 50-line <code>GEMINI.md<\/code> that actually matches reality beats a 500-line one that drifts the first time someone refactors. Typical sections:<\/p>\n\n\n<pre class=\"wp-block-code code\"><code># Project context\n\n## Stack\nNode.js 20 + TypeScript 5.5 + Fastify 5. Tests via Vitest.\n\n## Conventions\n- Absolute imports from `src\/`, no default exports.\n- Every public function has a JSDoc @example.\n- Commit messages follow Conventional Commits.\n\n## Commands\n- `npm run dev` - local dev server on port 3000\n- `npm run test` - full test suite\n- `npm run lint` - eslint + prettier --check\n\n## Do not touch\n- `src\/generated\/` is autogenerated from OpenAPI; edit the spec instead.<\/code><\/pre>\n\n\n<p>Gemini CLI traverses upward from the current directory collecting every <code>GEMINI.md<\/code> it finds, stopping at the first <code>memoryBoundaryMarkers<\/code> entry (default: <code>.git<\/code>). That lets monorepos ship a root <code>GEMINI.md<\/code> plus per-package <code>GEMINI.md<\/code> files without anything leaking across projects.<\/p>\n\n<h2 class=\"wp-block-heading\">Step 12: Use non-interactive mode in scripts<\/h2>\n\n<p>Headless mode is the same binary, different flags. Three shapes of output depending on what consumes the result.<\/p>\n\n\n<pre class=\"wp-block-code code\"><code># Plain text (default)\ngemini -p \"Summarise the README in two sentences\"\n\n# Structured JSON (one blob at the end)\ngemini -p \"Count the TypeScript files in src\/\" --output-format json\n\n# Newline-delimited events during the run\ngemini -p \"Run the test suite and explain any failures\" --output-format stream-json<\/code><\/pre>\n\n\n<p>Stream mode is ideal for CI jobs because you can tail the events with <code>jq<\/code> and react to specific ones (for example, post a message to Slack the first time a tool call blocks on approval).<\/p>\n\n<p>Two more flags are worth knowing for automation. <code>--yolo<\/code> approves every tool call without prompting (dangerous outside a sandbox). <code>--sandbox<\/code> runs the whole session in the official Docker container. Combine them inside a CI runner and Gemini CLI will do destructive work without ever touching the host filesystem.<\/p>\n\n<p>For GitHub Actions, Google publishes a ready-made action at <a href=\"https:\/\/github.com\/google-github-actions\/run-gemini-cli\" target=\"_blank\" rel=\"noreferrer noopener\">google-github-actions\/run-gemini-cli<\/a> that handles PR reviews, issue triage, and on-demand <code>@gemini-cli<\/code> mentions. It wraps exactly the same binary behind a familiar action interface. If you already run <a href=\"https:\/\/computingforgeeks.com\/setup-aider-ai-pair-programming\/\" target=\"_blank\" rel=\"noreferrer noopener\">Aider<\/a> or the <a href=\"https:\/\/computingforgeeks.com\/codex-cli-cheat-sheet\/\" target=\"_blank\" rel=\"noreferrer noopener\">OpenAI Codex CLI<\/a> for the same job, the flag shape will feel familiar.<\/p>\n\n<h2 class=\"wp-block-heading\">Step 13: Pick a release channel<\/h2>\n\n<p>Three channels, three cadences. Install the one that matches your risk tolerance.<\/p>\n\n\n<pre class=\"wp-block-code code\"><code># Stable (Tuesdays 20:00 UTC) - what production should use\nnpm install -g @google\/gemini-cli@latest\n\n# Preview (Tuesdays 23:59 UTC) - next week's stable, help test\nnpm install -g @google\/gemini-cli@preview\n\n# Nightly (daily 00:00 UTC) - main branch as-is, rough edges\nnpm install -g @google\/gemini-cli@nightly<\/code><\/pre>\n\n\n<p>The stable channel is the default when you run <code>npm install -g @google\/gemini-cli<\/code> without a tag. Preview is a week ahead of stable, so running it helps surface regressions before they ship. Nightly mirrors the main branch at midnight UTC and includes everything that passed CI that day, which is great for Google&#8217;s own team and less great for production servers. If you want to compare Gemini CLI against the other agent CLIs before you commit, <a href=\"https:\/\/computingforgeeks.com\/cursor-vs-windsurf-vs-kiro\/\" target=\"_blank\" rel=\"noreferrer noopener\">Cursor vs Windsurf vs Kiro<\/a> covers the IDE side of the ecosystem and <a href=\"https:\/\/computingforgeeks.com\/install-ollama-ubuntu-2604\/\" target=\"_blank\" rel=\"noreferrer noopener\">Ollama<\/a> is the right pick when you need to stay fully local.<\/p>\n\n<h2 class=\"wp-block-heading\">Troubleshooting common issues<\/h2>\n\n<p>Five real errors I hit or logged during the writeup. Fixes below.<\/p>\n\n<h3 class=\"wp-block-heading\">&#8220;Both GOOGLE_API_KEY and GEMINI_API_KEY are set. Using GOOGLE_API_KEY.&#8221;<\/h3>\n\n<p>Not an error. When both env vars are set, Gemini CLI prefers <code>GOOGLE_API_KEY<\/code>. If the key you want is in <code>GEMINI_API_KEY<\/code>, either <code>unset GOOGLE_API_KEY<\/code> before running, or store the same value in both variables (which is what <code>~\/.gemini\/.env<\/code> typically does).<\/p>\n\n<h3 class=\"wp-block-heading\">&#8220;Skill conflict detected&#8221; during startup<\/h3>\n\n<p>Means the same skill exists in two discovery paths (typically <code>~\/.agents\/skills\/<\/code> and <code>~\/.gemini\/skills\/<\/code>). Gemini uses the higher-precedence one. Safe to ignore, but cleaner to remove the duplicate:<\/p>\n\n\n<pre class=\"wp-block-code code\"><code>gemini skills uninstall android-cli --scope user\nandroid init --agent=gemini    # reinstall to the canonical location<\/code><\/pre>\n\n\n<p>Restart the CLI after the uninstall so the skill cache rebuilds.<\/p>\n\n<h3 class=\"wp-block-heading\">&#8220;Error executing tool activate_skill: Tool not found&#8221; in headless mode<\/h3>\n\n<p>Skill activation relies on a tool that only exists in interactive mode. In headless runs (<code>gemini -p<\/code>), the model still sees skill names and descriptions in the system prompt and can infer behavior from them, but it cannot dynamically load the full <code>SKILL.md<\/code>. Either run interactively, or pre-expand the skill into the prompt via <code>@~\/.agents\/skills\/android-cli\/SKILL.md<\/code>.<\/p>\n\n<h3 class=\"wp-block-heading\">&#8220;gemini mcp list&#8221; hangs<\/h3>\n\n<p>The list command connects to each configured server to enumerate its tools. If a server takes too long to start (for example, <code>npx<\/code> cold-starting a Context7 package), the whole command stalls until the default 600-second timeout. Shorten the wait by adding <code>--timeout 5000<\/code> to the <code>mcp add<\/code> call, or remove servers you no longer use with <code>gemini mcp remove &lt;name&gt;<\/code>.<\/p>\n\n<h3 class=\"wp-block-heading\">&#8220;prebuild-install is no longer maintained&#8221; warning on npm install<\/h3>\n\n<p>A transitive dependency (native addon tooling) prints a deprecation warning. It is cosmetic. The install still completes and the binary still runs. Google&#8217;s team tracks this against the CLI issue tracker; no action needed on your end until a future release drops the dependency.<\/p>\n\n<p>For anything not covered here, the in-CLI <code>\/bug \"&lt;short description&gt;\"<\/code> command opens a pre-filled GitHub issue against <a href=\"https:\/\/github.com\/google-gemini\/gemini-cli\/issues\" target=\"_blank\" rel=\"noreferrer noopener\">google-gemini\/gemini-cli<\/a> with your session metadata attached. Use it. The feedback loop is how 0.39 preview landed a month after 0.38 stable.<\/p>\n\n\n","protected":false},"excerpt":{"rendered":"<p>Gemini CLI is Google&#8217;s open-source AI agent for the terminal. It ships the full Gemini 3 model, a 1 million token context window, and a generous free tier (60 requests per minute, 1,000 per day) behind a single gemini binary. Free Google-account access to that tier ends on 18 June 2026 (see the migration section &#8230; <a title=\"Gemini CLI on Linux, macOS, and Windows (Agent Setup)\" class=\"read-more\" href=\"https:\/\/computingforgeeks.com\/install-configure-gemini-cli\/\" aria-label=\"Read more about Gemini CLI on Linux, macOS, and Windows (Agent Setup)\">Read more<\/a><\/p>\n","protected":false},"author":13,"featured_media":166646,"comment_status":"open","ping_status":"","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[39034,50],"tags":[17245,669,282,2254],"cfg_series":[],"class_list":["post-166650","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-ai","category-linux-tutorials","tag-ai","tag-dev","tag-linux","tag-ubuntu"],"_links":{"self":[{"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/posts\/166650","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/users\/13"}],"replies":[{"embeddable":true,"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/comments?post=166650"}],"version-history":[{"count":3,"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/posts\/166650\/revisions"}],"predecessor-version":[{"id":167365,"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/posts\/166650\/revisions\/167365"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/media\/166646"}],"wp:attachment":[{"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/media?parent=166650"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/categories?post=166650"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/tags?post=166650"},{"taxonomy":"cfg_series","embeddable":true,"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/cfg_series?post=166650"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}