Google Sheets

The Google Sheets VFS 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.vfs.gsheets import GSheetsConfig, GSheetsVFS

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

Field	Description
`timeout` default `30`	Seconds a request may wait to connect, or between two reads of its answer, before it fails; a download that keeps flowing is never cut off.
`access_token` secret	OAuth access token, or a callable that returns one. Takes precedence over `client_id` and `refresh_token`.
`client_id`	Google OAuth client ID. Required with `refresh_token` when `access_token` is unset; mirage then mints and renews access tokens itself.
`client_secret` secret	Google OAuth client secret, sent with the refresh-token grant. Omit it for a PKCE client.
`refresh_token` secret	User’s OAuth refresh token. Required with `client_id` when `access_token` is unset.
`api_base`	One base URL that replaces every Google API host and the OAuth token endpoint, such as a test server. Unset uses Google’s hosts.

Fields marked secret are redacted in snapshots.

VFS.md

The VFS.md an agent reads with Google Sheets mounted at /<path>.

Rendered
Raw

Virtual Filesystem

Path	Description
`/<path>`	`gsheets`, write

VFS Layout

`/<path>`

/<path>
  owned/     # sheets you created
    <YYYY-MM-DD>_<title>__<spreadsheet-id>.gsheet.json
  shared/    # sheets others shared with you
    <YYYY-MM-DD>_<title>__<spreadsheet-id>.gsheet.json

<YYYY-MM-DD> is the file’s modifiedTime, so a date glob such as 2026-05-* narrows by it.
<title> is sanitized: spaces and any character outside [A-Za-z0-9_.-] become _, at most 100 characters.
<spreadsheet-id> is the Google Sheets spreadsheet id.
shared/ holds sheets shared with you by others; ones you own and shared with others are still in owned/.

A .gsheet.json matches the Google Sheets API spreadsheets.get response:

{
  "spreadsheetId": "...",
  "spreadsheetUrl": "...",
  "properties": { "title": "...", "locale": "...", "timeZone": "..." },
  "sheets": [
    {                                      // one element per tab
      "properties": {
        "sheetId": 0, "title": "...", "index": 0,
        "gridProperties": { "rowCount": 1000, "columnCount": 26 }
      },
      "data": [
        {
          "rowData": [
            { "values": [
                { "formattedValue": "...",
                  "userEnteredValue": {...},
                  "effectiveValue": {...} }
            ]}    // an empty cell is {}, a trailing one absent
          ]
        }
      ]
    }
  ],
  "namedRanges": [...]
}

Useful jq paths:

.properties.title
.sheets[].properties.title                              # tab names
.sheets[0].data[0].rowData[].values[].formattedValue    # cell strings
.namedRanges[]

Delete, on a write path:

rm /<path>/owned/<file>.gsheet.json   # deletes it from Drive for good
rm -f <path>                       # ignores a missing file

Only .gsheet.json files can be removed; owned/ and shared/ cannot.Rename to a new title, on a write path:

mv /<path>/owned/<date>_<old>__<id>.gsheet.json \
   /<path>/owned/<date>_<new>__<id>.gsheet.json

Keep the folder, the date and the id, and spell the title the way the listing does (spaces become _); any other name is refused.

Supported Unix Commands for VFS

Unix commands work on each path as on a local filesystem, as far as the path supports them:

Path	Supported
`/<path>`	Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest), and `mv`, `rm` and `unlink`. `grep -r` and `rg` with `-w` ask `gsheets` which files may match.

Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

Path	Limitations
`/<path>`	Not supported: `>`, `>>`, `tee`, `tee -a`, `touch` of a new file, `cp`, `cp -r`, `mkdir`, `rm -r`, `rmdir`, `truncate`, `sed -i`. Without `-w`, `grep -r` and `rg` read every file. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused.

Run man <cmd> or <cmd> --help for one command’s usage.

---
name: workspace-filesystem
description: The virtual filesystem layout of this workspace.
---

# Virtual Filesystem

| Path | Description |
| --- | --- |
| `/<path>` | `gsheets`, write |

## VFS Layout

### `/<path>`

```text
/<path>
  owned/     # sheets you created
    <YYYY-MM-DD>_<title>__<spreadsheet-id>.gsheet.json
  shared/    # sheets others shared with you
    <YYYY-MM-DD>_<title>__<spreadsheet-id>.gsheet.json
```

- `<YYYY-MM-DD>` is the file's `modifiedTime`, so a date glob such as
  `2026-05-*` narrows by it.
- `<title>` is sanitized: spaces and any character outside
  `[A-Za-z0-9_.-]` become `_`, at most 100 characters.
- `<spreadsheet-id>` is the Google Sheets spreadsheet id.
- `shared/` holds sheets shared with you by others; ones you own
  and shared with others are still in `owned/`.

A `.gsheet.json` matches the Google Sheets API `spreadsheets.get`
response:

```jsonc
{
  "spreadsheetId": "...",
  "spreadsheetUrl": "...",
  "properties": { "title": "...", "locale": "...", "timeZone": "..." },
  "sheets": [
    {                                      // one element per tab
      "properties": {
        "sheetId": 0, "title": "...", "index": 0,
        "gridProperties": { "rowCount": 1000, "columnCount": 26 }
      },
      "data": [
        {
          "rowData": [
            { "values": [
                { "formattedValue": "...",
                  "userEnteredValue": {...},
                  "effectiveValue": {...} }
            ]}    // an empty cell is {}, a trailing one absent
          ]
        }
      ]
    }
  ],
  "namedRanges": [...]
}
```

Useful `jq` paths:

```jq
.properties.title
.sheets[].properties.title                              # tab names
.sheets[0].data[0].rowData[].values[].formattedValue    # cell strings
.namedRanges[]
```

Delete, on a `write` path:

```sh
rm /<path>/owned/<file>.gsheet.json   # deletes it from Drive for good
rm -f <path>                       # ignores a missing file
```

Only `.gsheet.json` files can be removed; `owned/` and `shared/` cannot.

Rename to a new title, on a `write` path:

```sh
mv /<path>/owned/<date>_<old>__<id>.gsheet.json \
   /<path>/owned/<date>_<new>__<id>.gsheet.json
```

Keep the folder, the date and the id, and spell the title the way the
listing does (spaces become `_`); any other name is refused.

## Supported Unix Commands for VFS

Unix commands work on each path as on a local filesystem, as far as the path supports them:

| Path | Supported |
| --- | --- |
| `/<path>` | Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest), and `mv`, `rm` and `unlink`. `grep -r` and `rg` with `-w` ask `gsheets` which files may match. |

## Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

| Path | Limitations |
| --- | --- |
| `/<path>` | Not supported: `>`, `>>`, `tee`, `tee -a`, `touch` of a new file, `cp`, `cp -r`, `mkdir`, `rm -r`, `rmdir`, `truncate`, `sed -i`. Without `-w`, `grep -r` and `rg` read every file. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |

Run `man <cmd>` or `<cmd> --help` for one command's usage.

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.

Shared Drives

The listing covers every corpus the account can reach, so a spreadsheet that lives in a Shared Drive appears here too. A Shared Drive spreadsheet has no owner (the drive owns it), so it lands under shared, which is what that directory means. This matches the gdrive mount, where Shared Drives are top-level directories: without it the same account would see a spreadsheet under one Google mount and not the other, with no error explaining the difference. Drive answers an all-corpora search best-effort. When it reports that it skipped a corpus, the short listing is still returned but is not cached as the directory, so the next ls re-lists instead of serving the gap until the cache expires.

Cache

The Google Sheets VFS uses IndexCacheStore. Index entries store spreadsheet IDs and metadata. File bytes go through the workspace file cache; a rendered read through FUSE, ws.vfs, a < file redirect or a cross-mount cp, sed or diff is not cached.

Example

import asyncio
import os

from dotenv import load_dotenv

from mirage import MountMode, Workspace
from mirage.commands.cli.builtin.gws import GWS
from mirage.vfs.gsheets import GSheetsConfig, GSheetsVFS

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"],
)
vfs = GSheetsVFS(config=config)


async def main():
    ws = Workspace({"/gsheets": vfs}, mode=MountMode.READ)
    ws.register_cli("gws", GWS, config)

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

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

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

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

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

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

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

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

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


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

See examples/python/vfs/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
`mv`	Retitle a spreadsheet (`MountMode.WRITE`)
`rm`	Delete a spreadsheet (`MountMode.WRITE`)

Integration

What Google Sheets answers through its own API, so fewer files are read. Integration explains each command.

Command	On Google Sheets
`grep -r`, `rg`	Drive full-text search, for whole words. It can miss words only in non-text values (formulas, the time zone, sheet titles, links and ids).

grep -rw and rg -w read only the spreadsheets Drive full-text search names; every one is read when the search fails or finds nothing. A word the rendered JSON may hold whatever the text says is never asked: one with a digit, a property name or enum value of the Sheets API (formattedValue, NUMBER), or a word every rendering carries (https, arial). walk_limit: -1 in the mount’s "@all" command limit reads every file instead, since Drive indexes a write some time after it lands and searches the file’s text, so one whose JSON holds the word only in another value (a formula, the time zone, a sheet title, a link or an id) can be left out. Acting on spreadsheets (read/write/append ranges, raw API calls) goes through the gws CLI when installed.

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Config

VFS.md

Virtual Filesystem

VFS Layout

`/<path>`

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Shared Drives

Cache

Example

Shell Commands

Integration

​Config

​VFS.md

​Virtual Filesystem

​VFS Layout

/<path>

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Shared Drives

​Cache

​Example

​Shell Commands

​Integration

Config

VFS.md

Virtual Filesystem

VFS Layout

`/<path>`

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Shared Drives

Cache

Example

Shell Commands

Integration