DEV Community

Cover image for Cómo Usar Google Workspace CLI: Guía Paso a Paso
Roobia
Roobia

Posted on • Originally published at apidog.com

Cómo Usar Google Workspace CLI: Guía Paso a Paso

CLI de Google Workspace (invocado como gws)

Google Workspace CLI (gws) es una herramienta de línea de comandos de código abierto que proporciona acceso unificado a Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin y todas las APIs de Google Workspace. Se basa en el Servicio de Descubrimiento en vivo de Google, por lo que siempre tendrás los comandos actualizados sin depender de actualizaciones manuales. Instala la CLI globalmente con npm, autentícate una sola vez con OAuth y úsala directamente o con agentes como Claude Code o Cursor. No requiere flujos de OAuth repetitivos ni múltiples SDKs.

Prueba Apidog hoy

¿Por qué usar Google Workspace CLI?

Automatizar tareas en Google Workspace normalmente implica lidiar con scripts curl, scopes de OAuth, paginación y SDKs obsoletos. Cada servicio tiene endpoints y autenticaciones distintos, lo que hace que el código sea difícil de mantener.

Google Workspace CLI elimina esa complejidad. Descubre en tiempo real cada método de la API usando el Servicio de Descubrimiento de Google. Así, obtienes acceso inmediato a nuevos endpoints y métodos. Tus scripts y flujos de trabajo en terminal siempre estarán actualizados y funcionales.

Características clave:

  • Salida JSON limpia.
  • Soporte para dry-run (simulación).
  • Helpers de paginación.
  • Más de 40 atajos (+) para tareas comunes, como gws gmail +send o gws calendar +agenda.
  • Habilidades listas para agentes IA (Claude Code, Cursor, OpenClaw, Gemini CLI).

Si automatizas APIs y usas herramientas como Apidog, puedes validar fácilmente tus integraciones. Apidog es un cliente API gratuito para enviar solicitudes, inspeccionar respuestas, gestionar entornos y ejecutar pruebas. Así, combinas acceso en vivo (gws) con verificación API (Apidog).

Instalación de Google Workspace CLI

Requisito: Node.js 18+

Verifica tu versión:

node --version
Enter fullscreen mode Exit fullscreen mode

Ejecutar sin instalar

Para pruebas rápidas:

npx @googleworkspace/cli --help
npx @googleworkspace/cli drive files list --params '{"pageSize":1}'
Enter fullscreen mode Exit fullscreen mode

Ideal para scripts de un solo uso.

Instalación global

Para uso frecuente:

npm install -g @googleworkspace/cli
gws --version
Enter fullscreen mode Exit fullscreen mode

Incluye binarios precompilados (no necesitas compilar Rust). Alternativamente, descarga de GitHub Releases, usa Homebrew (brew install googleworkspace/cli) o Nix.

Configuración y Autenticación

Autenticación inicial

Configura OAuth y credenciales con:

gws auth setup
Enter fullscreen mode Exit fullscreen mode

Esto abre tu navegador, crea el proyecto de Google Cloud, habilita APIs y guarda credenciales cifradas en tu sistema.

Instalar habilidades de agente

Agrega habilidades de agente:

npx skills add https://github.com/googleworkspace/cli
Enter fullscreen mode Exit fullscreen mode

O instala habilidades específicas (Claude Code, Cursor). Reinicia el agente para que detecte los comandos de gws.

Configuración por proyecto

Por defecto es global, pero puedes limitar la configuración a un proyecto:

gws auth setup --project
Enter fullscreen mode Exit fullscreen mode

Ciclo de autenticación

  • Reautenticar o cambiar de cuenta: 
  gws auth login
Enter fullscreen mode Exit fullscreen mode
  • Ver usuario actual y scopes: 
  gws auth whoami
Enter fullscreen mode Exit fullscreen mode
  • Cerrar sesión: 
  gws auth logout
Enter fullscreen mode Exit fullscreen mode
  • Uso sin UI/CI, exporta credenciales: 
  gws auth export --unmasked > creds.json
  export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/creds.json
Enter fullscreen mode Exit fullscreen mode
  • O reutiliza tokens de gcloud: 
  export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token)
Enter fullscreen mode Exit fullscreen mode

Telemetría

Desactiva la telemetría anónima:

export GOOGLE_WORKSPACE_CLI_NO_TELEMETRY=1
Enter fullscreen mode Exit fullscreen mode

Comandos principales: Ejemplos prácticos

Google Workspace CLI descubre comandos en tiempo real. Usa:

gws --help
Enter fullscreen mode Exit fullscreen mode

para ver los servicios disponibles.

Drive: Archivos y carpetas

Listar archivos recientes:

gws drive files list --params '{"pageSize":10, "q":"name contains report"}'
Enter fullscreen mode Exit fullscreen mode

Subir archivos:

gws drive +upload ./budget.xlsx --name "2026 Budget"
Enter fullscreen mode Exit fullscreen mode

Gmail

Enviar email:

gws gmail +send --to colega@example.com --subject "Update" --body "See attached." --attach ./file.pdf
Enter fullscreen mode Exit fullscreen mode

Responder o clasificar bandeja de entrada:

gws gmail +reply --message-id <ID> --body "Thanks!"
gws gmail +triage
Enter fullscreen mode Exit fullscreen mode

Calendar

Crear evento:

gws calendar +insert --summary "Sprint Planning" --start "2026-03-20T10:00" --end "2026-03-20T11:00" --attendees "team@example.com"
Enter fullscreen mode Exit fullscreen mode

Mostrar agenda de hoy:

gws calendar +agenda --today
Enter fullscreen mode Exit fullscreen mode

Sheets

Añadir fila:

gws sheets +append --spreadsheetId <ID> --range "Sheet1!A:C" --values "Task X,Done,2026-03-16"
Enter fullscreen mode Exit fullscreen mode

Docs

Insertar texto:

gws docs +write --documentId <ID> --text "New section added via Google Workspace CLI"
Enter fullscreen mode Exit fullscreen mode

Chat

Publicar mensaje:

gws chat +send --space <SPACE_ID> --text "Deployment complete 🚀"
Enter fullscreen mode Exit fullscreen mode

Tips:

  • Usa --dry-run para simular la llamada API.
  • Añade --page-all para paginación completa (NDJSON).

Configuración avanzada

Persiste configuración con variables de entorno o .env:

export GOOGLE_WORKSPACE_CLI_DEFAULT_PARAMS='{"prettyPrint":true}'
Enter fullscreen mode Exit fullscreen mode

Cambia formato (--json, --yaml), tiempo de espera, o fuerza el uso de llavero basado en archivos. Consulta configuración:

gws config
Enter fullscreen mode Exit fullscreen mode

Integración con agentes de IA y prompts

Una vez instaladas las habilidades, los agentes pueden invocar gws directamente.

Patrón de uso

En prompts:

  • "Listar mis archivos recientes de Drive usando Google Workspace CLI"
  • "Enviar un correo de seguimiento usando Google Workspace CLI"

Regla de invocación automática

En las instrucciones de tu agente (ej: CLAUDE.md):

"Siempre que la tarea involucre Gmail, Drive, Calendar, Sheets, Docs o Chat, usa los comandos de Google Workspace CLI automáticamente antes de responder. Resuelve primero el servicio y el método."

Los agentes devuelven archivos o resultados JSON, manteniendo el contexto ligero.

Usa Apidog para depuración y pruebas API

Google Workspace CLI te da acceso inmediato a tus datos, pero para depurar payloads, scopes o respuestas, necesitas visibilidad. Apidog es un cliente API gratuito para:

  • Enviar solicitudes y ver respuestas crudas.
  • Configurar entornos con tokens OAuth.
  • Automatizar aserciones.

Ejemplos de flujo de trabajo:

  • El agente sugiere añadir a Sheets → prueba el payload exacto con Sheets.values.append en Apidog.
  • Depura scopes de Gmail → crea y ejecuta la solicitud visualmente.
  • Almacena claves/tokens como variables para cambiar de cuenta y validar.

Juntos, Google Workspace CLI + Apidog te ofrecen acceso a datos en vivo y pruebas API verificables y repetibles.

Preguntas Frecuentes

¿Google Workspace CLI envía mis datos externamente?

No. Todas las llamadas van directamente a las APIs de Google. Tus datos no salen de tu cuenta.

¿Qué servicios soporta?

Todas las APIs de Workspace descubiertas dinámicamente: Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, Script, y más.

¿Qué tan actualizados están los comandos?

Se consulta el Servicio de Descubrimiento en vivo; los nuevos métodos aparecen automáticamente.

¿Requiere clave de API?

Utiliza OAuth estándar de Google o cuentas de servicio; no necesitas una clave separada.

¿Qué agentes y editores soporta?

Claude Code, Cursor, OpenClaw, Gemini CLI, extensiones VS Code y cualquier herramienta compatible con MCP/Agent Skills.

¿Cuál es la diferencia entre comandos "raw" y "helpers" (+)?

raw: métodos exactos de Discovery (ej: drive.files.list).

+ helpers: atajos para tareas comunes (ej: +upload, +send).

¿Puedo usar Google Workspace CLI sin agente IA?

Sí. Perfecto para scripts, automatización o uso diario en terminal.

Recursos adicionales

Top comments (0)