The Gemini CLI has recently become a valuable addition to many development workflows. This article will demonstrate how to leverage its features for a real-world use case, including building out a feature, fixing a bug, and generating documentation concurrently.

Installation and Setup

You can find the installation instructions on the official GitHub repository. To install it globally on your system, you can use a command similar to this:

# Example installation command
npm install -g @google/gemini-cli

Authentication is handled via a Google account, which provides a generous number of requests per day without needing a separate API key.

The first time you launch the tool, it prompts you to select a theme. You can change it anytime with the theme command.

gemini> theme
? Select a theme ›
  dracula
  nord
  ...

A Real-World Example

For this demonstration, we'll be working on a Python library project called random-number-mcp. A common setup involves using a terminal multiplexer like tmux to have the Gemini CLI open in one pane and the project files in another.

Interacting with the Shell

Gemini CLI provides a powerful shell mode. By typing !, you can execute shell commands directly within the agent's environment. This is useful for inspecting the project structure without leaving the interface.

gemini> !tree -l 2
.
├── source
│   ├── __init__.py
│   └── server.py
└── tests
    └── ...

After inspecting the file system, another ! returns you to the agent mode. To begin, we can instruct Gemini to familiarize itself with the project.

Read the README.md file to understand the project and then wait for further instruction.

The Project: An MCP Server

The project is an MCP (Model-Controlled Procedure) server that allows language models to call specific tools for generating random numbers, shuffling lists, and more. For instance, a model could use a tool to simulate a dice roll:

Prompt: roll a d20 Action: The model calls the random_int tool on the server with a range of 1 to 20. Response: The server returns a number, like 12, which the model then synthesizes into its answer.

However, a bug exists. When providing weighted choices, the weights parameter is incorrectly passed as a string instead of a list of numbers, leading to a validation error.

Error Example: Input validation error: weights should be a list of floats or integers, but it is a string.

Our goal is to use Gemini to help fix this bug and perform several other tasks.

Handling Multiple Tasks Concurrently

A powerful workflow is to manage separate, concurrent tasks by spawning multiple instances of the Gemini CLI. This keeps the context for each task isolated. For this project, we'll tackle three distinct tasks:

1. Fix the Validation Error: Address the weights string issue.
2. Generate Documentation: Create instructions for running the app locally.
3. Add a New Feature: Implement a random.sample tool for sampling without replacement.

Task 1: Fixing the Validation Error

In the first Gemini instance, we provide the context for the bug. We can attach the relevant file and describe the desired change.

The user is getting a validation error.
@source/server.py
I want to accept a string as input for the 'weights' parameter in case the user provides one, and then convert it to a list within the application.

Gemini's initial suggestion might involve using ast.literal_eval, which is a significant security risk as it can execute arbitrary code.

Initial Unsafe Change: ```python import ast

...

if isinstance(weights, str): weights = ast.literal_eval(weights) ```

This is a bad practice. It's crucial to provide feedback to the agent to guide it toward a safer solution.

Don't use ast.literal_eval. Use JSON to parse the string.

This leads to a much better implementation.

Improved, Secure Change: ```python import json

...

if isinstance(weights, str): try: weights = json.loads(weights) except json.JSONDecodeError: raise ValueError("Invalid JSON format for weights") ```

This version safely parses the string as a JSON array, which is exactly what's needed.

Task 2: Building Documentation

While the first task is in progress, we can open a new Gemini instance to work on documentation. We can provide an example of the desired output format.

Build out the documentation for being able to run this app locally using UV with a desktop client. Here is an example of what I'm looking for:

## Running Locally for Development

To test changes locally, you can run the server from your project directory.

First, install dependencies:
uv pip install -r requirements.txt

Then, run the server:
uv run python -m source.server

This allows Gemini to work on generating the README.md updates in a separate context, without interfering with the bug-fixing task.

Task 3: Adding a New random.sample Feature

In a third instance, we can request a new feature.

Add a random sampling tool (with replacement) using `random.sample` from the Python standard library.

At this point, you might encounter a notification: "Slow response times detected. Automatically switching from Gemini 1.5 Pro to Gemini 1.5 Flash." This indicates a trade-off: the Flash model is faster but may produce lower-quality results, sometimes requiring more guidance.

After the initial code is generated, it's important to ensure it's fully integrated.

Source this new tool up in the server file for users.

And then, ensure the tests are run correctly.

Try that shell command again, but use UV as my environment. Refer to the README for instructions on testing.

Gemini should then correctly identify and run the test suite using the proper command, such as uv run pytest. The agent even went a step further by building out a complete test suite for the new random.sample tool.

Final Verification

With all three tasks complete, the final step is to test the changes.

1. Documentation: The generated README.md section provides clear instructions for local setup.
2. Bug Fix: The application now correctly handles the weights parameter when passed as a string, resolving the validation error.
3. New Feature: The random.sample tool is available and functions as expected, allowing for new capabilities like picking multiple unique items from a list.

This multi-tasking approach, using isolated contexts for each task, demonstrates how the Gemini CLI can significantly enhance productivity and streamline complex development workflows.