Every time a new AI tool drops into the terminal ecosystem, half the sysadmin community treats it like a toy and the other half treats it like a production liability. Gemini CLI sits somewhere in between, and after running it across a handful of Ubuntu 26.04 boxes — from a throwaway VM to an actual dev workstation handling client repos — the honest take is this: it’s genuinely useful once you get past the installation quirks and understand what it’s actually touching on your filesystem.

If you’re reading this, you probably already know what Gemini CLI is. Google’s open-source terminal agent wraps the Gemini models in a REPL that can read files, run shell commands, search the web, and even patch code directly in your working directory. That last part is exactly why installation matters more than it looks. This isn’t a passive chatbot wrapper — it’s an agent with run_shell_command access sitting on your box, and how you install and configure it determines whether it’s a productivity multiplier or a headache waiting to happen.

Ubuntu 26.04 LTS ships with a newer kernel and updated Node.js packaging defaults compared to 24.04, which changes a few of the install steps you might have bookmarked from older tutorials. There’s also a timing wrinkle worth flagging up front: Google retired free-tier OAuth access to the hosted Gemini CLI backend on June 18, 2026, pushing casual users toward either a paid API key or the newer Antigravity CLI. That doesn’t kill this guide — the open-source gemini binary and any paid key path keep working exactly as documented — but it does change what “getting started” looks like today versus six months ago.

This walkthrough covers the full install path on Ubuntu 26.04 LTS: prerequisites, the actual npm install, authentication (including the post-June-2026 reality), configuration hardening, and the troubleshooting scenarios you’ll actually hit in a terminal, not the sanitized ones from a demo video. Expect real commands, real error output, and the kind of gotchas that only show up after you’ve broken something once.

Prerequisites Before You Touch npm

Gemini CLI has a short but non-negotiable dependency list. Skip any of these and the install either fails outright or half-works in a way that’s more annoying than a clean failure.

• Ubuntu 26.04 LTS with a current kernel — the CLI itself doesn’t care about kernel version directly, but Node’s native modules occasionally do on very old glibc.
• Node.js 20.0.0 or later — this is the hard requirement; anything below 20 will throw obscure errors mid-install.
• npm (bundled with Node, but verify the version anyway).
• At least 4GB RAM for casual use; bump to 16GB+ if you’re pointing it at large codebases or running long agentic sessions.
• A stable internet connection — Gemini CLI is not a local-first tool by default, every prompt round-trips to Google’s API unless you’re running the local Gemma fallback.

Check what you’re working with before installing anything:

lsb_release -a
node -v
npm -v

If Node isn’t installed, or you’ve got a stale version sitting from a previous project, don’t fight it with apt’s default repo — Ubuntu’s stock repos lag behind Node’s release cadence more often than not. Use NodeSource instead:

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
node -v

That last command should print something starting with v20. or higher. If it doesn’t, clear npm’s cache and check your PATH before proceeding — a half-upgraded Node install is worse than no install at all.

Installing Gemini CLI on Ubuntu 26.04 LTS

Here’s the part everyone’s actually here for. The recommended and most reliable method is a global npm install.

Step 1: Run the Global Install

sudo npm install -g @google/gemini-cli

This pulls the package and its dependencies — expect somewhere in the range of 600+ packages during resolution, which is normal for a Node CLI tool with this much surface area. On a decent connection this takes under a minute; on a throttled VPS it can crawl, so don’t panic if it sits for a bit.

Step 2: Verify the Installation

gemini --version

You should get a clean version string back, something like 0.40.1 depending on when you’re reading this. If this command hangs or errors immediately, jump to the troubleshooting section below rather than reinstalling blindly — reinstalling over a broken npm global path just compounds the mess.

Step 3: Alternative Install Paths Worth Knowing

npm isn’t the only door in. Depending on your environment, one of these might fit better:

• npx (no permanent install): npx @google/gemini-cli — useful for a quick test drive without committing disk space or global package pollution.
• Homebrew (if you’ve got linuxbrew set up): available but less common on server boxes.
• Snap: sudo snap install gemini-cli — convenient on desktop Ubuntu, less ideal for minimal server installs where snapd isn’t already running.
• Docker sandbox image: pull the published sandbox container directly if all you have is Docker and you want full isolation from the host.

For anything touching production infrastructure, skip snap and npx-on-demand and stick with the global npm install — it’s the path with the most predictable update behavior and the one every official doc assumes you’re on.

First Launch and Authentication

This is where most people get stuck, and it’s not because the process is hard — it’s because the free-tier landscape shifted mid-2026 and a lot of tutorials online are now outdated.

Launch the CLI for the first time:

gemini

You’ll be prompted to choose an authentication method. There are three real options:

If you’re setting this up today, on a fresh Ubuntu 26.04 box, and you’re not already grandfathered into an active paid plan, go straight for the API key path. Grab a key from Google AI Studio, then:

export GEMINI_API_KEY="your_key_here"
echo 'export GEMINI_API_KEY="your_key_here"' >> ~/.bashrc
source ~/.bashrc

Test it:

gemini --list-extensions

If that returns cleanly instead of throwing an auth error, you’re authenticated and ready to go. For a headless server where you’ll never see a browser popup, this is the only realistic path anyway — OAuth wants a browser redirect, which doesn’t exist on a bare SSH session.

A Note on the OAuth Deprecation

If you built muscle memory around “just sign in with Google and get a free tier,” that workflow is gone for casual accounts as of mid-June 2026. Google didn’t kill Gemini CLI itself — the binary, the open-source repo, and paid-key access all keep working exactly as before. What disappeared is the no-cost quota for plain Google-account logins, with Google steering that traffic toward a separate tool called Antigravity CLI instead. If you specifically need a zero-cost option and don’t want to touch billing, that’s the realistic alternative — but for anything approaching production or repeated daily use, a paid API key is the more stable long-term choice anyway. Free tiers, historically, are never built for reliability.

Configuration and Project Setup

Once authenticated, Gemini CLI drops its state into ~/.gemini/ — worth knowing this layout because you’ll be debugging it eventually.

~/.gemini/
├── history/        # REPL transcripts per project
├── installation_id # anonymized telemetry id
├── projects.json   # tracks which directories you've used the CLI in
├── tmp/             # tool sandbox scratch space
├── commands/        # custom TOML slash commands
└── settings.json    # created once you save any preference

Settings resolve in a strict priority order — project-level ./.gemini/settings.json wins over user-level ~/.gemini/settings.json, which wins over system-level /etc/gemini-cli/settings.json. That system-level file is genuinely underused; if you’re managing Gemini CLI across a fleet of dev machines, dropping a baseline policy there saves you from chasing individual configs.

A reasonably locked-down settings.json for a shared or production-adjacent environment looks like this:

{
  "selectedAuthType": "USE_GEMINI",
  "sandbox": "docker",
  "usageStatisticsEnabled": false,
  "excludeTools": ["run_shell_command"],
  "fileFiltering": {
    "respectGitIgnore": true,
    "respectGeminiIgnore": true
  },
  "telemetry": { "enabled": false }
}

Excluding run_shell_command outright is aggressive, but on a box where you don’t fully trust every prompt source, it’s the difference between an agent that edits files and one that can also execute arbitrary shell commands under your user. Decide deliberately, don’t default into it.

Also worth setting up on any repo you’ll use regularly: a .geminiignore file, syntax identical to .gitignore.

# .geminiignore
node_modules/
dist/
.env
.env.*
*.log
secrets/
infra/state/

Without this, the agent’s context-loading tools will happily read your .env file if you ask it something broad like “review this project” — and that’s not a hypothetical, that’s the default behavior if you don’t fence it off.

Real-World Use Cases and Edge Cases

On a WordPress-heavy stack or a mixed Nginx/PHP-FPM environment, Gemini CLI earns its keep doing things like:

• Reviewing an Nginx config diff before a reload: cat /etc/nginx/sites-available/prod.conf | gemini -p "Check this config for security misconfigurations"
• Summarizing a noisy access log during a traffic spike investigation without manually grepping for an hour.
• Drafting a first-pass fix for a WP-CLI script error, then handing it off for manual review rather than blind execution.

The edge case that trips people up: running Gemini CLI against an untrusted directory — a client’s repo you just cloned, for instance — triggers a hard block by design.

Gemini CLI is not running in a trusted directory.
To proceed, either use --skip-trust, set GEMINI_CLI_TRUST_WORKSPACE=true,
or trust this directory in interactive mode.

That’s not a bug, it’s a guardrail. Resist the urge to blanket-set GEMINI_CLI_TRUST_WORKSPACE=true globally on a shared machine — scope it per-session with --skip-trust on one-off calls instead, or trust interactively when you genuinely know the repo.

Troubleshooting Common Errors

“Please set an Auth method”

You’ll see this if there’s no env var and no saved settings.json auth type:

Please set an Auth method in your /root/.gemini/settings.json
or specify one of the following environment variables before running:
GEMINI_API_KEY, GOOGLE_GENAI_USE_VERTEXAI, GOOGLE_GENAI_USE_GCA

Fix: export GEMINI_API_KEY, or launch gemini interactively once and complete the auth flow so it persists to disk.

“Quota exceeded for metric: generate_content_free_tier_requests”

Quota exceeded for metric: generativelanguage.googleapis.com/generate_content_free_tier_requests,
limit: 5, model: gemini-3-flash

This means you’re hammering free-tier limits. The CLI auto-retries with backoff, but if the daily ceiling is hit, waiting is the only free fix — switch to a paid API key or fall back to a local Gemma model for the rest of the day.

“Ripgrep is not available. Falling back to GrepTool”

Not fatal, just slow on large repos. Install ripgrep:

sudo apt install -y ripgrep

The CLI degrades gracefully without it, but on a codebase with tens of thousands of files, that fallback grep is noticeably sluggish.

npm install fails with permission errors

If sudo npm install -g throws EACCES errors even with sudo, your global npm prefix is likely misconfigured from a prior install. Check with npm config get prefix and, if it points somewhere under your home directory instead of /usr/local, either fix ownership on that path or reconfigure npm to use a proper global directory rather than layering more sudo on top of a broken setup.

Command runs but hangs indefinitely

Usually a network/proxy issue, not a Gemini CLI bug. Confirm outbound HTTPS to Google’s API endpoints isn’t being blocked by a firewall rule or corporate proxy — a curl -I https://generativelanguage.googleapis.com is a fast sanity check before digging deeper into the CLI itself.

Best Practices and Optimization Tips

A few habits that separate a stable setup from a fragile one:

• Pin GEMINI_API_KEY via environment variables in a systemd service file rather than hardcoding it into scripts, especially on shared servers.
• Enable checkpointing ("checkpointing": {"enabled": true}) before letting the agent make bulk edits — /restore is faster than reconstructing a bad diff from git reflog.
• Use --approval-mode plan for audits and code review sessions where you explicitly don’t want the agent touching files, only reasoning about them.
• Run resource-heavy sessions with the sandbox flag (--sandbox) enabled when testing untrusted extensions or MCP servers — isolates shell execution inside Docker/Podman rather than your host.
• Monitor RAM usage during long agentic sessions on large codebases; the 16GB recommendation isn’t marketing fluff, context-heavy sessions genuinely eat memory.
• Disable telemetry ("telemetry": {"enabled": false}) on any box handling sensitive client code, and pair that with a .geminiignore covering secrets and env files.

On network-constrained boxes — think a small VPS running multiple services — treat Gemini CLI sessions like any other bursty process: don’t run it concurrently with a heavy build or database migration if bandwidth and CPU are already tight. It’s not resource-free; every prompt is a round trip plus local tool execution overhead.

Security Considerations Worth Taking Seriously

Because this agent can execute shell commands and write files, treat its installation with the same scrutiny you’d apply to any tool with sudo-adjacent reach:

• Never run Gemini CLI as root on a shared or production system unless the task specifically requires it.
• Firewall outbound rules should already permit HTTPS to Google’s API domains — don’t loosen firewall policy broadly just to accommodate this tool.
• Use excludeTools in settings.json to blacklist run_shell_command on machines where you only want file-reading and reasoning, not execution.
• Review MCP server configs before adding them — a malicious or misconfigured MCP server extends the agent’s reach in ways that aren’t obvious from the CLI alone.
• Keep npm and Node patched; a stale Node runtime is a bigger attack surface than the CLI package itself.