Google Workspace CLI

Google Workspace CLI (gws): Полное руководство по мощному инструменту автоматизации

Google Workspace CLI, известный как gws, представляет собой единый интерфейс командной строки для всех сервисов Google Workspace. Этот инструмент разработан специально для людей и AI-агентов, обеспечивая бесшовное взаимодействие с Google Drive, Gmail, Calendar и всеми доступными API Workspace без необходимости написания сложного шаблонного кода.

Что такое Google Workspace CLI (gws)?

Google Workspace CLI (gws) — это не просто статичный набор команд. Инструмент динамически считывает собственную службу Discovery Service от Google во время выполнения и на её основе строит всю поверхность команд. Это означает, что как только Google добавляет новую конечную точку или метод API, Google Workspace CLI автоматически подхватывает изменения.

Продукт ориентирован на две основные группы пользователей:

1. Для людей: Избавляет от необходимости вручную составлять curl-запросы к документации REST. gws предоставляет встроенную справку --help для каждого ресурса и флаг --dry-run для предварительного просмотра запросов.
2. Для AI-агентов: Каждый ответ представлен в формате структурированного JSON. В сочетании с 40+ встроенными навыками агентов (agent skills), ваш LLM может управлять Workspace без создания специальных инструментов.

Примечание: Данный проект находится в активной разработке и не является официально поддерживаемым продуктом Google.

Основные характеристики и возможности

Google Workspace CLI обладает впечатляющим набором функций для профессиональной работы:

• Динамическая генерация команд: Автоматическое обновление при изменении Google API.
• Структурированный вывод: Ответы в формате JSON и поддержка потоковой передачи NDJSON.
• Автоматическая пагинация: Удобная работа с большими списками данных через флаг --page-all.
• Безопасное хранение учетных данных: Шифрование AES-256-GCM с использованием системного связки ключей (OS keyring).
• Поддержка AI-агентов: Интеграция с Gemini CLI и наличие готовых навыков (Skills).
• Расширенные возможности загрузки: Поддержка многокомпонентной загрузки файлов (Multipart Uploads).
• Model Armor: Интеграция для санитарной обработки промптов и ответов на предмет инъекций.

Вспомогательные команды (Helpers)

Помимо стандартных методов API, Google Workspace CLI предлагает «хендмейд» помощники, начинающиеся с префикса +:

• +send, +reply, +forward для Gmail.
• +agenda для просмотра событий календаря с учетом часового пояса.
• +upload для быстрой загрузки файлов в Drive.
• +standup-report для генерации сводки по встречам и задачам.

Как использовать Google Workspace CLI

Требования

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

Установка

Вы можете установить Google Workspace CLI несколькими способами:

1. Через npm: npm install -g @googleworkspace/cli
2. Через Homebrew (macOS/Linux): brew install googleworkspace-cli
3. Из исходников (Rust): cargo install --git https://github.com/googleworkspace/cli --locked

Начало работы и аутентификация

Для начала работы выполните настройку:

1. gws auth setup — пошаговая настройка проекта Google Cloud (требуется gcloud CLI).
2. gws auth login — вход через OAuth. Если приложение не верифицировано, добавьте свой email в список «Test users» в консоли Google Cloud.

Примеры команд:

• Список последних 10 файлов в Drive: gws drive files list --params '{"pageSize": 10}'
• Создание таблицы в Sheets: gws sheets spreadsheets create --json '{"properties": {"title": "Бюджет Q1"}}'

Кейсы использования (Use Cases)

1. Автоматизация отчетности

Используйте команду gws sheets +append, чтобы автоматически добавлять данные из логов или CI/CD систем прямо в таблицы Google Sheets без написания скриптов на Python или JavaScript.

2. Управление электронной почтой для команд

С помощью gws gmail +triage можно быстро просматривать сводку входящих сообщений, а через +reply — автоматизировать ответы на стандартные запросы, сохраняя структуру цепочки писем.

3. Подготовка к рабочему дню

Команда gws workflow +standup-report собирает информацию о ваших встречах и открытых задачах, формируя готовый отчет для утреннего собрания.

4. Интеграция с AI-агентами

Установите расширение для Gemini CLI (gemini extensions install), чтобы дать вашему AI-помощнику прямой доступ к управлению календарем, почтой и документами через команды Google Workspace CLI.

Часто задаваемые вопросы (FAQ)

В: Почему я получаю ошибку "Access blocked" или 403 при входе? О: Если ваше OAuth-приложение находится в режиме тестирования, вы должны явно добавить свой адрес электронной почты в список "Test users" в консоли Google Cloud (раздел OAuth consent screen).

В: Нужно ли мне устанавливать Rust для использования CLI? О: Нет, при установке через npm загружаются предварительно скомпилированные бинарные файлы для вашей ОС.

В: Как работать с Google Sheets, если Bash интерпретирует восклицательный знак? О: Диапазоны в Sheets (например, Sheet1!A1) содержат !. Всегда заключайте такие значения в одинарные кавычки, чтобы избежать проблем с историей команд в терминале.

В: Поддерживает ли инструмент сервисные аккаунты? О: Да, вы можете использовать переменную окружения GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE, указав путь к JSON-файлу сервисного аккаунта для работы в режиме сервер-сервер.

В: Как обновить список доступных команд? О: gws делает это автоматически, опрашивая Discovery API. Кэш обновляется каждые 24 часа.