Gemini CLI: getting started

Beginner 15 min

Gemini CLI is Google’s open source AI agent for the terminal. It can read files, understand large projects, use tools, and run commands depending on your settings and permissions.

Requirements

Node.js 20+
Git
Internet connection
Google sign-in, Gemini API key, or Vertex AI
macOS, Linux, or Windows

Google currently recommends macOS 15+, Windows 11 24H2+, or Ubuntu 20.04+.

Install Gemini CLI

npm install -g @google/gemini-cli
gemini --version

Try it without a global install:

npx @google/gemini-cli

brew install gemini-cli

Choose auth

Start the CLI:

gemini

Common auth options:

Method	Best for
Google sign-in	Personal accounts, high free starting quota, and manual CLI use
`GEMINI_API_KEY`	Script mode, servers, CI, and clear API billing
Vertex AI	Enterprise, Google Cloud quotas, governance, and project-based billing

Example with API key:

export GEMINI_API_KEY="your-api-key"
gemini

Do not store API keys in screenshots, guides, or prompts.

First safe session

Enter a Git repo:
Terminal window
```
cd your-project
git status
```
Start Gemini CLI:
Terminal window
```
gemini
```

Send a read-only task:

Explain this folder and make a safe reading plan.
Do not make changes and do not run commands yet.

Use /permissions and /tools to understand what Gemini can do.

When Gemini CLI Is Strongest

Google ecosystem

Choose Gemini CLI when you already use Google, Gemini API, Vertex AI, or Google Workspace.

Free start

Google sign-in gives a high daily request quota for personal use according to the Gemini CLI docs.

Experiments

Checkpointing, worktrees, headless JSON/JSONL, and sandboxing make the CLI strong for testing and automation.

Good first task:

Read the repository and explain project structure, build/test commands, and risky files.
Do not make changes and do not run commands until I say so.

Good first change task:

Make a small change in one file.
Explain the plan first.
Run only test/build commands that already exist in the repository.
Use checkpointing or Git so the change can be rolled back.

GEMINI.md

Gemini CLI uses GEMINI.md as a context file. It can live globally in ~/.gemini/GEMINI.md or inside the project.

# GEMINI.md

## Project
- Use existing scripts before proposing new ones.
- Make small changes at a time.
- Ask before network calls or installations.

## Verification
- Run build/tests after code changes.

Gemini can read global, workspace, and just-in-time context. In large repositories, a GEMINI.md close to the folder being edited is often better than one long root file.

Useful commands

Command	Use
`/auth`	Change or check auth
`/model`	Choose Gemini model
`/permissions`	Inspect and change permissions
`/plan`	Plan before editing
`/resume`	Continue a session
`/stats`	Show usage and model info
`gemini -p "..."`	Run a single prompt

Headless, Checkpoints, and Worktrees

For scripts and automation, Gemini can run non-interactively:

gemini -p "Summarize this diff and find concrete risks. Do not make changes."

Use headless/JSON output when another script needs to read the result. Use checkpointing when you want a restore point before file edits. Use worktrees or normal Git worktrees when you want to test several solutions in parallel.

Feature	Use when
Headless mode	You want to run a prompt from CI, cron, or a script.
Checkpointing	You want a restore point before file edits.
Worktrees	Multiple agents or experiments need separate diffs.
Sandbox	You analyze unknown code or scripts you do not trust.

Sources

Last checked: April 11, 2026.