Quickstart

Get up and running with gws in 5 minutes

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
   

   Expected output

   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.

   What if gws auth setup doesn't work?

   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}'
   

   Expected output

   {
     "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
   

   Sample output

   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
   

   Sample Drive resources

   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"}}'

Expected output

{
  "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:[e-mail]", "maxResults": 3}'

Expected output

{
  "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"}
  }'

Expected output

{
  "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": "[e-mail]",
    "self": true
  },
  "organizer": {
    "email": "[e-mail]",
    "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:

Flag	Description	Example
--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-run	Preview the request without sending	--dry-run
--page-all	Auto-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

Dry run output

{
  "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'

Sample output

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

Schema output

{
  "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