WebFV
Agent runtimes / Field guide

Install Gemini CLI with npm and fix startup errors

Install the official npm package, check that the command starts, and follow the error for the stage that failed.

By WebFV Editorial · Checked October 22, 2026 · Gemini CLI 0.65.0

What the evidence coversIsolated package, version and help checks on macOS ARM64. No interactive login or model request. Error fixes are documentation-based.

Install the command you intend to run

To install Google's Gemini CLI as a terminal command, use:

npm install -g @google/gemini-cli

The -g matters. The search phrase npm install @google/gemini-cli omits it and installs a package in the current project. That does not make gemini available in every terminal directory. For a terminal tool, use the global command above unless you deliberately want a project dependency.

This guide follows the official installation instructions and the stable npm package, 0.65.0, checked October 22, 2026. Installation, command startup and access to a model are separate checks. A successful install does not establish account eligibility or available quota.

1. Check Node and npm in the same terminal

node --version
npm --version

Both commands should print a version and exit. The current installation documentation lists Node.js 20.0.0+, and the published package's engines.node field is >=20. Check that requirement again when installing a later release:

npm view @google/gemini-cli@latest version engines

If node or npm is missing, first follow npm's Node.js and npm installation guidance. If Node is too old, select a compatible version through your existing version manager, then repeat both checks in a new terminal. Do not assume the version in one terminal matches an IDE terminal or a different shell.

Google labels its OS and memory list as recommended specifications. The recommendations do not establish a hard support cutoff for every older machine. This page does not claim a compatibility test on Windows or Linux.

2. Choose one installation route

Your situation Command or next step
You want the gemini command available globally npm install -g @google/gemini-cli
You want to try the CLI without a permanent global installation npx @google/gemini-cli
You already manage tools with Homebrew on macOS or Linux brew install gemini-cli
You intentionally installed a project dependency Run it through that project's npm tooling; do not expect a global command

Use one route initially. Installing through both npm and Homebrew can leave you checking a different executable from the one you just updated. The npx route can download and cache packages; “no permanent global installation” does not mean “no download.” Homebrew is not the Windows route in this table.

The npm command without a release tag selects the stable latest channel. Preview and nightly releases are separate choices; they are unnecessary for this basic installation check.

3. Verify startup before signing in

After the npm installation finishes successfully, run:

gemini --version
gemini --help

Expected result: a version number, then command help. The version should correspond to the executable you installed; it need not stay at 0.65.0 after future updates. These checks establish that the shell can locate and start the CLI. They do not verify a model response.

For the first interactive launch, open an empty folder you created for the test, change into it, and run:

gemini

Follow the setup or authentication prompt appropriate to your account. You do not need to submit a prompt just to establish that the interface opens. If startup fails, retain the exact command and first meaningful error line before choosing a branch below.

4. Resolve the stage that actually failed

Node is missing or the engine requirement is unmet

Return to the two version checks. An EBADENGINE message identifies an engine mismatch; read the package name and required version in that message. Updating a different Node installation will not fix the Node selected by your current shell.

Once the active runtime meets the requirement, retry the same install route. If it still fails, preserve the new error instead of treating every nonzero exit as a Node problem.

npm reports EACCES while installing globally

For global-install permissions errors, npm recommends a Node version manager. Use that route first if you already manage Node this way.

npm also documents a user-directory alternative for macOS/Linux, not Windows:

npm config set prefix ~/.local

That changes where future global npm installs go. If you choose it, add the following line to ~/.profile in a text editor:

PATH=~/.local/bin:$PATH

For Zsh, npm's instructions additionally load that profile from ~/.zprofile with source ~/.profile. Reload the profile, retry the global Gemini CLI install, and check gemini --version. Keep this alternative separate from a version manager's own setup instructions. Do not apply both fixes blindly.

Avoid using sudo npm install, broad permission changes or disabled TLS verification as a generic response. They do not diagnose which directory or connection failed.

Installation succeeds, but gemini is not found

This distinction appears in public reports for Windows and macOS. Those reports establish the symptom; they do not prove your machine has the same cause.

Check the global installation and prefix:

npm ls -g --depth=0 @google/gemini-cli
npm prefix -g

If the package is absent, confirm whether you omitted -g or switched Node environments. If present, compare its executable location with PATH. npm's folder documentation places global executables in {prefix}/bin on macOS/Linux and directly in {prefix} on Windows.

For Bash/Zsh, inspect resolution and try the global binary directory in this terminal only:

command -v gemini
export PATH="$(npm prefix -g)/bin:$PATH"
gemini --version

For Windows PowerShell:

where.exe gemini
$env:Path = "$(npm prefix -g);$env:Path"
gemini --version

These PATH changes affect the current shell. If the check now works, add the verified directory through your normal shell or Windows user PATH configuration, then test a fresh terminal. Keep existing PATH entries. If multiple locations are returned, identify which installation you intend to keep before removing anything.

The CLI opens, but login, quota or the network fails

Proceed to Google's authentication guide for Google sign-in, Gemini API key or Vertex AI configuration. Account type and organization settings affect the appropriate route. We have not authenticated or run a paid request for this guide.

For a corporate certificate error, use the certificate-trust guidance in the official troubleshooting guide with your administrator's CA configuration. Do not disable certificate verification. For a quota message, check the quota for the authentication route you selected; reinstalling the npm package does not create quota.

An exit code alone is insufficient. Record whether failure occurred during npm installation, command lookup, CLI startup or authentication. Source-repository instructions such as npm run build apply to a source checkout; they are not a general repair for an ordinary npm installation.

What we verified, and what comes next

On macOS ARM64 with Node 24.5.0 and npm 11.5.1, we installed the exact 0.65.0 package into an isolated temporary prefix with install scripts disabled and optional native dependencies omitted. This limited check returned 0.65.0 for --version and command help for --help, both with exit code 0.

We did not change the machine’s global npm prefix, PATH or shell profiles. We did not test the full optional-dependency installation, interactive onboarding, Windows/Linux startup, EACCES repairs or an authenticated model response. The troubleshooting branches above are based on official documentation, not reproduced failures.

Once the command starts, continue with the official authentication documentation. If these installation instructions no longer match the package, report a correction with the CLI version, platform and a sanitized error. Keep account tokens, private file paths and credentials out of anything you share.