Gemini CLI is an open-source AI agent that brings Google’s Gemini models directly into your terminal, the same place you already spend most of your day. Gemini CLI can generate code, explain repositories, manage files, and write unit tests, all from the command line. This guide walks through installing Gemini CLI, authenticating, and running practical coding tasks so you can get started fast. If you are weighing your options first, see how it compares in my Gemini CLI vs Claude Code comparison.
Table of Contents
What Is Gemini CLI?
Gemini CLI is an open-source, terminal-based AI agent developed by Google. It connects to Google’s Gemini models and lets you interact with them directly from your command line. Unlike web-based chat interfaces, Gemini CLI operates within your local development environment, meaning it can read and modify files, run commands, and help you automate repetitive coding tasks without leaving the terminal. The project is actively maintained on GitHub, with frequent commits and over 105,000 stars, indicating strong community interest.
Getting Started: Installation and Setup
There are two primary ways to use Gemini CLI: install it locally on your machine or use it via Google Cloud Shell, where it comes pre-installed. Each method has different requirements and advantages.
Prerequisites for Local Installation
To install Gemini CLI locally, you need Node.js version 20 or later and npm (Node Package Manager). If you do not have Node.js installed, you will need to set it up before proceeding. Cloud Shell users can skip this step because Gemini CLI is already available in that environment.
Global Installation with npm
The official installation command is straightforward. Open your terminal and run:
npm install -g @google/gemini-cli
This installs the Gemini CLI package globally, making the gemini command available anywhere in your terminal. After installation, you can verify it worked by running gemini --version.
First Launch and Authentication
On first launch, Gemini CLI asks you to choose a theme and complete authentication. Authentication requires a Google account. You can either sign in with Google directly or configure a Google Cloud project for API access. If you are using Cloud Shell, these prompts use default values, so you can start using Gemini CLI immediately without any extra steps.
Configuration Options
Gemini CLI offers multiple levels of configuration to suit different workflows. Understanding how to manage settings helps you tailor the tool to your projects.
Settings File Levels
Configuration is stored in a settings.json file, which can exist at three levels: system, workspace, and user. The user-level file is located at ~/.gemini/settings.json. Settings are applied hierarchically, with workspace-level settings overriding user-level settings, and system-level settings acting as defaults. You can edit these files manually or use the /settings command within Gemini CLI to adjust preferences.
Enabling Gemini 3 Pro
Gemini 3 Pro is available in Gemini CLI for users who have a Google AI Ultra subscription or a paid Gemini API key. To enable it, you first need to upgrade Gemini CLI to version 0.16.x or later. Then run the /settings command inside Gemini CLI and toggle the ‘Preview features’ option to true. After saving the change, Gemini 3 Pro will be accessible. Other users can join a waitlist for access.
Common Coding Tasks
Gemini CLI can handle a variety of development tasks. The official documentation highlights several use cases, from generating new code to automating file operations.
Code Generation
You can ask Gemini CLI to write functions, classes, or entire scripts based on a natural language description. For example, you might say, “Create a Python script that reads a CSV file and prints the average of each column.” The agent will generate the code and, depending on your configuration, can save it directly to a file in your project.
Repository Explanation
When you join a new project or revisit old code, Gemini CLI can explain how a repository works. Point it at a directory, and it will analyse the structure, summarise the purpose of each module, and highlight key dependencies. This is especially useful for onboarding or reviewing unfamiliar codebases.
File Management and Automation
File operations are another area where Gemini CLI shines. For instance, you can ask it to rename all image files in a folder based on their content, combine multiple CSV files into one, or restructure directories according to a pattern. The agent interprets your instructions and executes the file commands directly, saving you from writing repetitive shell scripts.
Generating Unit Tests
Writing unit tests is a common but tedious task. Gemini CLI can examine your source code and produce test files automatically. You can specify the testing framework (e.g., pytest for Python, Jest for JavaScript) and any coverage requirements. The generated tests follow standard patterns and can be adjusted later if needed.
Monitoring Your Usage
If you are using a paid API key or have usage limits, you can check your token consumption and quota directly inside Gemini CLI. The command /stats model displays your current usage statistics, including how many tokens you have used and what your remaining limit is. This helps you avoid hitting rate limits during long coding sessions.
Understanding Access and Upcoming Changes
Access to Gemini CLI and its advanced models depends on your subscription tier. Additionally, an important change is planned for unpaid users.
Gemini 3 Pro Access
Gemini 3 Pro is currently available to Google AI Ultra subscribers and users with a paid Gemini API key. Gemini Code Assist Enterprise access is expected to follow soon. For everyone else, including Google AI Pro subscribers, Gemini Code Assist Standard users, and free-tier users, access to Gemini 3 Pro requires joining a waitlist. Check the official Google AI blog for the latest updates on availability.
Transition to Antigravity CLI
Gemini CLI will be replaced by a new tool called Antigravity CLI on June 18, 2026, for unpaid tier and Google One users. This means if you are not paying for a subscription, you will need to switch to Antigravity CLI to continue using the service. The exact feature differences between Gemini CLI and Antigravity CLI are not described in the available documentation, so it is best to monitor official announcements as the transition date approaches.
Frequently Asked Questions
What is Gemini CLI?
Gemini CLI is an open-source AI agent that brings Gemini models directly into your terminal. It can perform code generation, repository explanation, file management, and unit test creation, all from the command line. It is actively maintained on GitHub with over 105,000 stars.
How do I install Gemini CLI?
Install Gemini CLI globally using npm with the command npm install -g @google/gemini-cli. You need Node.js version 20 or later. Alternatively, you can use Google Cloud Shell, which comes with Gemini CLI pre-installed and requires no Node.js setup.
Will Gemini CLI be replaced?
Yes, on June 18, 2026, Gemini CLI will be replaced by Antigravity CLI for unpaid tier and Google One users. Paid subscribers and users with a Gemini API key can continue using Gemini CLI. The exact feature differences between the two tools are not yet detailed.
How do I use Gemini 3 Pro in Gemini CLI?
To use Gemini 3 Pro, upgrade Gemini CLI to version 0.16.x or later, then run the /settings command and enable ‘Preview features’. This model is available to Google AI Ultra subscribers and paid Gemini API key users. Others can join a waitlist.
Gemini CLI offers a powerful way to integrate AI assistance directly into your development workflow. With capabilities ranging from code generation to file automation, it can save you significant time on repetitive tasks. Start with a local installation or Cloud Shell, explore the settings to suit your preferences, and begin handing off tasks to your terminal-based AI agent. For more terminal AI workflows, read my Claude Code best practices guide.