Getting started with Gemini CLI

What is Gemini CLI?

Gemini CLI is an open-source command-line agent created by Google that brings the power of Gemini (their AI models) directly into your terminal.

In essence:

You can ask it (via natural language) to inspect your code, fix or refactor, explain files, generate tests, document, debug, or run shell commands.
It uses a “reason and act” (ReAct) loop, meaning it can break down tasks into subtasks and choose built-in tools to execute them.
It supports a protocol called MCP (Model Context Protocol) which allows you to plug in remote or local “servers” to give Gemini extra context or capabilities.
It shares quotas with Gemini Code Assist (Google’s tool for IDEs) when used under the same account.

At the time of writing, it’s in preview and many features are being actively refined.

The core advantage: you don’t bounce between your editor, browser, and CLI — you can stay in the terminal and treat the AI as a peer developer or assistant.

Prerequisites & Setup Checklist

Before you install Gemini CLI, here’s what you need:

Node.js (v18 or higher recommended). Many guides, including the official ones, assume you have Node.js ≥18.
npm / npx (usually comes with Node.js)
A Google (Gmail or Google) account to login or use for authentication/quotas.
(Optional but recommended) Familiarity with command line / terminal, as you’ll use shell commands and prompts.
(Optional but useful) Git (for working with repositories)
(Optional) A project directory you want the AI to inspect.

Once those are in place, you can proceed with installation.

Installing Gemini CLI

There are (at least) two main options:

Option A: Global installation (recommended for frequent use)

npm install -g @google/gemini-cli

You might need sudo on Unix systems (macOS, Linux) depending on your system setup.

After installation, you can run:

gemini --version

to verify it’s installed.

Option B: Run without installing (one-off / transient)

You can use npx to run Gemini CLI without globally installing:

npx https://github.com/google-gemini/gemini-cli

This is helpful if you don’t want to alter global settings or just want to quickly try it.

First Launch / Authentication / Configuration

When you first run gemini, it walks you through some interactive setup steps.

Here’s what typically happens:

Choose a theme
On the first run, Gemini CLI may ask you to pick a color theme or UI style. This is just cosmetic.
Select authentication method / login
The common path is: “Login with Google / personal account.” This gives you free access to a Gemini Code Assist license which includes access to Gemini 2.5 Pro, with quotas (e.g. 60 model requests per minute, 1,000 per day) for free.
Alternatively, you may use an API key from Google AI Studio, especially if you want to link with custom billing or higher quotas.

Persisted settings file

After the first run, Gemini CLI stores configuration (theme, auth type, etc.) in a settings.json file in places like:

User level: ~/.gemini/settings.json
System level: /etc/gemini-cli/settings.json
Workspace / project level: .gemini/settings.json

The precedence is: system → user → workspace. So workspace settings override user settings.

Permissions / prompts for tool execution
Gemini CLI may ask for permission when wanting to run built-in tools (e.g. shell, file read/write, search) as part of executing your natural language requests. You can allow once, always, or deny.

Basic Usage & Commands

Once setup is done, you’ll see an interactive prompt. Here’s how to use it and the core concepts.

Asking questions / tasks

You simply type a prompt, much like a chat with an assistant:

> Explain what the file server.js is doing in my project
> Refactor the authentication module to use async/await
> Generate unit tests for `utils/formatter.js`

Gemini will use internal reasoning, choose built-in tools (read-file, write-file, shell, etc.), and return structured output.

Shell commands prefix

You can directly run shell commands from within the CLI by prefixing them with !, e.g.:

> !ls -al
> !git status

This is useful to inspect files or get context.

Slash commands / meta commands

Gemini CLI supports commands (starting with /) to introspect or control the agent:

/help — show help / list commands
/tools — list available internal tools
/memory — show memory usage or summary
/stats — model / context stats
/mcp — switch or connect to MCP servers
/quit — exit

Also, you can launch the CLI with flags. For example:

gemini --help
gemini -m "gemini-2.5-flash"
gemini -p "What is the git command to deploy to Cloud Run"

-m lets you select which model (e.g. flash vs pro)
-p allows a one-off prompt (non-interactive mode)

Tools & built-in capabilities

Gemini CLI has several built-in “tools” that it can tap into when executing your prompt. Some common tools / capabilities include:

read-file: Read a file’s contents
write-file: Write or update a file
read-many-files: Read multiple files matching a pattern
glob / find-files: Search files by patterns
grep / search in files
shell: Execute shell commands
web-search / web-fetch: If the agent needs external information, it may ground via a search or HTTP fetch
memoryTool: Remember things during the session

These tools allow Gemini CLI to traverse your project, modify files, run commands, combine logic, and produce results in context.

Example session

Here’s a minimal illustrative session:

$ gemini
(choose theme, login, etc.)

> Explain the directory structure and purpose of files in this project
(Agent reads files using read-many-files, infers architecture, outputs a summary)

> Fix the bug in `routes/user.js` where `user.id` is undefined
(Agent finds the error, updates code with a write-file, shows diff or explanation)

> !git diff
(shows the changes made)

> Add error handling for missing fields in user creation
(Agent edits code, writes tests, explains changes)

You can loop: ask, inspect, refine.

Using It on a Project / Real Use Cases

Let me walk through applying Gemini CLI to a real (or dummy) project. This helps solidify its capabilities.

Step 1: Enter a project directory

Open a terminal and cd into your project (e.g. a Git repo). Gemini CLI works best when it can see the full context (all files).

Step 2: Ask for a high-level summary

Prompt it:

> Describe the architecture of this application and how the modules interact

It will read many files, identify key modules or layers (API, services, models, controllers), and produce a summary.

Step 3: Find and fix errors or refactor

For example:

> There's a bug reported in the order processing module — investigate and suggest a fix

Gemini CLI will locate relevant files, parse code, propose changes, and possibly apply them.

Step 4: Generate tests or documentation

> Create unit tests for `src/utils/math.js`
> Generate markdown API documentation for the `controllers` folder

It uses write-file or other tools to scaffold tests/docs.

Step 5: Integrate external context (MCP)

You can optionally connect to an MCP server to assist with extra memory, context, or chaining broader work. For example, you might have a remote server that aggregates docs, logs, or global config which the CLI can use.

You can switch or connect via /mcp commands.

Step 6: Use non-developer tasks

It’s not just for code. You can ask for content generation, research summaries, blog drafting, math solving, etc.

> Draft a blog outline titled “Top Node.js Performance Tips 2025”
> Summarize the latest news about AI agents

It may use web-search to ground responses.

Advanced Features & Tips

Once you’re comfortable with basics, here are more advanced tips and features to explore:

Model selection

By default, Gemini CLI may choose the “Pro” model. But you can switch to other models (like Flash) to change cost / performance tradeoffs.

For instance:

gemini -m "gemini-2.5-flash"

Also, remember the prompt / flags -p allow noninteractive mode.

Memory & context compression

Gemini maintains memory (within session) about prior steps, tasks, and file changes, enabling continuity. When context grows large, it may compress or summarize older context to stay within token limits.

You may use commands like /memory or /stats to inspect memory, token usage, etc.

Scripting & automation

Because Gemini CLI can be invoked non-interactively (via -p prompt) you can script prompts inside shell scripts, CI pipelines, or automation tools.

For example:

gemini -p "Refactor this file to add logging" > output.txt

You could then pipe or capture the output. This allows partial integration into toolchains.

Customizing via .gemini/settings.json / workspace configs

You can override or set settings (theme, auth, behavior) via workspace-level config. This helps when collaborating or having different behaviors per project.

You can override or set workspace-level settings to control themes, model defaults, and even plugin behavior.
If you want to see a real-world example of Gemini CLI extensions in action, check out this tutorial on getting started with the Shopify extension for Gemini CLI.
It demonstrates how developers can integrate external APIs and business tools (like Shopify) directly into Gemini’s command-line interface for automated eCommerce workflows.

Sandbox & security practices

Since Gemini CLI can run shell or write operations, be cautious with untrusted codebases. A few suggestions:

Use sandboxing (e.g. Docker, isolated environment) when experimenting.
Review diffs before accepting changes.
Be careful about hidden commands or chain-of-commands in files (some security researchers flagged risks in early versions).
(Note: Google has addressed some issues in newer versions)
Always stay updated to patch known vulnerabilities.

Stay within quotas / monitoring usage

The free license gives you 60 model requests per minute and 1,000 per day (shared across Gemini CLI + Code Assist) for personal accounts.

If you hit limits or require higher throughput, upgrade via API key or enterprise/Cloud plans.

You can monitor usage via /stats or by examining account dashboards in Google AI / Gemini.

Once you’re comfortable with the basics, you can explore more advanced tips and features — including extending Gemini CLI with custom plugins and integrations.
Developers can actually build their own Gemini CLI extensions to add tools or custom behaviors. For example, you can follow this detailed C# Corner guide on building a custom extension plugin for Gemini CLI, which walks through creating a personalized command and connecting it to your workflow.

Common Pitfalls & Troubleshooting

Node version issues: Older Node versions (< 18) may lead to install or runtime errors. Upgrade or use nvm.
Permission issues with global install: On Unix, sudo may be needed, or using a local install + npx if global install fails.
Authentication stuck / OAuth issues: Sometimes your browser or redirect may fail — retry login, use API key alternative.
Quota exceeded: Wait until reset or upgrade your plan.
Tools not executing: If Gemini asks for permission and you deny, certain prompts may fail.
Untrusted code: Be cautious accepting modifications in large or unknown repos. Review diffs.
Version bugs / security patches: Keep Gemini CLI up to date. Early versions had vulnerabilities.

If you see errors like “Cannot find module …” or “permission denied”, check your Node/npm setup, PATH, and privileges.

What’s Next / Roadmap & What to Watch For

Gemini CLI is evolving rapidly — expect new features, improved models, enhanced tooling, and integrations (e.g. with editors).
Integration into editors / merging with IDEs (so you can switch seamlessly between chat and code)
Better privacy / enterprise offerings with stricter data control
More reliable memory, context chaining, and long-term session persistence
Enhanced security / sandboxing to reduce risks of code injection
Community contributions (since it’s open source) expanding built-in tools and connectors
Higher quota / paid tiers for power users