Primeros pasos con las extensiones de Gemini CLI

1. Introducción

Gemini CLI es un agente de código abierto potenciado por IA para tu terminal que lleva el poder de los modelos de Gemini directamente a tu línea de comandos. Si bien es potente por sí sola, su verdadero potencial se libera a través de las extensiones de Gemini CLI.

Las extensiones son la forma oficial y estandarizada de aumentar las capacidades de Gemini CLI. Antes de las extensiones, personalizar la CLI a menudo implicaba editar manualmente archivos de configuración como settings.json, un proceso que podía ser "desordenado y propenso a errores".

Piensa en una extensión como un "contenedor de envío" para las personalizaciones de Gemini CLI. Es un paquete autónomo, con versiones y fácil de distribuir que incluye todos los componentes necesarios para enseñarle a Gemini un nuevo conjunto de habilidades. Este "contenedor de envío" puede incluir lo siguiente :

• Configuraciones del servidor de MCP: Conectan Gemini a herramientas y APIs externas, como las APIs de Google Cloud o los servicios de terceros.
• Archivos de contexto (GEMINI.md): Son "manuales" que proporcionan al modelo instrucciones y lineamientos específicos sobre cómo usar las nuevas herramientas de manera eficaz.
• Comandos de barra personalizados (archivos .toml): Estos encapsulan instrucciones complejas de varios pasos en comandos simples y fáciles de usar, como /deploy.
• Restricciones de herramientas (excludeTools): Pueden inhabilitar herramientas integradas para crear un entorno más seguro o enfocado.

El valor principal de las extensiones es transformar la CLI de Gemini de un asistente personal en una plataforma escalable y lista para la empresa. Un equipo puede empaquetar toda su pila de Cloud en una sola extensión, lo que permite que los desarrolladores nuevos sean productivos con un solo comando.

En este codelab, aprenderás a usar este potente ecosistema. No crearás una extensión, pero instalarás y usarás cuatro extensiones diferentes para agregar capacidades de implementación de aplicaciones, análisis de seguridad, análisis de datos y de infraestructura como código a tu terminal.

Actividades

• Instala y configura la CLI de Gemini y sus requisitos previos de Google Cloud.
• Explora la galería oficial de extensiones de Gemini CLI para encontrar extensiones.
• Usa la interfaz de línea de comandos de gemini extensions para instalar, enumerar y administrar extensiones.
• Explora algunas extensiones de Gemini CLI

Qué aprenderás

• Qué son las extensiones de Gemini CLI y por qué son el estándar para personalizar la CLI
• Cómo encontrar e instalar extensiones desde la Galería de extensiones o una URL de GitHub
• Función de los comandos de administración de claves: gemini extensions install, gemini extensions list y gemini extensions update.
• Instala y usa algunas extensiones de Gemini CLI

Requisitos

• Navegador web Chrome
• Una cuenta de Gmail
• Un proyecto de Cloud con la facturación habilitada

Este codelab está diseñado para usuarios y desarrolladores de todos los niveles (incluidos los principiantes). Se espera que tengas cierta familiaridad con la CLI de Gemini, aunque se proporcionarán los pasos para instalarla desde cero. Si quieres familiarizarte con Gemini CLI, prueba el codelab práctico sobre la CLI de Gemini.

2. Antes de comenzar

Para obtener créditos de Google Cloud: Para ayudarte a comenzar, canjea tus créditos gratuitos de Google Cloud con este vínculo. Puedes seguir las instrucciones aquí para activar el crédito y crear un proyecto nuevo.

Crea un proyecto

1. En la página del selector de proyectos de la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.
2. Asegúrate de que la facturación esté habilitada para tu proyecto de Cloud. Obtén información sobre cómo verificar si la facturación está habilitada en un proyecto.
3. Usarás Cloud Shell, un entorno de línea de comandos que se ejecuta en Google Cloud y que viene precargado con bq. Haz clic en Activar Cloud Shell en la parte superior de la consola de Google Cloud.

4. Una vez que te conectes a Cloud Shell, verifica que ya te autenticaste y que el proyecto se configuró con el ID de tu proyecto con el siguiente comando:

gcloud auth list

5. En Cloud Shell, ejecuta el siguiente comando para confirmar que el comando gcloud conoce tu proyecto.

gcloud config list project

6. Si tu proyecto no está configurado, usa el siguiente comando para hacerlo:

gcloud config set project <YOUR_PROJECT_ID>

7. Habilita las APIs requeridas con el siguiente comando. Este proceso puede tardar unos minutos, así que ten paciencia.

gcloud services enable cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       run.googleapis.com \
                       cloudbuild.googleapis.com \

Si el comando se ejecuta correctamente, deberías ver un mensaje similar al que se muestra a continuación:

Operation "operations/..." finished successfully.

Si olvidas alguna API, puedes habilitarla durante el proceso de implementación.

Consulta la documentación para ver los comandos y el uso de gcloud.Antes de realizar la configuración y ejecutar la CLI de Gemini, creemos una carpeta que usarás como carpeta principal para todos los proyectos que crees dentro de ella. Este es un punto de partida para que la CLI de Gemini funcione, aunque también hará referencia a otras carpetas de tu sistema que verás más adelante, según sea necesario.

Crea una carpeta de muestra (gemini-cli-projects) y navega a ella con los comandos que se muestran a continuación. Si prefieres usar otro nombre de carpeta, hazlo.

mkdir gemini-cli-projects

Naveguemos a esa carpeta:

cd gemini-cli-projects

Nota: Si usas Google Cloud Shell, la CLI de Gemini ya está instalada.

Puedes iniciar Gemini CLI directamente con el comando gemini en una nueva terminal de Cloud Shell, o bien ya se habrá iniciado en una terminal de Cloud Shell separada.

Nuestra primera interacción con la CLI de Gemini

Debemos asegurarnos de que todo esté bien con nuestro entorno de la CLI de Gemini para poder dar nuestra primera instrucción, como se muestra a continuación:

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

Notarás que nuestra búsqueda generó una herramienta GoogleSearch (una herramienta integrada en la CLI de Gemini) que se invocó. En otras palabras, ya usaste una de las potentes herramientas integradas de Gemini CLI, GoogleSearch, que fundamenta sus respuestas en la información que obtiene de la Web. Deberías recibir una respuesta a tu búsqueda.

A continuación, comencemos con las extensiones.

3. ¿Qué es una extensión?

Una extensión es un paquete autónomo, con versiones y fácil de distribuir. Piensa en él como el "contenedor de envío" para tus personalizaciones de Gemini CLI, que agrupa todo lo necesario para un flujo de trabajo específico en un solo paquete ordenado.

Una extensión puede incluir cualquier combinación de los siguientes elementos:

• Comandos de barra personalizados (tus archivos .toml)
• Configuraciones del servidor de MCP (que antes se encontraban en settings.json)
• Archivos de contexto (GEMINI.md) para proporcionar instrucciones y lineamientos específicos al modelo
• Restricciones de herramientas (excludeTools) para crear un entorno más seguro y enfocado

¿Por qué usar extensiones? Los beneficios principales

Adoptar las extensiones para tus personalizaciones ofrece varias ventajas poderosas:

• Instalación con un solo comando: Esto es clave. En lugar de una configuración manual de varios pasos, un usuario puede instalar un conjunto de herramientas completo y complejo con un solo comando: gemini extensions install <URL> o gemini extensions install --path=some/local/path. La <URL> en el comando anterior podría ser la URL de GitHub donde alojaste la extensión.
• Distribución simplificada: Compartir tu trabajo es tan fácil como compartir una sola URL de repositorio de Git. Ya no tendrás que pasar archivos individuales ni fragmentos de configuración.
• Administración de versiones y dependencias: Debido a que las extensiones suelen alojarse en repositorios de Git, obtienes el control de versiones de forma gratuita. Hay gemini extensions update command para actualizar una extensión a la versión más reciente.
• Descubrimiento y ecosistema: Las extensiones son la base de un ecosistema enriquecido y abierto, al igual que los mercados de VS Code o Chrome. El mecanismo de extensiones podría formar la base de un futuro mercado en el que estas extensiones estén disponibles para su revisión, descarga y mucho más, al verdadero estilo de la comunidad.

La introducción del framework de extensiones es una señal clara de que Gemini CLI está evolucionando de una potente herramienta independiente a una verdadera plataforma extensible.

4. Conceptos básicos de las extensiones

En esta sección, se abarcan las partes del ecosistema de extensiones orientadas al usuario: cómo encontrar extensiones y cómo administrarlas.

Explora la Galería de extensiones

La Galería de extensiones es el mercado central para descubrir todas las extensiones oficiales creadas por Google y de terceros:

1. Abre la siguiente URL en tu navegador: https://geminicli.com/extensions/browse/.
2. Esta galería es el motor de descubrimiento del ecosistema. Puedes ver extensiones de empresas como GitHub, Redis y DynaTrace, que muestran la amplitud de las herramientas disponibles.
3. Desplázate hacia abajo y busca la tarjeta de extensión de Cloud Run.
4. Observa que la tarjeta proporciona una descripción, el autor (Google) y un botón de comando Copy install con un solo clic. Esta es la forma más sencilla de obtener el comando de instalación de una extensión.

Extensiones de la CLI de Gemini: Comandos de administración

El comando gemini extensions es tu punto de entrada para administrar tus extensiones locales.

Ejecútalo en la terminal para ver la lista de comandos disponibles.

Los comandos son sencillos (instalar/desinstalar, listar, actualizar, habilitar/inhabilitar, etcétera) y usaremos algunos de ellos en este codelab.

Verifica tu estado actual

Antes de instalar cualquier cosa, verifiquemos nuestro "punto de partida".

1. Ejecuta el comando gemini extensions list:
2. Deberías ver el siguiente resultado, que confirma que aún no se instaló ninguna extensión.

No extensions installed.

5. Extensión de Cloud Run (implementación de una app)

La extensión de Cloud Run disponible en la galería de extensiones de la CLI de Gemini es un servidor de MCP que nos permite implementar nuestras aplicaciones en Cloud Run.

A continuación, se muestra la tarjeta de la extensión de Cloud Run de la galería de extensiones:

Primero, haz clic en Copiar comando de instalación, como se muestra arriba, para instalar la extensión de Cloud Run. Luego, pega ese comando en la terminal de Cloud Shell (debería ser similar al siguiente):

gemini extensions install https://github.com/GoogleCloudPlatform/cloud-run-mcp

Cuando ejecutes el comando anterior, verás que se requiere tu confirmación. Aprobar la solicitud La extensión de Cloud Run debería instalarse correctamente.

Installing extension "cloud-run".
**Extensions may introduce unexpected behavior. Ensure you have investigated the extension source and trust the author.**
This extension will run the following MCP servers:
  * cloud-run (local): npx -y @google-cloud/cloud-run-mcp
This extension will append info to your gemini.md context using gemini-extension/GEMINI.md
Do you want to continue? [Y/n]: Y
Extension "cloud-run" installed successfully and enabled.

Si ahora ejecutas el comando gemini extensions list, deberías ver la extensión de Cloud Run instalada, como se muestra a continuación:

✓ cloud-run (1.0.0)
 Path: <HOME_FOLDER>/.gemini/extensions/cloud-run
 Source: https://github.com/GoogleCloudPlatform/cloud-run-mcp (Type: github-release)
 Release tag: v1.5.0
 Enabled (User): true
 Enabled (Workspace): true
 Context files:
  <HOME_FOLDER>/.gemini/extensions/cloud-run/gemini-extension/GEMINI.md
 MCP servers:
  cloud-run

Si inicias Gemini CLI ahora y ejecutas el comando /mcp, verás lo siguiente:

Ahora volvamos a Cloud Shell y tratemos de implementar una aplicación. Para ello, primero necesitaremos una aplicación simple para implementar en Cloud Run. Sigue los pasos que se indican a continuación:

Asegúrate de estar en la carpeta que creamos antes, es decir, gemini-cli-projects. Crea otra carpeta dentro de esta llamada gemini-cloud-run y navega hasta ella.

mkdir gemini-cloud-run

cd gemini-cloud-run

Ahora crea dos archivos en esta carpeta (archivos app.py y requirements.txt), cuyos contenidos se indican a continuación:

app.py

from flask import Flask
app = Flask(__name__)
@app.route('/')
def hello_world():
  return 'Hello from Gemini and Cloud Run!'
if __name__ == "__main__":
  app.run(debug=True, host='0.0.0.0', port=8080)

requirements.txt

Flask
gunicorn

Ahora, inicia Gemini CLI desde la carpeta gemini-cloud-run y, cuando la terminal esté lista, ingresa la siguiente instrucción:

/deploy --project="PROJECT_ID" --location="PROJECT_LOCATION" --name="SERVICE_NAME"

Deberás especificar el PROJECT_ID (ID del proyecto de Google Cloud), el PROJECT_LOCATION y el SERVICE_NAME. Si no proporcionas esta información, el comando de Cloud Run invoca las herramientas adecuadas para ayudarte a elegir.

Como parte del proceso, se seleccionará la herramienta adecuada de la extensión del servidor de MCP de Cloud Run que instalamos. Por ejemplo, deberías ver un mensaje como este:

Permite que se use la herramienta.

Eso es todo. Ahora, Gemini CLI tiene toda la información que necesita, además de tu permiso para ejecutar las herramientas. Ahora se ejecutará toda la canalización de implementación: se compilará la imagen de Docker, se enviará a Artifact Registry y se configurará y se implementará un nuevo servicio de Cloud Run.

Después de unos momentos (en realidad, de 2 a 3 minutos), verás un mensaje de éxito con una URL de servicio. A continuación, se muestra un ejemplo de ejecución:

The Cloud Run service SERVICE_NAME has been deployed from the current folder in project PROJECT_ID.
  You can view the service in the Cloud Console: https://console.cloud.google.com/run/detail/PROJECT_LOCATION/SERVICE_NAME?project=PROJECT_ID
  The service is accessible at: https://SERVICE_NAME-SOME-ID.a.run.app

Haz clic en ese vínculo. Deberías ver la app de Flask que entrega la página principal:

Esto demuestra el poder de una extensión de Gemini CLI (Cloud Run en este caso), en la que se encapsuló por completo la complejidad de los comandos de gcloud CLI y simplemente se encargó de todos los detalles por ti.

Puedes explorar otras herramientas en el servidor de MCP de Cloud Run.

6. La extensión de BigQuery (análisis de conjuntos de datos grandes)

Para seguir los pasos, necesitarás lo siguiente:

• Proyecto de Google Cloud con la API de BigQuery habilitada
• Permisos de IAM:
• Usuario de BigQuery (roles/bigquery.user)

1. Ejecuta este comando para configurar tu variable de entorno BIGQUERY_PROJECT. Este es el proyecto que ejecutará los trabajos de BigQuery, no necesariamente el proyecto en el que residen tus datos (aunque podrían ser el mismo).

export BIGQUERY_PROJECT=<YOUR_GCP_PROJECT_ID>

2. Instala la extensión de BigQuery Data Analytics con el siguiente comando. Otorga el permiso para instalarlo. Si la instalación se realiza correctamente, tendrás 2 extensiones instaladas en tu configuración : cloud-run y bigquery-data-analytics.

gemini extensions install https://github.com/gemini-cli-extensions/bigquery-data-analytics

3. Volvamos a iniciar Gemini CLI con el siguiente comando:

gemini

La Gemini CLI debería iniciarse en tu terminal:

Los siguientes comandos se deben ingresar en la terminal de Gemini CLI.

4. Para confirmar que la extensión de BigQuery esté instalada y lista para usarse, ingresa el siguiente comando de barra:

/extensions list

También deberías ver la extensión bigquery-data-analytics en la lista.

5. Ejecuta el siguiente comando para consultar las herramientas disponibles:

/mcp list

6. Hagamos una pregunta básica de análisis sobre el conjunto de datos públicos de BigQuery: el comercio electrónico de Look. Este conjunto de datos contiene información sobre clientes, productos y pedidos de un sitio de comercio electrónico de ropa ficticio. Ingresa esta instrucción en Gemini CLI:

Look at BigQuery's the look ecommerce public dataset. Identify the top 5 products that had the most orders.

• La CLI de Gemini te preguntará si quieres permitir la ejecución de las herramientas de BigQuery. Para continuar, selecciona la tercera opción: Yes, always allow all tools from server "bigquery_data_analytics".
• En segundo plano, Gemini generará la consulta en SQL adecuada, invocará la herramienta execute_sql y devolverá una respuesta en lenguaje natural junto con tus datos:

7. Ahora, le pediremos a Gemini que pronostique cuál será la tasa de devoluciones de los productos según los datos históricos. Para este comando, Gemini CLI no debe intentar generar un código SQL detallado para crear esta previsión, sino que debe invocar la herramienta forecast del servidor de MCP, que usará AI.Forecast de BigQuery de forma interna:

Forecast what the return rate will be next month.

• Deberías ver una respuesta como la siguiente:

7. La extensión de Google Workspace (flujos de trabajo diarios)

La extensión de Google Workspace está disponible como un servidor de MCP que se integra con aplicaciones de Google Workspace, como Documentos, Chat, Calendario, Drive y muchas más. Una característica clave de esta extensión es su modelo de ejecución local. El servidor de MCP se ejecuta en la máquina del usuario, no en la nube. Usa las credenciales de OAuth del usuario para comunicarse directamente con las APIs de Google.

A continuación, se muestra la tarjeta de extensión de Google Workspace de la galería de extensiones:

Para instalar la extensión de Google Workspace, haz clic en el botón Copiar y pega ese comando en la terminal de Cloud Shell (debería ser similar al siguiente):

gemini extensions install https://github.com/gemini-cli-extensions/workspace

Cuando ejecutes el comando anterior, verás que se requiere tu confirmación. Aprobar la solicitud La extensión de Google Workspace debería instalarse correctamente.

Si ahora ejecutas el comando gemini extensions list, deberías ver la extensión de Google Workspace instalada, como se muestra a continuación (o un resultado similar):

✓ google-workspace (v0.0.3)
 ID: 40be7ad1253320a38aba2f107f21349b41a458416fd4616550c832ff1d3b7dce
 name: a1f88ed96997755f9cd591bb26d8e1087e5969979caabe19fcde7b3544ea1a1e
 Path: /Users/romin/.gemini/extensions/google-workspace
 Source: https://github.com/gemini-cli-extensions/workspace (Type: github-release)
 Release tag: v0.0.3
 Enabled (User): true
 Enabled (Workspace): true
 Context files:
  /Users/romin/.gemini/extensions/google-workspace/WORKSPACE-Context.md
 MCP servers:
  google-workspace

Si inicias Gemini CLI ahora, deberás realizar el paso más importante del proceso de configuración de esta extensión, que es la autenticación. A diferencia de una secuencia de comandos simple que podría usar una clave de API estática, la extensión de Workspace actúa como un agente autorizado en nombre del usuario, lo que requiere acceso a permisos sensibles (Drive, Correo y Calendario).

La extensión inicia un flujo de OAuth 2.0. Elige tu cuenta y, luego, Google mostrará una lista de los permisos (alcances) que solicita la extensión. Son extensas y, entre ellas, se incluyen las principales, como se muestra a continuación:

Una vez que completes este intercambio de OAuth 2.0, todo estará listo.

Para verificar si la extensión se instaló correctamente, inicia Gemini y, luego, usa el comando /mcp list. Esto debería mostrar que la extensión está instalada y que los comandos se expusieron como herramientas de MCP. A continuación, se muestra una captura de pantalla de este proceso:

Herramientas de Workspace

La extensión asigna extremos de API específicos de Google Workspace a "Herramientas" que el LLM puede invocar. Estas herramientas no son aleatorias, sino que se seleccionan cuidadosamente para abarcar las principales modalidades del trabajo del conocimiento:

• Administración de archivos (Drive)
• Creación de documentos (Documentos)
• Administración del tiempo (Calendario)
• Comunicación (Gmail/Chat)

Veamos algunos ejemplos que puedes probar con las diferentes herramientas disponibles. Para probar estas herramientas, se espera que tengas algunos correos electrónicos en tu cuenta de Gmail conectada, un programa de Calendario, archivos en Google Drive, etcétera.

Ten en cuenta que, a medida que ingreses las instrucciones que se indican a continuación, la CLI de Gemini identificará la herramienta correcta para usar de las herramientas de Google Workspace y te pedirá permiso para invocar las herramientas. Así que da el visto bueno en el momento adecuado.

Drive y Documentos : La base de conocimiento

Si tienes un documento de diseño o un documento interesante en tu Google Drive, puedes intentar buscarlo y resumirlo con una instrucción de ejemplo como esta:

Search for <DOC_NAME> in Google Drive

Una vez que se encuentren los documentos, la CLI de Gemini los enumerará junto con sus IDs. Luego, puedes pedirle que resuma el documento de la siguiente manera:

Summarize <DOC_ID> for me

Hagamos una actividad que solemos hacer cuando necesitamos información. Buscamos en la Web y, luego, colocamos la información pertinente en un documento de Google.

Piensa en una instrucción como esta:

Lookup information on The Richat Structure (Eye of Africa) and create a 1-pager document for me with relevant information about

Esta instrucción primero hace que la CLI de Gemini ejecute la herramienta de Búsqueda de Google para recuperar la información de la Web y, una vez que la obtiene, la sintetiza en un documento de 1 página, como solicitamos, y crea un nuevo documento de Google en Google Drive.

Visita Google Drive para tu cuenta y consulta el documento que creó. El siguiente documento es de una ejecución de muestra.

Calendario

Usa las herramientas de calendario disponibles en la extensión para que funcione como un asistente ejecutivo que administra tu tiempo.

Puedes usar /calendar:get-schedule o simplemente usar consultas en lenguaje natural para obtener la información.

Comencemos con lo más básico para saber cómo será tu agenda de hoy. Proporciona la siguiente instrucción y observa que accedió a tu calendario del día y te proporcionó los eventos del calendario configurados para el día (asegúrate de tener algunos eventos configurados en tu calendario para el día).

What does my schedule look like for today?

Luego, puedes probar lo siguiente:

Pídele un horario específico de tu agenda para el día y, si te gustan los horarios que te presentó, incluso puedes pedirle que cree un evento para el día. Pruébalo.

Comunicaciones: Gmail y Chat

Puedes usar la herramienta /gmail:search para buscar correos electrónicos y permitir la recuperación del contexto de los hilos de correos electrónicos.

Por ejemplo, si tienes un correo electrónico específico que recibes semanalmente o de algún equipo, etc., intenta buscar esos correos electrónicos con una instrucción como esta:

/gmail:search "Project Phoenix updates"

Luego, puedes pedirle que resuma el correo específico y que también lo envíe a un espacio de Google Chat con un mensaje como este:

Send a chat message to <SPACE_NAME> and highlight the key points from the email.

Los ejemplos anteriores son solo algunos. Considera los flujos de trabajo más complejos de la siguiente manera:

Find the 'Project Phoenix Design Doc' in Drive,
read the section on API authentication,
and help me scaffold the middleware based on those specs.

Send a message to the ‘Core Eng' chat space letting them know the deployment is starting now.

La mejor manera de usar extensiones como esta es probarlas con tus propios archivos, calendario, Gmail, etcétera, y crear flujos que quieras automatizar o simplemente tener una mejor manera de evitar el cambio de contexto y ahorrar tiempo.

8. Exploración adicional

Con esto, completamos nuestro codelab en el que explicamos qué son las extensiones de Gemini CLI, los comandos básicos para trabajar con ellas y exploramos un par de extensiones : las extensiones de cloud-run y bigquery-data-analytics.

Visita la Galería de extensiones de Gemini en https://geminicli.com/extensions/ para explorar las extensiones disponibles actualmente (más de 100 en el momento de escribir este artículo) que puedes usar hoy mismo. Cada tarjeta de Extensiones contiene información, el tipo de extensión que es (MCP, Contexto, etc.), junto con el vínculo a su repositorio de GitHub y un comando para instalar la extensión en tu entorno.

9. Felicitaciones

¡Felicitaciones! Comprendiste correctamente las extensiones de Gemini CLI y cómo instalar y usar varias de ellas.

Documentos de referencia

• Extensiones de Gemini CLI
• Galería de extensiones de Gemini CLI