{"repo":"googleworkspace/cli","free":true,"listed":false,"github":"https://github.com/googleworkspace/cli","clone":"git clone https://github.com/googleworkspace/cli.git","description":"Google Workspace CLI — one command-line tool for Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and more. Dynamically built from Google Discovery Service. Includes AI agent skills.","language":"Rust","stars":30408,"topics":["agent-skills","ai-agent","automation","cli","discovery-api","gemini-cli-extension","google-admin","google-api","google-calendar","google-chat","google-docs","google-drive","google-sheets","google-workspace","oauth2","rust"],"license":"Apache-2.0","category":"dev_tool","readme_excerpt":"<h1 align=\"center\">gws</h1>\n\n**One CLI for all of Google Workspace — built for humans and AI agents.**<br>\nDrive, Gmail, Calendar, and every Workspace API. Zero boilerplate. Structured JSON output. 40+ agent skills included.\n\n> [!NOTE]\n> This is **not** an officially supported Google product.\n\n<p>\n  <a href=\"https://www.npmjs.com/package/@googleworkspace/cli\"><img src=\"https://img.shields.io/npm/v/@googleworkspace/cli\" alt=\"npm version\"></a>\n  <a href=\"https://github.com/googleworkspace/cli/blob/main/LICENSE\"><img src=\"https://img.shields.io/github/license/googleworkspace/cli\" alt=\"license\"></a>\n  <a href=\"https://github.com/googleworkspace/cli/actions/workflows/ci.yml\"><img src=\"https://img.shields.io/github/actions/workflow/status/googleworkspace/cli/ci.yml?branch=main&label=CI\" alt=\"CI status\"></a>\n  <a href=\"https://www.npmjs.com/package/@googleworkspace/cli\"><img src=\"https://img.shields.io/npm/unpacked-size/@googleworkspace/cli\" alt=\"install size\"></a>\n</p>\n<br>\n\n⬇️ **[Download the latest release for your OS](https://github.com/googleworkspace/cli/releases)**\n\n`gws` doesn't ship a static list of commands. It reads Google's own [Discovery Service](https://developers.google.com/discovery) at runtime and builds its entire command surface dynamically. When Google Workspace adds an API endpoint or method, `gws` picks it up automatically.\n\n> [!IMPORTANT]\n> This project is under active development. Expect breaking changes as we march toward v1.0.\n\n## Contents\n\n- [Prerequisites](#prerequisites)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Why gws?](#why-gws)\n- [Authentication](#authentication)\n- [AI Agent Skills](#ai-agent-skills)\n- [Advanced Usage](#advanced-usage)\n- [Environment Variables](#environment-variables)\n- [Exit Codes](#exit-codes)\n- [Architecture](#architecture)\n- [Troubleshooting](#troubleshooting)\n- [Development](#development)\n\n## Prerequisites\n\n- **Node.js 18+** — for `npm install` (or download a pre-built binary from [GitHub Releases](https://github.com/googleworkspace/cli/releases))\n- **A Google Cloud project** — required for OAuth credentials. You can create one via the [Google Cloud Console](https://console.cloud.google.com/) or with the [`gcloud` CLI](https://cloud.google.com/sdk/docs/install) or with the `gws auth setup` command.\n- **A Google account** with access to Google Workspace\n\n## Installation\n\nThe recommended way to install `gws` is to download the pre-built binary for your OS and architecture from the **[GitHub Releases](https://github.com/googleworkspace/cli/releases)** page. Extract the archive and place the `gws` binary in your `$PATH`.\n\nFor convenience, you can also use `npm` to automate downloading the appropriate binary from GitHub Releases:\n\n```bash\nnpm install -g @googleworkspace/cli\n```\n\nOr build from source:\n\n```bash\ncargo install --git https://github.com/googleworkspace/cli --locked\n```\n\nA Nix flake is also available at `github:googleworkspace/cli`\n\n```bash\nnix run github:googleworkspace/cli\n```\n\nOn macOS and Linux, you can also install via [Homebrew](https://brew.sh/):\n\n```bash\nbrew install googleworkspace-cli\n```\n\n## Quick Start\n\n```bash\ngws auth setup     # walks you through Google Cloud project config\ngws auth login     # subsequent OAuth login\ngws drive files list --params '{\"pageSize\": 5}'\n```\n\n## Why gws?\n\n**For humans** — stop writing `curl` calls against REST docs. `gws` gives you `--help` on every resource, `--dry-run` to preview requests, and auto‑pagination.\n\n**For AI agents** — every response is structured JSON. Pair it with the included agent skills and your LLM can manage Workspace without custom tooling.\n\n```bash\n# List the 10 most recent files\ngws drive files list --params '{\"pageSize\": 10}'\n\n# Create a spreadsheet\ngws sheets spreadsheets create --json '{\"properties\": {\"title\": \"Q1 Budget\"}}'\n\n# Send a Chat message\ngws chat spaces messages create \\\n  --params '{\"parent\": \"spaces/xyz\"}' \\\n  --json '{\"text\": \"Deploy complete.\"}' \\\n  --dry-run\n\n# Introspect any method's request/response schema\ngws schema drive.files.list\n\n# Stream paginated results as NDJSON\ngws drive files list --params '{\"pageSize\": 100}' --page-all | jq -r '.files[].name'\n```\n\n## Authentication\n\nThe CLI supports multiple auth workflows so it works on your laptop, in CI, and on a server.\n\n### Which setup should I use?\n\n| I have… | Use |\n|---|---|\n| `gcloud` installed and authenticated | [`gws auth setup`](#interactive-local-desktop) (fastest) |\n| A GCP project but no `gcloud` | [Manual OAuth setup](#manual-oauth-setup-google-cloud-console) |\n| An existing OAuth access token | [`GOOGLE_WORKSPACE_CLI_TOKEN`](#pre-obtained-access-token) |\n| Existing Credentials | [`GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE`](#service-account-server-to-server) |\n\n### Interactive (local desktop)\n\nCredentials are encrypted at rest (AES-256-GCM) with the key stored in your OS keyring (or `~/.config/gws/.encryption_key` when `GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file`).\n\n```bash\ngws auth setup       # one-time: creates a Cloud project, enables APIs, logs you in\ngws auth login       # subsequent scope selection and login\n```\n\n> `gws auth setup` requires the [`gcloud` CLI](https://cloud.google.com/sdk/docs/install). If you don't have `gcloud`, use the [manual setup](#manual-oauth-setup-google-cloud-console) below instead.\n\n> [!WARNING]\n> **Scope limits in testing mode:** If your OAuth app is unverified (testing mode),\n> Google limits consent to ~25 scopes. The `recommended` scope preset includes 85+\n> scopes and **will fail** for unverified apps (especially for `@gmail.com` accounts).\n> Choose individual services instead to filter the scope picker:\n> ```bash\n> gws auth login -s drive,gmail,sheets\n> ```\n\n\n### Manual OAuth setup (Google Cloud Console)\n\nUse this when `gws auth setup` cannot automate project/client creation, or when you want explicit control.\n\n1. Open Google Cloud Console in the target project:\n   - OAuth consent screen: `https://console.cloud.google.com/apis/credentials/consent?project=<PROJECT_ID>`\n   - Credentials: `https://console.cloud.google.com/apis/credentials?project=<PROJECT_ID>`\n2. Configure OAuth branding/audience if prompted:\n   - App type: **External** (testing mode is fine)\n3. Add your account under **Test users**\n4. Create an OAuth client:\n   - Type: **Desktop app**\n5. Download the client JSON and save it to:\n   - `~/.config/gws/client_secret.json`\n\n> [!IMPORTANT]\n> **You must add yourself as a test user.** In the OAuth consent screen, click\n> **Test users → Add users** and enter your Google account email. Without this,\n> login will fail with a generic \"Access blocked\" error.\n\nThen run:\n\n```bash\ngws auth login\n```\n\n### Browser-assisted auth (human or agent)\n\nYou can complete OAuth either manually or with browser automation.\n\n- **Human flow**: run `gws auth login`, open the printed URL, approve scopes.\n- **Agent-assisted flow**: the agent opens the URL, selects account, handles consent prompts, and returns control once the localhost callback succeeds.\n\nIf consent shows **\"Google hasn't verified this app\"** (testing mode), click **Continue**.\nIf scope checkboxes appear, select required scopes (or **Select all**) before continuing.\n\n### Headless / CI (export flow)\n\n1. Complete interactive auth on a machine with a browser.\n2. Export credentials:\n   ```bash\n   gws auth export --unmasked > credentials.json\n   ```\n3. On the headless machine:\n   ```bash\n   export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json\n   gws drive files list   # just works\n   ```\n\n### Service Account (server-to-server)\n\nPoint to your key file; no login needed.\n\n```bash\nexport GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/service-account.json\ngws drive files list\n```\n\n### Pre-obtained Access Token\n\nUseful when another tool (e.g. `gcloud`) already mints tokens for your environment.\n\n```bash\nexport GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token)\n```\n\n### Precedence\n\n| Priority | Source                 | Set via                                 |\n| -------- | ---------------------- | --------------------------------------- |\n| 1        | Access token           | `GOOGLE_WORKSPACE_CLI_TOKEN`            |\n| 2        | Credentials file       | `GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE` |\n| 3        | Encrypted credentials  | `gws auth login`                        |\n| 4        | Plaintext credentials  | `~/.config/gws/credentials.json`        |\n\nEnvironment variables can also live in a `.env` file.\n\n## AI Agent Skills\n\nThe repo ships 100+ Agent Skills (`SKILL.md` files) — one for every supported API, plus higher-level helpers for common workflows and 50 curated recipes for Gmail, Drive, Docs, Calendar, and Sheets. See the full [Skills Index](docs/skills.md) for the complete list.\n\n```bash\n# Install all skills at once\nnpx skills add https://github.com/googleworkspace/cli\n\n# Or pick only what you need\nnpx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-drive\nnpx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-gmail\n```\n\n<details>\n<summary>OpenClaw setup</summary>\n\n```bash\n# Symlink all skills (stays in sync with repo)\nln -s $(pwd)/skills/gws-* ~/.openclaw/skills/\n\n# Or copy specific skills\ncp -r skills/gws-drive skills/gws-gmail ~/.openclaw/skills/\n```\n\nThe `gws-shared` skill includes an `install` block so OpenClaw auto-installs the CLI via `npm` if `gws` isn't on PATH.\n\n</details>\n\n## Gemini CLI Extension\n\n1. Authenticate the CLI first:\n\n   ```bash\n   gws auth setup\n   ```\n\n2. Install the extension into the Gemini CLI:\n   ```bash\n   gemini extensions install https://github.com/googleworkspace/cli\n   ```\n\nInstalling this extension gives your Gemini CLI agent direct access to all `gws` commands and Google Workspace agent skills. Because `gws` handles its own authentication securely, you simply need to authenticate your terminal once prior to using the agent, and the extension will automatically inherit your credentials.\n\n## Advanced Usage\n\n##","default_branch":"main","files":222,"tree":[".agent/skills/vhs.md",".agent/workflows/verify-skills.md",".changeset/README.md",".changeset/config.json",".changeset/sheets-append-range.md",".claude/settings.json",".env.example",".gemini/config.yaml",".gemini/style_guide.md",".github/CODEOWNERS",".github/PULL_REQUEST_TEMPLATE.md",".github/labeler.yml",".github/workflows/audit.yml",".github/workflows/automation.yml",".github/workflows/ci.yml",".github/workflows/cla.yml",".github/workflows/coverage.yml",".github/workflows/generate-skills.yml",".github/workflows/policy.yml",".github/workflows/publish-skills.yml",".github/workflows/release-changesets.yml",".github/workflows/release.yml",".github/workflows/stale.yml",".gitignore",".vscode/extensions.json","AGENTS.md","CHANGELOG.md","CLAUDE.md","CONTEXT.md","Cargo.lock","Cargo.toml","LICENSE","README.md","SECURITY.md","art/features.txt","art/intro.txt","art/outro.txt","art/qr.txt","art/scene1.txt","art/scene2.txt","art/scene2b.txt","art/scene3.txt","art/scene3b.txt","art/scene4.txt","art/scene5.txt","art/scene6.txt","art/scene7.txt","art/scene8.txt","art/scene9.txt","crates/google-workspace-cli/Cargo.toml","crates/google-workspace-cli/README.md","crates/google-workspace-cli/registry/personas.toml","crates/google-workspace-cli/registry/recipes.toml","crates/google-workspace-cli/src/auth.rs","crates/google-workspace-cli/src/auth_commands.rs","crates/google-workspace-cli/src/client.rs","crates/google-workspace-cli/src/commands.rs","crates/google-workspace-cli/src/credential_store.rs","crates/google-workspace-cli/src/discovery.rs","crates/google-workspace-cli/src/error.rs","crates/google-workspace-cli/src/executor.rs","crates/google-workspace-cli/src/formatter.rs","crates/google-workspace-cli/src/fs_util.rs","crates/google-workspace-cli/src/generate_skills.rs","crates/google-workspace-cli/src/helpers/README.md","crates/google-workspace-cli/src/helpers/calendar.rs","crates/google-workspace-cli/src/helpers/chat.rs","crates/google-workspace-cli/src/helpers/docs.rs","crates/google-workspace-cli/src/helpers/drive.rs","crates/google-workspace-cli/src/helpers/events/mod.rs","crates/google-workspace-cli/src/helpers/events/renew.rs","crates/google-workspace-cli/src/helpers/events/subscribe.rs","crates/google-workspace-cli/src/helpers/gmail/forward.rs","crates/google-workspace-cli/src/helpers/gmail/mod.rs","crates/google-workspace-cli/src/helpers/gmail/read.rs","crates/google-workspace-cli/src/helpers/gmail/reply.rs","crates/google-workspace-cli/src/helpers/gmail/send.rs","crates/google-workspace-cli/src/helpers/gmail/triage.rs","crates/google-workspace-cli/src/helpers/gmail/watch.rs","crates/google-workspace-cli/src/helpers/mod.rs","crates/google-workspace-cli/src/helpers/modelarmor.rs","crates/google-workspace-cli/src/helpers/script.rs","crates/google-workspace-cli/src/helpers/sheets.rs","crates/google-workspace-cli/src/helpers/workflows.rs","crates/google-workspace-cli/src/logging.rs","crates/google-workspace-cli/src/main.rs","crates/google-workspace-cli/src/oauth_config.rs","crates/google-workspace-cli/src/output.rs","crates/google-workspace-cli/src/schema.rs","crates/google-workspace-cli/src/services.rs","crates/google-workspace-cli/src/setup.rs","crates/google-workspace-cli/src/setup_tui.rs","crates/google-workspace-cli/src/text.rs","crates/google-workspace-cli/src/timezone.rs","crates/google-workspace-cli/src/token_storage.rs","crates/google-workspace-cli/src/validate.rs","crates/google-workspace-cli/templates/modelarmor/jailbreak.json","crates/google-workspace/Cargo.toml","crates/google-workspace/README.md","crates/google-workspace/src/client.rs","crates/google-workspace/src/discovery.rs","crates/google-workspace/src/error.rs","crates/google-workspace/src/lib.rs","crates/google-workspace/src/services.rs","crates/google-workspace/src/validate.rs","demo.gif","deny.toml","docs/CODE_OF_CONDUCT.md","docs/CONTRIBUTING.md","docs/demo.tape","docs/logo.jpg","docs/skills.md","flake.lock","flake.nix","gemini-extension.json","lefthook.yml","npm/.gitignore","npm/install.js","npm/package.json","npm/platform.js","npm/run.js","package.json","pnpm-lock.yaml","scripts/coverage.sh","scripts/show-art.sh","scripts/tag-release.sh","scripts/version-sync.sh","skills/gws-admin-reports/SKILL.md","skills/gws-calendar-agenda/SKILL.md","skills/gws-calendar-insert/SKILL.md","skills/gws-calendar/SKILL.md","skills/gws-chat-send/SKILL.md","skills/gws-chat/SKILL.md","skills/gws-classroom/SKILL.md","skills/gws-docs-write/SKILL.md","skills/gws-docs/SKILL.md","skills/gws-drive-upload/SKILL.md","skills/gws-drive/SKILL.md","skills/gws-events-renew/SKILL.md","skills/gws-events-subscribe/SKILL.md","skills/gws-events/SKILL.md","skills/gws-forms/SKILL.md","skills/gws-gmail-forward/SKILL.md","skills/gws-gmail-read/SKILL.md","skills/gws-gmail-reply-all/SKILL.md","skills/gws-gmail-reply/SKILL.md","skills/gws-gmail-send/SKILL.md","skills/gws-gmail-triage/SKILL.md","skills/gws-gmail-watch/SKILL.md","skills/gws-gmail/SKILL.md","skills/gws-keep/SKILL.md","skills/gws-meet/SKILL.md","skills/gws-modelarmor-create-template/SKILL.md","skills/gws-modelarmor-sanitize-prompt/SKILL.md","skills/gws-modelarmor-sanitize-response/SKILL.md","skills/gws-modelarmor/SKILL.md","skills/gws-people/SKILL.md","skills/gws-script-push/SKILL.md","skills/gws-script/SKILL.md","skills/gws-shared/SKILL.md","skills/gws-sheets-append/SKILL.md","skills/gws-sheets-read/SKILL.md","skills/gws-sheets/SKILL.md","skills/gws-slides/SKILL.md","skills/gws-tasks/SKILL.md","skills/gws-workflow-email-to-task/SKILL.md","skills/gws-workflow-file-announce/SKILL.md","skills/gws-workflow-meeting-prep/SKILL.md","skills/gws-workflow-standup-report/SKILL.md","skills/gws-workflow-weekly-digest/SKILL.md","skills/gws-workflow/SKILL.md","skills/persona-content-creator/SKILL.md","skills/persona-customer-support/SKILL.md","skills/persona-event-coordinator/SKILL.md","skills/persona-exec-assistant/SKILL.md","skills/persona-hr-coordinator/SKILL.md","skills/persona-it-admin/SKILL.md","skills/persona-project-manager/SKILL.md","skills/persona-researcher/SKILL.md","skills/persona-sales-ops/SKILL.md","skills/persona-team-lead/SKILL.md","skills/recipe-backup-sheet-as-csv/SKILL.md","skills/recipe-batch-invite-to-event/SKILL.md","skills/recipe-block-focus-time/SKILL.md","skills/recipe-bulk-download-folder/SKILL.md","skills/recipe-collect-form-responses/SKILL.md","skills/recipe-compare-sheet-tabs/SKILL.md","skills/recipe-copy-sheet-for-new-month/SKILL.md","skills/recipe-create-classroom-course/SKILL.md","skills/recipe-create-doc-from-template/SKILL.md","skills/recipe-create-events-from-sheet/SKILL.md","skills/recipe-create-expense-tracker/SKILL.md","skills/recipe-create-feedback-form/SKILL.md","skills/recipe-create-gmail-filter/SKILL.md","skills/recipe-create-meet-space/SKILL.md","skills/recipe-create-presentation/SKILL.md","skills/recipe-create-shared-drive/SKILL.md","skills/recipe-create-task-list/SKILL.md","skills/recipe-create-vacation-responder/SKILL.md","skills/recipe-draft-email-from-doc/SKILL.md","skills/recipe-email-drive-link/SKILL.md","skills/recipe-find-free-time/SKILL.md","skills/recipe-find-large-files/SKILL.md","skills/recipe-forward-labeled-emails/SKILL.md","skills/recipe-generate-report-from-sheet/SKILL.md","skills/recipe-label-and-archive-emails/SKILL.md","skills/recipe-log-deal-update/SKILL.md","skills/recipe-organize-drive-folder/SKILL.md","skills/recipe-plan-weekly-schedule/SKILL.md","skills/recipe-post-mortem-setup/SKILL.md","skills/recipe-reschedule-meeting/SKILL.md","skills/recipe-review-meet-participants/SKILL.md","skills/recipe-review-overdue-tasks/SKILL.md","skills/recipe-save-email-attachments/SKILL.md","skills/recipe-save-email-to-doc/SKILL.md","skills/recipe-schedule-recurring-event/SKILL.md","skills/recipe-send-team-announcement/SKILL.md","skills/recipe-share-doc-and-notify/SKILL.md","skills/recipe-share-event-materials/SKILL.md","skills/recipe-share-folder-with-team/SKILL.md","skills/recipe-sync-contacts-to-sheet/SKILL.md","skills/recipe-watch-drive-changes/SKILL.md"],"storefront":"/r/googleworkspace","claimed":false,"request_supported":{"post":"https://gitbuyer.com/r/googleworkspace/cli/request-supported","requests":0},"note":"indexed from public GitHub; nothing is for sale on this page. Clone it from GitHub. Paid listings live at /search."}