gws — единый CLI для всего Google Workspace

gws — консольная утилита с открытым кодом из организации googleworkspace на GitHub. Она закрывает работу со всеми сервисами Google Workspace: Drive, Gmail, Calendar, Sheets, Docs, Chat и десятки других API. Одна команда, нулевой boilerplate, структурированный JSON на выходе. Инструмент написан на Rust и распространяется под лицензией Apache-2.0. Формально это не официально поддерживаемый продукт Google, но репозиторий живёт в организации googleworkspace и развивается активно — авторы предупреждают, что до версии 1.0 возможны ломающие изменения.

Главная особенность gws в том, что он спроектирован сразу для двух аудиторий: людей и AI-агентов.

Зачем он нужен

Для человека gws заменяет ручные curl-запросы к REST API. У каждой команды есть --help, есть --dry-run для предпросмотра запроса без отправки, есть автоматическая пагинация.

Для AI-агента важнее другое: любой ответ CLI — это JSON. Агенту не нужны парсеры вывода и кастомные инструменты, достаточно умения запускать shell-команды. Плюс к репозиторию прилагается больше сотни скиллов в формате SKILL.md — по одному на каждый поддерживаемый API.

Несколько примеров:

# 10 последних файлов на Drive
gws drive files list --params '{"pageSize": 10}'

# Создать таблицу
gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'

# Посмотреть схему запроса и ответа любого метода
gws schema drive.files.list

# Пролистать все страницы и вывести результат как NDJSON
gws drive files list --params '{"pageSize": 100}' --page-all | jq -r '.files[].name'

Команды строятся динамически

В gws нет захардкоженного списка команд. При запуске утилита читает Discovery Service от Google и строит всё дерево команд прямо во время работы. Google Workspace добавил новый метод API — gws подхватит его автоматически, без обновления.

Технически это двухфазный разбор аргументов:

1. gws читает первый аргумент и определяет сервис: drive, gmail, calendar;
2. загружает Discovery-документ сервиса, он кэшируется на 24 часа;
3. строит дерево команд из ресурсов и методов документа;
4. разбирает остальные аргументы;
5. проходит аутентификацию, собирает HTTP-запрос и выполняет его.

Установка

Рекомендуемый способ — скачать готовый бинарник под свою ОС и архитектуру со страницы релизов и положить его в $PATH. Есть и пакетные менеджеры:

npm install -g @googleworkspace/cli
brew install googleworkspace-cli
cargo install --git https://github.com/googleworkspace/cli --locked
nix run github:googleworkspace/cli

Быстрый старт выглядит так:

gws auth setup     # настроит проект Google Cloud и включит нужные API
gws auth login     # обычный OAuth-вход
gws drive files list --params '{"pageSize": 5}'

Потребуются Node.js 18+ для установки через npm (либо готовый бинарник), проект Google Cloud и аккаунт Google с доступом к Workspace.

Аутентификация

gws поддерживает несколько сценариев входа — от ноутбука до CI-сервера:

• интерактивный вход: gws auth setup с автоматическим созданием проекта через gcloud или gws auth login для повторных входов;
• ручная настройка OAuth-клиента через Google Cloud Console, если автоматика не подходит;
• service account для серверных сценариев без участия человека;
• готовый access token, например от gcloud auth print-access-token;
• экспорт учётных данных для машин без браузера: gws auth export --unmasked.

Локальные учётные данные шифруются алгоритмом AES-256-GCM, ключ хранится в системном keyring. Приоритет источников такой: токен из GOOGLE_WORKSPACE_CLI_TOKEN, затем файл из GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE, затем зашифрованные данные после gws auth login и, наконец, открытый файл ~/.config/gws/credentials.json. Все переменные можно задать и через .env-файл, готовый шаблон лежит в .env.example.

Важный нюанс: неподтверждённые OAuth-приложения в testing mode ограничены примерно 25 scope. Пресет recommended содержит 85+ scope и упрётся в этот лимит. Выбирайте конкретные сервисы:

gws auth login -s drive,gmail,sheets

Скиллы для AI-агентов

В репозитории лежит больше сотни скиллов: по одному на каждый поддерживаемый API, высокоуровневые сценарии поверх них и 50 подобранных рецептов для Gmail, Drive, Docs, Calendar и Sheets. Полный список — в индексе скиллов.

Устанавливаются одной командой:

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

# или только нужные
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-drive
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-gmail

Для Gemini CLI есть отдельное расширение. Сначала выполните gws auth setup, затем gemini extensions install https://github.com/googleworkspace/cli. Агент получит доступ ко всем командам gws и скиллам, а учётные данные терминала унаследуются автоматически — передавать их агенту отдельно не нужно.

Хелперы с плюсом

Поверх автогенерируемого слоя Discovery в gws есть рукописные команды-помощники. Они начинаются с +, чтобы не пересекаться с методами API и сразу выделяться в выводе --help:

gws gmail +send --to alice@example.com --subject "Hello" --body "Hi there"
gws calendar +agenda --today
gws sheets +append --spreadsheet SPREADSHEET_ID --values "Alice,95"
gws drive +upload ./report.pdf --name "Q1 Report"
gws workflow +standup-report

Среди них есть готовые рабочие процессы: +standup-report собирает сегодняшние встречи и открытые задачи в сводку для стендапа, +meeting-prep готовит повестку, участников и документы к следующей встрече, +email-to-task превращает письмо в задачу Google Tasks, +weekly-digest делает недельную сводку встреч и непрочитанной почты. Состав команд зависит от сервиса: gws gmail --help покажет +send, +reply, +forward, +triage и другие.

Хелперы, привязанные ко времени, учитывают таймзону аккаунта Google. Она берётся из Calendar Settings API и кэшируется на сутки. Переопределить её можно флагом --timezone.

Защита от prompt injection

Письма и документы в Workspace могут содержать скрытые вредоносные инструкции. Если агент получит такое письмо, инструкция может сработать. gws умеет прогонять ответы API через Google Cloud Model Armor до того, как отдать их агенту:

gws gmail users messages get --params '...' \
  --sanitize "projects/P/locations/L/templates/T"

По умолчанию при обнаружении проблемы выводится предупреждение, это режим warn. Режим block блокирует выдачу целиком. Шаблон и режим настраиваются переменными GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE и GOOGLE_WORKSPACE_CLI_SANITIZE_MODE.

Скриптам понравятся коды выхода

gws возвращает структурные коды выхода, чтобы скрипты ветвились по типу ошибки без разбора текста ответа:

Итоги

gws — редкий случай, когда CLI от крупного вендора изначально спроектирован под AI-агентов: JSON-вывод, сотня скиллов, расширение для Gemini CLI, санитизация ответов от prompt injection. Если ваши агенты работают с Google Workspace, это самый короткий путь: не нужно писать обвязку над REST API и разбирать произвольный текстовый вывод. Людям тоже удобно, особенно с хелперами вроде +agenda и +standup-report. Учитывайте только, что проект ещё не добрался до версии 1.0 и может менять интерфейс команд.