Google Slides

The Google Slides VFS exposes presentations as a virtual filesystem mounted at some prefix such as /gslides/. For Google OAuth setup, see Google Workspace Setup.

Config

import os

from mirage import MountMode, Workspace
from mirage.vfs.gslides import GSlidesConfig, GSlidesVFS

config = GSlidesConfig(
    client_id=os.environ["GOOGLE_CLIENT_ID"],
    client_secret=os.environ["GOOGLE_CLIENT_SECRET"],
    refresh_token=os.environ["GOOGLE_REFRESH_TOKEN"],
)
vfs = GSlidesVFS(config=config)
ws = Workspace({"/gslides": 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 Slides mounted at /<path>.

Rendered
Raw

Virtual Filesystem

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

`/<path>` layout

/<path>
  owned/
    <date>_<title>__<presentation-id>.gslide.json
  shared/
    <date>_<title>__<presentation-id>.gslide.json

  Filename: <YYYY-MM-DD>_<title>__<presentation-id>.gslide.json
    <YYYY-MM-DD>       modifiedTime, used for date-glob (e.g. 2026-05-*)
    <title>            sanitized: spaces->_, non-[A-Za-z0-9_.-]->_, <=100 chars
    <presentation-id>  Google Slides presentation ID

  Buckets:
    owned/   presentations you created
    shared/  presentations shared with you by others
             - does NOT include presentations you own and shared with others;
               those are still in owned/.

  gslide.json structure (matches the Google Slides API presentations.get response):
    {
      "presentationId": "...",
      "title": "...",
      "pageSize": { "width": {...}, "height": {...} },
      "slides": [
        {                                      # one element per slide
          "objectId": "...",
          "pageElements": [
            {
              "objectId": "...",
              "shape": {
                "shapeType": "TEXT_BOX",
                "text": {
                  "textElements": [
                    { "textRun": { "content": "the actual text\n",
                                   "style": {...} } }
                  ]
                }
              }
            },
            { "image": {...} },
            { "table": {...} }
          ]
        }
      ],
      "masters": [...],
      "layouts": [...]
    }

  Useful jq paths:
    .title
    .slides | length                                                    # slide count
    .slides[].pageElements[].shape.text.textElements[].textRun.content  # all text
    .slides[0].objectId

  Delete, on a `write` path:
    rm /<path>/owned/<file>.gslide.json     # permanent delete from Drive
    rm -f <path>                             # ignore if missing
    Only operates on .gslide.json files; owned/ and shared/ themselves
    cannot be removed.

  Rename to a new title, on a `write` path:
    mv /<path>/owned/<date>_<old>__<id>.gslide.json \
       /<path>/owned/<date>_<new>__<id>.gslide.json
    Keep the folder, the date and the id, and spell the title the way
    the listing does (spaces->_); 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 `gslides` 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>` | `gslides`, write |

## `/<path>` layout

```text
/<path>
  owned/
    <date>_<title>__<presentation-id>.gslide.json
  shared/
    <date>_<title>__<presentation-id>.gslide.json

  Filename: <YYYY-MM-DD>_<title>__<presentation-id>.gslide.json
    <YYYY-MM-DD>       modifiedTime, used for date-glob (e.g. 2026-05-*)
    <title>            sanitized: spaces->_, non-[A-Za-z0-9_.-]->_, <=100 chars
    <presentation-id>  Google Slides presentation ID

  Buckets:
    owned/   presentations you created
    shared/  presentations shared with you by others
             - does NOT include presentations you own and shared with others;
               those are still in owned/.

  gslide.json structure (matches the Google Slides API presentations.get response):
    {
      "presentationId": "...",
      "title": "...",
      "pageSize": { "width": {...}, "height": {...} },
      "slides": [
        {                                      # one element per slide
          "objectId": "...",
          "pageElements": [
            {
              "objectId": "...",
              "shape": {
                "shapeType": "TEXT_BOX",
                "text": {
                  "textElements": [
                    { "textRun": { "content": "the actual text\n",
                                   "style": {...} } }
                  ]
                }
              }
            },
            { "image": {...} },
            { "table": {...} }
          ]
        }
      ],
      "masters": [...],
      "layouts": [...]
    }

  Useful jq paths:
    .title
    .slides | length                                                    # slide count
    .slides[].pageElements[].shape.text.textElements[].textRun.content  # all text
    .slides[0].objectId

  Delete, on a `write` path:
    rm /<path>/owned/<file>.gslide.json     # permanent delete from Drive
    rm -f <path>                             # ignore if missing
    Only operates on .gslide.json files; owned/ and shared/ themselves
    cannot be removed.

  Rename to a new title, on a `write` path:
    mv /<path>/owned/<date>_<old>__<id>.gslide.json \
       /<path>/owned/<date>_<new>__<id>.gslide.json
    Keep the folder, the date and the id, and spell the title the way
    the listing does (spaces->_); 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 `gslides` 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.

/gslides/
  owned/
    <YYYY-MM-DD>_<sanitized-title>__<presentation-id>.gslide.json
    ...
  shared/
    <YYYY-MM-DD>_<sanitized-title>__<presentation-id>.gslide.json
    ...

Example:

/gslides/
  owned/
    2026-04-04_QBR_Deck__1AbCdEf.gslide.json
    2026-04-10_Team_Update__2BcDeFg.gslide.json
  shared/
    2026-04-03_Design_Review__9XyZ.gslide.json

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

<YYYY-MM-DD>_<sanitized-title>__<presentation-id>.gslide.json

If the modified date is unavailable, the date prefix is omitted. Reading a presentation file returns the full Google Slides API JSON for that presentation.

Shared Drives

The listing covers every corpus the account can reach, so a presentation that lives in a Shared Drive appears here too. A Shared Drive presentation 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 presentation 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 Slides VFS uses IndexCacheStore. Index entries store presentation 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.gslides import GSlidesConfig, GSlidesVFS

load_dotenv(".env.development")

config = GSlidesConfig(
    client_id=os.environ["GOOGLE_CLIENT_ID"],
    client_secret=os.environ["GOOGLE_CLIENT_SECRET"],
    refresh_token=os.environ["GOOGLE_REFRESH_TOKEN"],
)
vfs = GSlidesVFS(config=config)


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

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

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

    # Read a presentation
    r = await ws.shell(
        "cat /gslides/owned/2026-04-04_QBR_Deck__1AbCdEf.gslide.json")
    print(await r.stdout_str())

    # Extract title with jq
    r = await ws.shell(
        'jq ".title"'
        " /gslides/owned/2026-04-04_QBR_Deck__1AbCdEf.gslide.json")
    print(await r.stdout_str())

    # Search across all presentations
    r = await ws.shell('rg "quarterly" /gslides/owned/')
    print(await r.stdout_str())

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

    # Create a new presentation
    r = await ws.shell(
        'gws slides presentations create --json \'{"title":"MIRAGE Deck"}\'')
    print(await r.stdout_str())

    # Batch update a presentation
    r = await ws.shell(
        'gws slides presentations batchUpdate'
        ' --params \'{"presentationId":"1AbCdEf"}\''
        ' --json \'{"requests":[]}\'')
    print(await r.stdout_str())


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

See examples/python/vfs/gslides/gslides.py for the full working example.

Shell Commands

Standard commands available on the mounted Google Slides tree:

Command	Notes
`ls`	List owned/shared presentations
`cat`	Read presentation 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 presentation (`MountMode.WRITE`)
`rm`	Delete a presentation (`MountMode.WRITE`)

Integration

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

Command	On Google Slides
`grep -r`, `rg`	Drive full-text search, for whole words. It can miss words only in non-text values (fonts, links, layout names and ids) or split by styling.

grep -rw and rg -w read only the presentations 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 Slides API (pageElements, SLIDE), 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 font, a link or image address, a layout name or an id), or only as part of a word styling splits into text runs (snow bold in snowman), can be left out. Acting on presentations (create, batchUpdate, raw API calls) goes through the gws CLI when installed.

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Config

VFS.md

Virtual Filesystem

`/<path>` layout

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Shared Drives

Cache

Example

Shell Commands

Integration

​Config

​VFS.md

​Virtual Filesystem

​/<path> layout

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Shared Drives

​Cache

​Example

​Shell Commands

​Integration

Config

VFS.md

Virtual Filesystem

`/<path>` layout

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Shared Drives

Cache

Example

Shell Commands

Integration