How to Use Gemini CLI: Install, Auth & Free Tier 2026
If you want to learn how to use Gemini CLI, the short version is this: install it on Node 20 or newer, sign in with a Google account for the free tier, then describe a task in plain language and let the agent carry it out in your terminal. Google's open-source command-line tool brings Gemini models into your shell through a ReAct reason-and-act loop, with built-in tools for files, shell, and the web. Getting it running takes one command. The parts that pay off most, picking the right authentication path, knowing what the free tier actually allows, wiring up an MCP server, and scripting it into your pipelines, are not obvious from the welcome prompt. This guide walks the whole path: checking prerequisites, installing, authenticating, running your first commands, picking a model, extending it, and driving it non-interactively from scripts.
Before anything else: Gemini CLI is open source (Apache 2.0) and free to start. Signing in with a personal Google account gives a free tier that, as of June 16, 2026, allows 60 requests per minute and 1,000 requests per day. Those are vendor-reported preview numbers and may change, so confirm current limits in the documentation.
Before You Start
There is a little setup before your first real session, and it is quick. The one real requirement is a recent Node.js, and then a Google account or API key to sign in. The thing to understand up front is that this is a terminal agent, not a desktop app or an editor extension. You run it in your shell, point it at a project folder, and talk to it in plain language, so the first step is confirming your runtime, not installing an IDE.
One thing to settle early: decide which authentication path fits before your first real session. A personal Google account is simplest and free, an API key suits scripting, and Vertex AI is the production route. We compare all three in the authentication step.
How to Install Gemini CLI
The first concrete step is getting the tool onto your machine. There are three common ways to install, and which you pick depends on how often you expect to reach for it. For a quick try, run it with npx and nothing is installed permanently. If it becomes part of your routine, a global install puts gemini on your path. On macOS, Homebrew is the cleanest option, and MacPorts and Anaconda are also supported.
gemini
gemini
If you are already in Google Cloud Shell, you do not need to install anything: Gemini CLI is preinstalled there. Whichever route you take, the command you run afterward is the same, gemini, launched from inside the project folder you want to work on.
Package name note: commands like the global install use the published package name. If a copy-pasted command fails, check the install instructions in the official GitHub repository for the current package name and supported managers rather than guessing.
Authenticate and the Free Tier
Authentication is the step that most shapes your day-to-day experience, because it decides your limits and your billing. The first time you run gemini, it asks how you want to sign in. There are three paths, and the right one depends on whether you are experimenting, scripting, or running in production.
Sign in with Google (free tier)
The simplest path is to sign in with a personal Google account. There is no API key to create or store, and it puts you on the free tier. As of June 16, 2026, that free tier allows 60 requests per minute and 1,000 requests per day, with access to Gemini 3 models and a 1M-token context window. These figures are reported by Google as a preview-level allowance, so date-stamp them and confirm the current numbers before you depend on them.
Use a Gemini API key
If you would rather authenticate with a key, for example to drive the tool from scripts, you can set a Gemini API key. The key-based path also has a free daily allowance and supports usage-based billing once you exceed it. Note that Google's own documentation pages have disagreed on the exact key-based free limit (a current page cites 1,000 requests per day on Gemini 3, while an older page cited 100 per day on Gemini 2.5 Pro), so the precise number depends on the model version and the docs you are reading. Treat the live documentation as the source of truth.
Use Vertex AI (enterprise)
For teams and production workloads, you can authenticate through Vertex AI using a Google Cloud billing account, which provides higher rate limits than the personal free tier. This is the path to choose when usage is steady and predictable rather than exploratory.
| Path | Best For | Cost Model |
|---|---|---|
| Sign in with Google | Trying it out, daily individual use | Free tier: 60/min, 1,000/day (vendor-reported, Jun 16 2026) |
| Gemini API key | Scripts, automation | Free daily allowance, then usage-based billing |
| Vertex AI | Enterprise, production | Google Cloud billing, higher rate limits |
Shared quota to know about: if you also use Gemini Code Assist in VS Code, its quotas are shared between the CLI and the Code Assist agent mode. Heavy use in one draws down the same allowance in the other.
First Commands
This is where setup ends and real work begins. With sign-in done, launch the tool from inside a project and you land at an interactive prompt. From here you describe what you want in plain language, and Gemini CLI works through it with a ReAct loop: it reasons about a multi-step plan, then acts using its built-in tools, checking its own progress and recovering when a step does not go as expected.
gemini
A good first task is something small and readable. Ask it to explain what a file does, summarize the structure of the project, or make a contained change you can review in a couple of minutes. Because it can read files and run shell commands as part of its plan, you see the steps it takes rather than just a final answer, which makes it easier to learn what it is good at before you hand it bigger work.
The mental model worth carrying: the agent is most reliable when the task is well scoped and the success condition is clear. Describe the outcome you want, let it propose and carry out the steps, and review the result the way you would review a colleague's pull request.
Pick a Model and Use Built-in Tools
Getting good results comes partly from knowing what is under the hood. The tool runs on Gemini 3 models, a mix of faster Flash variants and more capable Pro variants, with a 1M-token context window so it can hold a large amount of code and conversation at once. An earlier preview cited Gemini 2.5 Pro, so if you see an older model named in a tutorial, check what your install actually reports rather than assuming.
The part that makes the agent useful is its set of built-in tools. Out of the box it can read and write files, run shell commands, and fetch web pages, and it can ground answers in Google Search so responses can draw on current information rather than only what the model was trained on.
- File operations let the agent read your code for context and write the edits it proposes.
- Shell access lets it run commands, for example to run a test suite or inspect the environment, as part of a multi-step plan.
- Web fetch and Google Search grounding let it pull in documentation and current facts, which is useful when a task depends on information newer than the model.
On model names: available models change as Google ships new versions. Confirm what your installed version offers rather than relying on a fixed list from any article, including this one.
Add an MCP Server and GEMINI.md
Once the core loop feels comfortable, the next layer is connecting the tool to the rest of your workflow, and two features do that: MCP servers and project context files.
Add an MCP server
Gemini CLI supports the Model Context Protocol, an open standard for giving an AI agent access to external systems and data sources. You register servers in ~/.gemini/settings.json under an mcpServers entry, giving each one a command to launch and any arguments it needs. Once configured, those servers' tools sit alongside the built-in ones, so the agent can reach the services you already use.
"mcpServers": {
"my-server": {
"command": "npx",
"args": ["-y", "@example/mcp-server"]
}
}
}
Write a GEMINI.md context file
A GEMINI.md file lets you give the agent standing context about a project: conventions, architecture notes, commands to use, and anything you would otherwise repeat in every prompt. Place it in the project so the agent reads it automatically, and your instructions carry across sessions instead of being restated each time.
You do not need either of these on day one. Start with the built-in tools, then add an MCP server when you have a specific system to connect, and write a GEMINI.md once you find yourself repeating the same project context.
Script It and Checkpointing
Some of the most valuable work happens away from the interactive prompt, where a non-interactive mode is built for automation. You can pass a prompt directly and request structured output with --output-format json (or stream-json), which makes the result easy to parse in a shell script or a continuous-integration pipeline.
This is the same agent capability you use interactively, exposed in a form a machine can consume. It is how teams fold Gemini CLI into existing automation, and there is also an official GitHub Action for pull-request review, issue triage, and on-demand runs triggered with @gemini-cli in a comment.
Checkpointing and token caching
For longer interactive work, Gemini CLI supports conversation checkpointing, which saves a session's state so you can resume it later rather than starting over. It also uses token caching to reduce repeated work. Together these make a long-running session cheaper and easier to pick back up, which matters once your tasks grow past a single prompt.
A scripting caution: the agent can run shell commands and modify files, so treat non-interactive runs the way you would any automation with write access. Scope what it can touch, review changes before merging, and keep destructive operations behind human approval.
Troubleshooting
These are the questions newcomers run into most often, with the practical answer for each.
Tips for Getting the Most From Gemini CLI
Now that you know how to use Gemini CLI end to end, a few habits make it noticeably more useful day to day. Most of them come down to scoping work tightly and keeping a human in the loop.
- Scope each task so the success condition is obvious. The agent is most reliable when you describe a clear outcome and let it plan the steps.
- Lean on a GEMINI.md file for project context you would otherwise retype, so conventions and commands carry across sessions.
- Reach for Google Search grounding when a task depends on current information rather than only what the model was trained on.
- Review before you accept any file edit or shell command, exactly as you would a colleague's pull request, and keep destructive steps behind your own approval.
- Watch your quota if you also run Gemini Code Assist in VS Code, because the two share the same allowance.
Want the bigger picture first? If you are still deciding whether this tool fits your workflow, read what Gemini CLI is for how the ReAct agent works and where it sits among coding tools, then come back to this guide when you are ready to set it up.