GWS

Mirage’s built-in Google Workspace API client follows the command surface of the upstream googleworkspace/cli project, with Discovery passthroughs plus ergonomic helpers. The Mirage command tree is discoverable with gws --help. Licenses: The upstream project uses Apache-2.0; Mirage’s independent implementation uses Apache-2.0.

Install

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

config = GoogleConfig(client_id="...", client_secret="...", refresh_token="...")
ws = Workspace({"/mail": GmailVFS(config)})
ws.register_cli("gws", GWS, config.model_dump())

Two installs under different names are two accounts. In YAML, the same install rides the clis: section; see the CLI overview.

Verbs

The syntax mirrors the upstream Google Workspace CLI: one passthrough leaf per Discovery method, plus hand-written helpers under each service.

gws <service> <resource> <method> [--params JSON] [--json JSON]   # API passthrough
gws <service> <helper> [flags]                                    # ergonomic helper

Services: drive, sheets, docs, slides, gmail. The whole surface is discoverable from the shell:

gws --help                # services
gws drive files --help    # methods on a Discovery resource
gws gmail send --help     # helper flags

API passthrough

Passthrough commands call the corresponding API method directly: --params fills URL path and query parameters, --json is the request body, and the output is the compact API response JSON. List methods follow nextPageToken to the end by default (pages print as NDJSON); --page-limit N stops early.

# List Drive files
gws drive files list --params '{"q": "name contains \'report\'"}'

# Read a Gmail message raw
gws gmail users messages get --params '{"userId": "me", "id": "msg123"}'

# Batch-update a spreadsheet
gws sheets spreadsheets batchUpdate \
  --params '{"spreadsheetId": "SHEET_ID"}' \
  --json '{"requests": [...]}'

# Share a Drive file
gws drive permissions create \
  --params '{"fileId": "FILE_ID"}' \
  --json '{"role": "reader", "type": "anyone"}'

Folder scope

A config carrying folder_id scopes what the CLI creates, so a file it makes lands in the same folder a GDriveVFS sharing that config mounts, and the agent’s own ls shows what it just made:

config = GoogleConfig(client_id="...", refresh_token="...", folder_id="FOLDER_ID")
ws = Workspace({"/data": GDriveVFS(config)})
ws.register_cli("gws", GWS, config.model_dump())

gws sheets spreadsheets create --json '{"properties": {"title": "Q3"}}'
ls /data                                   # Q3.gsheet.json

Three things worth knowing:

Two divergences from the official CLI’s passthrough. drive files create and copy get parents defaulted into the request body, and the Docs/Sheets/Slides create methods have no parents field at all, so mirage issues a second Drive call to move the new file. Both also send supportsAllDrives, which is what lets a scope name a Shared Drive folder.
An explicit parents array always wins, and then nothing is injected into the query either: you typed the call, you own it. The key being present is what counts, so "parents": [] is honored too rather than read as absent.
Reads are not scoped. gws drive files list still sees the whole account. The scope is about where new files go, not a fence.
Helpers are spelled bare, not +-prefixed. Upstream marks its hand-written commands with a + (gws docs +write); mirage’s tree does not need the marker, because a helper and a Discovery method cannot collide inside a typed spec. So an upstream line carrying + has to drop it here. The flag names are upstream’s own and match it (--document --text, gmail send’s --to --subject --body, sheets read’s --spreadsheet --range); --tab is the single addition, because upstream’s +write takes no tab argument and upstream has no tab support at all.

Document tabs

A Google Doc holds one or more tabs, and the Docs API reports them only when asked. documents.get fills the legacy top-level body from the first tab and leaves tabs empty unless includeTabsContent is set; with it, the content moves under tabs[].documentTab and body is left empty. The two shapes are exclusive, so it is a shape switch rather than a verbosity knob, and tabs nest through childTabs. A .gdoc.json on a mount is always the tab-aware shape, because that is the only one that can represent a document with more than one tab. Through the passthrough you choose:

# every tab, the shape a mount serves
gws docs documents get --params '{"documentId": "DOC_ID", "includeTabsContent": true}'

# the legacy flat body, which is the FIRST tab only
gws docs documents get --params '{"documentId": "DOC_ID"}'

Writes pick a tab the same way. gws docs write without --tab appends to the first tab, which is the API’s own default for a request that names no tab; read the ids out of a mounted file with jq '[.. | .tabProperties? // empty | .tabId]'. Note that replaceAllText is one of three requests that instead default to every tab, so a bare batchUpdate replacement is document-wide.

Helpers

Helper	Description
`gws gmail send`	Send a new email (`--to --subject --body`)
`gws gmail reply`	Reply to the sender (`--message-id --body`)
`gws gmail reply-all`	Reply to all recipients (To + CC)
`gws gmail forward`	Forward a message (`--message-id --to`)
`gws gmail read`	One message as processed JSON (`--id`)
`gws gmail triage`	Summaries for a search query (`--query --max`)
`gws sheets read`	Read a cell range (`--spreadsheet --range`)
`gws sheets write`	Overwrite a range (`--values` / `--json-values`)
`gws sheets append`	Append rows after a range
`gws docs write`	Append text to a doc or tab (`--document --text [--tab]`)

gws gmail send --to "user@example.com" --subject "Hello" --body "Hi there"
gws gmail triage --query "is:unread" --max 10
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 that tab"

Getting Started

AI Agents

VFS

CLIs

Watch

Runtimes

Install

Verbs

API passthrough

Folder scope

Document tabs

Helpers

​Install

​Verbs

​API passthrough

​Folder scope

​Document tabs

​Helpers

Install

Verbs

API passthrough

Folder scope

Document tabs

Helpers