Gemini CLI Onboarding Reality Report: What Community Data Shows About the First-Hour Experience

Introduction

Across the open issue tracker on the official google-gemini/gemini-cli repository, a clear pattern emerges for first-time users: the install command itself runs without incident for the vast majority, but the ten minutes that follow — authentication, PATH resolution, understanding which account type unlocks the free tier — produce a disproportionate share of reported friction. GitHub issue #7717 ("Simplified Onboarding Flow for Gemini CLI") and issue #5821 ("Overhaul README.md for Better Clarity and User Onboarding") both document this gap explicitly: the tool's authors themselves acknowledge that the current entry path leaves new users without enough context to choose the right authentication method or understand what the free tier actually covers.

This article is not a step-by-step tutorial walkthrough — that exists at the Gemini CLI quick-start page. Instead it synthesizes what community data reveals about the actual first-hour experience: which friction points appear repeatedly, how the free-tier quota plays out in real use, and what the minimum path to productive work looks like once those early obstacles are resolved.

The sources drawn on here are: the official Gemini CLI documentation, the GitHub issue tracker, the official quota and pricing page, and community tutorials indexed on Google Codelabs and DEV Community.

---

TL;DR

• Install rarely fails; PATH does. The npm install -g @google/gemini-cli command succeeds for most users, but gemini: command not found after install is the single most-reported first-day issue — caused by the npm global bin directory not being on PATH.
• Account type determines free-tier access. Personal Google accounts unlock 1,000 requests/day via OAuth. Google Workspace accounts do not qualify for the free tier and require a separately provisioned API key or Cloud project.
• "1,000 requests/day" is not 1,000 prompts. A single agentic task can trigger dozens of internal API calls. Community discussion #4122 documents users hitting the daily limit faster than expected for this reason.
• The .env bypass is unintuitive. Issue #3144 documents a documented but unexpected behavior: if a .env file in the working directory contains GEMINI_API_KEY, the onboarding auth flow is silently skipped, leaving new users unsure whether authentication succeeded.
• Node 18 minimum; many tutorials cite Node 20. The official installation docs now specify Node 20+ as the recommended baseline. Users on older Node versions see cryptic errors that do not clearly identify the version mismatch as the root cause.

---

What the Official Docs Show

The official quickstart describes a two-command entry path:

npm install -g @google/gemini-cli
gemini

On first run, the CLI presents an authentication menu. For personal Google accounts, the recommended path is OAuth via browser, which provisions access to the Gemini Code Assist free tier: 60 requests per minute and 1,000 model requests per day. The official quota page distinguishes this from API-key access, which is subject to the Gemini API rate limits — a separate quota bucket with its own ceiling (100 requests/day on the free API tier for Gemini 2.5 Pro).

The official authentication setup page documents two authentication paths: Google account OAuth (recommended for personal use) and API key via GEMINI_API_KEY (for scripting and CI environments). The distinction matters because the two paths draw from different quota pools, but nothing in the install output or first-run prompt makes this clear to a new user.

The official troubleshooting guide lists PATH misconfiguration, Node version mismatch, and corporate SSL interception as the three most common causes of a broken install. The Google Codelabs hands-on lab supplements the official docs with a guided walkthrough that covers authentication in more depth than the README does.

---

What Community Reports Actually Find

Friction Point 1: PATH resolution

GitHub issue #8397 ("gemini command not found after successful installation") is one of several open threads describing an identical experience: npm install -g exits with no error, but running gemini immediately produces command not found. Issue #13248 documents the same failure appearing after an update, not just initial install — suggesting the issue is structural to how npm global binaries interact with shell PATH configuration rather than specific to any release.

The fix is documented in the official troubleshooting guide:

# Find the npm global bin directory
npm config get prefix

# Add it to PATH (replace with actual path from above)
export PATH="$(npm config get prefix)/bin:$PATH"

# Persist across sessions
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc

The arm.com install guide notes that Homebrew installation on macOS sidesteps this problem by handling the PATH registration automatically, which may explain why Homebrew is increasingly recommended in community tutorials for macOS users.

Friction Point 2: Authentication and account type

Issue #3144 documents a subtle but consequential behavior: when GEMINI_API_KEY is present in a .env file in the working directory, the CLI silently uses it and skips the onboarding auth flow entirely. First-time users who have previously set an API key for another Google project and then attempt to run Gemini CLI in that directory never see the plan-selection screen and are left uncertain about which quota they are drawing from.

For Google Workspace users, the confusion runs deeper. The Gemini Code Assist FAQ confirms that the free tier is not available for Workspace accounts. Issue #11785 documents the downstream consequence: Workspace users who authenticate via OAuth get the browser flow, receive no explicit error, but then find that their free-tier quota is zero. The correct path for Workspace users — obtain an API key from Google AI Studio and set GEMINI_API_KEY — is documented in the FAQ but not surfaced during the onboarding flow itself.

Friction Point 3: Node version requirements

The official installation page now lists Node 20 as the recommended minimum. Community tutorials diverge: some cite Node 18, others Node 20. Users on Node 16 or 17 encounter errors that do not mention the version mismatch as a cause — the error output references internal module resolution failures rather than a clear "unsupported Node version" message. The Gemini CLI Tutorial Series on Google Cloud Medium calls out the Node version check as a required pre-step that the README undersells.

# Verify Node version before installing
node --version
# Should be >= 20.x for best compatibility

# Update via nvm if needed
nvm install 20
nvm use 20

Friction Point 4: Corporate and CI environment interference

The official troubleshooting guide documents two environment-specific failure modes that appear repeatedly in the issue tracker. First, corporate networks with SSL/TLS interception produce UNABLE_TO_GET_ISSUER_CERT_LOCALLY errors; the fix requires setting NODE_EXTRA_CA_CERTS to the enterprise CA bundle. Second, CI environments where any environment variable prefixed with CI_ is set cause the CLI to detect a non-interactive context and refuse to launch, producing confusing output for developers who run the tool locally under CI-style env configurations.

---

The Minimum Path to Productive Use

Synthesizing the official docs and the friction patterns above, the minimum viable onboarding path — the sequence least likely to produce blockers — looks like this:

Step 1: Verify Node version. Confirm node --version returns 20.x or higher before running the install command. This eliminates the largest category of silent install failures.

Step 2: Install.

npm install -g @google/gemini-cli

Step 3: Verify PATH before proceeding.

gemini --version

If this returns command not found, run npm config get prefix and add the resulting path's bin subdirectory to PATH before continuing. Do not proceed to authentication until this resolves — auth state is not persisted if the binary cannot be found on subsequent sessions.

Step 4: Authenticate with the correct account type.

• Personal Google account: run gemini and select the OAuth option. This provisions the 1,000 requests/day free tier.
• Google Workspace account: skip OAuth, obtain an API key from Google AI Studio, then run:

export GEMINI_API_KEY="your-key-here"
gemini

Step 5: Run the orientation prompt.

gemini "List the files in the current directory and summarize what kind of project this is."

A successful response confirms that authentication, PATH, and model access are all working. This single prompt exercises the full request path and surfaces any remaining configuration issues before a user invests time in a longer workflow.

---

Free Tier Reality

The official quota page states the free tier quota as 60 requests per minute and 1,000 model requests per day for personal Google account authentication. Community discussion #4122 ("Clarification on Daily Request Limit") adds an important clarification that the official docs do not prominently surface: the 1,000 requests/day figure counts API calls, not user-visible prompts. Agentic tasks — where the CLI reads multiple files, runs shell commands, and iterates on results — generate multiple API calls per user interaction.

The practical implication, drawn from reports in that thread: a developer running three to five multi-step coding tasks per day can approach the daily limit within a normal working session if those tasks involve significant file context or tool use. Single-shot questions (asking the CLI to explain a function or summarise a file) consume one or two requests each and leave the quota largely intact.

The quota split between authentication methods is also relevant:

| Auth method | Daily limit | Notes | |---|---|---| | Personal Google OAuth | 1,000 requests/day | Gemini Code Assist free tier | | Gemini API key (free) | 100 requests/day (Gemini 2.5 Pro) | Per Gemini API rate limits | | Gemini API key (paid) | Varies by plan | Billing via Google Cloud |

The Gemini API billing docs cover the paid tier transition if the free quota proves insufficient for regular use.

---

Common First-Day Confusions

"I authenticated successfully but queries fail." The most common cause is Workspace account usage with the OAuth path. The auth flow completes without error but the free-tier quota is zero for Workspace accounts. Resolution: switch to API key authentication as described above.

"My quota ran out but I only sent a few prompts." Agentic and file-heavy prompts generate multiple API calls internally. Community discussion #4122 confirms this is a known discrepancy between user-visible interactions and API call counts. Single-question prompts are quota-efficient; multi-step file-editing tasks are not.

"The CLI picked up an old API key I didn't intend to use." Issue #3144 describes exactly this: a GEMINI_API_KEY in a .env file in the project directory silently overrides the authenticated session. Check for .env files if quota appears to come from an unexpected pool.

"I installed successfully on one machine but not another." Node version differences between machines are the most frequent root cause when the install command succeeds on one system and fails on another. The official installation docs explicitly list the version requirement; checking it first eliminates this variable.

"The onboarding flow looks different from tutorial screenshots." As documented in issue #7717, Google has been iterating on the onboarding flow. Screenshots in older tutorials (including the initial README) do not match the current v0.38.x flow. The official quickstart reflects the current state.

---

Recommendation

Based on the friction patterns documented above, the most reliable onboarding path for new users is: verify Node 20+, install via npm, confirm gemini --version works before attempting auth, and select the account type that matches the actual account being used. Personal Google account users should use OAuth; Workspace users should use an API key.

For free-tier sustainability, the evidence from community discussion #4122 suggests treating the 1,000 requests/day ceiling as roughly 50–100 agentic-task interactions under typical working conditions — adequate for learning and moderate daily use, but likely to bind during intensive refactoring sessions. Users who reach the free-tier ceiling regularly should evaluate the paid API key tiers via Google AI Studio billing.

The Gemini CLI quick-start page on this site covers the command patterns in detail once the installation and authentication foundation is in place.

---

FAQ

Q: Why do I see "gemini: command not found" even after a successful npm install?

This is the most frequently reported first-day issue, documented in issues #8397 and #13248. The cause is that the npm global binary directory is not on the shell PATH. Run npm config get prefix, then add its bin subdirectory to PATH in your shell profile (~/.zshrc or ~/.bashrc). The official troubleshooting guide covers this with platform-specific steps.

Q: Does my Google Workspace account qualify for the free tier?

No. The Gemini Code Assist FAQ confirms that the free tier is restricted to personal Google accounts. Workspace account holders need to provision an API key from Google AI Studio and authenticate via GEMINI_API_KEY. This is a common source of confusion because the OAuth flow completes without error even for Workspace accounts, and no quota-zero warning appears until the first API call fails.

Q: How quickly does the 1,000 requests/day free tier actually run out?

It depends on task type. Single-question prompts (explain this function, summarise this file) use one to two API calls each. Multi-step agentic tasks (edit files, run commands, iterate) can consume ten to thirty API calls per user-visible prompt. Community discussion #4122 documents users hitting the daily limit within a single working session on coding-heavy days. Light use — fewer than twenty short prompts — will not approach the ceiling.

Q: What Node version does Gemini CLI actually require?

The official installation page now specifies Node 20 as the recommended minimum, though earlier documentation cited Node 18. The Google Cloud Gemini CLI Tutorial Series calls out the version check as a required pre-step. Running on older versions produces internal module errors that do not clearly identify the Node version as the root cause.

Q: Is there an official interactive tutorial beyond the README?

Yes. Google publishes a hands-on Codelab that walks through authentication, basic commands, and file operations with more context than the repository README. It is referenced in the official documentation index and reflects the current CLI version more reliably than third-party tutorials, which frequently lag behind the release cadence documented on the changelogs page.