8. Modo headless / no interactivo

Objetivo del tema

Aprender a ejecutar Gemini CLI sin la interfaz interactiva, integrándolo en scripts, pipelines y contenedores para automatizar tareas repetitivas.

El modo headless reutiliza tu configuración local (autenticación, contextos, sandbox) y acepta entrada y salida estandarizadas, ideales para CI/CD o cron jobs.

8.1 Ejecución de comandos en scripts o pipelines

La forma más directa de ejecutar una petición sin abrir el REPL es mediante tuberías o flags especiales:

Comando Uso
echo "Pregunta" | gemini Envía la cadena estándar a Gemini y finaliza cuando la respuesta está disponible.
gemini --prompt "Describe src/index.ts" Utiliza el flag --prompt (o -p) para enviar preguntas sin tuberías.
gemini --prompt "Genera un resumen" --include-directories docs Combina flags para proporcionar contexto adicional, igual que en el modo interactivo.
gemini --output-format json --prompt "Explica el esquema" Solicita la respuesta en JSON para procesarla posteriormente (disponible en versiones recientes).

Gemini CLI

La salida se imprime en stdout, por lo que puedes redirigirla a archivos o herramientas como jq o grep:

gemini --prompt "Resumen del README" > output.txt
cat output.txt

Los flags de aprobación (--approval-mode) y sandbox (--sandbox) también aplican en headless. Asegúrate de establecer el modo adecuado si tus scripts invocan herramientas que escriben archivos.

8.2 Automatización de flujos con Gemini CLI

El CLI puede formar parte de pipelines complejos: captura indicadores, genera reportes y persiste resultados. Un ejemplo inspirado en la documentación oficial:

result=$(gemini -p "Analiza la carpeta db" --include-directories db --output-format json)
total_tokens=$(echo "$result" | jq -r '.stats.models // {} | to_entries | map(.value.tokens.total) | add // 0')
tool_calls=$(echo "$result" | jq -r '.stats.tools.totalCalls // 0')
echo "$(date): $total_tokens tokens y $tool_calls herramientas" >> usage.log
echo "$result" | jq -r '.response' > db-readme.md

En este flujo:

  • Guardas la respuesta en JSON.
  • Extraes métricas de uso (.stats.models, .stats.tools).
  • Persistes la respuesta textual para documentación o artefactos.

Tambien puedes programar tareas recurrentes con cron o Task Scheduler, asegurándote de que las variables de entorno (GEMINI_API_KEY, GOOGLE_CLOUD_PROJECT, etc.) estén disponibles en el contexto del proceso.

8.3 Ejecución desde contenedores y pipelines CI/CD

Gemini CLI es compatible con contenedores Docker. Estas prácticas te ayudarán a integrarlo de forma segura:

  • Imagen base: utiliza la imagen oficial us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:VERSION o crea una imagen propia derivada de ella con tus dependencias.
  • Sandbox habilitado: ejecuta con gemini --sandbox dentro del contenedor para aislar operaciones sensibles, especialmente en CI.
  • Credenciales: monta secretos o variables de entorno seguras para GEMINI_API_KEY o credenciales de Vertex AI; evita hardcodearlas en la imagen.
  • Persistencia de resultados: redirige la salida a archivos dentro del contenedor y copia los artefactos como parte del pipeline (cat, tee, jq, etc.).
  • Checkpointing: habilita --checkpointing o define general.checkpointing.enabled para conservar backups si ejecutas tareas de escritura en el contenedor.

En plataformas de CI/CD (GitHub Actions, GitLab CI, Jenkins), invoca el binario dentro de un paso del pipeline, asegurando que la herramienta tenga acceso al repositorio y a los contextos necesarios.

8.4 Ejemplos prácticos

8.4.1 Generar un reporte diario

#!/bin/bash
fecha=$(date +"%Y-%m-%d")
gemini --prompt "Resume los tickets cerrados hoy" --include-directories docs/tickets > "reportes/$fecha.txt"

Programado con cron, este script genera un informe cada día, listo para compartir con el equipo.

8.4.2 Validar un cambio en CI

steps:
  - name: Instala dependencias
    run: npm install
  - name: Ejecuta validación con Gemini
    run: |
      gemini --prompt "Revisa si hay cambios en el README" --include-directories README.md \
        --approval-mode review --sandbox
  - name: Procesa resultado
    run: cat output.txt

El pipeline puede analizar la salida y decidir si aprueba o bloquea el despliegue.

8.4.3 Documentar un esquema de base de datos

result=$(gemini -p "Explica la carpeta db" --include-directories db --output-format json)
echo "$result" | jq -r '.response' > docs/db-overview.md

Automatiza la generación de documentación al ritmo de los cambios en tus estructuras de datos.

Recuerda limpiar o encriptar cualquier output que contenga datos sensibles antes de subirlo a repositorios o tableros compartidos.

Conclusión: el modo headless convierte a Gemini CLI en una herramienta versátil para automatizar reportes, validar cambios y documentar proyectos desde pipelines y contenedores. Al combinar prompts estructurados, flags adecuados y buenas prácticas de seguridad, puedes integrar inteligencia generativa en cualquier flujo sin depender del modo interactivo.

Retornar