GWS

Use Google Drive, Sheets, Docs, Slides, Calendar, Forms and Gmail through one command tree. Mirage implements a subset of the Google Workspace CLI (gws), with selected API methods and helpers for mail, spreadsheet ranges and document text.

Setup

Use Google Workspace setup to obtain OAuth credentials and the scopes needed by each service.

from mirage import Workspace
from mirage.commands.cli.builtin.gws import GWS
from mirage.core.google.config import GoogleConfig

config = GoogleConfig(client_id="...", client_secret="...", refresh_token="...")
ws = Workspace({})
ws.register_cli("gws", GWS, config)

No service mount is required. For YAML and multiple accounts, see the CLI overview.

Supported commands

Run gws <command> --help for the supported flags and operands. This list is generated from Mirage’s registered command tree.

Command	Description
`gws drive files list`	GET /files (Google drive API passthrough)
`gws drive files get`	GET /files/{fileId} (Google drive API passthrough)
`gws drive files create`	POST /files (Google drive API passthrough)
`gws drive files update`	PATCH /files/{fileId} (Google drive API passthrough)
`gws drive files copy`	POST /files/{fileId}/copy (Google drive API passthrough)
`gws drive files delete`	DELETE /files/{fileId} (Google drive API passthrough)
`gws drive files export`	GET /files/{fileId}/export (Google drive API passthrough)
`gws drive permissions create`	POST /files/{fileId}/permissions (Google drive API passthrough)
`gws drive permissions list`	GET /files/{fileId}/permissions (Google drive API passthrough)
`gws drive permissions delete`	DELETE /files/{fileId}/permissions/{permissionId} (Google drive API passthrough)
`gws sheets spreadsheets get`	GET /spreadsheets/{spreadsheetId} (Google sheets API passthrough)
`gws sheets spreadsheets create`	POST /spreadsheets (Google sheets API passthrough)
`gws sheets spreadsheets batchUpdate`	POST /spreadsheets/{spreadsheetId}:batchUpdate (Google sheets API passthrough)
`gws sheets read`	Read a cell range
`gws sheets write`	Overwrite a range with 2D values
`gws sheets append`	Append rows after a range
`gws docs documents get`	GET /documents/{documentId} (Google docs API passthrough)
`gws docs documents create`	POST /documents (Google docs API passthrough)
`gws docs documents batchUpdate`	POST /documents/{documentId}:batchUpdate (Google docs API passthrough)
`gws docs write`	Append text to a document
`gws slides presentations get`	GET /presentations/{presentationId} (Google slides API passthrough)
`gws slides presentations create`	POST /presentations (Google slides API passthrough)
`gws slides presentations batchUpdate`	POST /presentations/{presentationId}:batchUpdate (Google slides API passthrough)
`gws calendar calendarList list`	GET /users/me/calendarList (Google calendar API passthrough)
`gws calendar calendars get`	GET /calendars/{calendarId} (Google calendar API passthrough)
`gws calendar events list`	GET /calendars/{calendarId}/events (Google calendar API passthrough)
`gws calendar events get`	GET /calendars/{calendarId}/events/{eventId} (Google calendar API passthrough)
`gws calendar events insert`	POST /calendars/{calendarId}/events (Google calendar API passthrough)
`gws calendar events patch`	PATCH /calendars/{calendarId}/events/{eventId} (Google calendar API passthrough)
`gws calendar events delete`	DELETE /calendars/{calendarId}/events/{eventId} (Google calendar API passthrough)
`gws calendar freebusy query`	POST /freeBusy (Google calendar API passthrough)
`gws forms forms create`	POST /forms (Google forms API passthrough)
`gws forms forms get`	GET /forms/{formId} (Google forms API passthrough)
`gws forms forms batchUpdate`	POST /forms/{formId}:batchUpdate (Google forms API passthrough)
`gws forms forms responses list`	GET /forms/{formId}/responses (Google forms API passthrough)
`gws forms forms responses get`	GET /forms/{formId}/responses/{responseId} (Google forms API passthrough)
`gws gmail users drafts create`	POST /users/{userId}/drafts (Google gmail API passthrough)
`gws gmail users drafts delete`	DELETE /users/{userId}/drafts/{id} (Google gmail API passthrough)
`gws gmail users drafts get`	GET /users/{userId}/drafts/{id} (Google gmail API passthrough)
`gws gmail users drafts list`	GET /users/{userId}/drafts (Google gmail API passthrough)
`gws gmail users drafts send`	POST /users/{userId}/drafts/send (Google gmail API passthrough)
`gws gmail users drafts update`	PUT /users/{userId}/drafts/{id} (Google gmail API passthrough)
`gws gmail users labels list`	GET /users/{userId}/labels (Google gmail API passthrough)
`gws gmail users messages list`	GET /users/{userId}/messages (Google gmail API passthrough)
`gws gmail users messages get`	GET /users/{userId}/messages/{id} (Google gmail API passthrough)
`gws gmail users messages send`	POST /users/{userId}/messages/send (Google gmail API passthrough)
`gws gmail users messages trash`	POST /users/{userId}/messages/{id}/trash (Google gmail API passthrough)
`gws gmail users messages attachments get`	GET /users/{userId}/messages/{messageId}/attachments/{id} (Google gmail API passthrough)
`gws gmail send`	Send a new email via Gmail
`gws gmail read`	Fetch one Gmail message as processed JSON (same shape as cat <path>.gmail.json)
`gws gmail reply`	Reply to the sender of a Gmail message (excludes CC)
`gws gmail reply-all`	Reply to a Gmail message including all recipients (To+CC)
`gws gmail forward`	Forward a Gmail message to a new recipient
`gws gmail triage`	List message summaries (id, from, subject, date, snippet) for a Gmail search query

Call an API method

gws drive files list --params '{"pageSize":10}'
gws gmail users messages get --params '{"userId":"me","id":"MESSAGE_ID"}'
gws drive permissions create --params '{"fileId":"FILE_ID"}' --json '{"role":"reader","type":"anyone"}'
gws sheets spreadsheets create --json '{"properties":{"title":"Q3 planning"}}'

The form is gws SERVICE RESOURCE METHOD. --params supplies URL path and query parameters; --json supplies the body. Methods return the API response as compact JSON. Lists follow nextPageToken by default and print multiple pages as NDJSON. Use --page-limit N to stop early. Export methods can return raw bytes instead of JSON. The supported methods are the registered subset above, not every method in Google’s Discovery documents.

Use helpers

gws gmail triage --query 'is:unread' --max 10
gws gmail read --id MESSAGE_ID
gws gmail send --to user@example.com --subject Hello --body 'Hi there'
gws gmail reply --message-id MESSAGE_ID --body 'Thanks'
gws sheets read --spreadsheet SHEET_ID --range 'Sheet1!A1:C10'
gws sheets append --spreadsheet SHEET_ID --values 'alice,42'
gws docs write --document DOC_ID --text 'New paragraph'
gws docs write --document DOC_ID --tab TAB_ID --text 'Into this tab'

Helpers omit the upstream CLI’s + prefix: use gws docs write, not gws docs +write. --tab is Mirage’s addition for document tabs.

Choose a document tab

gws docs documents get --params '{"documentId":"DOC_ID"}' returns the legacy body of the first tab. Add "includeTabsContent":true to receive tabs[].documentTab, including nested childTabs, instead of that flat body. Mounted .gdoc.json files always use the tab-aware shape. docs write appends to the first tab unless --tab selects another one. A raw batchUpdate follows the API’s defaults: replaceAllText without a tab restriction can affect every tab.

VFS, folder placement and limits

The CLI can share GoogleConfig with Google’s VFS adapters. Each registration owns its config and requires no mount. Setting folder_id (folderId in TypeScript) changes creation placement, not which files the CLI may read:

Drive files create and copy default parents to that folder.
An explicit parents array wins, including an empty array.
Docs, Sheets and Slides creation is followed by a Drive move into the folder. These are separate requests, so a failed move can leave the new file created.
Injected placement requests include Shared Drive support.

Reads still reach the whole account allowed by the credential. Use command policy to restrict operations; a mounted folder is not a CLI access boundary. Mirage registers a fixed command subset; upstream builds commands from Google Discovery at runtime. Folder placement and helper spelling also differ, and the host config supplies credentials instead of an interactive login. Mirage paginates list methods by default; upstream requires --page-all. Parser refusals use Mirage’s declared command style, so upstream exit codes and diagnostics are not a blanket compatibility promise. The original gws is Apache-2.0 licensed. Mirage’s command implementation is also Apache-2.0; see compatibility and licenses.

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Setup

Supported commands

Call an API method

Use helpers

Choose a document tab

VFS, folder placement and limits

​Setup

​Supported commands

​Call an API method

​Use helpers

​Choose a document tab

​VFS, folder placement and limits

Setup

Supported commands

Call an API method

Use helpers

Choose a document tab

VFS, folder placement and limits