googleworkspace/cli

What is it?

Key features

• 01Dynamically builds commands from Google's Discovery Service, so new API methods appear automatically.
• 02Outputs structured JSON for every response, including errors.
• 03Supports --dry-run to preview requests and --page-all for NDJSON pagination.
• 04Ships 100+ Agent Skills and a Gemini CLI extension for AI agent use.
• 05Offers multiple auth paths: interactive OAuth, service accounts, access tokens, and exported credentials for CI.

Use cases

• Scripting routine Drive, Sheets, or Gmail operations from a terminal or CI job.
• Letting an AI agent read calendars, send emails, or update spreadsheets through structured commands.
• Automating Google Chat notifications, such as posting a message after a deploy.
• Piping Workspace data into jq or other shell tools for reporting.

Quick start

1. 1

   Install the CLI via npm

   npm install -g @googleworkspace/cli
2. 2

   Set up Google Cloud project and OAuth credentials

   gws auth setup
3. 3

   Log in with OAuth (subsequent logins)

   gws auth login
4. 4

   List your five most recent Drive files

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

Things to know

• !This is not an officially supported Google product.
• !The project is under active development and may have breaking changes before v1.0.
• !Unverified apps in testing mode are limited to about 25 scopes, so the full recommended scope preset will fail.
• !You must add your own Google account as a test user, or login fails with an access blocked error.

Topics

FAQ

What is cli?

A command-line tool that gives one interface to Google Workspace APIs like Drive, Gmail, Calendar, Sheets, Docs, and Chat, with JSON output for scripts and AI agents. gws is a command-line client for Google Workspace. Instead of hand-writing curl calls against REST endpoints, you run commands such as gws drive files list or gws sheets spreadsheets create. The command set is built at runtime from Google's Discovery Service, so newly added API methods become available without a tool update. Every resource has --help, --dry-run previews a request before it is sent, and --page-all streams paginated results as NDJSON.

Is cli free to use? What license does it have?

cli is open source under the Apache-2.0 license. Check the license terms before using it in commercial products.

Is cli still maintained?

Actively maintained. The last commit to cli was on Oct 6, 2026.

What can I use cli for?

Scripting routine Drive, Sheets, or Gmail operations from a terminal or CI job. Letting an AI agent read calendars, send emails, or update spreadsheets through structured commands. Automating Google Chat notifications, such as posting a message after a deploy. Piping Workspace data into jq or other shell tools for reporting.

How do I install cli?

Install the CLI via npm: npm install -g @googleworkspace/cli Set up Google Cloud project and OAuth credentials: gws auth setup Log in with OAuth (subsequent logins): gws auth login List your five most recent Drive files: gws drive files list --params '{"pageSize": 5}'

Where can I get cli?

The source code and installation instructions are on GitHub: https://github.com/googleworkspace/cli