Hands-on with Gemini CLI

1. Introduction

In this codelab, you will learn about Gemini CLI, an open-source AI agent that brings the power of Gemini directly into your terminal.

What you'll learn

1. Installing and configuring Gemini CLI
2. Exploring tools, built-in commands and configuring MCP Servers in Gemini CLI
3. Customizing Gemini CLI via the GEMINI.md file
4. Exploring a few use cases with Gemini CLI

What you'll need

This codelab can be run entirely within Google Cloud Shell, which comes pre-installed with Gemini CLI.

Alternatively, if you prefer to work on your own machine, there is a section to install Gemini CLI locally.

You would need the following:

• Chrome web browser
• A Gmail account

This codelab, designed for users and developers of all levels (including beginners). The use cases in the codelab have been categorized into developer and non-developer tasks. The developer use cases demonstrate how to vibe code with Gemini CLI and working with a GitHub repository to perform common development tasks like code explanation/understanding, generating documentation, fixing issues and more. It is recommended that you complete these use cases in the codelab. There is an optional section at the end that covers several every day tasks that are non-developer focused.

2. Before you begin

Create a project

1. In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.
2. Make sure that billing is enabled for your Cloud project. Learn how to check if billing is enabled on a project.
3. You'll use Cloud Shell, a command-line environment running in Google Cloud that comes preloaded with bq. Click Activate Cloud Shell at the top of the Google Cloud console.

4. Once connected to Cloud Shell, you check that you're already authenticated and that the project is set to your project ID using the following command:

gcloud auth list

5. Run the following command in Cloud Shell to confirm that the gcloud command knows about your project.

gcloud config list project

6. If your project is not set, use the following command to set it:

gcloud config set project <YOUR_PROJECT_ID>

3. Installation

Before you do the setup and run Gemini CLI, let us create a folder that we will be using as our home folder for all the projects that we create inside of it. This is a starting point for the Gemini CLI to work with, though it will also reference some other folders on your system and which you will come to later, as needed.

Go ahead and create a sample folder (gemini-cli-projects) and navigate to that via the commands shown below. If you prefer to use some other folder name, please do so.

mkdir gemini-cli-projects

Let's navigate to that folder:

cd gemini-cli-projects

You can directly launch Gemini CLI via the gemini command.

Please navigate directly to the next section (Gemini CLI configuration via settings.json).

If you want to install Gemini CLI locally, follow the instructions given below. Note that Gemini CLI comes pre-installed on Cloud Shell and Cloud Workstations.

The first step is to install Node 20+ on your machine. Once this is complete, you can install and run Gemini CLI via any one of the following methods:

1. You can install Gemini CLI globally on your system first. You may need Administrator access to perform this step.

# option 1: install Gemini CLI

npm install -g @google/gemini-cli

# .. and then run
gemini

2. Run it with the following command:

# option 2: run without installing Gemini CLI

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

You can confirm the CLI is installed by running:

gemini --version

Assuming that you have launched Gemini CLI via any of the methods above, on first launch, you might be asked about selecting a theme. If it does, you can either go with the default or choose a theme of your choice.

The next important thing is Authentication. It will ask for the Authentication method. It is recommended that you use your personal Google Account and not non-Google or Google Workspace related accounts in this lab.

If you hit limits with the current free quota given to Google Accounts, you can opt to use the Gemini API Key or even Google Cloud Vertex AI, where you will need to have a Project Id and the location name for that project. Do refer to the Authentication section of the documentation, if you plan to use other methods of authentication.

Go ahead and click on Enter. This will open up a Google Authentication page in the browser. Go ahead with the authentication with your Google Account, accept the terms and once you are successfully authenticated, you will notice that the Gemini CLI is ready and waiting for your command.

A sample screenshot is given below:

In this case, we have selected the Vertex AI option, but it can be the personal account in your case. You will notice that we have selected the Gemini 2.5 model (visible in the bottom right). You can choose your specific model at any time using the /model command.

4. Gemini CLI configuration via settings.json

If you choose Cloud Shell to run Gemini, a default theme for Gemini CLI and the authentication method is already selected and configured for you.

If you installed Gemini CLI on your machine and launched it for the first time, you selected a theme and then an authentication method.

Now, on subsequent runs of Gemini CLI, you will not be asked to select a theme and authentication method again. This means that it is getting persisted somewhere and the file that it uses is called settings.json and it is the way to customize Gemini CLI.

Settings are applied with the following precedence (Cloud Shell only makes User settings available):

1. System: /etc/gemini-cli/settings.json (applies to all users, overrides user and workspace settings).
2. Workspace: .gemini/settings.json (overrides user settings).
3. User: ~/.gemini/settings.json.

Windows User: %USERPROFILE%.gemini\settings.json (which typically expands to C:\Users<YourUsername>.gemini\settings.json)

System: %ProgramData%\gemini-cli\settings.json (which typically expands to C:\ProgramData\gemini-cli\settings.json)

Mac User: ~/.gemini/settings.json (which expands to /Users/<YourUsername>/.gemini/settings.json)

System: /etc/gemini-cli/settings.json

If you recollect, at the time of selecting the theme, you selected for the settings to be saved in the User Settings. So visit the ~/.gemini folder and you will notice the settings.json file.

My settings.json file is shown below. If you had selected another theme, you would see the name there.

{
  "security": {
    "auth": {
      "selectedType": "oauth-personal" or "cloud-shell"
    }
  },
  "ui": {
    "theme": "Default"
  }
}

5. Our first interaction with Gemini CLI

Let's get started with Gemini CLI and type your first query as shown below:

Give me a famous quote on Artificial Intelligence and who said that?

The expected response is shown below:

 > Give me a famous quote on Artificial Intelligence and who said that?                 
✦ "The only way to do great work is to love what you do." - Steve Jobs (While not directly about AI, it's a famous quote related to technology and innovation, which underpins AI development.)
Alternatively:
  "The development of full artificial intelligence could spell the end of the human race." - Stephen Hawking

A quick way to understand Gemini CLI and the various commands that it supports is to type /help (forward slash) and you will see a variety of commands and keyboard shortcuts.

Let's quit Gemini CLI for now. You can do that either via the /quit command or you can do Ctrl-C twice in the interactive Gemini CLI terminal session. When you exit Gemini CLI, it will show you your session statistics that give you some insight into your session, model usage and other metrics.

6. Gemini CLI - Command Parameters

There are a few command line parameters that one can provide when you start Gemini CLI. To get a full list of options, you can use the --help as shown below.

gemini --help

This should show the full range of options available. You are encouraged to go through the documentation here.

Let us take a look at a few of them. The first one is to configure Gemini CLI to use a specific Gemini mode. Currently, at the time of updating this lab, here is the list of models supported. To use a specific model, you can do that at the time of starting Gemini CLI via the -m parameter as shown below:

gemini -m "gemini-2.5-flash"

You will notice that if you start in the above manner, you can check the model at the bottom right of the Gemini CLI terminal.

Once you are in the Gemini CLI application, you can use the /model command to open a dialog that allows you to choose a model. A sample run is shown below and depending on your requirements and guidance given, you can keep switching the model to choose the right one for the task depending on complexity and the need to control costs.

Non-interactive mode

An interesting option is to run Gemini CLI in a non-interactive mode. This means that you directly provide it the prompt and it will go ahead and respond to it, without the Gemini CLI interactive terminal opening up. This is very useful if you plan to use Gemini CLI in an automated fashion as part of the script or any other automation process. You use the -p parameter to provide the prompt to Gemini CLI as shown below:

gemini -p "What is the gcloud command to deploy to Cloud Run"

Do keep in mind that there is no scope to continue the conversation with follow up questions. This mode also does not allow you to authorise tools (including WriteFile) or to run shell commands.

Remember that if you miss out on the -p parameter and just provide the following, it will open up Gemini CLI with the prompt and continue inside of that.

gemini "What is the gcloud command to deploy to Cloud Run"

7. Gemini CLI - built-in Tools

Gemini CLI comes with a set of built-in tools and the tools documentation states "Gemini model uses these tools to interact with your local environment, access information, and perform actions. These tools enhance the CLI's capabilities, enabling it to go beyond text generation and assist with a wide range of tasks."

To get a list of current Built-in Tools, invoke the /tools command as shown below:

Available Gemini CLI tools:
  - Activate Skill (activate_skill)
  - Ask User (ask_user)
  - Edit (replace)
  - Enter Plan Mode (enter_plan_mode)
  - FindFiles (glob)
  - GoogleSearch (google_web_search)
  - Invoke Subagent (invoke_agent)
  - List Background Processes (list_background_processes)
  - Read Background Output (read_background_output)
  - ReadFile (read_file)
  - ReadFolder (list_directory)
  - SearchText (grep_search)
  - Shell (run_shell_command)
  - Update Topic Context (update_topic)
  - WebFetch (web_fetch)
  - WriteFile (write_file)

One of the things that should strike you immediately is to ask yourself if Gemini CLI can simply call these tools, when it wants to? The default answer is no, when it comes to sensitive operations that might involve writing to the local system, reading from an external system, going to the external network and so on.

While there is a --yolo available when you start the CLI (not typically recommended), you will find that Gemini CLI will prompt you for permission to run the tool that it has chosen. You can refuse permission, or let it run once or give it blanket permission to always run. You are and should be in full control of things.

Let's use a prompt that will make Gemini CLI choose one of the inbuilt tools to execute and that will give you a good understanding of how it all works.

Imagine a scenario where you would like to get information on latest financial news across the world and save that into a file in the local working directory from where you launched Gemini CLI. Use the following prompt:

Search for the latest headlines today in the world of finance and save them in a file named finance-news-today.txt

Imagine for a moment what it should do. Ideally it needs to go out to do a GoogleSearch to get news from some relevant sources of information that can provide it financial news. It then needs to create a file named finance-news-today.txt (a write operation on your local system that will require your permission) with its content.

Let's see what happens (you should proceed doing the same on your machine).

The first thing it does is that it invokes the GoogleSearch tool to search the web and retrieve the results, as shown below:

 Searching for Finance News: 
  I will first search for the latest finance headlines and then save them to a file.
  ✓  GoogleSearch  Searching the web for: "latest finance headlines"
   → Search results for "latest finance headlines" returned.
  Saving Finance News: I will now save the finance headlines to the file 'finance-news-today.txt'.

Once that is done, it is ready to write this to the file and it will use the WriteFile tool, but since that is a sensitive operation (write), it will ask for your permission. You can decide the permission type i.e. allow once , allow always, etc. Go ahead and select allow once for now.

This will then write the information to the file and a success message is shown below:

✦ I have saved the latest finance news to finance-news-today.txt.
  Finance News Saved: The task is complete.

How do you check if the file is written or not? You can use the @file to ask it to read the content. As you type @, it displays a list of files in the current folder and it has shown the file that it has just created. Select that and submit the prompt. My prompt is shown below:

read the contents of @finance-news-today.txt

This results in the required tools (ReadManyFiles, ReadFile) being invoked and the contents are displayed as shown below:

  ✓  ReadManyFiles  Attempting to read files from finance-news-today.txt → Read 1 file(s)
  Topic: Summarizing the financial news headlines.
✦ The latest finance headlines as of May 15, 2026, include:
  Global Markets & Economy:
   * The Dow Jones Industrial Average surpassed 50,000 for the first time, driven by strong earnings from Cisco
     Systems and a 2% rise in Nasdaq due to tech stocks.
   * Inflation concerns are growing, hinting at potential Fed interest rate hikes.
   * Kevin Warsh has been confirmed as the new Federal Reserve head.
   * A "constructive" U.S.-China summit took place in Beijing between President Trump and President Xi, with
     markets watching for impacts from proposed tariffs.
  Corporate & Tech News:
   
<REST OF THE CONTENT>

8. Gemini CLI - Shell mode

This is a good time to learn how to directly work with the Shell from within Gemini CLI. You can go into shell mode by pressing ! in the message box. This will toggle to a Shell mode. You can get back by pressing ! again or by hitting the ESC key.

When in shell mode, you will see the ! at the start of the prompt as shown below:

You can directly check using standard commands like pwd and ls as shown below. Please note that the commands assume a Linux type OS. If you are on another operating system (Windows), please use equivalent commands like (cd, dir and type). Do note that the output of these calls is included in the model's context window.

You can print the contents of the file via the cat command too i.e. cat finance-news-today.txt.

Exercise: Here is a short exercise to try out. Choose an RSS feed of your choice. Give a prompt to Gemini CLI to fetch the contents of the RSS feed and format the results for you in a specific way. This is a good way to automate something at the start of the day. You might even ask Gemini CLI to figure out if there is RSS Feed for a specific area for e.g. Google Cloud Platform Release Notes.

A sample prompt is shown below:

Get the latest release notes for Google Cloud from its RSS Feed and display the key points in a well-formatted list.

This prompt should ideally first invoke the GoogleSearch tool to find the Google Cloud Platform RSS feed and then it will use the WebFetch tool to get the contents of the RSS Feed and display them. You might be asked for permissions to invoke these tools, please give the necessary go ahead.

9. Gemini CLI Extensions

As the documentation states, Gemini CLI extensions package prompts, MCP servers, and custom commands into a familiar and user-friendly format. With extensions, you can expand the capabilities of Gemini CLI and share those capabilities with others. It is the primary mechanism to extend the functionality of Gemini CLI beyond its in-built tools.

An extension is a self-contained, versionable, and easily distributable package. Think of it as the "shipping container" for your Gemini CLI customizations, bundling everything needed for a specific workflow into a single, neat package.

An extension can bundle any combination of:

• Custom slash commands (your .toml files).
• MCP server configurations (which previously lived in settings.json).
• Context files (GEMINI.md) to provide specific instructions and guidelines to the model.
• Tool restrictions (excludeTools) to create a safer, more focused environment.

Explore the Extensions Gallery