# gws CLI setup — Google Workspace prieiga tavo asistentui

You need to set up and use the gws CLI (Google Workspace CLI) to interact with Gmail, Calendar, Drive, Sheets, Docs, and Tasks. This is an open-source CLI from the `googleworkspace` GitHub organization; its README says it is not an officially supported Google product. This optional step adds a CLI route for selected tasks. Keep existing Google MCP connections from step 101; do not remove them or rewrite the assistant’s general routing rules. During installation use read-only checks only. The write examples below are reference material, not installation tests: do not send mail, create events or upload files. Connect only the account and services the user selected. Request only the needed read permissions; if that cannot be done, stop rather than grant broad write access. Do not enable billing or paid services.

## What to do

### 1. Verify it's installed

```bash
which gws        # should return /opt/homebrew/bin/gws (macOS) or similar
gws --version    # expect 0.22.5 or newer
```

If missing, install via Homebrew:

```bash
brew install googleworkspace-cli

# NOTE: the formula is `googleworkspace-cli`, NOT `gws`.
# Homebrew has an unrelated formula named `gws` (a git workspace manager).
# Both install a binary called `gws` and they conflict with each other.
# Installing the wrong one leaves the assistant unable to reach Gmail,
# and the error message does not explain why.
```

If `brew list gws` succeeds (it prints files instead of an error), the unrelated git workspace tool is installed. Remove it first, then install the right formula:

```bash
brew uninstall gws
brew install googleworkspace-cli
```

On Windows (no Homebrew), install via npm instead. It needs Node.js, which the kit installs first:

```bash
npm install -g @googleworkspace/cli

# npm may warn that the package's postinstall script was not run.
# That is fine: the first `gws` command downloads the program itself.
# Then check `gws --version` as above.
```

If that fails, check the current install instructions in the official docs before guessing.

### 2. Optional second account

Use only the account the user chose. A second account is optional: do not check or connect it automatically. If the user explicitly needs both personal and business accounts, each gets its own config directory so tokens do not collide:

| Account                                | Config dir              | Purpose                                              |
|----------------------------------------|-------------------------|------------------------------------------------------|
| YOUR_PERSONAL@gmail.com (personal)     | ~/.config/gws/ (default)| Personal inbox, calendar, Drive                      |
| YOU@YOURBUSINESS.com (business)        | ~/.config/gws-biz/      | Business inbox, business Drive, client comms, invoices |

The default account is invoked as `gws ...`. The business (or any second) account requires the config-dir override:

```bash
GOOGLE_WORKSPACE_CLI_CONFIG_DIR=~/.config/gws-biz gws <cmd>
```

Or, much easier, add this alias to your `~/.zshrc` (or `~/.bashrc`) once:

```bash
alias gws-biz='GOOGLE_WORKSPACE_CLI_CONFIG_DIR=~/.config/gws-biz gws'
```

Reload your shell (`source ~/.zshrc`) and from then on just call `gws-biz <cmd>`.

You can name the second config dir and alias whatever you want — `gws-work`, `gws-company`, `gws-darbas`, etc. Pick something memorable.

### 3. Check authentication only for the selected account

Run only the matching command below. Do not probe the other account.

```bash
gws gmail users getProfile --params '{"userId": "me"}'                                      # personal
GOOGLE_WORKSPACE_CLI_CONFIG_DIR=~/.config/gws-biz gws gmail users getProfile --params '{"userId": "me"}'   # business
```

If you get an email address back, you're connected. Don't use `gws gmail +triage` for this
check: it defaults to unread mail only, so an inbox with zero unread messages looks exactly
like a missing connection and gives a false negative.

If you get an auth error instead, that account still needs the one-time setup below.

### 3a. First-time setup: a Google Cloud project

`gws auth login` needs OAuth credentials tied to a Google Cloud project. Most accounts don't
have one yet, so run this once per account, before `auth login`:

```bash
gws auth setup                                                           # personal
GOOGLE_WORKSPACE_CLI_CONFIG_DIR=~/.config/gws-biz gws auth setup              # business
```

If an appropriate project and OAuth client already exist, reuse them after confirming the account; do not create duplicates.

`gws auth setup` requires the `gcloud` CLI: it uses it to create the Cloud project and
enable the needed APIs for you. If `gcloud` is not installed, `gws auth setup` will fail and
say so. In that case, don't try to work around it by guessing: create an OAuth client
manually in the Google Cloud Console (type Desktop app), download its JSON, and save it to
`~/.config/gws/client_secret.json` for the personal account (or the matching file under
`~/.config/gws-biz/` for the business one) before the login step below.

### 3b. Log in

```bash
gws auth login                                                           # personal
GOOGLE_WORKSPACE_CLI_CONFIG_DIR=~/.config/gws-biz gws auth login              # business
```

This opens a browser for OAuth consent. Authenticate with the matching Google account. The token is stored inside that config dir, so future calls are silent.

If you're not sure what flags `auth` supports, run `gws auth --help` first instead of guessing at options.

### 4. Basic usage patterns

```bash
# Helper commands (prefix +) — the high-leverage shortcuts
gws gmail +triage                                  # inbox summary
gws gmail +send --to a@b.com --subject 'X' --body 'Y'
gws calendar +agenda --today
gws calendar +agenda --week
gws calendar +insert --summary 'Meeting' --start '2026-06-01T14:00:00+03:00' --end '2026-06-01T15:00:00+03:00'
gws drive +upload /path/to/file

# Raw API calls (when no + helper exists)
gws gmail users messages list --params '{"userId": "me", "maxResults": 10}'
gws gmail users messages get  --params '{"userId": "me", "id": "MSG_ID"}'
gws drive files list --params '{"pageSize": 10, "q": "name contains '\''invoice'\''"}'
gws sheets spreadsheets values get --params '{"spreadsheetId": "ID", "range": "Sheet1!A1:D10"}'
```

### 5. Important gotchas

- Gmail params ALWAYS require `"userId": "me"`.
- Calendar times must be RFC3339 with timezone, e.g. `2026-06-01T14:00:00+03:00`. Lithuania timezone is Europe/Vilnius (UTC+2 / UTC+3 DST).
- POST methods (e.g. `gws gmail users drafts create`) take body via `--json '...'`, NOT `--params`. If a method fails with a param error, immediately run `gws <cmd> --help` instead of guessing.
- To explore an API surface: `gws schema <service>.<resource>.<method>` returns the schema. Use `--resolve-refs` to expand `$ref` pointers.
- Output formats: `--format json` (default), `--format table`, `--format yaml`, `--format csv`, `--page-all` to auto-paginate.
- Use `--dry-run` to validate a call without executing.

### 6. Which account for which task

- Business clients, client invoices, business Drive files, business inbox → business (`gws-biz`).
- Personal calendar, personal inbox, side projects → personal (`gws`).
- If ambiguous, check the surrounding context. The business address is the one you give to clients.

### 7. Routing for this optional CLI step

Use gws for the selected CLI checks in this step. This does not revoke or replace the working MCP connections from step 101. Future tasks use the route already recorded for the selected account. Never add a global ban on Google MCP tools from this installation guide.
