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
- Installing and configuring Gemini CLI
- Exploring tools, built-in commands and configuring MCP Servers in Gemini CLI
- Customizing Gemini CLI via the
GEMINI.mdfile - 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
- In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.
- Make sure that billing is enabled for your Cloud project. Learn how to check if billing is enabled on a project.
- 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.
- 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
- Run the following command in Cloud Shell to confirm that the gcloud command knows about your project.
gcloud config list project
- 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:
- 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
- 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):
- System:
/etc/gemini-cli/settings.json(applies to all users, overrides user and workspace settings). - Workspace:
.gemini/settings.json(overrides user settings). - 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
The Extensions Gallery is the central marketplace for discovering all official Google-built and third-party extensions:
- Open the following URL in your browser:
https://geminicli.com/extensions/ - This gallery is the discoverability engine for the ecosystem. You can see Extensions from companies like GitHub, Redis, and DynaTrace, showing the breadth of available tools.
- Scroll down and find the extension card for Cloud Run or here is the link to it.
- Notice that the card provides a description, the author (Google), and a one-click
Copycommand button. This is the simplest way to get the installation command for an extension.
Gemini CLI Extensions - Management Commands
The gemini extensions command is your entry point for managing your local Extensions.
Run it in your terminal to see the list of available commands.
gemini extensions <command>
Manage Gemini CLI extensions.
Commands:
gemini extensions install <source> [--auto-update] [--pre-release]
Installs an extension from a git repository URL or a local path.
gemini extensions uninstall [names..]
Uninstalls one or more extensions.
gemini extensions list
Lists installed extensions.
gemini extensions update [<name>] [--all]
Updates all extensions or a named extension to the latest version.
gemini extensions disable [--scope] <name>
Disables an extension.
gemini extensions enable [--scope] <name>
Enables an extension.
gemini extensions link <path>
Links an extension from a local path. Updates made to the local path
will always be reflected.
gemini extensions new <path> [template]
Create a new extension from a boilerplate example.
gemini extensions validate <path>
Validates an extension from a local path.
gemini extensions config [name] [setting]
Configure extension settings.
Options:
The commands are straightforward (install/uninstall, list, update, enable/disable, etc) and we will be using some of these commands in this codelab.
Check your current list of extensions
Before we install anything, let's check our "clean slate."
- Run the
gemini extensions listcommand: - You should see the following output, confirming that no Extensions are installed yet.
No extensions installed.
Configuring Cloud Run MCP Server
The Cloud Run extension available in the Gemini CLI Extensions gallery is a MCP Server that allows us to deploy our applications to Cloud Run.
The Cloud Run Extension card from the Extensions gallery is shown below:
Let's first install the Cloud Run Extension by clicking on the Copy install command as shown above. Then paste that command in the Cloud Shell terminal (it should be similar to the following):
gemini extensions install https://github.com/GoogleCloudPlatform/cloud-run-mcp
On running the above command, you would see a confirmation required from you. Go ahead and give it your approval. The Cloud Run extension will ask you for your Google project id and Google project location. Do provide that. The Cloud Run Extension should then install successfully.
If you now execute the gemini extensions list command, you should see the Cloud Run extension installed as shown below:
✓ cloud-run (1.0.0)
ID: 3c1a38909b6d7d90b6acc8ca1e80d97b4a867253a3cd12d841b2aab4e556a58f
name: 0b1820c1f0c043bbb3b54f496d862c02172424c930eb965d61f468be52e6f127
Path: /Users/romin/.gemini/extensions/cloud-run
Source: https://github.com/GoogleCloudPlatform/cloud-run-mcp (Type: github-release)
Release tag: v1.10.0
Enabled (User): true
Enabled (Workspace): true
Context files:
/Users/romin/.gemini/extensions/cloud-run/gemini-extension/GEMINI.md
MCP servers:
cloud-run
Settings:
Project ID: YOUR_GCP_PROJEC_ID (User - /Users/romin/.gemini/extensions/cloud-run/.env)
Region: YOUR_GCP_PROJECT_LOCATION (User - /Users/romin/.gemini/extensions/cloud-run/.env)
If you launch Gemini CLI now and execute the /mcp list command, you will see the following. Notice the tools and prompts of the Cloud Run MCP Server.
Configured MCP servers:
🟢 cloud-run (from cloud-run) - Ready (8 tools, 2 prompts)
Tools:
- mcp_cloud-run_create_project
- mcp_cloud-run_deploy_container_image
- mcp_cloud-run_deploy_file_contents
- mcp_cloud-run_deploy_local_folder
- mcp_cloud-run_get_service
- mcp_cloud-run_get_service_log
- mcp_cloud-run_list_projects
- mcp_cloud-run_list_services
Prompts:
- deploy
- logs
This is just one example of a Gemini CLI Extension that we have shown how to configure. You can look at the Extensions Gallery to discover more of them.
10. Use cases to try out
Gemini CLI can be applied to a wide range of use cases that apply to both developers and non-developers alike. Presented here are a few scenarios and depending on your area of interest, you can try any or all of them out.
In each of these cases, the prompt is provided. You are free to try this out in the Gemini CLI interactive mode or non-interactive mode via the -p parameter at the time of launching the Gemini CLI.
Vibe coding with Gemini CLI
Let's use Gemini CLI to vibe code an application. In this task, you will ask Gemini CLI to generate an application and then push the initial version to a GitHub repository.
Prerequisite
To perform the tasks in this section, there are a few prerequisites:
- Git
- Gemini CLI
- Setup
gh( GitHub CLI tool). - Familiarity with Git basics and a bit of programming knowledge
We will assume that you have launched Gemini CLI in a specific folder of your choice. In our case, we have launched Gemini CLI from the initial home folder : gemini-cli-projects and another folder event-website inside of that.
Start with an initial prompt. Think of it as a specification for your application. Feel free to modify it as you see fit. Keep in mind that throughout the session with Gemini CLI, it will ask you for permissions to create the files, etc. Do give the required permissions.
In this task, we are not looking for Gemini CLI to run the application or test it out for us since we would like a little more control. But it is completely up to you if you would like to do that.
Generate a website for a 1-day event filled with technical talks. There are going to be 6 talks in a single track of 1 hour each. Each talk has the following information: title, 1 or maximum of 2 speakers, category (1 or maximum of 3 keywords), duration and a description. The website has a single page where users can see the schedule for the entire day with the timings. There will be one lunch break of an hour and the event starts at 10:00 AM. Keep a 10 minute transition between talks. I would like to use Node.js on the server side and standard HTML, JavaScript and CSS on the front-end. The users should be able to search the talks based on category.
I would like you to proceed in the following way:
1. Plan out how you would design and code this application.
2. Ask me for any clarifications along the way.
3. Once I am fine with it, do generate the code and provide me instructions to run and test locally.
The next few prompts and responses are a sample flow that was observed. Gemini CLI will come up with a plan and ask you for any confirmations / clarifications or go ahead. Please follow the instructions. As a sample, this is my sample conversational thread:
✦ Of course. I will start by creating a plan for the application.
Plan:
1. Backend (Node.js):
* I'll set up a simple Node.js server using the Express.js framework.
* This server will have two main purposes:
1. Serve the static frontend files (HTML, CSS, JavaScript).
2. Provide an API endpoint (e.g., /api/talks) that will send the event schedule data to the frontend as a JSON object.
* The talk data will be stored in a separate talks.json file for easy management.
2. Frontend (HTML, CSS, JS):
* HTML: A single index.html file will define the structure of the page, including a container for the schedule and a search input field for filtering by category.
* CSS: A style.css file will be used to style the website for a clean and professional look, ensuring the schedule is easy to read.
* JavaScript: A script.js file will handle the dynamic aspects of the site:
1. It will fetch the talk data from the backend API when the page loads.
2. It will dynamically render the schedule on the page based on the fetched data.
3. It will implement the search functionality. As the user types in the search box, it will filter the displayed talks based on the category keywords.
3. Project Structure:
I will organize the project with a clear and standard structure:
1 /
2 ├── public/
3 │ ├── index.html
4 │ ├── style.css
5 │ └── script.js
6 ├── talks.json
7 └── server.js
8 └── package.json
Before I proceed with generating the code, I have a few questions to ensure the final product meets your expectations:
It even asks me a few questions (shown below and which I answer):
It then proceeds with generating code, asking me for confirmations at several points and to which I do provide the necessary permission to go ahead.
Finally it started the server and asked me to go ahead and inspect the page:
The server is now running in the background.
3. View Your Website
You can now open your web browser and navigate to the following address to see your website:
http://localhost:3000 (http://localhost:3000)
4. Test the Search Functionality
Once the page is loaded, you can test