Google Workspace Integration
Your inbox, documents, spreadsheets, and calendar hold the real context of your work — meeting decisions buried in threads, project status locked in sheets, action items scattered across docs. The Google Workspace extension wires Gemini CLI directly into all of it, turning a 45-minute "find and summarize all emails about the budget" task into a 10-second prompt.
What You'll Learn
- Install the Google Workspace extension and complete OAuth authorization
- Understand every scope the extension requests and what data flows where
- Use
/gmail,/gdocs,/gdrive,/gsheets, and/gcalendarslash commands - Chain Gmail, Drive, and GitHub into compound multi-tool workflows
- Use Sheets as a readable/writable data layer for automated dashboards
- Schedule meetings intelligently with conflict detection via
/gcalendar - Revoke access safely and understand enterprise Workspace admin policies
Installing the Workspace Extension
Before the Workspace extension, Gemini CLI was like a brilliant assistant who had read every programming book ever written — but had no access to your actual office. They couldn't read the email thread you're referring to, couldn't look up the spreadsheet you want summarized, couldn't see your calendar. The pain: you copy-pasted content manually, losing formatting, context, and the relationships between documents. The mapping: installing the Workspace extension is like giving your assistant a pass card to your entire office — they can now walk to the filing cabinet, pull the right folder, and work with it in full context without you having to describe what's in it.
One Command to Install
gemini extensions install google-workspacegemini --version first.
After installation, Gemini CLI opens your default browser for OAuth authorization. You'll see a Google consent screen listing every scope being requested.
New Commands After Install
/gmail
Read, search, draft, and send Gmail messages. Supports label filtering and attachment references.
/gdocs
Read and create Google Docs. Accepts Drive file IDs or names. Supports export to Markdown.
/gdrive
Search Drive, access files by URL or name using @drive:// syntax. List and navigate folders.
/gsheets
Read and write Google Sheets. Supports cell range notation (A1:C10), named ranges, and formulas.
/gcalendar
Read calendar events, check availability, and create new events. Supports timezone-aware scheduling.
After installing the extension, start a Gemini CLI session and type / to see all available commands. The Workspace commands appear grouped under the google-workspace namespace with inline descriptions.
Gmail Workflows
The /gmail commandA Workspace extension skill that uses the Gmail API (gmail.readonly + gmail.compose + gmail.send scopes) to fetch message metadata, retrieve full message bodies, and draft or send messages. All API calls go directly from Gemini CLI to Google's servers — the content is processed by Gemini's model but never stored by the CLI. invokes the Gmail API on your behalf using the OAuth token stored locally. When you ask Gemini to "summarize unread emails," it calls messages.list with q: "is:unread", retrieves each message body, then passes the combined text as context to the model. The model response is streamed back to your terminal — your email content is never written to disk by the CLI.
Workflow 1 — Inbox Triage
- URGENT Re: Production incident — auth service down (DevOps, 08:14) — P0 outage affecting 12% of users, needs your go/no-go on rollback plan. Action needed by 10:00 AM.
- URGENT Q3 budget sign-off deadline (Finance, yesterday) — Final approval window closes today at 5 PM. Document attached.
- FYI Sprint planning notes (Engineering) — Summary of yesterday's planning session. No action required.
- + 7 more emails — newsletters, calendar notifications, and team updates. No action required today.
2 emails flagged as urgent. Recommend addressing the auth incident first, then the budget approval.
Workflow 2 — Smart Email Drafting
Hi [Name],
Thank you so much for the invite — I appreciate you thinking of me. My schedule is pretty packed this sprint, so I won't be able to join live, but I'd love to contribute asynchronously.
Would you be open to a short Loom from me instead? I can walk through my thoughts on [topic] in 5 minutes and you can watch when it fits your schedule. Let me know!
Best,
[Your name]
Reply "send" to send this draft, "edit: [changes]" to revise, or "save" to save to Drafts.
@email.txt loads the email file as context so Gemini knows who you're declining and what the original request was. WHY: Without context, the draft would be generic. With it, Gemini tailors the tone and references the specific meeting topic.
Workflow 3 — Cross-App Research
- Searching Gmail for
subject:Q3 budget OR body:Q3 budget... - Extracting key decisions, figures, and action items across thread...
- Creating Google Doc "Q3 Budget Thread Summary" in Drive root...
- Doc created:
drive://Q3-Budget-Thread-Summary.gdoc
The doc contains: Timeline, 3 key decisions made, final approved figures ($2.4M), and 5 open action items with owners. Link copied to clipboard.
What Just Happened?
Gemini CLI chained three API calls: Gmail search → message retrieval → Drive document creation. From your perspective it was one prompt. From the extension's perspective it was a coordinated multi-tool sequence — exactly the kind of workflow that previously took 45 minutes manually.
Google Docs + Drive
Generate a Status Report from Code + Docs
Running:
git log --since="1 week ago" --onelineCreating Google Doc: "Project Status Report — Week of June 9, 2026"
Doc structure: Executive Summary · Features Delivered (mapped against PRD goals) · In Progress · Blocked Items · Next Week Plan · Metrics
Doc link: drive://Project-Status-Report-June-9.gdoc — Shared with edit access.
Update a Spreadsheet via Drive Reference
@drive://project-tracker.gsheet Update the Status column for the auth module to 'Done'@drive:// prefix tells Gemini CLI to resolve the filename against your Drive and load it as context. GOTCHA: File names must be unique in your Drive for this to work unambiguously. If multiple files match, Gemini CLI will ask you to clarify by file ID.
Extract Action Items to GitHub Issues
Extracted 6 action items. Creating GitHub issues in repo:
- #247 — "Set up staging environment for auth service" (owner: @devops-team)
- #248 — "Review and merge OpenAPI spec PR" (owner: @backend-team)
- #249 — "Write migration guide for v2 API breaking changes" (owner: @you)
- + 3 more issues created with labels from meeting context
All 6 issues created. Issues labelled meeting-action-item and assigned based on names mentioned in notes.
Sheets as a Data Layer
Before using Sheets with Gemini CLI, teams would manually paste test results into spreadsheets at the end of a sprint — error-prone, delayed, and always out of date. The pain: a dashboard that's stale by definition, because updating it competes with actually doing the work. The mapping: Gemini CLI treats your Sheets file the same way a backend service treats a database — it can read it, process the data with model reasoning, and write results back. Your "dashboard" stays current because Gemini does the updating automatically after every test run.
A common pattern is an automated test results dashboard: read the current sheet, append new test run data, have Gemini compute trend summaries, and write back a formatted status row.
@drive://test-results-dashboard.gsheet
Read columns A:E (date, suite, passed, failed, duration).
Calculate the 7-day pass rate trend.
Append a new row for today's run: passed=487, failed=12, duration=143s.
Add a summary in column F: STABLE if pass rate > 95%, DEGRADED if between 90-95%, CRITICAL if below 90%.Engineering teams spend an average of 90 minutes per week manually updating dashboards. A Sheets + Gemini CLI automation running in CI reduces this to zero. The @drive:// reference makes the automation self-documenting — anyone reading the prompt immediately knows which spreadsheet is being updated and why.
Google Calendar
The /gcalendar command brings free/busy lookupA Calendar API method (freebusy.query) that returns time ranges where a user has events, without revealing event details. Used for scheduling assistants to find open slots without exposing private calendar contents to the requester. and event creation directly into your prompts.
Timezone detected: America/New_York (UTC-4)
2:00 PM – 2:30 PM ET: Available
Checking for back-to-back conflicts... No meeting ends at 2:00 PM. No meeting starts before 2:30 PM.
Creating event: "Sprint Retro" · June 18 · 2:00–2:30 PM ET
Inviting: team@company.com (from GEMINI.md contacts)
Conferencing: Google Meet link auto-generated
Event created. Calendar invite sent to 4 attendees. Reply "cancel" within 60 seconds to undo.
freebusy.query for the requested time window, finds the first available 30-minute slot matching your request, then calls events.insert with the full event details. GOTCHA: Gemini CLI reads timezone from your system locale — verify this is correct before scheduling across timezones by checking /gcalendar timezone.
Privacy Model & OAuth Scopes
When you authorize the Workspace extension, Google presents a consent screen listing each scope. Here's exactly what each scope means in plain English:
| Scope | What It Allows | Used For |
|---|---|---|
gmail.readonly |
Read all Gmail messages and metadata | Inbox triage, email search, summarization |
gmail.compose |
Create and save drafts (not send) | Drafting replies — you review before sending |
gmail.send |
Send email on your behalf | Only invoked if you explicitly say "send" |
drive.readonly |
Read files and folder metadata | @drive:// file references |
drive.file |
Create and modify files Gemini CLI creates | Creating new Docs/Sheets from prompts |
spreadsheets |
Read and write Sheets data | Dashboard automation, data updates |
calendar.events |
Read and create calendar events | Scheduling, free/busy lookup |
Your email and document content is sent to the Gemini API for processing. This is subject to Google's standard API data usage policy. For personal Google accounts: content may be used to improve models unless you opt out in myaccount.google.com. For Google Workspace (enterprise) accounts: data is processed under your organization's data processing agreement — admin policies control whether third-party apps can access Workspace data at all. Always check with your IT/security team before using Workspace integrations on corporate accounts.
Revoking Access
# Remove the locally stored OAuth tokens
Remove-Item "$env:USERPROFILE\.gemini\credentials\workspace.json" -Force
# Uninstall the extension
gemini extensions uninstall google-workspace
# Also revoke at the Google account level (recommended)
# Visit: https://myaccount.google.com/permissions
# Find "Gemini CLI" and click "Remove Access"Google Workspace admins can block OAuth app installs via the Admin Console at admin.google.com → Security → API Controls → App Access Control. If your organization has this policy enabled, the authorization step will fail with a "This app is blocked" error. You'll need admin approval or a service account issued by your IT team.
Compound Multi-Tool Workflows
The real value of Workspace integration isn't any single skill — it's chaining them together with other tools (GitHub, Slack MCP, your codebase) into workflows that span your entire work context.
Workflow: Gmail → Summarize → Slack
Find unread emails about production incidents from the last 24 hours.
Summarize each one: service affected, severity, current status, and next action.
Post a formatted summary to the #engineering-alerts Slack channel.Workflow: Drive → Extract → GitHub Issues
Read @drive://q3-planning-brief.gdoc.
Find every action item — look for lines starting with "Action:", "TODO:", or owner names followed by a colon.
For each action item, create a GitHub issue in org/repo with:
- Title from the action
- Body with context from the surrounding paragraph
- Assignee from the owner name (map to GitHub usernames in GEMINI.md)
- Label: planning-q3
- Milestone: Q3 2026Checkpoint — You Now Have a Workspace-Connected AI Workflow Layer
Gmail, Docs, Drive, Sheets, and Calendar are now part of your Gemini CLI context. The compound patterns here — read from one app, process with AI, write to another — are the foundation of everything in Track 5. Save a useful compound prompt as a Skill (.gemini/skills/) to run it again with one command.
Knowledge Check
Five questions on the Google Workspace extension.
1. After running gemini extensions install google-workspace, what is the next required step before Workspace commands are available?
WORKSPACE_API_KEY environment variable
2. You want to reference a Google Sheets file called "project-tracker" in a prompt without knowing its full Drive URL. Which syntax should you use?
@sheets:project-tracker
@drive://project-tracker.gsheet
/gsheets open project-tracker
@https://docs.google.com/spreadsheets/...
@drive://filename.extension syntax tells Gemini CLI to search your Drive for a file matching that name. It works for .gdoc, .gsheet, .gslides, and regular files stored in Drive.@drive://filename.gsheet. The @drive:// prefix triggers a Drive search by filename. You can also use a full Drive URL if you have it.3. Which Gmail OAuth scope is required specifically for the CLI to send an email (not just draft it)?
gmail.readonly
gmail.compose
gmail.send
gmail.full
gmail.compose only creates drafts. gmail.send is the additional scope required to actually transmit the message. The CLI only invokes send when you explicitly confirm in the prompt (e.g. "send this").gmail.send. gmail.compose creates drafts only. This separation is intentional — you stay in control of what actually leaves your inbox.4. A developer on a corporate Google Workspace account gets "This app is blocked" when trying to authorize the extension. What is the most likely cause?
5. You want to chain Gmail → Gemini summarization → Slack notification in a single prompt. What prerequisite must be set up for the Slack step to work?
SLACK_TOKEN in .env
slack Gemini extension separately