# Google Workspace via `gws`

Use this skill when the user wants Google Workspace access through the external `gws` CLI.

This is **not** a native ShortcutXL integration:

- `gws` must be installed separately
- `gws` manages its own authentication
- use raw bash to run `gws ...`

## What To Do

Help with:

- checking whether `gws` is installed
- checking auth readiness
- telling the user the next step when auth is broken
- using `gws` through raw bash once it is ready

Do **not** invent a wrapped Google API surface if `gws` already provides the command surface.

## Install

Check first:

```bash
which gws
gws --version
```

If missing:

```bash
pnpm add -g @googleworkspace/cli
```

## Auth

### Status

```bash
gws auth status
```

### Scratch Profile / Start From Scratch

Use a separate config dir when testing from scratch so you do not touch the user's main `gws` state:

```bash
export GOOGLE_WORKSPACE_CLI_CONFIG_DIR="$HOME/.config/gws-test"
export GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file
gws auth status
```

This should show a clean state if the config dir is new.

### Setup OAuth client config

Use when client config is missing:

```bash
gws auth setup
```

This may require `gcloud`, and on first-time setup it may stop and require manual Google Cloud Console work.

### Real First-Time Setup Flow

Verified flow:

```bash
gcloud auth login
gws auth setup --login
```

What can happen:

1. `gcloud auth login` is required first
2. `gws auth setup --login` may detect the current GCP project
3. if the OAuth consent screen or Desktop OAuth client does not already exist, `gws` may stop and tell the user to finish setup manually in the Cloud Console

Manual Cloud Console steps may include:

- configuring the OAuth consent screen
- creating a Desktop OAuth client ID
- downloading `client_secret.json`
- saving it to the `gws` config dir or exporting:

```bash
export GOOGLE_WORKSPACE_CLI_CLIENT_ID="..."
export GOOGLE_WORKSPACE_CLI_CLIENT_SECRET="..."
gws auth login
```

If `gws auth setup --login` prints Cloud Console URLs or setup instructions, report them exactly. Do not paraphrase loosely.

### Login

```bash
gws auth login
```

### Reset

```bash
gws auth logout
```

Then re-run:

```bash
gws auth login
```

### Reauthentication Failures

If API calls fail with errors like `invalid_grant` or `invalid_rapt`, the next step is usually:

```bash
gws auth login
```

If `gws auth setup --login` fails because `gcloud` cannot refresh credentials non-interactively, run:

```bash
gcloud auth login
```

then retry `gws auth setup --login`.

## Schema Discovery

Prefer checking the schema before guessing arguments:

```bash
gws schema drive.files.list
gws schema gmail.users.messages.get
gws schema sheets.spreadsheets.values.get
```

Also use help:

```bash
gws --help
gws auth --help
gws auth login --help
```

## Common Commands

### Drive

```bash
gws drive files list --params '{"pageSize":10}'
gws drive files get --params '{"fileId":"FILE_ID"}'
gws drive files create --params '{"name":"example.txt"}' --upload ./example.txt
```

### Gmail

```bash
gws gmail users messages list --params '{"userId":"me","maxResults":10}'
gws gmail users messages get --params '{"userId":"me","id":"MESSAGE_ID"}'
```

### Sheets

```bash
gws sheets spreadsheets get --params '{"spreadsheetId":"SPREADSHEET_ID"}'
gws sheets spreadsheets values get --params '{"spreadsheetId":"SPREADSHEET_ID","range":"Sheet1!A1:C10"}'
```

## Failure Handling

If the user is not ready to use `gws`, tell them exactly which step is missing:

- not installed -> install `@googleworkspace/cli`
- `gcloud` not authenticated -> `gcloud auth login`
- client config missing -> `gws auth setup` or `gws auth setup --login`
- login missing/stale -> `gws auth login`
- first-time OAuth client setup incomplete -> follow the exact Cloud Console steps printed by `gws`

If `gws` prints a backend/keychain/native trust error, report the exact message instead of guessing.

## Working Style

1. check readiness first if there is any doubt
2. use `gws schema ...` or `--help` before guessing arguments
3. keep commands close to the native `gws` surface
4. when setup is broken, tell the user the exact next command or Cloud Console step to run
