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

CLI de Google Workspace (invocado como gws)

Google Workspace CLI (invocado como gws) es una herramienta de línea de comandos dinámica de código abierto que brinda a los humanos y agentes de IA acceso unificado a Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin y cada API de Google Workspace, construida directamente a partir del Servicio de Descubrimiento en vivo de Google para que los comandos se mantengan actualizados sin necesidad de actualizaciones. Instale Google Workspace CLI globalmente a través de npm, autentíquese una vez con OAuth y conéctese a agentes como Claude Code o Cursor con las habilidades incluidas. No se necesitan flujos de OAuth repetitivos ni SDKs separados.

¿Qué es Google Workspace CLI y por qué es importante?Aquí hay un problema con el que se encuentra todo desarrollador, administrador y usuario de agente de IA: desea automatizar o consultar servicios de Google Workspace (archivos de Drive, enviar Gmail, crear eventos de Calendar, añadir a Sheets, editar Docs, publicar en Chat), pero termina escribiendo scripts curl personalizados, luchando con los ámbitos de OAuth, manejando la paginación manualmente o uniendo múltiples SDKs que se quedan obsoletos.

Esto sucede porque las APIs de Google Workspace son potentes pero están fragmentadas: cada servicio tiene sus propios puntos finales, flujos de autenticación y particularidades. Las herramientas tradicionales te obligan a mantener código repetitivo que se rompe con los cambios de la API.

Google Workspace CLI resuelve esto. Lanzado a principios de 2026 por el equipo de Google (anunciado por Addy Osmani), es una única CLI impulsada por Rust que descubre dinámicamente cada método de la API de Workspace en tiempo de ejecución utilizando el Servicio de Descubrimiento de Google. Obtiene acceso instantáneo a nuevos puntos finales sin esperar actualizaciones de la herramienta.

El resultado: sus scripts, agentes y trabajo diario en la terminal se mantienen precisos y actualizados. Google Workspace CLI produce JSON limpio, admite ejecuciones en seco (dry-runs), ayudantes de paginación e incluye más de 40 atajos fáciles de usar (precedidos de +) como gws gmail +send o gws calendar +agenda.

Google Workspace CLI también se entrega con habilidades de agente listas para instalar, por lo que herramientas como Claude Code, Cursor, OpenClaw o Gemini CLI pueden administrar autónomamente su Workspace—no se requieren definiciones de herramientas personalizadas.

Si está construyendo o probando integraciones de API junto con la automatización de Workspace, Apidog se encarga de la verificación. Es un cliente API gratuito para enviar solicitudes, inspeccionar respuestas, gestionar entornos y ejecutar conjuntos de pruebas. Juntos, Google Workspace CLI le da acceso en vivo a sus datos, y Apidog confirma que cada llamada se comporta como se espera.

Instalación de Google Workspace CLIEl único requisito es Node.js 18 o posterior. Verifique su versión con:

node --version

Ejecutar sin instalarLa forma más rápida de probar Google Workspace CLI es con npx (obtiene la última versión cada vez):

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

Ideal para pruebas rápidas o scripts de uso único.

Instalar globalmentePara uso regular, instálelo globalmente para que el comando gws esté siempre disponible:

npm install -g @googleworkspace/cli
gws --version

Google Workspace CLI incluye binarios precompilados, por lo que el inicio es rápido — no es necesario compilar Rust localmente. También puede obtener los binarios de GitHub Releases, usar Homebrew (brew install googleworkspace/cli) o ejecutar a través de Nix si lo prefiere.

Configuración de Google Workspace CLI para su agente de codificación de IAEl comando gws auth setup maneja la creación de proyectos, la habilitación de la API y el OAuth inicial en un flujo guiado. Ejecute:

gws auth setup

Abre su navegador, crea un proyecto de Google Cloud si es necesario, habilita las APIs requeridas y guarda las credenciales de forma segura en el llavero de su sistema operativo (cifrado con AES-256-GCM).

Dirigirse a un agente específico o instalar habilidadesDespués de la configuración, instale las habilidades de agente incluidas:

npx skills add https://github.com/googleworkspace/cli

O ejecute instaladores específicos para agentes (por ejemplo, para Claude Code o Cursor). Reinicie su agente para que descubra los comandos de Google Workspace CLI automáticamente.

Configuración a nivel de proyecto vs. globalPor defecto, la configuración se aplica globalmente. Para una configuración solo a nivel de proyecto:

gws auth setup --project

AutenticaciónVuelva a autenticarse o cambie de cuenta en cualquier momento:

gws auth login

Verifique el usuario actual y los ámbitos:

gws auth whoami

Cierre sesión cuando sea necesario:

gws auth logout

Para uso sin interfaz/CI, exporte credenciales:

gws auth export --unmasked > creds.json
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/creds.json

O reutilice los tokens de gcloud: export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token).

TelemetríaDesactive la recopilación anónima de uso:

export GOOGLE_WORKSPACE_CLI_NO_TELEMETRY=1

Uso de comandos principales en Google Workspace CLI (Drive, Gmail, Calendar, Sheets, Docs, Chat)Google Workspace CLI descubre comandos dinámicamente, no hay una lista fija. Ejecute gws --help para ver los servicios disponibles.

Archivos y carpetas de DriveListar archivos recientes:

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

Subir con ayuda:

gws drive +upload ./budget.xlsx --name "2026 Budget"

GmailEnviar correo electrónico:

gws gmail +send --to colleague@example.com --subject "Update" --body "See attached." --attach ./file.pdf

Responder o clasificar bandeja de entrada:

gws gmail +reply --message-id <ID> --body "Thanks!"
gws gmail +triage

CalendarCrear evento:

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

Mostrar agenda de hoy:

gws calendar +agenda --today

SheetsAñadir fila:

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

DocsInsertar texto:

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

ChatPublicar mensaje:

gws chat +send --space <SPACE_ID> --text "Deployment complete 🚀"

Use --dry-run en cualquier comando para previsualizar la llamada API exacta sin ejecutarla. Añada --page-all para una paginación completa como NDJSON.

Configuración avanzada y opciones globales en Google Workspace CLIPersista la configuración con variables de entorno o un archivo .env:

export GOOGLE_WORKSPACE_CLI_DEFAULT_PARAMS='{"prettyPrint":true}'

Ajuste los tiempos de espera, el formato de salida (--json, --yaml) o fuerce el uso de un llavero basado en archivos. Ver configuración:

gws config

Integración de Google Workspace CLI con agentes de IA y promptsUna vez instaladas las habilidades, los agentes llaman a Google Workspace CLI de forma nativa.

El patrón "usar gws"En los prompts: "Listar mis archivos recientes de Drive usando Google Workspace CLI" o "Enviar un correo electrónico de seguimiento a través de Google Workspace CLI".

Regla de invocación automáticaAñada a las instrucciones de su agente (por ejemplo, CLAUDE.md o reglas de Cursor):

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

Los agentes devuelven rutas de archivo o resultados JSON, manteniendo el contexto ligero.

Combínelo con Apidog para una confianza total en la APIGoogle Workspace CLI hace que las APIs de Workspace sean accesibles instantáneamente, pero al depurar payloads, ámbitos o respuestas, necesita visibilidad.

Apidog es un cliente API gratuito que le permite enviar solicitudes, inspeccionar respuestas sin procesar, configurar entornos con tokens OAuth y automatizar aserciones.

Flujos de trabajo reales:

• El agente sugiere añadir a una hoja → Pruebe primero el payload exacto de Sheets.values.append en Apidog.
• Solucione problemas de ámbitos de envío de Gmail → Construya y ejecute la solicitud visualmente.
• Almacene claves de cuentas de servicio o tokens de usuario como variables → Cambie de cuenta y valide el comportamiento.

Google Workspace CLI + Apidog ofrece acceso a datos en vivo más pruebas de API verificadas y repetibles.

Preguntas Frecuentes¿Google Workspace CLI envía mis datos externamente?Ninguna llamada va directamente a las APIs de Google. Su contenido nunca sale de su cuenta de Google.

¿Qué servicios soporta Google Workspace CLI?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?Google Workspace CLI consulta el Servicio de Descubrimiento en vivo; los nuevos métodos aparecen automáticamente.

¿Requiere una clave de API?Utiliza OAuth estándar de Google o cuentas de servicio; no se necesita una clave separada más allá de las credenciales de autenticación.

¿Qué agentes y editores soporta Google Workspace CLI?Claude Code, Cursor, OpenClaw, Gemini CLI, extensiones de VS Code—cualquier herramienta compatible con MCP o Agent Skills.

¿Cuál es la diferencia entre los comandos "raw" y los "helpers" con +?Raw = métodos exactos de Discovery (por ejemplo, drive.files.list). + helpers = atajos para tareas comunes (por ejemplo, +upload, +send).

¿Puedo usar Google Workspace CLI sin un agente de IA?Sí, es perfecto para scripts, automatización o uso diario de la terminal.

Recursos adicionales

• Repositorio de Google Workspace CLI en GitHub → https://github.com/googleworkspace/cli
• README completo y documentación → https://github.com/googleworkspace/cli/blob/main/README.md
• Carpeta de habilidades del agente → https://github.com/googleworkspace/cli/tree/main/skills
• Referencia de la API de Google Workspace → https://developers.google.com/workspace
• Panel de cuotas → https://console.cloud.google.com/apis/api
• Cliente API gratuito de Apidog → https://apidog.com