Installing Gemini CLI should leave you with two things: a command your terminal can find and an authenticated session that can answer a small prompt. This guide focuses on reaching that point and diagnosing setup failures. You do not need to connect a repository, install extensions, or configure an automated workflow to verify the installation.
Keep a note of the operating system, terminal, and CLI version you use. Those details make a useful bug report if a later step fails. Run the setup commands yourself in your terminal; they are not prompts to send to an AI agent.
Check the Runtime Before Installing
The current official installation guide lists Node.js 20 or newer and an internet connection among the requirements. Check your terminal:
node --version
npm --version
If either command is missing, install a supported Node.js release using your existing Node installation method, then open a new terminal and check again. If you use a version manager, activate the intended Node version before installing the CLI. Avoid mixing several Node installation methods while diagnosing a problem: otherwise, the executable used for installation may differ from the one used at launch.
On Windows, choose whether you are working in PowerShell or a WSL Linux shell. Treat them as separate environments. Installing an npm package inside WSL does not establish that the same command is installed in native Windows.
Install and Check the Executable
For a global npm installation, run:
npm install -g @google/gemini-cli
gemini --version
gemini --help
The version command checks that the executable starts; it does not establish that authentication or model access works. Save the version number if you need to investigate a failure.
For a trial without a permanent global installation, the documented alternative is:
npx @google/gemini-cli
Neither an unversioned npm installation nor an unversioned npx invocation is a commitment to a particular release forever. Record the version you actually run. Consult the installation guide when you need a specific release or a different installation method.
Authenticate Through the Supported Flow
Start an interactive session:
gemini
Follow the authentication choice appropriate to your account. The authentication guide separates Google sign-in, a Gemini API key, and Vertex AI credentials. Organization accounts can have additional project requirements. Check the current account conditions rather than assuming every sign-in receives the same model access or quota.
If you choose a Gemini API key, set it in the same terminal before launching the CLI. These examples use placeholder values; do not copy a real key into a shared document.
In Bash or Zsh:
export GEMINI_API_KEY="REPLACE_WITH_YOUR_KEY"
gemini
In PowerShell:
$env:GEMINI_API_KEY="REPLACE_WITH_YOUR_KEY"
gemini
These examples set the variable for the current shell session. Do not paste the Bash syntax into a PowerShell profile. Vertex AI has its own credential and project setup; follow that documented path instead of treating an AI Studio key as an interchangeable Vertex configuration.
Verify Access With a Small Prompt
For this check, use a new empty folder rather than opening a private repository. Once authenticated, enter this prompt in Gemini:
Reply with a single sentence confirming that you received this message.
Do not read files, execute commands, or change anything.
The purpose is narrow: verify that the session can receive a model response. It does not test repository access, tool execution, or the correctness of generated code. The wording is a request to the agent, not an enforced permission boundary.
If you receive a response, the installation and basic access check are complete. A response about a quota or account restriction means the executable may be working while model access still needs attention. Keep those diagnoses separate.
Diagnose the Layer That Failed
The terminal cannot find gemini
First check whether you installed it in this environment and under the active Node version. Inspect the npm prefix:
npm config get prefix
In Bash or Zsh, check the command selected by the shell:
command -v node
command -v npm
command -v gemini
In PowerShell, use:
Get-Command node, npm, gemini
If installation succeeded but the executable is absent from command lookup, investigate PATH and the installation location. Opening a new terminal may be necessary after a runtime installation. Repeating the same global install without checking the environment can hide the underlying mismatch.
npm reports a permission error
Record the failing path and check whether it belongs to a system installation or a user-managed Node environment. Follow the configuration appropriate to that installation method. Do not immediately add sudo or change the global npm prefix: that can introduce another configuration problem, especially when a version manager already manages the location.
Authentication opens a browser but does not finish
Check the environment in which the CLI is running and where the browser opens. A local terminal, a remote machine, and a WSL session do not necessarily share the same browser setup. Use the documented authentication method appropriate to that environment and check organization restrictions if applicable.
The session reports an account, network, or quota error
Capture the error category without copying credentials. Verify the selected account and authentication method, then check the relevant service and network requirements. A proxy, expired credential, unavailable service, and usage limit require different responses; reinstalling the CLI is not a universal repair.
Keep Configuration Minimal Until Setup Works
Use the interactive settings and authentication flow before copying configuration from an old tutorial. The configuration reference documents nested settings such as ui.theme and security.auth.selectedType. A JSON object with similarly named keys at the root is not automatically equivalent.
Repository instructions in GEMINI.md, approval policies, and sandboxing affect later work. They are not prerequisites for proving that the executable launches and authenticates. Configure them for a concrete task rather than disabling protections to get past an unrelated setup error.
Frequently Asked Questions
No. The documented npx command provides an alternative to a permanent global install. Record the version actually used if you need to reproduce a problem.
Choose the environment in which you intend to work and follow its setup requirements. Check Node, npm, Gemini, and authentication inside that environment. Do not assume an installation in one is also configured in the other.
The version check only proves that the executable starts. A model request also needs usable credentials, network access, and account access within the applicable limits. Diagnose the request error separately.
For an npm global installation, the official FAQ documents npm install -g @google/gemini-cli@latest. Check gemini --version afterward. Use the update process for your actual installation method if you did not install with npm.
Not for the basic checks in this guide. Start with the supported interactive flow and consult the current configuration reference before adding settings for a specific need.
Conclusion
You have finished setup when the command resolves in your chosen terminal, the executable starts, and an authenticated session answers a small prompt. Keep the version and any environment notes for future troubleshooting. Next, use the Gemini CLI debugging tutorial to practice a small code change with an explicit test and review process.
Transparency Note: Links in this article are not affiliate links. No compensation is received for including them.