Skip to main content

​
Quickstart

This guide will walk you through installing the Google Workspace CLI, setting up authentication, and running your first commands.
1

Install the CLI

Install gws via npm:
Terminal
npm install -g @googleworkspace/cli
Verify the installation:
Terminal
gws --version

gws 0.3.3
Alternatively, you can build from source using Cargo if you prefer.
2

Set up authentication

Run the interactive setup command to create a Google Cloud project and configure OAuth:
Terminal
gws auth setup
This command will:
  • Create a new Google Cloud project (or use an existing one)
  • Enable required Google Workspace APIs
  • Create OAuth 2.0 credentials
  • Walk you through the OAuth consent flow
  • Store encrypted credentials in your OS keyring
gws auth setup requires the gcloud CLI to be installed and authenticated.
If automated setup fails, you can configure OAuth manually through the Google Cloud Console:
  1. Create an OAuth 2.0 Desktop client
  2. Download the client secret JSON
  3. Save it to ~/.config/gws/client_secret.json
  4. Run gws auth login
3

Run your first command

List files in your Google Drive:
Terminal
gws drive files list --params '{"pageSize": 5}'

{
  "kind": "drive#fileList",
  "incompleteSearch": false,
  "files": [
    {
      "kind": "drive#file",
      "mimeType": "application/vnd.google-apps.folder",
      "id": "1abc123...",
      "name": "My Documents"
    },
    {
      "kind": "drive#file",
      "mimeType": "application/vnd.google-apps.spreadsheet",
      "id": "1xyz789...",
      "name": "Q1 Budget"
    }
  ]
}
All responses are structured JSON by default. Use --format table for human-readable output.
4

Explore available services

See all available Google Workspace services:
Terminal
gws --help

gws — Google Workspace CLI

USAGE:
    gws <service> <resource> [sub-resource] <method> [flags]
    gws schema <service.resource.method> [--resolve-refs]

SERVICES:
    drive                Drive API - File storage and sync
    gmail                Gmail API - Email management
    calendar             Calendar API - Events and scheduling
    sheets               Sheets API - Spreadsheets
    docs                 Docs API - Document editing
    slides               Slides API - Presentations
    chat                 Chat API - Messaging
    admin                Admin SDK - Workspace administration
    people               People API - Contacts
    tasks                Tasks API - Task management
Browse commands for a specific service:
Terminal
gws drive --help

RESOURCES:
    files                File operations
    permissions          Sharing and permissions
    comments             File comments
    drives               Shared drives
    changes              Change feed
    revisions            File revision history

​
Try More Commands

Now that you’re set up, try these common operations:

​
Create a Spreadsheet

Terminal
gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'

{
  "spreadsheetId": "1abc123xyz789...",
  "properties": {
    "title": "Q1 Budget",
    "locale": "en_US",
    "timeZone": "America/Los_Angeles"
  },
  "sheets": [
    {
      "properties": {
        "sheetId": 0,
        "title": "Sheet1",
        "index": 0,
        "sheetType": "GRID"
      }
    }
  ]
}

​
Search Gmail Messages

Terminal
gws gmail users messages list --params '{"userId": "me", "q": "from:notifications@github.com", "maxResults": 3}'

{
  "messages": [
    {
      "id": "18d1234567890abcd",
      "threadId": "18d1234567890abcd"
    },
    {
      "id": "18d0987654321efgh",
      "threadId": "18d0987654321efgh"
    },
    {
      "id": "18d5555555555ijkl",
      "threadId": "18d5555555555ijkl"
    }
  ],
  "resultSizeEstimate": 47
}

​
Create a Calendar Event

Terminal
gws calendar events insert \
  --params '{"calendarId": "primary"}' \
  --json '{
    "summary": "Team Standup",
    "start": {"dateTime": "2026-03-10T10:00:00-08:00"},
    "end": {"dateTime": "2026-03-10T10:30:00-08:00"}
  }'

{
  "kind": "calendar#event",
  "id": "abc123def456",
  "status": "confirmed",
  "htmlLink": "https://www.google.com/calendar/event?eid=...",
  "created": "2026-03-05T08:30:00.000Z",
  "updated": "2026-03-05T08:30:00.000Z",
  "summary": "Team Standup",
  "creator": {
    "email": "you@example.com",
    "self": true
  },
  "organizer": {
    "email": "you@example.com",
    "self": true
  },
  "start": {
    "dateTime": "2026-03-10T10:00:00-08:00",
    "timeZone": "America/Los_Angeles"
  },
  "end": {
    "dateTime": "2026-03-10T10:30:00-08:00",
    "timeZone": "America/Los_Angeles"
  }
}

​
Useful Flags

gws includes powerful flags that work across all commands:
FlagDescriptionExample
--params <JSON>URL/query parameters as JSON--params '{"pageSize": 10}'
--json <JSON>Request body for POST/PATCH/PUT--json '{"title": "New Doc"}'
--format <FMT>Output format: json, table, yaml, csv--format table
--dry-runPreview the request without sending--dry-run
--page-allAuto-paginate all results as NDJSON--page-all
--upload <PATH>Upload a local file (multipart)--upload ./file.pdf
--output <PATH>Save response to file--output response.json

​
Dry Run Example

Preview a request before sending it:
Terminal
gws chat spaces messages create \
  --params '{"parent": "spaces/AAAAabcd123"}' \
  --json '{"text": "Deploy complete!"}' \
  --dry-run

{
  "method": "POST",
  "url": "https://chat.googleapis.com/v1/spaces/AAAAabcd123/messages",
  "headers": {
    "Authorization": "Bearer [redacted]",
    "Content-Type": "application/json"
  },
  "body": {
    "text": "Deploy complete!"
  }
}

​
Pagination Example

Fetch all pages and stream results as NDJSON:
Terminal
gws drive files list \
  --params '{"pageSize": 100}' \
  --page-all \
  | jq -r '.files[].name'

My Documents
Q1 Budget.xlsx
Team Photos
Project Roadmap.pdf
Meeting Notes.docx
...
Each page is emitted as a separate JSON line. Pipe to jq to extract specific fields.

​
Schema Introspection

Use gws schema to inspect API method schemas without leaving your terminal:
Terminal
gws schema drive.files.list

{
  "id": "drive.files.list",
  "path": "drive/v3/files",
  "httpMethod": "GET",
  "description": "Lists the user's files.",
  "parameters": {
    "pageSize": {
      "type": "integer",
      "description": "The maximum number of files to return per page.",
      "minimum": "1",
      "maximum": "1000",
      "default": "100"
    },
    "pageToken": {
      "type": "string",
      "description": "Token for continuing a previous list request."
    },
    "q": {
      "type": "string",
      "description": "Query string for searching files."
    }
  },
  "scopes": [
    "https://www.googleapis.com/auth/drive",
    "https://www.googleapis.com/auth/drive.readonly"
  ]
}
Inspect response schemas with --resolve-refs:
Terminal
gws schema drive.File --resolve-refs

​
Next Steps

Authentication Options

Learn about headless auth, service accounts, and CI workflows

Command Reference

Browse all available services and commands

Advanced Features

Master pagination, uploads, and schema introspection

AI Integration

Use gws with AI agents via MCP or OpenCode skills