gws-cli

gws-cli

Use this skill when the task should be executed through the Google Workspace CLI instead of handwritten HTTP requests or ad hoc API wrappers.

When to use this skill

• The user asks to interact with Google Drive, Gmail, Sheets, Docs, Slides, Calendar, Chat, Tasks, People, Meet, or Workspace Admin APIs.
• The user wants structured JSON output that is easy for an agent to inspect.
• The user needs to inspect Google API schemas before building a request.
• The user wants a repeatable CLI workflow that can run locally, in CI, or in a headless environment.

Required operating model

1. Confirm that gws is installed and available on PATH.
2. Check authentication status before making API calls.
3. Inspect the target method with gws schema or gws <service> --help before composing flags.
4. Prefer read-only commands first.
5. For write, update, or delete operations, confirm intent with the user before execution.
6. Prefer --dry-run when the command supports local validation and the operation is risky.

Quick start

# Install the CLI
npm install -g @googleworkspace/cli

# Check the binary and auth status
bash scripts/check-prereqs.sh

# Inspect command space
gws drive --help
gws schema drive.files.list

# Run a read-only command
gws drive files list --params '{"pageSize": 10}' --format json

Authentication workflow

Choose the lightest auth flow that satisfies the task.

Local interactive

gws auth setup
gws auth login

Service account

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json
gws auth status

CI or headless flows

• Prefer exported credentials or service-account based execution.
• Never echo secrets back to the user.
• If credentials are missing, stop and ask for the appropriate auth setup instead of guessing.

More detail is in references/REFERENCE.md.

Command discovery workflow

Always inspect before executing.

# Browse resources and helper commands for a service
gws sheets --help

# Inspect a specific method schema
gws schema sheets.spreadsheets.values.get

Use schema output to determine:

• required --params values
• whether a request body is needed via --json
• whether pagination or file upload flags apply
• which field names and types the API expects

Command patterns

Read-only list or get

gws drive files list --params '{"pageSize": 10}' --format json
gws gmail users messages get --params '{"userId": "me", "id": "MESSAGE_ID"}' --format json

Create or update with explicit confirmation

gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}' --format json
gws docs documents batchUpdate --params '{"documentId": "DOC_ID"}' --json '{"requests": [...]}' --format json

Schema-driven request building

gws schema calendar.events.insert
gws calendar events insert --params '{"calendarId": "primary"}' --json '{"summary": "Standup", "start": {"dateTime": "2026-03-07T09:00:00Z"}, "end": {"dateTime": "2026-03-07T09:15:00Z"}}'

Pagination

gws drive files list --params '{"pageSize": 100}' --page-all

File upload or download

gws drive files create --json '{"name": "report.pdf"}' --upload ./report.pdf
gws drive files get --params '{"fileId": "FILE_ID", "alt": "media"}' --output ./download.bin

Safety rules

• Treat create, insert, update, patch, delete, and helper commands that change state as write operations.
• Confirm the target resource, identity, and scope before executing a write operation.
• Never print tokens, OAuth client secrets, or service account JSON contents.
• Prefer --format json unless the user explicitly wants a human-oriented table.
• Use --page-all intentionally because it changes output shape to NDJSON.
• If the upstream API or CLI help is ambiguous, inspect the schema again instead of guessing flag names.

Available support files

• references/REFERENCE.md for installation, auth, and common command templates
• scripts/check-prereqs.sh for local environment checks

Troubleshooting

• If gws is missing, install it from npm or a GitHub release, confirm it is on PATH, and rerun bash scripts/check-prereqs.sh.
• If gws auth status shows no credentials, run gws auth setup and gws auth login, or export GOOGLE_APPLICATION_CREDENTIALS for a service-account flow.
• If gws auth login fails due to OAuth client restrictions, prefer the upstream manual OAuth flow or a service account where appropriate.
• If a request returns 403 Forbidden or insufficient permissions, confirm the active identity, API enablement, scopes, and resource sharing before retrying.
• If a method is unknown, confirm the service alias with gws <service> --help before assuming the REST method name maps directly.
• If a request fails schema validation, rerun gws schema <service.resource.method> and compare every required field name with the command you built.
• If --page-all changes the output shape unexpectedly, remember that pagination output becomes NDJSON and should be parsed line by line.