google-workspace skill

Google Workspace

Gmail, Calendar, Drive, Contacts, Sheets, and Docs — through Hermes-managed OAuth and a thin CLI wrapper. When gws is installed, the skill uses it as the execution backend for broader Google Workspace coverage; otherwise it falls back to the bundled Python client implementation.

References

• references/gmail-search-syntax.md — Gmail search operators (is:unread, from:, newer_than:, etc.)
• references/domain-registrars-indonesia.md — Domain registrar comparison for Google Workspace setup (Indonesia context, pricing in IDR)

Scripts

• scripts/setup.py — OAuth2 setup (run once to authorize)
• scripts/google_api.py — compatibility wrapper CLI. It prefers gws for operations when available, while preserving Hermes' existing JSON output contract.

First-Time Setup

The setup is fully non-interactive — you drive it step by step so it works on CLI, Telegram, Discord, or any platform.

Define a shorthand first:

GSETUP="python ${HERMES_HOME:-$HOME/.hermes}/skills/productivity/google-workspace/scripts/setup.py"

Step 0: Check if already set up

$GSETUP --check

If it prints AUTHENTICATED, skip to Usage — setup is already done.

Step 1: Triage — ask the user what they need

Before starting OAuth setup, ask the user TWO questions:

Question 1: "What Google services do you need? Just email, or also Calendar/Drive/Sheets/Docs?"

instead — it works with a Gmail App Password (Settings → Security → App Passwords) and takes 2 minutes to set up. No Google Cloud project needed. Load the himalaya skill and follow its setup instructions.

• Email only → They don't need this skill at all. Use the himalaya skill

--services email,calendar during auth so the consent screen only asks for the scopes they actually need.

• Email + Calendar → Continue with this skill, but use

narrower --services set like calendar,drive,sheets,docs.

• Calendar/Drive/Sheets/Docs only → Continue with this skill and use a

all service set.

• Full Workspace access → Continue with this skill and use the default

Question 2: "Does your Google account use Advanced Protection (hardware security keys required to sign in)? If you're not sure, you probably don't — it's something you would have explicitly enrolled in."

allowed apps list before Step 4 will work. Let them know upfront.

• No / Not sure → Normal setup. Continue below.
• Yes → Their Workspace admin must add the OAuth client ID to the org's

Step 2: Create OAuth credentials (one-time, ~5 minutes)

Tell the user:

You need a Google Cloud OAuth client. This is a one-time setup:

1. Create or select a project:

https://console.cloud.google.com/projectselector2/home/dashboard

2. Enable the required APIs from the API Library:

https://console.cloud.google.com/apis/library

Enable: Gmail API, Google Calendar API, Google Drive API,

Google Sheets API, Google Docs API, People API

3. Create the OAuth client here:

https://console.cloud.google.com/apis/credentials

Credentials → Create Credentials → OAuth 2.0 Client ID

4. Application type: "Desktop app" → Create

5. If the app is still in Testing, add the user's Google account as a test user here:

https://console.cloud.google.com/auth/audience

Audience → Test users → Add users

6. Download the JSON file and tell me the file path

Important Hermes CLI note: if the file path starts with /, do NOT send only the bare path as its own message in the CLI, because it can be mistaken for a slash command. Send it in a sentence instead, like:

The JSON file path is: /home/user/Downloads/clientsecret....json

Once they provide the path:

$GSETUP --client-secret /path/to/client_secret.json

If they paste the raw client ID / client secret values instead of a file path, write a valid Desktop OAuth JSON file for them yourself, save it somewhere explicit (for example ~/Downloads/hermes-google-client-secret.json), then run --client-secret against that file.

Step 3: Get authorization URL

Use the service set chosen in Step 1. Examples:

$GSETUP --auth-url --services email,calendar --format json
$GSETUP --auth-url --services calendar,drive,sheets,docs --format json
$GSETUP --auth-url --services all --format json

This returns JSON with an authurl field and also saves the exact URL to ~/.hermes/googleoauthlasturl.txt.

Agent rules for this step:

• Extract the auth_url field and send that exact URL to the user as a single line.
• Tell the user that the browser will likely fail on http://localhost:1 after approval, and that this is expected.
• Tell them to copy the ENTIRE redirected URL from the browser address bar.
• If the user gets Error 403: access_denied, send them directly to https://console.cloud.google.com/auth/audience to add themselves as a test user.

Step 4: Exchange the code

The user will paste back either a URL like http://localhost:1/?code=4/0A...&scope=... or just the code string. Either works. The --auth-url step stores a temporary pending OAuth session locally so --auth-code can complete the PKCE exchange later, even on headless systems:

$GSETUP --auth-code "THE_URL_OR_CODE_THE_USER_PASTED" --format json

If --auth-code fails because the code expired, was already used, or came from an older browser tab, it now returns a fresh freshauthurl. In that case, immediately send the new URL to the user and have them retry with the newest browser redirect only.

Step 5: Verify