Skip to main content
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:
CommandNotes
lsList owned/shared spreadsheets
catRead spreadsheet JSON
head / tailFirst/last N lines
grep / rgPattern search
jqQuery JSON fields
wcLine/word/byte counts
statFile metadata
findRecursive search
treeDirectory tree view
basename / dirname / realpathPath utilities
nlNumber lines
Resource-specific commands:

​
gws-sheets-read

Read cell values from a spreadsheet range. 
gws-sheets-read --spreadsheet 1AbCdEf --range "Sheet1!A1:C3"
OptionRequiredDescription
--spreadsheetyesGoogle spreadsheet ID
--rangeyesA1 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"]]}'
OptionRequiredDescription
--paramsyesJSON with spreadsheetId, range, optional valueInputOption
--jsonyesJSON 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"]]'
OptionRequiredDescription
--spreadsheetyesGoogle spreadsheet ID
--rangenoA1 notation range (defaults to A1)
--valuesnoComma-separated values for one row
--json-valuesnoJSON 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"}}'
OptionRequiredDescription
--jsonyesJSON 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":[]}'
OptionRequiredDescription
--paramsyesJSON with spreadsheetId
--jsonyesJSON with requests array
Returns the batch update response JSON.