Google Sheets

The Google Sheets resource exposes Sheets spreadsheets as a virtual filesystem mounted at some prefix such as /gsheets/. For Google OAuth setup, see Google Workspace Setup.

Config

import os

from mirage import MountMode, Workspace
from mirage.resource.gsheets import GSheetsConfig, GSheetsResource

config = GSheetsConfig(
    client_id=os.environ["GOOGLE_CLIENT_ID"],
    client_secret=os.environ["GOOGLE_CLIENT_SECRET"],
    refresh_token=os.environ["GOOGLE_REFRESH_TOKEN"],
)
resource = GSheetsResource(config=config)
ws = Workspace({"/gsheets": resource}, mode=MountMode.READ)

Filesystem Layout

/gsheets/
  owned/
    <YYYY-MM-DD>_<sanitized-title>__<spreadsheet-id>.gsheet.json
    ...
  shared/
    <YYYY-MM-DD>_<sanitized-title>__<spreadsheet-id>.gsheet.json
    ...

Example:

/gsheets/
  owned/
    2026-04-04_Roadmap__1AbCdEf.gsheet.json
    2026-04-10_Expenses__2BcDeFg.gsheet.json
  shared/
    2026-04-03_Budget__9XyZ.gsheet.json

Spreadsheets are split into owned (spreadsheets you created) and shared (spreadsheets shared with you). The filename shape is:

<YYYY-MM-DD>_<sanitized-title>__<spreadsheet-id>.gsheet.json

If the modified date is unavailable, the date prefix is omitted. Reading a spreadsheet file returns the full Google Sheets API JSON for that spreadsheet, including sheet metadata.

Cache

The Google Sheets resource uses IndexCacheStore. Index entries store spreadsheet IDs and metadata. There is no separate content cache — file content caching is handled by the workspace IOResult mechanism.

Example

import asyncio
import os

from dotenv import load_dotenv

from mirage import MountMode, Workspace
from mirage.resource.gsheets import GSheetsConfig, GSheetsResource

load_dotenv(".env.development")

config = GSheetsConfig(
    client_id=os.environ["GOOGLE_CLIENT_ID"],
    client_secret=os.environ["GOOGLE_CLIENT_SECRET"],
    refresh_token=os.environ["GOOGLE_REFRESH_TOKEN"],
)
resource = GSheetsResource(config=config)


async def main():
    ws = Workspace({"/gsheets": resource}, mode=MountMode.READ)

    # List structure
    r = await ws.execute("ls /gsheets/")
    print(await r.stdout_str())

    # List owned spreadsheets
    r = await ws.execute("ls /gsheets/owned/")
    print(await r.stdout_str())

    # Read a spreadsheet
    r = await ws.execute(
        "cat /gsheets/owned/2026-04-04_Roadmap__1AbCdEf.gsheet.json")
    print(await r.stdout_str())

    # Extract title with jq
    r = await ws.execute(
        'jq ".properties.title"'
        " /gsheets/owned/2026-04-04_Roadmap__1AbCdEf.gsheet.json")
    print(await r.stdout_str())

    # Search across all spreadsheets
    r = await ws.execute('rg "revenue" /gsheets/owned/')
    print(await r.stdout_str())

    # Tree view
    r = await ws.execute("tree -L 1 /gsheets/")
    print(await r.stdout_str())

    # Read cell values
    r = await ws.execute(
        'gws-sheets-read --spreadsheet 1AbCdEf --range "Sheet1!A1:C3"')
    print(await r.stdout_str())

    # Append rows
    r = await ws.execute(
        "gws-sheets-append --spreadsheet 1AbCdEf --values Alice,30,NYC")
    print(await r.stdout_str())

    # Create a new spreadsheet
    r = await ws.execute(
        'gws-sheets-spreadsheets-create'
        ' --json \'{"properties":{"title":"MIRAGE Sheet"}}\'')
    print(await r.stdout_str())


if __name__ == "__main__":
    asyncio.run(main())

See examples/gsheets/gsheets.py for the full working example.

Shell Commands

Standard commands available on the mounted Google Sheets tree:

Command	Notes
`ls`	List owned/shared spreadsheets
`cat`	Read spreadsheet JSON
`head` / `tail`	First/last N lines
`grep` / `rg`	Pattern search
`jq`	Query JSON fields
`wc`	Line/word/byte counts
`stat`	File metadata
`find`	Recursive search
`tree`	Directory tree view
`basename` / `dirname` / `realpath`	Path utilities
`nl`	Number lines

Resource-specific commands:

`gws-sheets-read`

Read cell values from a spreadsheet range.

gws-sheets-read --spreadsheet 1AbCdEf --range "Sheet1!A1:C3"

Option	Required	Description
`--spreadsheet`	yes	Google spreadsheet ID
`--range`	yes	A1 notation range to read

Returns the cell values as JSON.

`gws-sheets-write`

Write cell values to a spreadsheet range.

gws-sheets-write --params '{"spreadsheetId":"1AbCdEf","range":"Sheet1!A1"}' --json '{"values":[["x"]]}'

Option	Required	Description
`--params`	yes	JSON with `spreadsheetId`, `range`, optional `valueInputOption`
`--json`	yes	JSON with `values` 2D array

Returns the update response JSON.

`gws-sheets-append`

Append rows to a spreadsheet.

gws-sheets-append --spreadsheet 1AbCdEf --values Alice,30,NYC
gws-sheets-append --spreadsheet 1AbCdEf --range "Sheet1!A1" --json-values '[["Bob",25,"LA"]]'

Option	Required	Description
`--spreadsheet`	yes	Google spreadsheet ID
`--range`	no	A1 notation range (defaults to `A1`)
`--values`	no	Comma-separated values for one row
`--json-values`	no	JSON 2D array of values

Either --values or --json-values is required. Returns the append response JSON.

`gws-sheets-spreadsheets-create`

Create a new spreadsheet.

gws-sheets-spreadsheets-create --json '{"properties":{"title":"MIRAGE Sheet"}}'

Option	Required	Description
`--json`	yes	JSON body with `properties.title` field

Returns the created spreadsheet JSON.

`gws-sheets-spreadsheets-batchUpdate`

Batch update a spreadsheet.

gws-sheets-spreadsheets-batchUpdate --params '{"spreadsheetId":"1AbCdEf"}' --json '{"requests":[]}'

Option	Required	Description
`--params`	yes	JSON with `spreadsheetId`
`--json`	yes	JSON with `requests` array

Returns the batch update response JSON.

Getting Started

Agents

Resources

Config

Filesystem Layout

Cache

Example

Shell Commands

`gws-sheets-read`

`gws-sheets-write`

`gws-sheets-append`

`gws-sheets-spreadsheets-create`

`gws-sheets-spreadsheets-batchUpdate`

​Config

​Filesystem Layout

​Cache

​Example

​Shell Commands

​gws-sheets-read

​gws-sheets-write

​gws-sheets-append

​gws-sheets-spreadsheets-create

​gws-sheets-spreadsheets-batchUpdate

Config

Filesystem Layout

Cache

Example

Shell Commands

`gws-sheets-read`

`gws-sheets-write`

`gws-sheets-append`

`gws-sheets-spreadsheets-create`

`gws-sheets-spreadsheets-batchUpdate`