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:

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:

  1. Node.js (v18 or higher recommended). Many guides, including the official ones, assume you have Node.js ≥18.

  2. npm / npx (usually comes with Node.js)

  3. A Google (Gmail or Google) account to login or use for authentication/quotas.

  4. (Optional but recommended) Familiarity with command line / terminal, as you’ll use shell commands and prompts.

  5. (Optional but useful) Git (for working with repositories)

  6. (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:

  1. Choose a theme

    On the first run, Gemini CLI may ask you to pick a color theme or UI style. This is just cosmetic.

  2. 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:

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

  1. 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:

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"

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:

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:

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

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

Download Gemini CLI Cheat Sheet