Developers, admins and agent builders who are comfortable in a terminal; you need to know basic OAuth and have a Google Cloud project, since setup involves creating credentials.

What can you build with cli?

Triage unread Gmail and send or reply to messages from a terminal or script. Export a Drive file list or Sheets range as JSON and process it with jq. Append rows to a spreadsheet from a CI job or cron task. Post a Chat message when a deploy finishes, previewing it first with --dry-run. Give an AI agent access to Calendar, Drive and Gmail through the included skills.

googleworkspace /

cli

One command-line tool for Drive, Gmail, Calendar, Sheets and other Workspace APIs

31.8k stars
566 stars since 3 Oct
Rust
Updated 16 days ago
Some experience
Automation & workflows

Open on GitHub (opens in a new tab) Website (opens in a new tab)

Google Workspace has many separate APIs, and calling them usually means reading REST docs and hand-writing curl requests or client code. gws puts them behind one command-line tool. Every resource has --help, and you can preview a request with --dry-run before it is sent.

It does not ship a fixed list of commands. At runtime it reads Google's Discovery Service and builds the commands from that, so new API methods show up without a new release. On top of that it adds hand-written helpers prefixed with +, such as gmail +send, calendar +agenda and workflow +standup-report.

Output is structured JSON, and paginated results can be streamed as NDJSON, so it pipes easily into jq or to an LLM. The repo also includes 100+ agent skills (SKILL.md files) and a Gemini CLI extension. The README says this is not an officially supported Google product and that breaking changes are expected before v1.0.

What it does

Commands built from Discovery
The command set is generated at runtime from Google's Discovery Service, so new Workspace API methods appear automatically. gws schema shows the request and response shape of any method.
Friendly for scripting
Responses are JSON, --page-all streams every page as NDJSON, and --dry-run previews a request. Multipart file uploads work through --upload.
Helper commands
Hand-written + commands cover common jobs: sending, replying to and triaging Gmail, appending to Sheets, uploading to Drive, and listing calendar events. Workflow helpers build a standup report, meeting prep or weekly digest.
Several ways to authenticate
Works with interactive OAuth login, an exported credentials file for headless machines and CI, a service account, or an existing access token. Stored credentials are encrypted with a key in the OS keyring.
Agent skills and Gemini extension
The repo includes 100+ agent skills, installable with npx skills add, plus a Gemini CLI extension that reuses your gws login.

What you could build

Triage unread Gmail and send or reply to messages from a terminal or script.
Export a Drive file list or Sheets range as JSON and process it with jq.
Append rows to a spreadsheet from a CI job or cron task.
Post a Chat message when a deploy finishes, previewing it first with --dry-run.
Give an AI agent access to Calendar, Drive and Gmail through the included skills.

Get started

Install the binary (npm, a release download, Homebrew or cargo all work), then run gws auth setup, which needs the gcloud CLI, to create a Cloud project and log in. Without gcloud, follow the manual OAuth setup and add yourself as a test user. After that, try a Drive list command.

npm install -g @googleworkspace/cli

gws auth setup

gws drive files list --params '{"pageSize": 5}'

Commands are copied from the project's README. Read it on GitHub for the full setup.