How to Use Gemini CLI: The Beginner's Guide

CodexFuse Team · 2026-10-29T15:23:52.503Z · 12 min read

Install Gemini CLI, pick the right auth path, run your first session, learn the slash commands and GEMINI.md, and respect the safety line — with the post-June-2026 free-tier truth.

If you want to learn how to use Gemini CLI in 2026, start with one decision: how you will sign in. Everything else in this guide — installing it, running your first session, the slash commands, the GEMINI.md file, the safety rules — only works once the authentication path is settled. And the sign-in picture changed this year: on June 18, 2026, Google moved free personal access to Antigravity CLI, so this guide covers the current state, not the launch-era story most old tutorials still tell.

What is Gemini CLI, and who can actually use it in 2026?

Gemini CLI is Google's open-source terminal AI agent: a program you run in your terminal that reads your code, edits files, and runs shell commands through Gemini models. As of 2026 it is maintained for enterprise Code Assist workflows — free individual accounts and Google AI Pro/Ultra personal accounts were moved to Antigravity CLI on June 18, 2026.

The project lives on GitHub at google-gemini/gemini-cli under the Apache 2.0 license, with over 100,000 stars and thousands of commits. The repository stays public and installable; what changed is which accounts Google's servers will answer. If you are a developer who already pays for Gemini through an API key, Vertex AI, or a Code Assist Standard or Enterprise license, Gemini CLI is still your terminal agent.

If you are an individual developer who picked Gemini CLI because it was free, the honest next step is Google's closed-source replacement, Antigravity CLI (command: agy) — not this tool. If you use a different terminal agent today, our Claude Code beginner guide covers the most popular alternative.

Is Gemini CLI free?

No — not for personal accounts anymore. The free tier that made Gemini CLI famous (60 requests per minute, 1,000 requests per day on a personal Google account, launched with the tool in 2025) stopped serving on June 18, 2026, with no grace period. Scripts and automations that called gemini on a personal login simply broke that day.

The transition was announced on Google's developer blog in May 2026, and the Gemini CLI repository's own README now carries the notice at the top. One warning: Google's own documentation is still inconsistent — some pages still describe personal Google sign-in as the recommended path. Trust the transition notice and the quota page over the stale prose: if a personal sign-in doesn't serve you, that is why.

How do you install Gemini CLI?

Installing it costs nothing and takes a minute — you need Node.js (version 18 or newer) for the npm paths. Pick one:

1. Try it once, no install: npx @google/gemini-cli
2. Install it for good with npm: npm install -g @google/gemini-cli
3. Install with Homebrew (macOS/Linux): brew install gemini-cli
4. Install with MacPorts (macOS): sudo port install gemini-cli

Only install from these official sources. Never pipe a script from an unfamiliar website into your shell to install a tool like this. Verify with gemini --version after installing.

Gemini CLI ships on three release channels. Beginners should stay on stable:

How do you sign in to Gemini CLI?

Authentication is the first decision, not an afterthought. There are three paths, and the right one depends on who pays for your Gemini access:

To make environment variables permanent, add them to your shell's startup file (~/.bashrc, ~/.zshrc), or put them in .gemini/.env inside your project — Gemini CLI loads that file automatically. Headless mode (scripts and CI) can only use the API-key or Vertex paths, since there is no browser to complete an interactive sign-in.

One more time, because stale guides hide it: there is no "free personal sign-in" path anymore. If you sign in with a personal Google account and get nowhere, that is the June 18, 2026 change at work — Google wants individuals on Antigravity CLI now.

What does your first session look like?

Your first ten minutes with Gemini CLI should follow a fixed order. Open your terminal in a project folder and type gemini. Complete the sign-in with the auth method you chose above. Then:

1. Ask an orientation question. Try "Explain the structure of this codebase" or "What does this project do?" It reads the files it needs before answering.
2. Open the help. Type /help inside the session to see the available slash commands.
3. Give it a small, reversible task. For example: "Find where errors are logged and explain the flow to me." Keep the first task read-only.
4. Watch the approval prompt. When it wants to edit a file or run a command, it asks first. Read what it proposes before accepting.
5. End with a summary request. Ask it to summarize what it found — this also shows you how it reports back.

For the broader idea behind tools like this — an AI that plans and acts rather than just chats — see our explainer on agentic AI.

Which commands and flags should beginners learn first?

You only need a handful of commands to be productive. Here is the beginner set, verified against the current CLI help output:

A caution about tutorials: several ranking guides list subcommands like gemini chat, gemini prompt, or gemini summarize — these do not exist. The real interface is the gemini command with the flags above plus slash commands inside the session. When a guide and the tool disagree, gemini -h is the truth.

What is GEMINI.md and how do you write one?

GEMINI.md is a Markdown file in your project's root folder that gives Gemini CLI standing instructions — the things you would otherwise repeat every session. Think of it as the project brief the agent never forgets.

A good one is short: what the project is, how to run it (the exact test command), the conventions it follows, and what it must never do without asking. For example: "This is a Node.js API. Run tests with npm test. Never edit files under /migrations without asking. Summarize changes at the end of each task." Keep it under a page — long context files cost tokens on every turn.

How do you run Gemini CLI safely?

The approval prompt is the product. In its default mode, Gemini CLI asks before every file edit and every shell command — that prompt is the entire safety system, so never treat it as an annoyance to click through. Read each proposal, especially the command it wants to run.

The approval modes give you a dial, not just on and off:

The -y / --yolo flag auto-accepts all actions. Never use it on a first run, in a production folder, or anywhere you could not afford a wrong file delete. For genuinely risky work, use the sandbox instead: gemini -s runs the agent's commands and file changes in isolation, away from the rest of your machine. Two more guardrails: checkpointing lets you save and resume long sessions (and roll back a bad turn), and trusted folders let you set stricter execution policies for sensitive directories.

Gemini CLI vs Claude Code: which terminal agent fits you?

Both are terminal agents with the same shape — you type, it reads files, it proposes edits and commands, it asks first. The difference in 2026 is access:

If you are deciding between the two terminal-first agents, our Claude Code beginner guide walks the other side of this choice with the same first-session system. Terminal-agent fans who want a GUI around the same ideas should read our Cursor beginner guide, and Warp beginner guide covers the agentic terminal lane. The VS Code beginner guide is useful too — Gemini CLI ships IDE integration for it.

What comes after your first session?

Three directions are worth knowing. First, headless mode: gemini -p "Summarize the last 5 commits" runs one prompt and exits, and --output-format json (or stream-json for long runs) makes the output machine-readable — that is how Gemini CLI fits into scripts, cron jobs, and CI pipelines, with a GitHub Action available for pull-request reviews and issue triage.

Second, MCP servers: configure them in ~/.gemini/settings.json to give the agent new tools — database access, issue trackers, even media generation. Type @ inside a session to reach an MCP tool. Third, extensions and IDE integration: gemini extensions manages packaged add-ons, and the VS Code companion brings the agent into your editor when you want a GUI.

Sources

• Google Gemini CLI repository README (github.com/google-gemini/gemini-cli) — fetched in full on 2026-10-29: Apache 2.0 license, installation methods, release channels, authentication options, basic usage, and the June 18, 2026 free-tier transition notice.
• Gemini CLI authentication setup (geminicli.com) — fetched in full on 2026-10-29: the three authentication methods, environment variables, .gemini/.env persistence, and headless-mode requirements.
• Sharkly.ai, "Is Gemini CLI Still Free? What Changed on June 18 (2026)" — accessed 2026-10-29; the what-survived/what-got-cut breakdown.
• DevelopersDigest, "Gemini CLI Guide: 1M Token Context and Who Can Still Use It" (updated October 9, 2026) — accessed 2026-10-29; quota-page banner and supported-route confirmation.
• dev.to, "Claude Code vs Gemini CLI (and Antigravity CLI): The 2026 Comparison" — accessed 2026-10-29; launch-era free-tier figures (60 requests/minute, 1,000/day) and the Antigravity CLI replacement details.
• jenariusganlary.com, "Gemini CLI Shut Down: How I Pick AI Tools Now" — accessed 2026-10-29; the June 18 cutoff with no grace period.
• note.com (AI guide on the Gemini CLI free-tier transition) — accessed 2026-10-29; the May 19, 2026 announcement and the docs-site banner text.
• Kali Linux gemini-cli tools page — accessed 2026-10-29; the current gemini -h subcommand and flag reference used for the commands table.
• tecyfy.com, "Gemini CLI: AI-Powered Development in Your Terminal" (14 days old) — accessed 2026-10-29; install paths and first-session steps.
• inventivehq.com, "Install Google Gemini CLI: Mac & Windows Setup Guide" — accessed 2026-10-29; API-key and Vertex AI paths plus release channels.
• gist.github.com, "Comprehensive guide to using Gemini CLI" — accessed 2026-10-29; usage rules and the -y flag warning.
• cloudzy.com, "Claude Code vs Codex CLI vs Gemini CLI vs Cline" — accessed 2026-10-29; Claude Code access facts used in the comparison table.

Frequently Asked Questions

Is Gemini CLI still free for personal Google accounts?

No. On June 18, 2026, Google stopped serving Gemini CLI to free-tier individuals and Google AI Pro/Ultra personal accounts, moving them to Antigravity CLI. Gemini CLI now serves paid Gemini API keys, Vertex AI users, and Gemini Code Assist Standard/Enterprise licenses.

What is the difference between Gemini CLI and Antigravity CLI?

Gemini CLI (gemini) is the open-source terminal agent, now maintained for enterprise and paid access. Antigravity CLI (agy) is Google's closed-source replacement for the free personal tier — a separate tool with a multi-agent architecture, announced at Google I/O 2026.

What is GEMINI.md?

It is a Markdown file in your project's root that gives Gemini CLI standing instructions — what the project is, how to run its tests, its conventions, and what it must never do without asking. The agent reads it automatically every session.

Should I use the --yolo flag?

Not as a beginner, and not in any folder you care about. --yolo auto-approves every file edit and shell command, bypassing the approval prompt that is Gemini CLI's entire safety system. Use --approval-mode plan for read-only exploration and -s sandbox for risky work instead.

A tutorial's Gemini CLI commands don't work. What should I do?

Run gemini -h and compare. The tool moves fast and some guides list subcommands that never existed (such as gemini chat or gemini summarize). The real interface is the gemini command with its flags, plus slash commands like /help inside a session.