Use the Gemini CLI

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see thelaunch 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, anddata developers who work with Vertex AI Workbench. This documentassumes 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 toGemini directly in a terminal. For more information,seegeminicli.com.

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 filesbased on a single, high-level instruction.
  • Run basic shell commands.
  • Run commands to interact with other Google Cloud services, such asVertex AI and BigQuery.

Limitations

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

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

  • When you ask Gemini CLI to modify a notebook, theGemini CLI changes the notebook file directly on theinstance's disk. Because of this, you can't undo edits made bythe Gemini CLI by using the notebook editor'sUndo buttonorControl+Z (Command+Z on macOS). However, you can askthe Gemini CLI to undo a change by using a natural languagecommand, such asUndo 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, seeGemini for Google Cloud and responsible AI.

  1. 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.

  2. 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 theresourcemanager.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

  3. Verify that billing is enabled for your Google Cloud project.

  4. 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 theserviceusage.services.enable permission.Learn how to grant roles.

    Enable the APIs

  5. 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 theresourcemanager.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

  6. Verify that billing is enabled for your Google Cloud project.

  7. 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 theserviceusage.services.enable permission.Learn how to grant roles.

    Enable the APIs

Required roles

To use the Gemini CLI in Vertex AI Workbench, you mustgrant permissions to the user of the Vertex AI Workbench instance andthe instance's service account.

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.

Grant permissions to the user of the instance

To get the permissions that you need to use the Gemini CLI in a Vertex AI Workbench instance, ask your administrator to grant you theVertex AI User (roles/aiplatform.user) IAM role on the project. For more information about granting roles, seeManage access to projects, folders, and organizations.

You might also be able to get the required permissions throughcustom roles or otherpredefined roles.

Grant a permission to your instance's service account

To ensure that your Vertex AI Workbench instance's service account has the necessary permission to enable the Gemini CLI to run in a Vertex AI Workbench instance, ask your administrator to grant your Vertex AI Workbench instance's service account theVertex AI User (roles/aiplatform.user) IAM role on the project.Important: You must grant this role to your Vertex AI Workbench instance's service account,not to your user account. Failure to grant the role to the correct principal might result in permission errors. For more information about granting roles, seeManage access to projects, folders, and organizations.

This predefined role contains the aiplatform.endpoints.predict permission, which is required to enable the Gemini CLI to run in a Vertex AI Workbench instance.

Your administrator might also be able to give your Vertex AI Workbench instance's service account this permission withcustom roles or otherpredefined roles.

Use the Gemini CLI

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

    Go to Instances

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

    Your Vertex AI Workbench instance opens JupyterLab.

  3. In JupyterLab, clickFile >New launcher.

  4. In theLauncher tab, in theOther section, click theGemini CLI tile.

  5. If it's the first time you've opened a Gemini CLI terminal, enterY 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 enterCreate a new notebook named 'test-notebook'. To see examples of prompts that might be helpful, seeSample prompts.

Sample prompts

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

  • "Create a new notebook that trains a model to predict 'income bracket' frombigquery-public-data.ml_datasets.census_adult_income, usingBigQuery and Python."

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

  • "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 tablesfrom within Vertex AI Workbench."

  • "Query the bigquery-public-data.ml_datasets.census_adult_income tableto 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 filesfrom my current directory to it."

  • "Create a Compute Engine instance with a Debian 11 image and ann1-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 Workbenchby using the following methods:

  • An administrator can set up an organization policy to restrict usage ofspecific Gemini models at an organization, folder, orproject level. SeeControl access to Model Gardenmodels.The Gemini CLI continues to appear in JupyterLab, butthe CLI doesn't respond to prompts.

  • By not granting theaiplatform.endpoints.predict permission,an administrator can block some identities from being able to useGemini endpoints for inference.

Use the Gemini CLI magic command

To use the Gemini CLI directly within a cell in your notebook file,do the following:

  1. Ensure that the Gemini CLI is enabled and the user or creatorhas agreed to the terms and conditions.
  2. On the first line of a new cell, enter%%geminicli_magic.
  3. In the same cell, enter your prompt on the following line.
  4. Run the cell.

The Gemini CLI adds a new cell below with its response.

Troubleshoot

If you encounter a problem using the Gemini CLI withVertex AI Workbench instances, seeTroubleshootingVertex AI Workbenchfor help with common issues.

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-19 UTC.