@googleworkspace/cli

¿Qué es googleworkspace-cli?

googleworkspace/cli (publicado como @googleworkspace/cli) es una herramienta de línea de comandos para Google Workspace. Te permite trabajar con múltiples APIs de Workspace —como Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin y más— mediante una sola CLI.

La superficie de comandos se construye dinámicamente en tiempo de ejecución a partir del Discovery Service de Google, en lugar de incluir una lista fija de comandos. El proyecto también se describe como que incluye “habilidades para agentes de IA”, y la CLI enfatiza la salida en JSON estructurado para automatización.

Características principales

• Una sola CLI para múltiples servicios de Workspace: Proporciona una interfaz única para interactuar con Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin y otras APIs de Workspace.
• Generación dinámica de comandos desde Discovery Service: Los comandos y métodos se construyen leyendo el Discovery Service de Google en tiempo de ejecución, por lo que se pueden captar nuevos endpoints/métodos sin una lista estática de comandos.
• Salida en JSON estructurado: Diseñada para usarse con automatización y agentes de IA; las respuestas se devuelven en JSON estructurado.
• Introspección de esquemas para métodos de API: Usa gws schema <...> para inspeccionar el esquema de solicitud/respuesta de un método.
• Simulación de solicitudes y ayudantes de paginación: Usa --dry-run para previsualizar solicitudes y --page-all para transmitir resultados paginados (opcionalmente a herramientas como jq).
• Flujos de autenticación múltiples: Soporta flujos de configuración/inicio de sesión adecuados para uso local, CI y servidores, incluyendo integración con gcloud cuando está disponible.
• Habilidades de agente incluidas: La documentación del repositorio indica que incluye “más de 40 habilidades para agentes”.

Cómo usar googleworkspace-cli

1. Instala la CLI:
   • Vía npm: npm install -g @googleworkspace/cli
   • O usando un binario precompilado desde GitHub Releases
   • O compila desde el código fuente: cargo install --git https://github.com/googleworkspace/cli --locked
   • (macOS/Linux también mencionan Homebrew; hay un flake de Nix disponible.)
2. Autentícate (configuración única del proyecto, luego inicio de sesión):
   • gws auth setup (requiere gcloud instalado y autenticado)
   • gws auth login (inicio de sesión OAuth subsiguiente)
   • Para flujos basados en tokens manuales o de consola, la documentación lista variables de entorno y un camino de configuración OAuth manual.
3. Ejecuta comandos contra un recurso. Ejemplos de flujos de la documentación incluyen:
   • Listar archivos: gws drive files list --params '{"pageSize": 5}'
   • Crear una hoja de cálculo: gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'
   • Enviar un mensaje de Chat: gws chat spaces messages create --params '{"parent": "spaces/xyz"}' --json '{"text": "Deploy complete."}'
   • Introspeccionar esquema: gws schema drive.files.list

Casos de uso

• Automatiza flujos de Drive con paginación y JSON: Transmite conjuntos de resultados grandes de endpoints de lista de Drive y procésalos con herramientas downstream (p. ej., combinando la salida de --page-all con jq).
• Envía solicitudes de Gmail/Chat/Calendar sin escribir llamadas REST crudas: Usa los comandos centrados en recursos de la CLI para crear o actualizar objetos mientras confías en la interfaz generada.
• Valida la estructura de la solicitud antes de ejecutar: Usa --dry-run para previsualizar lo que enviaría la CLI, lo que ayuda al generar payloads para Sheets, Chat y otros recursos.
• Construye herramientas para agentes de IA alrededor de APIs de Workspace: Usa respuestas en JSON estructurado y las habilidades de agente incluidas para que un agente impulsado por LLM decida qué acciones de Workspace llamar con menos pegamento personalizado.
• Descubre cómo llamar a un método de API desde la CLI: Cuando sabes que un método existe pero no su forma exacta de solicitud, usa gws schema <method> para inspeccionar el esquema de solicitud/respuesta.

Preguntas frecuentes

• ¿Es googleworkspace-cli un producto oficial de Google? No. El repositorio indica: “Este no es un producto oficialmente soportado por Google”.

• ¿Tiene una lista fija de comandos? No. La documentación afirma que no incluye una lista estática de comandos; lee el Discovery Service de Google en tiempo de ejecución y construye su superficie de comandos dinámicamente.

• ¿Qué necesito instalar y ejecutar? La lista de requisitos incluye Node.js 18+ para el flujo de instalación vía npm. La autenticación requiere un proyecto de Google Cloud para credenciales OAuth y una cuenta de Google con acceso a Workspace.

• ¿Qué configuración de autenticación debo usar? La documentación describe múltiples opciones:

  • Configuración asistida por gcloud (gws auth setup) cuando tienes gcloud instalado y autenticado
  • Configuración OAuth manual vía Google Cloud Console cuando la automatización no es posible
  • Credenciales basadas en tokens/manuales vía variables de entorno (como se documenta)

• ¿Hay limitaciones relacionadas con scopes durante desarrollo/pruebas? Sí. La documentación advierte que si la app OAuth no está verificada (modo de prueba), Google limita el consentimiento a ~25 scopes y que el preset de scopes recomendado (85+ scopes) fallará para apps no verificadas —especialmente para cuentas @gmail.com.

Alternativas

• Llamadas directas a la API REST con curl o un cliente HTTP: Te permite llamar directamente a los endpoints de Workspace, pero debes gestionar tú mismo el formato de las solicitudes, la paginación y los detalles de autenticación.
• SDK oficiales para servicios específicos de Workspace (p. ej., bibliotecas de Google APIs específicas de un lenguaje): Proporcionan métodos de cliente tipados para servicios particulares, pero normalmente rutas de código separadas por API en lugar de una interfaz CLI dinámica generada.
• Otras herramientas CLI para APIs de Google: CLIs alternativas pueden centrarse en servicios específicos o usar conjuntos de comandos estáticos; según la herramienta, es posible que no ofrezcan la misma generación dinámica de comandos basada en el servicio de Discovery ni el flujo de trabajo de JSON estructurado + introspección de esquemas descrito aquí.