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
• La 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

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.

Para obtener créditos de Google Cloud: Si deseas obtener créditos de Google Cloud para comenzar, usa este vínculo para canjear créditos que te ayudarán a completar el lab. Puedes seguir las instrucciones aquí para canjearlo.

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 funcione la CLI de Gemini, 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 ella 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 importantes:

• Instalación con un solo comando: Esto es clave. En lugar de una configuración manual de varios pasos, el 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 del 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. Comprende los 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 visibilidad 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.), 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 (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 el 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 CLI de Gemini 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 la CLI de Gemini:

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

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