cli

Abstract

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.

The Problem

Developers and automation agents that need to interact with many Google Workspace services must write repetitive HTTP calls, maintain separate auth flows, and keep client libraries in sync with Google’s ever‑changing API surface.

What This Does

The gws CLI reads Google’s Discovery Service at runtime and builds a full command hierarchy for Drive, Gmail, Calendar, Docs, Sheets, Chat, Admin, etc. Core logic lives in src/ – e.g., src/auth.rs and src/auth_commands.rs handle credential acquisition, while src/executor.rs builds and sends HTTP requests. The repository also ships 92 “skill” definitions under skills/ that expose ready‑made agent actions (e.g., skills/gws-gmail-reply-all/SKILL.md). The binary is produced from Rust (src/main.rs) and packaged for npm via package.json and the pre‑built binaries referenced in the README.

How It Is Wired

Execution starts at src/main.rs::main (line 46). main calls run, which parses CLI arguments and ultimately invokes fetch_discovery_document – a network call (client.get(&url).send). The discovery payload drives dynamic command generation used by src/commands.rs.

User‑initiated actions flow through a small hub:

src/auth_commands.rs (93 functions) – parses gws auth … sub‑commands, reads/writes credential files via src/credential_store.rs.
src/setup_tui.rs (87 functions) – provides the interactive TUI for auth setup; its handle_key is called from 35 places.
src/executor.rs (53 functions) – builds HTTP requests (build_http_request), sends them (send_with_retry in src/client.rs), and processes responses.
src/helpers/gmail/mod.rs (64 functions) – implements Gmail‑specific helpers used by many skills.

The internal call graph contains 1,028 edges; the most fan‑out functions are make_items (41 callers) and handle_key (35 callers). No circular imports were detected.

File‑level responsibilities (high‑impact paths):

File	Core duties	External effect
`src/auth_commands.rs`	Auth CLI parsing, token cache handling	Reads/writes token files
`src/setup_tui.rs`	TUI rendering, key handling	Reads config, writes UI state
`src/executor.rs`	HTTP request construction, retry logic	Outbound network calls
`src/client.rs`	Low‑level HTTP client, retry wrapper	Network I/O
`src/credential_store.rs`	Secure key storage, file I/O	File reads/writes
`src/helpers/gmail/reply.rs`	Build reply‑all payloads, dedup recipients	Network request payload

Because the CLI builds commands dynamically, most service‑specific code lives in src/helpers/<service>/. Changing a service’s request format typically requires editing the corresponding helper module without touching the core executor.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/cli
cd cli

# Install Node‑side wrapper (pnpm is the lockfile’s manager)
pnpm install -g @googleworkspace/cli   # pulls pre‑built binary

# Or build the Rust binary locally
cargo install --git https://github.com/googleworkspace/cli --locked

Authentication requires a Google Cloud project and OAuth credentials. The CLI creates a credential directory (.gws/ by default) and stores tokens via src/credential_store.rs. Run the interactive setup:

gws auth setup   # walks through project ID, OAuth consent screen, etc.
gws auth login   # opens a browser for user consent

After login, any Workspace API can be called, e.g.:

gws drive files list --params '{"pageSize":5}'
gws gmail messages send --json '{"raw":"<base64‑url>" }' --dry-run

Skills are invoked as sub‑commands, for example:

gws recipe-create-sheet-for-new-month --params '{"title":"July"}'

Real‑World Use

A CI pipeline can generate weekly reports: gws gws-gmail-watch streams new messages, gws gws-sheets-append writes rows, and a custom skill processes the data. All steps run from a single binary, reducing dependency churn and eliminating custom HTTP client code.

Code Health & Issues

High – Add a test suite – 38 source files, no tests (src/ only).
Medium – Least‑privilege GITHUB_TOKEN – .github/workflows/ci.yml lacks a permissions block.
Medium – Enable Dependabot/Renovate – No update bot for Cargo.toml or package.json.
Medium – Gate PRs on vulnerability scan – CI lacks a dependency‑review or osv‑scanner step.
Medium – Set persist-credentials: false – Checkout step keeps the token, exposing it to post‑install scripts.
Low – Add timeout-minutes – Workflow jobs have no explicit timeout, risking runaway runs.

Additional static findings (not in the health block) show deep nesting (max depth 8 in src/auth.rs), duplicated 6‑line blocks across many files, and several oversized modules (>1,600 lines). Refactoring these hotspots would lower cognitive load and reduce blast radius for future changes.

The Bottom Line

gws provides a single, dynamically generated CLI for the full Google Workspace suite and bundles useful agent “skills”. The core is functional but lacks automated tests and exhibits maintainability concerns (deep nesting, duplicated code). It is suitable for teams that need rapid Workspace automation and are comfortable adding their own test coverage and refactoring the identified hotspots.