Gemini CLI Explained in 10 Minutes: From Setup to One-Shot App Creation |

In this article, we're going to deep dive into Gemini CLI. We'll explore how to get started, review several command-line options, and examine various configuration methods, such as using gemini.md or agents.md files. To wrap up, we'll walk through some hands-on examples, demonstrating how Gemini understands an existing project and even attempts to build a complete application from a single prompt.

Getting Started with Gemini CLI

To begin, you need to have NodeJS installed on your machine. Once that's ready, you can install the Gemini CLI globally using npm.

Open your terminal and run the following command:

npm install -g @google/gemini-cli

After a successful installation, you can launch the tool by simply typing:

gemini

Upon the first launch, you'll be prompted to choose a theme for the interface—options include nc-dark, atom-one-dark, and the default. After selecting a theme, you'll need to log in with your Google account to authorize the CLI.

Once logged in, you'll see a few helpful tips. You can type /help to see a list of available commands and keyboard shortcuts to familiarize yourself with the environment. To exit the application at any time, simply press Ctrl+C.

Key Command-Line Options

When launching Gemini from your terminal, you can pass several arguments to customize its behavior:

gemini help: Displays all available options, including how to change the model (it defaults to Gemini 1.5 Pro).
--prompt: Allows you to pass a prompt directly, similar to interacting with a chatbot.
--sandbox: This is a crucial feature for safety. It runs Gemini in an isolated environment. You can specify a Docker image URI to create a containerized sandbox.
--show-memory-usage: Displays real-time memory usage in the bottom-right corner of the interface.
-y: Automatically accepts all actions proposed by Gemini, which is useful for scripting but should be used with caution.
-e or --extensions: Extends the CLI's capabilities with custom extensions.

Interacting with Gemini: Core Commands

Inside the Gemini interface, there are three primary command prefixes you'll use frequently: the forward slash (/), the at symbol (@), and the exclamation mark (!).

1. The Forward Slash (`/`) for System Commands

The / prefix is used for built-in tool commands:

/clear: Clears the screen.
/memory: Manages the AI's instructional context. You can add, show, or refresh the memory, which is loaded from gemini.md files.
/chat: Manages conversation history. You can save the current session with chat save <name> and resume it later, which is useful for branching conversations.
/compress: Summarizes the current context if it becomes too long.
/tools: Lists all available tools, such as readFile, glob, and googleSearch.

2. The At Symbol (`@`) for File Context

The @ symbol allows you to pass a file as context for your prompt. For example, you could ask Gemini to analyze an image:

@cake.jpeg What's going on in this image?

The AI would then provide a detailed description, such as: "This is a food photograph of a cake on a wooden serving platter, which is on a dark tablecloth. In the background, there's a white vase with some greenery and a container with utensils."

3. The Exclamation Mark (`!`) for Shell Mode

The ! symbol is a powerful feature that toggles between the Gemini interface and your system's shell. This is incredibly handy for running terminal commands without exiting the application.

Hit ! to enter shell mode.
Run any command, like ls -l, to see a file listing.
Hit ! again to return to the Gemini interface.

Advanced Configuration Explained in 7 Steps

Gemini CLI offers a layered configuration system, with settings in higher-numbered layers overriding those in lower ones.

Hard-coded Defaults: The application's built-in defaults.
User-Level Settings: Located in ~/.gemini/settings.json, this file is created automatically and stores user-specific preferences like the chosen theme.
Project-Level Settings: A gemini/settings.json file in your project's root directory.
System-Level Settings: A global configuration file (e.g., /etc/gemini-cli/settings.json on Linux).
Environment Variables: Using a .env file, you can set variables like GEMINI_API_KEY. The CLI searches for this file in the current directory and then traverses upwards.
Context Files: Hierarchical instructional files (defaulting to gemini.md) that provide project-specific context, coding styles, and other background information to the AI.
Command-Line Arguments: The highest level of precedence, these are the flags you pass when launching Gemini.

The `settings.json` File

This file allows you to customize various behaviors, such as: * contextFileName: Change the default context file from gemini.md to something else, like agents.md. * codeTools: Specify a list of code tools to make available to the model (e.g., readFileTool, globTool). * excludeTools: Restrict the model from using certain tools. * sandbox: Define sandbox settings, like using Docker.

Context Files (`gemini.md`)

This is where you provide persistent instructions to the AI. You can define general instructions, coding styles, and even component-specific guidelines.

Example gemini.md:

# General Instructions
This is a TypeScript library. When generating new TypeScript code, please follow the existing coding style. Prefer the functional programming paradigm when appropriate. All code should be compatible with TypeScript 5.0 and NodeJS 20.

# Coding Style
- Use two spaces for indentation.
- Use single quotes for strings.

# Components

## client.ts
This file handles all outbound API requests. Whenever adding a new API call function, ensure it includes robust error handling and logging.

Hands-On Example 1: Understanding an Existing Project

Let's see how Gemini analyzes a simple web application designed to blur an uploaded image. After launching Gemini in the project's directory, we can ask:

"Explain what's going on in this project."

Gemini will analyze the project components and report its findings. It correctly identifies the stack: a React/TypeScript frontend with Tailwind CSS and a Python FastAPI backend with OpenCV and Pillow for image processing. It then examines the main application logic in app.tsx and main.py and concludes:

"In short, this is a full-stack application that lets you upload an image, blur it, and then download the result. It also has features to convert an image to an SVG."

Hands-On Example 2: One-Shot App Creation

For a more ambitious test, let's try to build a full-stack task management application with a single prompt. We'll switch to the Gemini 1.5 Flash model for this.

The prompt:

"Build a full-stack app for task management. I want to be able to create new tasks, edit and delete existing tasks. I should be able to arrange them in Kanban style with the columns: To Do, In Progress, Done, and Archive. Use a standard user interface."

Gemini gets to work, scaffolding a React+TS application and creating multiple components like KanbanBoard.tsx and TaskCard.tsx. After a series of file creation and editing steps, it provides instructions to run the app.

The final result is a functional application. It features a user registration and login system. Once logged in, there is a Kanban board where you can add tasks, edit them, and drag them between columns (To Do, In Progress, Done, Archive). While functionally complete, the user interface is very basic and lacks any significant CSS styling. This seems to be a common issue where the logic is sound but the presentation layer is minimal.