gsuite-sdk

Name: gsuite-sdk
Author: Pablo Alaniz

Work with Gmail, Google Calendar, Drive, Sheets, Tasks and Contacts through the gsuite-sdk Python library and its `gsuite` CLI (JSON output for agents). Use it to read and send ema…

Pablo Alaniz

@pabloalaniz

Install

$ openclaw skills install @pabloalaniz/gsuite-sdk

gsuite-sdk

One OAuth login for Gmail, Calendar, Drive, Sheets, Tasks and Contacts, usable three ways: the gsuite CLI (prefer it: most commands print JSON with -o json), the Python SDK, or a REST API (gsuite serve).

Docs: https://pabloalaniz.github.io/google-suite/ · Source: https://github.com/PabloAlaniz/google-suite

Setup

pip install "gsuite-sdk[cli]"      # the gsuite command; [all] adds the REST API, async and Secret Manager

Configuration comes from environment variables (or a .env file):

Variable	Default	Meaning
`GSUITE_CREDENTIALS_FILE`	`credentials.json`	OAuth client file from Google Cloud (how to get it)
`GSUITE_TOKEN_DB_PATH`	`tokens.db`	Where the login token is stored (SQLite)
`GSUITE_DEFAULT_TIMEZONE`	`UTC`	Time zone for "today" and for naive datetimes

Both paths are relative to the current directory: run every command from the same place, or set absolute paths. Set GSUITE_DEFAULT_TIMEZONE (e.g. America/Argentina/Buenos_Aires), or "today" and new events use UTC.

Login (once, opens a browser)

gsuite auth login                                  # Gmail, Calendar, Drive, Sheets
gsuite auth login --force --scopes default,tasks,contacts   # add Tasks and Contacts
gsuite auth status

--scopes takes a comma-separated list of default, gmail, calendar, drive, sheets, tasks, contacts, all. Tasks and Contacts are not in the default login. The token refreshes itself; log in again (--force) only after a TokenRefreshError or when a call fails with PermissionDeniedError because a scope is missing.

Without a browser (servers, CI) use a service account:

from gsuite_core import GoogleAuth, Scopes

auth = GoogleAuth.from_service_account(
    "service-account.json",
    scopes=Scopes.default(),
    subject="user@your-domain.com",  # Workspace domain-wide delegation; omit otherwise
)

CLI (preferred)

Add -o json where supported and parse stdout. Errors exit with code 1 and a one-line message.

gsuite gmail list --unread --limit 10 -o json
gsuite gmail list --query "from:boss@example.com newer_than:7d" -o json
gsuite gmail read MESSAGE_ID -o json
gsuite gmail send --to ana@example.com --subject "Report" --body "Attached." --attach report.pdf
gsuite gmail reply MESSAGE_ID --body "Thanks!"

gsuite calendar list --days 1 -o json        # events in the next 24 hours
gsuite calendar create "Sync" --start "2026-03-02 10:00" --end "2026-03-02 10:30" --attendee ana@example.com --meet --notify

gsuite drive list --name "invoice" -o json
gsuite drive upload ./report.pdf --to FOLDER_ID
gsuite drive download FILE_ID --out ./file.pdf
gsuite drive share FILE_ID ana@example.com --role writer

gsuite sheets read SPREADSHEET --range "A1:D20" -o json   # SPREADSHEET: title, ID or URL
gsuite sheets append SPREADSHEET --value "Ana" --value 42
gsuite sheets export SPREADSHEET --format xlsx --out ./budget.xlsx

gsuite tasks list -o json
gsuite tasks add "Pay rent" --due 2026-03-01
gsuite tasks done TASK_ID

gsuite contacts search ana -o json

No JSON output on calendar today, calendar week or gmail search: use calendar list --days N -o json and gmail list --query ... -o json instead.

Python SDK

from gsuite_core import GoogleAuth
from gsuite_gmail import Gmail, query
from gsuite_calendar import Calendar
from gsuite_drive import Drive
from gsuite_sheets import Sheets

auth = GoogleAuth()   # reads the token saved by `gsuite auth login`

gmail = Gmail(auth)
for msg in gmail.search(query.from_("boss@example.com") & query.newer_than(days=7)):
    print(msg.subject, msg.sender, msg.date)

calendar = Calendar(auth)
for event in calendar.get_today():
    print(event.start, event.summary, event.meet_link)

drive = Drive(auth)
uploaded = drive.upload("report.pdf", parent_id="FOLDER_ID")
drive.share(uploaded.id, "ana@example.com", role="reader")

sheets = Sheets(auth)
spreadsheet = sheets.open_by_key("1AbC...")     # by ID; sheets.open(title) searches by title
ws = spreadsheet.sheet1                         # first tab, whatever its name
rows = ws.get_all_records()                     # list of dicts; values are strings
ws.append_rows([["Ana", 42], ["Bob", 7]])
ws.update("A1", [["Name", "Score"]])            # values are always a 2D list

Per service, with everything else the SDK can do: Gmail · Calendar · Drive · Sheets · Tasks and Contacts · REST API and deployment

Errors and return values

Lookups return None when the item doesn't exist (gmail.get_message, calendar.get_event, drive.get, tasks.get_task, contacts.get), and deletes return False. Check for them instead of catching exceptions.
Every error is a gsuite_core.GSuiteError:
- NotFoundError: HTTP 404 from Google.
- PermissionDeniedError: HTTP 403, usually a scope missing from the login (log in again with --force --scopes ...) or no access to that item.
- RateLimitError / QuotaExceededError: already retried with backoff before being raised.
- ValidationError: bad input (.field names it).
- CredentialsNotFoundError: GSUITE_CREDENTIALS_FILE doesn't exist and a browser login is needed.
- NotAuthenticatedError / TokenRefreshError: run gsuite auth login.
Sheets: sheets.open(title) raises ValueError when no spreadsheet has that title (use open_by_key when you have the ID); engine operations raise SpreadsheetNotFoundError, WorksheetNotFoundError and InvalidRangeError (all GSuiteError).

Notes for agents

Confirm with the user before sending email, inviting attendees (--notify / send_updates="all"), sharing files or deleting anything.
Gmail search uses Gmail's query syntax (from:, newer_than:7d, has:attachment, is:unread), or the query builder in Python.
Dates for --due, --start and the SDK are ISO (2026-03-01, 2026-03-01 10:00); naive times are in GSUITE_DEFAULT_TIMEZONE.

Top skills in this category

GitHub

@byungkyu

GitHub API integration with managed OAuth. Access repositories, issues, pull requests, commits, branches, and users. Use this skill when users want to interact with GitHub repositories, manage issues and PRs, search code, or automate workflows. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway). Calls run through the `maton` CLI with OAuth login, or over raw HTTP with a Maton API key where the CLI cannot be installed. Every call is authenticated as the user's connection and reaches only what that connection's authorization allows, which the provider enforces on every request; the endpoints documented here are the ones this skill uses, and any other endpoint of this app needs the user to ask for it by name. Default to read and list calls, and confirm every write or new connection with the user. This file also documents the three constructs that turn a GitHub connection into automation, in the order they are used: the connection (the first step), a hosted function that runs a GitHub action through the Maton SDK, and a trigger that calls that function on a schedule or on an event. Those sections are the platform's own reference text, shared with the api-gateway skill, with GitHub examples; they add no GitHub capability - GitHub is itself an event source, so its own events are in `references/github/triggers.md`, and the files under `references/<source>/triggers.md` are the platform's event catalogues for the sources Maton offers (time, Calendly, GitHub, Gmail, HubSpot, Linear, Notion, Slack, Stripe).

4719k

google-slides

@byungkyu

Google Slides API integration with managed OAuth. Create presentations, add slides, insert content, and manage slide formatting. Use this skill when users want to interact with Google Slides. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway). Calls run through the `maton` CLI with OAuth login, or over raw HTTP with a Maton API key where the CLI cannot be installed. Every call is authenticated as the user's connection and reaches only what that connection's authorization allows, which the provider enforces on every request; the endpoints documented here are the ones this skill uses, and any other endpoint of this app needs the user to ask for it by name. Default to read and list calls, and confirm every write or new connection with the user. This file also documents the three constructs that turn a Google Slides connection into automation, in the order they are used: the connection (the first step), a hosted function that runs a Google Slides action through the Maton SDK, and a trigger that calls that function on a schedule or on an event. Those sections are the platform's own reference text, shared with the api-gateway skill, with Google Slides examples; they add no Google Slides capability - Google Slides is not an event source, a trigger cannot read Google Slides data, and the files under `references/<source>/triggers.md` are the platform's event catalogues for the sources Maton offers (time, Calendly, GitHub, Gmail, HubSpot, Linear, Notion, Slack, Stripe).

3420k

google-workspace-admin

@byungkyu

Google Workspace Admin SDK integration with managed OAuth. This is a write-capable administrative integration for users, groups, organizational units, roles, and domain settings. Only connect with a least-privileged Google admin account, restrict OAuth scopes to the specific resources needed, and revoke the connection after use. All write operations require explicit user approval showing the exact HTTP method, endpoint path, and target resource identifier before execution. Use this skill only when users need Google Workspace administration. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway). Calls run through the `maton` CLI with OAuth login, or over raw HTTP with a Maton API key where the CLI cannot be installed. Every call is authenticated as the user's connection and reaches only what that connection's authorization allows, which the provider enforces on every request; the endpoints documented here are the ones this skill uses, and any other endpoint of this app needs the user to ask for it by name. Default to read and list calls, and confirm every write or new connection with the user. This file also documents the three constructs that turn a Google Workspace Admin connection into automation, in the order they are used: the connection (the first step), a hosted function that runs a Google Workspace Admin action through the Maton SDK, and a trigger that calls that function on a schedule or on an event. Those sections are the platform's own reference text, shared with the api-gateway skill, with Google Workspace Admin examples; they add no Google Workspace Admin capability - Google Workspace Admin is not an event source, a trigger cannot read Google Workspace Admin data, and the files under `references/<source>/triggers.md` are the platform's event catalogues for the sources Maton offers (time, Calendly, GitHub, Gmail, HubSpot, Linear, Notion, Slack, Stripe).

2119k

Linear

@byungkyu

Linear API integration with managed OAuth. Query and manage issues, projects, teams, cycles, and labels using GraphQL. Use this skill when users name Linear explicitly or ask about their Linear issues, cycles, projects, or teams — for example "create a Linear issue for this bug", "what is in my current cycle", "move ENG-412 to done". Not for GitHub issues, Jira, or generic task lists, and not for planning work that is not tracked in Linear. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway). Requires network access and valid Maton API key. Calls run through the `maton` CLI with OAuth login, or over raw HTTP with a Maton API key where the CLI cannot be installed. Every call is authenticated as the user's connection and reaches only what that connection's authorization allows, which the provider enforces on every request; the endpoints documented here are the ones this skill uses, and any other endpoint of this app needs the user to ask for it by name. Default to read and list calls, and confirm every write or new connection with the user. This file also documents the three constructs that turn a Linear connection into automation, in the order they are used: the connection (the first step), a hosted function that runs a Linear action through the Maton SDK, and a trigger that calls that function on a schedule or on an event. Those sections are the platform's own reference text, shared with the api-gateway skill, with Linear examples; they add no Linear capability - Linear is itself an event source, so its own events are in `references/linear/triggers.md`, and the files under `references/<source>/triggers.md` are the platform's event catalogues for the sources Maton offers (time, Calendly, GitHub, Gmail, HubSpot, Linear, Notion, Slack, Stripe).

1815k

google-play

@byungkyu

Google Play Developer API (Android Publisher) integration with managed OAuth. Manage apps, subscriptions, in-app purchases, and reviews. Use this skill when users want to interact with Google Play Console programmatically. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway). Calls run through the `maton` CLI with OAuth login, or over raw HTTP with a Maton API key where the CLI cannot be installed. Every call is authenticated as the user's connection and reaches only what that connection's authorization allows, which the provider enforces on every request; the endpoints documented here are the ones this skill uses, and any other endpoint of this app needs the user to ask for it by name. Default to read and list calls, and confirm every write or new connection with the user. This file also documents the three constructs that turn a Google Play connection into automation, in the order they are used: the connection (the first step), a hosted function that runs a Google Play action through the Maton SDK, and a trigger that calls that function on a schedule or on an event. Those sections are the platform's own reference text, shared with the api-gateway skill, with Google Play examples; they add no Google Play capability - Google Play is not an event source, a trigger cannot read Google Play data, and the files under `references/<source>/triggers.md` are the platform's event catalogues for the sources Maton offers (time, Calendly, GitHub, Gmail, HubSpot, Linear, Notion, Slack, Stripe).

1218k