gws es una herramienta de línea de comandos de código abierto que unifica el acceso a Google Workspace: Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin y prácticamente todas las APIs del ecosistema. Fue diseñada tanto para personas como para agentes de IA, con salidas JSON estructuradas y más de 100 habilidades de agente incluidas. Su código está disponible públicamente en GitHub.

¿Qué es gws y por qué importa?

gws es la CLI de Google Workspace que elimina el boilerplate, es decir, el código repetitivo que normalmente exige trabajar con las APIs de Google. En lugar de escribir llamadas REST a mano, el usuario escribe comandos simples desde la terminal y recibe resultados listos para procesar. Lo interesante es que no se trata de un envoltorio limitado: la herramienta construye su superficie de comandos de forma dinámica leyendo el propio Discovery Service de Google en tiempo de ejecución.

Eso tiene una consecuencia práctica notable: cuando Google agrega un endpoint o método nuevo a su API, gws lo incorpora automáticamente, sin actualizar el programa. El proyecto está bajo desarrollo activo y sus responsables advierten que pueden presentarse cambios importantes antes de la versión 1.0. También aclara, de forma transparente, que no es un producto con soporte oficial de Google, sino una herramienta comunitaria publicada en el repositorio de Google Workspace en GitHub.

¿Cómo empezar a usar gws en cinco minutos?

Para quienes quieren probarla de inmediato, esta guía rápida condensa el recorrido mínimo documentado en el README oficial, desde la instalación hasta el primer resultado en pantalla:

1. Instala la herramienta. La vía más rápida con Node.js 18 o superior es ejecutar npm install -g @googleworkspace/cli; también puedes descargar el binario desde la página de releases, compilar con cargo o usar Homebrew en macOS y Linux.
2. Configura las credenciales. Con gcloud instalado, gws auth setup crea el proyecto de Google Cloud, habilita las APIs e inicia sesión en un solo paso; sin gcloud, usa la configuración OAuth manual en la consola de Google Cloud.
3. Inicia sesión. Ejecuta gws auth login y, si tu app está en modo de prueba, selecciona servicios individuales con gws auth login -s drive,gmail,sheets para evitar el límite de consentimiento de Google.
4. Haz tu primera consulta. Lista los archivos de Drive con gws drive files list –params ‘{“pageSize”: 5}’ y verifica que la respuesta llegue como JSON estructurado.
5. Explora los comandos auxiliares. Consulta tu agenda del día con gws +agenda o envía un correo desde la terminal con gws +send especificando destinatario, asunto y cuerpo.

Un consejo práctico que ahorra dolores de cabeza: antes de ejecutar cualquier operación que escriba datos, usa –dry-run para previsualizar la solicitud, y gws schema seguido del nombre del método para inspeccionar su esquema de petición y respuesta. Ambos comandos están documentados como la forma segura de aprender la superficie de la herramienta sin romper nada.

¿Cómo funciona la CLI de Google Workspace paso a paso?

El flujo básico se reduce a tres pasos. Primero, la configuración inicial con gws auth setup, que guía la creación del proyecto en Google Cloud y las credenciales OAuth. Segundo, el inicio de sesión con gws auth login. Tercero, la ejecución de comandos como gws drive files list para listar archivos o gws sheets spreadsheets create para crear una hoja de cálculo. Cada recurso incluye ayuda con –help, un modo –dry-run para previsualizar solicitudes y paginación automática de resultados.

Para instalarlo existen varias rutas oficiales: descargar el binario desde la página de releases del proyecto, ejecutar npm install -g @googleworkspace/cli con Node.js 18 o superior, compilar desde el código fuente con cargo, o usar gestores como Homebrew y Nix. Esta flexibilidad es valiosa porque, al provenir del propio repositorio del proyecto, cada canal se mantiene sincronizado con la misma versión estable.

Agentes de IA: la razón de ser de esta herramienta

El verdadero diferencial de gws está en su diseño para agentes de IA. Toda respuesta se entrega en JSON estructurado, el formato que los modelos de lenguaje procesan sin fricción. Así, un agente puede administrar un buzón de Gmail, crear eventos en Calendar o subir archivos a Drive sin integraciones personalizadas. El repositorio incluye más de 100 habilidades de agente listas para instalar (una por cada API soportada), además de 50 recetas curadas para Gmail, Drive, Docs, Calendar y Sheets.

La instalación es igualmente directa: npx skills add con la URL del repositorio agrega todas las habilidades de golpe, o solo las necesarias por servicio, como las de drive o gmail. Existe además una extensión oficial para Gemini CLI que da al agente acceso directo a todos los comandos y habilidades del proyecto, heredando las credenciales ya autenticadas en la terminal. Este enfoque conecta con la tendencia más amplia de la IA en Google Workspace frente a Copilot y ChatGPT, donde la clave ya no es solo responder, sino ejecutar tareas reales sobre las herramientas de trabajo.

¿Qué opciones de autenticación ofrece gws?

La autenticación es el punto donde más fallan los primeros intentos, así que conviene conocer las opciones documentadas antes de empezar:

En el escritorio local, las credenciales se cifran en reposo con AES-256-GCM y la llave se guarda en el llavero del sistema operativo. Para servidores sin navegador, el flujo de exportación permite autenticarse una vez y reutilizar las credenciales en la máquina remota. Vale la pena señalar que, en modo de prueba, Google limita el consentimiento a unos 25 scopes, mientras que el preset recomendado incluye más de 85; por eso conviene iniciar con servicios individuales, por ejemplo gws auth login -s drive,gmail,sheets.

¿Por qué usar una CLI en lugar de las apps de Workspace?

La pregunta es legítima: si Gmail y Drive ya funcionan bien, ¿para qué una terminal? La respuesta está en la automatización. Comandos auxiliares como gws +agenda consultan el calendario del día y gws +send envía un correo con destinatario, asunto y cuerpo definidos en la misma instrucción. Para equipos técnicos, la posibilidad de encadenar comandos con scripts y procesar salidas con jq convierte a la suite completa de Google en material manipulable desde una sola ventana.

La herramienta también incluye introspección de esquemas con gws schema, códigos de salida estructurados del 0 al 5 para manejo de errores y un flujo NDJSON para resultados paginados de gran volumen. En un contexto donde Google sigue incorporando voz e IA a sus aplicaciones, como ya analizamos en las nuevas funciones de voz en Google Workspace, la automatización por terminal no compite con la interfaz visual: la complementa para casos donde la escala y la repetición importan.

¿Qué limitaciones debe considerar antes de adoptarla?

Hay que ser honestos con las advertencias del propio proyecto. Al estar en desarrollo activo rumbo a la versión 1.0, pueden presentarse cambios que rompan flujos existentes. La configuración inicial requiere un proyecto de Google Cloud con credenciales OAuth y, si la app no está verificada, hay que agregarse a uno mismo como usuario de prueba para evitar errores genéricos de acceso bloqueado. Para quien ya trabaja con asistentes de terminal, esta herramienta encaja de forma natural junto a la automatización desde la terminal con Gemini CLI.

El paquete también está publicado en el registro oficial de npm como googleworkspace cli en npm, lo que facilita su instalación en flujos de desarrollo existentes. En conjunto, gws representa un ejemplo claro de hacia dónde va la productividad: interfaces unificadas, salidas legibles por máquinas y humanos trabajando con las mismas herramientas.