How to Use Google's Gemini CLI for AI Code Assistance

Verify Your Node.js Installation

Gemini CLI is primarily implemented in TypeScript, which requires Node.js. You’ll need Node.js version 20 or higher to run Gemini CLI. First, check if you have Node.js installed in the required version by opening your terminal and running this command:

$ node --version
v24.11.1

If you see a version number of 20 or higher, then you’re all set. Otherwise, if you encounter a command not found error or have an older version, then you’ll need to install or update Node.js before continuing.

The recommended approach to install Node.js is to use the Node Version Manager (nvm), which allows you to install and switch between multiple Node.js versions, much like pyenv does for Python. You can find detailed installation instructions for your operating system on the Node.js download page.

Once Node.js is installed, you’ll also have access to the Node Package Manager (npm), which you’ll use in the next step.

Install Gemini CLI Globally

With Node.js installed, you can now install Gemini CLI using npm. The -g flag installs the package globally, making the gemini command available from anywhere in your file system:

$ npm install -g @google/gemini-cli

This command downloads and installs the latest version of @google/gemini-cli from the npm registry, which is like PyPI but for Node.js packages. The global installation is important since it allows you to use Gemini CLI in any project directory without local installation.

After the installation completes, verify that Gemini CLI is correctly installed by checking its version:

$ gemini --version
0.15.4

If you see a version number, then the installation was successful. Gemini CLI automatically updates itself on startup when it detects a newer version, ensuring you always have the latest features and bug fixes upon restart. You can control this behavior with the disableAutoUpdate property in settings.json, for example, if you prefer manual updates.

Authenticate With Google

Even though Gemini CLI offers a generous free tier, you must authenticate to use it. This helps Google prevent abuse, track usage, and provide a smooth upgrade path if you ever need more capacity.

The first time you run the gemini command, you’ll be presented with three authentication options:

1. Login with Google: The simplest option for individual developers who want to start experimenting immediately
2. Use Gemini API Key: A static API key suitable for automation and scripting
3. Vertex AI: Enterprise-grade authentication for organizations requiring fine-grained permission management and Google Cloud Platform integration

For this tutorial, choose the first option, Login with Google. This method requires only a Google account and is perfect for getting started quickly:

When you select this option, your default web browser will open with a Google sign-in page:

After you confirm your identity and authorize Gemini CLI to access your Google account, an OAuth token will be stored in a configuration file and used for subsequent sessions. You won’t need to authenticate again unless the token expires or you explicitly log out.

Unless you started your Gemini CLI session from the root folder of the sample project downloaded earlier, you can now close the session by hitting Ctrl+C or Ctrl+D twice. Alternatively, you can type /quit or /exit at the Gemini CLI prompt to terminate your current session.

Test Your First Prompt

To confirm everything is working correctly, navigate to the todolist/ directory from the supporting materials and start an interactive Gemini CLI session if you haven’t already:

$ cd ~/Projects/todolist/
$ gemini

When you run this command in a new directory, Gemini CLI first analyzes the project structure and indexes the files for context. Afterward, you’ll see a welcome message and a prompt where you can enter natural language queries:

For starters, try a simple question to verify the connection. Say you wanted to know the primary programming language this project is written in:

What programming language is this project written in?

Based on the presence of pyproject.toml and the Python source files (.py), Gemini should quickly respond with the correct answer:

This confirms that Gemini CLI is successfully communicating with Google’s AI models and can analyze your project’s files. Note that the answer you get might be worded differently, but the overall meaning should be preserved.

Great! You’re now ready to give Gemini CLI a more challenging task.

Ask Gemini What the Project Does

Before you start hunting for bugs, it’s worth getting familiar with the codebase. If you haven’t already, start an interactive Gemini CLI session in the todolist/ directory. Once the Gemini CLI prompt appears, ask it to explain what the project does:

What does this project do?

To analyze project files, Gemini CLI might leverage one of its built-in tools, such as ReadFile. But, due to its non-deterministic nature, it may occasionally need your permission to run certain shell commands on your behalf. For example, it might choose to execute dir or ls to list the directory content.

Before running any shell commands, Gemini CLI will ask you for permission. It’ll specify the exact command, its arguments, and the target directory. Depending on the exact command, it’ll give you a few choices, such as these:

1. Yes, allow once
2. Yes, allow always …
3. No, suggest changes (esc)

The first option will require you to approve the subsequent instances of that command during the current session. The second option lets Gemini CLI run that same command automatically, without asking again—but only for this session. The third option lets you review or modify the command before it runs.

You can also configure permissions at the project or workspace level to skip these confirmations entirely, though that’s beyond the scope of this tutorial.

When you approve the command and give Gemini CLI a few seconds to process the output, it’ll provide a summary. You should get a response similar to this one:

Remember that AI models are inherently non-deterministic, so you might see a slightly different output than the one above for exactly the same input. Moreover, when you run the same prompt more than once, you should generally assume different results as well.

This is already valuable. You’ve gained a high-level understanding of the project without reading through every file manually. But you can go deeper. Try asking more specific questions, like this:

How does the emoji feature work?

Gemini CLI will explain that the emojis.py module uses OpenAI’s GPT-4 model to match tasks with relevant emojis. It’ll also note that this feature is optional and controlled by the OPENAI_API_KEY environment variable:

This natural language interface makes exploring unfamiliar code much faster than traditional code reading.

Generate Project Documentation

Now that you have an idea of what the project does, you can see how Gemini CLI can help with documentation tasks. Imagine you’ve inherited this project and need to create comprehensive instructions for new users. Ask Gemini to help:

Can you write detailed installation and usage instructions for this project?

Gemini will generate a well-structured guide that follows Python best practices. It’ll include steps like creating a Python virtual environment and installing dependencies from pyproject.toml:

# TodoList

A simple command-line todo app.

## Installation

1. **Create a virtual environment:**

    ```bash
    python3 -m venv .venv
    source .venv/bin/activate
    ```

2. **Install the project in editable mode:**

    ```bash
    pip install -e ".[dev]"
    ```

## Usage

The command to interact with the todo list is `todo`.

### Commands

-   `todo add <task>... [-l <list_name>]`: Add one or more tasks.
    -   Example: `todo add "Buy milk" "Walk the dog"`
    -   Example with a list: `todo add "Finish report" -l work`

-   `todo remove <task>... [-l <list_name>]`: Remove one or more tasks.
    -   Example: `todo remove "Walk the dog"`

-   `todo done <task>... [-l <list_name>]`: Mark one or more tasks as done.
    -   Example: `todo done "Buy milk"`

-   `todo undo <task>... [-l <list_name>]`: Mark one or more tasks as not done.
    -   Example: `todo undo "Buy milk"`

-   `todo rename <old_name> <new_name> [-l <list_name>]`: Rename a task.
    -   Example: `todo rename "Buy milk" "Buy almond milk"`

-   `todo show [-l <list_name>]`: Show tasks in a list. If no list is specified, it shows the default list.
    -   Example: `todo show`
    -   Example: `todo show -l work`

-   `todo clear [-l <list_name>]`: Clear a task list.
    -   Example: `todo clear -l work`

-   `todo lists`: Show all task lists.

-   `todo export`: Export all tasks to a file.

You can review the generated content and, once you’re satisfied, ask Gemini to add it to your README file if it hasn’t already done that.

The instructions should be clear and easy to follow. However, if the results aren’t what you expected, then it’s possible that Gemini CLI has switched to a less capable model for this task. To enforce a more powerful model, run the /model command at the prompt and choose Pro instead of auto:

The model indicator in the bottom-right corner of the Gemini CLI prompt should now display gemini-2.5-pro rather than auto:

This example demonstrates how Gemini CLI can accelerate documentation tasks that are often tedious but essential for maintainability.

Request a Code Quality Analysis

With a better understanding of the project, you’re ready for the main event, which is identifying defects. Ask Gemini CLI to perform a comprehensive code quality analysis:

Can you analyze the code in this project and identify any potential bugs or code quality issues?

Gemini CLI scans through the source files and examines patterns that might lead to bugs. With a recent Gemini CLI version, you’ll probably see it spin up the Codebase Investigator Agent to evaluate the code. The agent’s analysis is thorough and can take up to a few minutes to complete.

Afterward, the agent will provide you with a high-level summary with suggestions for improvements grouped by category. However, the quality of these suggestions can be hit or miss due to frequent hallucinations. For more reliable results, you may want to instruct Gemini CLI to use a specific tool.

In some cases, Gemini CLI might even leverage the available linters on its own to help it identify issues in your codebase. For example, it may find Ruff listed as an optional dependency in the project metadata and decide to use that instead:

✦ I’ll use ruff to check for linting issues.

To follow along with this tutorial, you’ll clarify that you want Gemini CLI to take advantage of Ruff for this task:

Use Ruff to analyze the code in this project and identify any potential bugs or code quality issues.

If you don’t have Ruff installed globally, then allow Gemini CLI to create a virtual environment for this project and install Ruff as a dependency. Then, let it run the ruff check command to analyze your codebase and provide actionable feedback. In this case, Ruff will identify several potential issues, including one critical finding that it won’t be able to fix by itself:

B006 Do not use mutable data structures for argument defaults
  --> src/todolist/exporter.py:28:34
   |
26 |         self,
27 |         output: SupportsWrite[str],
28 |         options: FormatOptions = {}
   |                                  ^^
29 |     ) -> None:
30 |         self.output = output
   |
help: Replace with `None`; initialize within function

The exporter.py file defines a mutable default argument value, which is a classic Python gotcha. You’ll combine the power of Ruff and Gemini CLI to address this issue later.

The problematic code is in the .__init__() method of the JSONExporter class:

# ...

class JSONExporter:
    def __init__(
        self,
        output: SupportsWrite[str],
        options: FormatOptions = {}
    ) -> None:
        # ...

# ...

When asked for more details, Gemini CLI should explain that using a mutable default argument like an empty dictionary {} is a common Python pitfall. The default dictionary is created once when the function is defined, not each time it’s called. This means all instances of JSONExporter that don’t provide their own options argument will share the same dictionary object, leading to unexpected behavior when options are modified.

Here’s an excerpt from Gemini CLI’s sample response:

 1def __init__(self, output: SupportsWrite[str], options: FormatOptions = {}) -> None:
 2    self.output = output
 3    self.options = options

 1def __init__(self, output: SupportsWrite[str], options: FormatOptions | None = None) -> None:
 2    self.output = output
 3    self.options = options or {}

This is exactly the kind of subtle bug that’s easy to miss during code review but can cause confusing issues in production. Gemini CLI not only found the bug with Ruff but also explained why it’s problematic, helping you learn while you work.

Ask Gemini to Suggest a Fix

With the bug identified, you can ask Gemini CLI to suggest the appropriate fix. At the Gemini CLI prompt, type:

How should I fix the mutable default argument bug in the JSONExporter class?

Gemini CLI will likely explain that the standard Python solution is to use None as the default argument and create a new dictionary inside the function when None is received. The corrected code should look something like this:

# ...

class JSONExporter:
    def __init__(
        self,
        output: SupportsWrite[str],
        options: FormatOptions = None
    ) -> None:
        if options is None:
            options = {}
        # ...

# ...

This idiom ensures that each instance of JSONExporter gets its own independent dictionary when no options are provided, preventing the shared state problem.

Gemini CLI might also explain additional context, such as why using a dictionary as a default value is problematic and how this relates to Python’s function definition behavior. Gemini CLI may even suggest alternative approaches, like using a factory pattern or data classes instead of dictionaries.

Apply the Fix With Gemini’s Assistance

Gemini CLI can help you apply the fix directly. As long as you continue the conversation in the same thread, you can ask the AI assistant to make the change for you. To reference a particular file in your project, use the @ symbol. This opens an interactive filter that narrows down files as you type, so you don’t need to enter the full path manually:

You can use the Up and Down arrow keys to navigate the list of files, or start typing and press Tab to let Gemini CLI autocomplete the file name for you. As a result, this is the complete question you’ll end up asking:

Can you apply this fix to the @src/todolist/exporter.py file?

Gemini CLI will show you the exact change it plans to make, and it’ll ask for your approval. Notice that it’ll also give you the option to edit the proposed changes in an external code editor. But this option will only work if you have previously used the /editor command and then restarted Gemini CLI. You can choose your preferred editor from the following supported options:

• Cursor
• Emacs
• Neovim
• Vim
• VS Code
• VSCodium
• Windsurf
• Zed

Gemini CLI automatically detects the editors installed on your system and only lets you choose from those.

Assuming you chose Vim, this is what you might see:

Under the hood, Gemini CLI generates two temporary files representing the old and new versions of your code. It then opens them side by side for you to compare. The left side represents your current workspace with the original file, while the right side is what the file will look like after applying the suggested changes.

Depending on your editor, you can edit one or both views, or click the arrow buttons between them to move blocks of code around. When you’re happy with the end result, simply save your edits and quit. In Vim, you do that by pressing Esc and running :wqa to confirm your changes.

If you’ve ever used an IDE to resolve merge conflicts between Git branches, this workflow should feel familiar.

After you exit and confirm the update, Gemini CLI will modify the file accordingly. This interactive approval process gives you control over what changes are made to your codebase while still benefiting from AI assistance.

Verify the Fix Works

After applying the fix, it’s important to verify that the code still works correctly and that you haven’t introduced any new issues. Ask Gemini CLI to help you verify:

Can you confirm that the bug is fixed and suggest how I can verify this works correctly?

Gemini CLI might use a few alternative approaches depending on what tools are available to it and if your project already comes with a test suite. Here, there are none, so the AI coding assistant might prefer to just rerun Ruff. However, a much better approach would be to install a test framework like pytest, implement new unit tests, and have Gemini CLI execute them for you behind the scenes.

To get the best results, try phrasing your prompts as requests for specific actions, like so:

Use pytest to write a unit test that verifies the bug fix you’ve just implemented.

Here’s what the resulting test case might look like:

import io
from todolist.exporter import JSONExporter

def test_json_exporter_mutable_default_arg_fix():
    """
    Verify that JSONExporter instances do not share the same options dictionary.
    """
    # Arrange
    output1 = io.StringIO()
    output2 = io.StringIO()

    exporter1 = JSONExporter(output1)
    exporter2 = JSONExporter(output2)

    # Act
    exporter1.options["indent"] = 2

    # Assert
    assert exporter2.options == {}

This test checks that each instance of JSONExporter has its own separate .options attribute instead of sharing one mutable default across instances. It creates two exporters, modifies the options in the first one, and then asserts that the second exporter’s options remain unchanged.

After successfully running this test, Gemini CLI can show you a quick summary of what it did:

 1.venv/bin/pytest

At this point, it might be a good idea to validate the test itself for additional confidence, since it wasn’t written by following the test-driven development (TDD) methodology. If you were to revert Gemini CLI’s change in src/todolist/exporter.py and rerun the test with pytest, then you should get a failed test report:

================================= FAILURES =================================
________________ test_json_exporter_mutable_default_arg_fix ________________
tests/test_exporter.py:20: in test_json_exporter_mutable_default_arg_fix
    assert exporter2.options == {}
E   AssertionError: assert {'indent': 2} == {}
E
E     Left contains 1 more item:
E     {'indent': 2}
E
E     Full diff:
E     - {}
E     + {
E     +     'indent': 2,
E     + }
========================= short test summary info ==========================
FAILED tests/test_exporter.py::test_json_exporter_mutable_default_arg_fix -
AssertionError: assert {'indent': 2} == {}
============================ 1 failed in 0.16s =============================

This confirms that your test indeed checks what it’s supposed to. Now you can reapply the fix.

This test-driven approach not only verifies the fix but also prevents regression if someone accidentally reintroduces the bug in the future. With the bug fixed and verified, you’ve completed a full debugging workflow entirely within your terminal, using natural language to guide the process.

Adn remember, to close Gemini CLI, you can press Ctrl+C or Ctrl+D twice, or you can use the /quit or /exit command.