Gemini CLI: A Guide With Practical Examples

Now let’s dive into how I applied Gemini CLI to explore, fix issues, and implement changes to an open-source project.

Step 1: Prerequisites

To get started, install Node.js (version 18 or higher). You can also download the installer of your choice here, or you can run the following bash commands in your terminal:

# Download and install nvm:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
# in lieu of restarting the shell
\. "$HOME/.nvm/nvm.sh"
# Download and install Node.js:
nvm install 22
# Verify the Node.js version:
node -v # Should print "v22.17.0".
nvm current # Should print "v22.17.0".
# Verify npm version:
npm -v # Should print "10.9.2".

To set up your environment for Gemini CLI:

• Install the NVM (Node Version Manager) by running the official install script
• Then, initialize it in your current terminal session using source
• Finally, use NVM to install Node.js v22 and verify the installation using node -v, nvm current, and npm -v commands

This setup ensures your system is ready to run Gemini CLI smoothly.

Step 2: Setting Up Gemini CLI 

Now that we have the prerequisite in place, we can set up Gemini CLI on our system.

Step 2.1: Install Gemini CLI

Once Node.js and npm are installed and verified, install Gemini CLI by running the following command in your terminal:

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

Or use npm to run it:

npm install -g @google/gemini-cli
gemini

Once gemini-cli is installed, type gemini in your terminal to access it.

Step 2.2: Authentication

You can use your personal Google account to authenticate when prompted. This will grant you up to 60 model requests per minute and 1,000 model requests per day using Gemini.

In this tutorial, I authenticated using Login with Google, but you can also use the API Key (set as an environment variable) or Vertex AI for authentication. To generate a new API key, log in to AI Studio with your Google account and click Create API key. You can also use an existing key from a Google Cloud project to access specific models or request higher usage limits.

export GEMINI_API_KEY=”Your_API_Key”

Or create a .env file

GEMINI_API_KEY=”Your_API_Key”

You can use /auth in the textbox to switch the authentication as and when required.

Once authenticated, you will find a textbox to interact with the CLI in your terminal for free.

Step 3: Setting Up a Project on Gemini CLI

Once the CLI is running, we can start interacting with Gemini from the terminal. There are two ways to work on a project with CLI.

1. Start a new project

To start a project from scratch, run the following commands:

cd new-project/
gemini

Inside CLI, use a prompt to solve a problem that interests you—for example:

> Write the encoder code for a transformer from scratch.

This command will create a new project directory and initialize Gemini on the terminal. Then, you can ask Gemini to populate your new directory with code.

2. Work with an existing project

If you already have an existing codebase, then you can work with it using the following commands:

git clone https://github.com/AashiDutt/Google-Agent-Development-Kit-Demo
cd Google-Agent-Development-Kit-Demo
gemini

Inside CLI, use a prompt like:

> Give me a summary of all of the changes made to the codebase today.

If you're working with an existing codebase, either cloned from GitHub or already present on your local machine, you can run Gemini CLI from within the project directory.

Alternatively, after launching Gemini, you can enter the full path to the code directory in the prompt textbox using the /path command to load the local project manually.

Step 4: Experimenting With the Gemini CLI

In this tutorial, we will work with an existing project that I used to write a tutorial on Google’s Agent Development Kit (ADK). The repository is stored on GitHub. Using Gemini CLI, we will:

1. Explore and understand the codebase
2. Detect a bug or an issue on GitHub or within a file
3. Refactor code and generate unit tests
4. Create a markdown report of changes made
5. Visualise the codebase by generating a flowchart or a diagram

Exploring and understanding the codebase

Let’s begin by asking Gemini to explore and explain the codebase.

Prompt: Explore the current directory and describe the architecture of the project.

Gemini CLI returned a structured summary, explaining how:

• agents/ contains individual agent implementations
• shared/ defines common schemas used by all agents
• common/ includes reusable A2A utility functions for inter-agent messaging

This helped me get oriented without reading every file manually.

Analyzing and fixing a GitHub issue

Let’s explore some open issues from the GitHub repository. You can use the /compress tool to compress the context by replacing it with a summary. This helps us to pass more information in a limited context length.

Note: Gemini will ask for acknowledgement before accessing the GitHub repository. In this case, the repo is open-sourced.

Prompt: Here's a GitHub issue: [@search https://github.com/AashiDutt/Google-Agent-Development-Kit-Demo/issues/1]. Analyze the codebase and suggest a 3-step fix plan. Which files/functions should I modify?

Gemini CLI explored the issue:

• Using the @search feature, and returned a 3-step fix plan for the GitHub issue.
• It then identified the root cause as a JSON serialization error.
• Finally, Gemini suggested changes and response handling in a few files.

Next, the CLI awaits input from the user to evaluate the changes, and if the user agrees, then it will make the suggested changes. Choose the option to apply suggested changes by clicking Enter.

The CLI makes changes to every affected file. Once the changes have been made, it will return a summary of the changes made.

Implementing and testing the fix

Let’s implement and test the suggested fixes by Gemini. For this, I used the following prompt and allowed execution.

Prompt: Write a pytest unit test for this change in test_shared.py.

Gemini CLI:

• Inserted json.dumps() before sending task payloads in the previously suggested files.
• Then, it created test_agents.py if missing to add unit tests.
• Finally, it added a new test case to validate the schema and transmission of nested agent messages.

The CLI generates the test_agents.py file and runs it using multiple shell scripts. However, at one point, Gemini entered a loop repeating the same error. A refined prompt, a rerun, or simply using a different model via API would help resolve this.

Here is the new file generated by Gemini in the project folder:

Generating documentation

Now that we have made the fixes, let’s summarize the changes made and write them as Markdown in a .txt file.

For this, I used the following prompt:

Prompt: Write a markdown summary of the bug, fix, and test coverage. Format it like a changelog entry under "v0.2.0".

To save the summary in a document, I used the following prompt:

Prompt: Save this summary in a .txt file and name it summary.txt

Gemini CLI uses the WriteFile tool to save the summary.txt file in the project directory.

Here is the summary.txt file generated by Gemini for this project:

Generating a flowchart using MCP

This section extends the previous experiments, where I explore how Gemini CLI uses Model Context Protocol (MCP) to maintain file-level summaries and task history across prompts. This gives Gemini a working memory within the session. Using this capability of Gemini, I asked Gemini to generate a project flowchart and convert it into an image. 

Here is the prompt I used:

Prompt: Generate a flowchart that shows how agents communicate via A2A and how the main.py orchestrates the system. Highlight where the issue occurred and how it was fixed.

This visualization is powered by Gemini's persistent memory, which retained the full context of our earlier bug fix and agent structure without needing any re-upload or file hints.

Although image generation tools were not directly available within the CLI (they may be accessible via API), this visualization proved helpful in understanding agent routing. 

Available Gemini CLI tools 

Some tools Gemini CLI supports include:

• ReadFile, WriteFile, Edit
• FindFiles, ReadFolder, ReadManyFiles
• Shell, SaveMemory
• GoogleSearch or Search, WebFetch

These tools help you navigate, query, and modify large codebases efficiently.

To learn more about Gemini CLI, I recommend reading the official announcement article and the GitHub page.

Conclusion

In summary, this tutorial demonstrated how Gemini CLI can be used to:

• Understand a multi-agent codebase structure
• Fix a GitHub issue
• Generate unit tests and markdown documentation for the changes.
• Visualize data flow

Gemini CLI reduced the time I’d normally spend parsing files and manually planning fixes. While Gemini CLI is still in its early stages and may occasionally feel slow when used via the API, it is already matching the capabilities of Claude Code.

If you are a developer looking to add AI agents to your workflow, check out this four-part tutorial series on Devin:

1. Setup and First Pull Request (Part 1)
2. Shipping a Vertical Slice with Devin (Part 2) 
3. Integrations, Testing, and CI/CD (Part 3) 
4. Security, Deployment, Maintenance (Part 4)