@googleworkspace/cli

Что такое googleworkspace-cli?

googleworkspace/cli (публикуется как @googleworkspace/cli) — это инструмент командной строки для Google Workspace. Он позволяет работать с несколькими API Workspace — такими как Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin и другими — с помощью единого CLI.

Интерфейс команд формируется динамически во время выполнения на основе Google’s Discovery Service, а не поставляется фиксированным списком команд. Проект также описывается как включающий «AI agent skills», а CLI акцентирует структурированный JSON-вывод для автоматизации.

Ключевые возможности

• Единый CLI для нескольких сервисов Workspace: Обеспечивает один интерфейс для взаимодействия с Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin и другими API Workspace.
• Динамическая генерация команд из Discovery Service: Команды и методы строятся путём чтения Discovery Service Google во время выполнения, поэтому новые конечные точки/методы доступны без статического списка команд.
• Структурированный JSON-вывод: Разработан для автоматизации и AI-агентов; ответы возвращаются в структурированном JSON.
• Интроспекция схем API-методов: Используйте gws schema <...> для просмотра схемы запроса/ответа метода.
• Симуляция запросов и помощники пагинации: Используйте --dry-run для предварительного просмотра запросов и --page-all для потоковой передачи пагинированных результатов (опционально в инструменты вроде jq).
• Различные рабочие процессы аутентификации: Поддерживает настройку/логин для локального использования, CI и серверов, включая интеграцию с gcloud при наличии.
• Встроенные навыки агентов: Документация репозитория отмечает, что включено «40+ agent skills».

Как использовать googleworkspace-cli

1. Установите CLI:
   • Через npm: npm install -g @googleworkspace/cli
   • Или с помощью готового бинарника из GitHub Releases
   • Или сборка из исходников: cargo install --git https://github.com/googleworkspace/cli --locked
   • (macOS/Linux также поддерживают Homebrew; доступен Nix flake.)
2. Аутентифицируйтесь (одноразовая настройка проекта, затем логин):
   • gws auth setup (требует установленного и аутентифицированного gcloud)
   • gws auth login (последующий OAuth-логин)
   • Для ручных токенов или консольных потоков документация описывает переменные окружения и ручную настройку OAuth.
3. Выполняйте команды для ресурса. Примеры из документации:
   • Список файлов: gws drive files list --params '{"pageSize": 5}'
   • Создать таблицу: gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'
   • Отправить сообщение в Chat: gws chat spaces messages create --params '{"parent": "spaces/xyz"}' --json '{"text": "Deploy complete."}'
   • Просмотр схемы: gws schema drive.files.list

Сценарии использования

• Автоматизация рабочих процессов Drive с пагинацией и JSON: Потоковая передача больших наборов результатов из конечных точек списка Drive и обработка с помощью downstream-инструментов (например, комбинация --page-all с jq).
• Отправка запросов Gmail/Chat/Calendar без сырых REST-вызовов: Используйте команды CLI, ориентированные на ресурсы, для создания или обновления объектов, полагаясь на сгенерированный интерфейс.
• Проверка структуры запроса перед выполнением: Используйте --dry-run для предварительного просмотра того, что отправит CLI, — полезно при генерации payload для Sheets, Chat и других ресурсов.
• Создание инструментов для AI-агентов вокруг API Workspace: Используйте структурированные JSON-ответы и включённые навыки агентов, чтобы LLM-агент мог выбирать действия Workspace с меньшим количеством custom-кода.
• Поиск способа вызова API-метода из CLI: Если известен метод, но не точная форма запроса, используйте gws schema <method> для просмотра схемы запроса/ответа.

FAQ

• Является ли googleworkspace-cli официальным продуктом Google? Нет. Репозиторий отмечает: «This is not an officially supported Google product.»

• Есть ли у него фиксированный список команд? Нет. Документация указывает, что статический список команд не поставляется; во время выполнения читается Google’s Discovery Service, и интерфейс команд строится динамически.

• Что нужно для установки и запуска? Для установки через npm требуются Node.js 18+. Аутентификация требует проекта Google Cloud для OAuth-учётных данных и учётной записи Google с доступом к Workspace.

• Какую настройку аутентификации выбрать? Документация описывает несколько путей:

  • Настройка с gcloud (gws auth setup), если gcloud установлен и аутентифицирован
  • Ручная OAuth-настройка через Google Cloud Console, если автоматизация невозможна
  • Токены/ручные учётные данные через переменные окружения (как описано)

• Есть ли ограничения по scopes при разработке/тестировании? Да. Документация предупреждает, что для не верифицированного OAuth-приложения (режим тестирования) Google ограничивает согласие ~25 scopes, и рекомендуемый пресет (85+ scopes) не сработает для не верифицированных приложений — особенно для @gmail.com-учёток.

Альтернативы

• Прямые REST API-вызовы с curl или HTTP-клиентом: Позволяют вызывать конечные точки Workspace напрямую, но вам придётся самостоятельно управлять форматированием запросов, пагинацией и деталями аутентификации.
• Официальные SDK для конкретных сервисов Workspace (например, библиотеки Google APIs для конкретных языков): Предоставляют типизированные методы клиента для отдельных сервисов, но обычно требуют отдельных путей кода для каждого API вместо единого динамически генерируемого CLI-интерфейса.
• Другие CLI-инструменты для Google APIs: Альтернативные CLI могут фокусироваться на конкретных сервисах или использовать статические наборы команд; в зависимости от инструмента, они могут не предлагать такую же динамическую генерацию команд на основе Discovery Service или рабочий процесс с структурированным JSON и интроспекцией схем, как описано здесь.