Use the Gemini CLI

Use the Gemini CLI

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

This page describes how to use the Gemini command line interface (CLI) with a Vertex AI Workbench instance.

This document is intended for data analysts, data scientists, and data developers who work with Vertex AI Workbench. This document assumes you have knowledge of how to write code in a notebook environment.

Overview

The Gemini CLI is an open source AI agent that provides access to Gemini directly in a terminal. For more information, see gemini-cli on GitHub.

The Gemini CLI is available in Vertex AI Workbench instances. You can use the Gemini CLI to do the following:

• Create a new notebook.
• Run notebook cells.
• Write and edit a notebook's code and text cells.
• Explain code and technical concepts.
• Interact with a Vertex AI Workbench instance's local file system, including performing complex file operations that span multiple files based on a single, high-level instruction.
• Run basic shell commands.
• Run commands to interact with other Google Cloud services, such as Vertex AI and BigQuery.

Limitations

Consider the following limitations when you use the Gemini CLI with Vertex AI Workbench:

• The Gemini CLI is a CLI only. A graphical chat interface and advanced in-editor tools aren't included.

• When you ask Gemini CLI to modify a notebook, the Gemini CLI changes the notebook file directly on the instance's disk. Because of this, you can't undo edits made by the Gemini CLI by using the notebook editor's Undo button or Control+Z (Command+Z on macOS). However, you can ask the Gemini CLI to undo a change by using a natural language command, such as Undo your last change.

Before you begin

As an early-stage technology, Gemini for Google Cloud products can generate output that seems plausible but is factually incorrect. We recommend that you validate all output from Gemini for Google Cloud products before you use it. For more information, see Gemini for Google Cloud and responsible AI.

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Compute Engine, Notebooks, and Vertex AI APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Compute Engine, Notebooks, and Vertex AI APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Required roles

To get the permissions that you need to use the Gemini CLI in a Vertex AI Workbench instance, ask your administrator to grant you the following IAM roles on the project:

• Vertex AI User (roles/aiplatform.user)
• Notebooks Runner (roles/notebooks.runner)

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Note: The Gemini CLI operates strictly within the permissions of your Vertex AI Workbench instance's environment. If you (or the service account your instance uses) don't have permission to access a specific resource, Gemini CLI won't be able to access it either. If a command fails due to permissions, ask your administrator to grant the necessary permissions.

Use the Gemini CLI

1. In the Google Cloud console, go to the Instances page.

   Go to Instances

2. Next to a Vertex AI Workbench instance's name, click Open JupyterLab.

   Your Vertex AI Workbench instance opens JupyterLab.

3. In JupyterLab, click File > New launcher.

4. In the Launcher tab, in the Other section, click the Gemini CLI tile.

5. If it's the first time you've opened a Gemini CLI terminal, enter Y to agree to the terms and conditions.

   Your Vertex AI Workbench instance installs the Gemini CLI.

6. In the Gemini CLI terminal, enter a prompt.

   For example, you might enter Create a new notebook named 'test-notebook'. To see examples of prompts that might be helpful, see Sample prompts.

Sample prompts

To help you get ideas for how to use the Gemini CLI, see the following sample prompts:

• "Create a new notebook that trains a model to predict 'income bracket' from bigquery-public-data.ml_datasets.census_adult_income, using BigQuery and Python."

• "Summarize the notebook named 'test-file', and propose next steps for the project."

• "I want to get a quick overview of the notebooks in this directory. For every .ipynb file, show me the first 5 lines of the file."

• "Create a script using the contents of the 'test-file' notebook."

• "Show me how to access data from BigQuery tables from within Vertex AI Workbench."

• "Query the bigquery-public-data.ml_datasets.census_adult_income table to find the number of people with an income bracket of > 50K."

• "Set my default Google Cloud project to my-project."

• "Create a Cloud Storage bucket, and upload all the CSV files from my current directory to it."

• "Create a Compute Engine instance with a Debian 11 image and an n1-standard-4 machine type."

• "Create a notebook file that runs through the code in the 'test-script'. Add text cells that explain the code."

Control access to the Gemini CLI

You can control access to the Gemini CLI in Vertex AI Workbench by using the following methods:

• An administrator can set up an organization policy to restrict usage of specific Gemini models at an organization, folder, or project level. See Control access to Model Garden models. The Gemini CLI continues to appear in JupyterLab, but the CLI doesn't respond to prompts.

• By not granting the aiplatform.endpoints.predict permission, an administrator can block some identities from being able to use Gemini endpoints for inference.

Troubleshoot

If you encounter a problem using the Gemini CLI with Vertex AI Workbench instances, see Troubleshooting Vertex AI Workbench for help with common issues.

What's next

• Learn more about Gemini.

• To learn about methods for querying BigQuery data in Vertex AI Workbench notebooks, see Query data in BigQuery from within JupyterLab.