# gws
> Unified CLI for all Google Workspace APIs

## Summary
Unified CLI for all Google Workspace APIs — Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin — with dynamic command generation and structured JSON output.

## Capabilities
- Access all Google Workspace APIs from the terminal
- Dynamic command generation from Google Discovery Service
- Structured JSON output for piping and automation
- Multiple auth methods: OAuth, service accounts, access tokens
- Auto-pagination with --page-all
- File uploads via --upload
- Schema introspection for any API method
- Dry-run mode to preview requests

## When to Use
- You need to manage Google Drive, Gmail, Calendar, or Sheets from the CLI
- You want to automate Google Workspace tasks in scripts
- You need structured JSON output from Google APIs
- You are building AI agent workflows with Google Workspace

## When NOT to Use
- You don't have a Google Workspace or Google Cloud account
- You need only a single Google service (dedicated CLI may suffice)

## Key Flags
- `--page-all`: Auto-paginate through all results
- `--upload`: Upload a file
- `--dry-run`: Preview the API request without executing
- `--output-format`: Set output format (json, csv, table)

## Usage Patterns
### List Drive files
```
gws drive files list --page-all
```
List all files in Google Drive with auto-pagination

### Send an email
```
gws gmail users.messages send --user me --body '{...}'
```
Send a Gmail message via the API

### Inspect API schema
```
gws schema drive.files.list
```
View the schema for a specific API method

### Create a spreadsheet
```
gws sheets spreadsheets create --body '{"properties":{"title":"New Sheet"}}'
```
Create a new Google Sheets spreadsheet

## Input / Output
- **stdout**: Structured JSON API responses

## Installation
- **npm**: `npm install -g @googleworkspace/cli`
- **cargo**: `cargo install --git https://github.com/googleworkspace/cli --locked`
- **nix**: `nix run github:googleworkspace/cli`

## Related Tools
- [gcalcli](/tools/gcalcli) (complementary): Dedicated Google Calendar CLI

---
Source: https://littlescripts.sh/tools/gws