Google Workspace CLI — Command-Line Access to Drive, Gmail, Calendar and Sheets

Introduction

Google Workspace CLI (gws) is an official command-line tool that provides terminal access to Google Workspace services. It enables scripting, automation, and quick interactions with Drive, Gmail, Calendar, Sheets, and other Workspace products without opening a browser. The tool is designed for developers, sysadmins, and power users who prefer working from the command line.

What Google Workspace CLI Does

• Manages Google Drive files: upload, download, list, search, and share
• Sends, reads, and searches Gmail messages from the terminal
• Creates, lists, and manages Google Calendar events
• Reads, writes, and queries Google Sheets data programmatically
• Supports scripting and piping for workflow automation

Architecture Overview

The CLI is a compiled binary that communicates with Google Workspace APIs using OAuth 2.0 authentication. It stores credentials locally after the initial browser-based login flow. Each subcommand maps to a specific Workspace API endpoint, handling pagination, retries, and rate limiting transparently. Output formats include JSON, table, and CSV for easy integration with other command-line tools.

Self-Hosting & Configuration

• Install the binary via Homebrew, apt, or direct download from GitHub releases
• Run gws auth login to complete OAuth authentication in a browser
• Set GWS_DEFAULT_ACCOUNT to switch between multiple Google accounts
• Configure output format globally with gws config set output json
• Use --project flag to scope operations to a specific Google Cloud project

Key Features

• Unified CLI for Drive, Gmail, Calendar, Sheets, and other Workspace services
• JSON, table, and CSV output formats for scripting and data pipelines
• Batch operations for uploading or downloading multiple files at once
• Tab completion for Bash, Zsh, Fish, and PowerShell
• Cross-platform support for macOS, Linux, and Windows

Comparison with Similar Tools

• gdrive — community CLI for Google Drive only; gws covers the full Workspace suite
• rclone — multi-cloud file sync; gws provides deeper Workspace-specific features like Gmail and Calendar
• Google Cloud CLI (gcloud) — targets Google Cloud Platform infrastructure; gws targets Workspace productivity apps
• GAM — admin-focused Google Workspace CLI; gws targets end-user productivity workflows
• mutt/neomutt — terminal mail clients; gws provides native Gmail API integration with labels and threads

FAQ

Q: Does it work with personal Gmail accounts? A: Yes. It supports both personal Google accounts and Google Workspace organizational accounts.

Q: Can I use it in CI/CD pipelines? A: Yes. Service account authentication is supported for headless environments.

Q: Is my data stored locally? A: Only OAuth tokens are stored locally. All data operations go directly through Google's APIs.

Q: Can I pipe output to other commands? A: Yes. Use --output json to produce structured output suitable for jq, awk, or other CLI tools.

Sources

• https://github.com/googleworkspace/cli
• https://developers.google.com/workspace