Google Slides

GSlidesVFS exposes Slides decks as .gslide.json files containing the deck structure, slides, and text content. Setup steps for OAuth credentials live at Google Workspace Credentials.

Node

pnpm add @struktoai/mirage-node

import { GSlidesVFS, MountMode, Workspace } from '@struktoai/mirage-node'

const slides = new GSlidesVFS({
  clientId: process.env.GOOGLE_CLIENT_ID!,
  clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
  refreshToken: process.env.GOOGLE_REFRESH_TOKEN!,
})

const ws = new Workspace({ '/slides': slides }, { mode: MountMode.READ })
await ws.shell('ls /slides/owned/')

Browser

pnpm add @struktoai/mirage-browser

import { GSlidesVFS, MountMode, Workspace } from '@struktoai/mirage-browser'

const slides = new GSlidesVFS({
  clientId: GOOGLE_CLIENT_ID,
  clientSecret: GOOGLE_CLIENT_SECRET,
  refreshToken: localStorage.getItem('gslides.refresh_token')!,
})

Config

Field	Description
`timeout` default `DEFAULT_TIMEOUT`	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.
`accessToken` secret	OAuth access token, or a function (sync or async) that returns one. Takes precedence over `clientId` and `refreshToken`.
`clientId`	Google OAuth client ID. Required with `refreshToken` when `accessToken` is unset; mirage then mints and renews access tokens itself.
`clientSecret` secret	Google OAuth client secret, sent with the refresh-token grant. Omit it for a PKCE client.
`refreshToken` secret	User’s OAuth refresh token. Required with `clientId` when `accessToken` is unset.
`refreshFn` secret	Function that exchanges the refresh token for `{ accessToken, expiresIn }` instead of Google’s token endpoint, so the client secret can stay on a backend. Still needs `clientId` and `refreshToken`.
`apiBase`	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.

Mount mode

read. A MountMode.WRITE mount also allows mv (retitle) and rm (delete). Edit a deck with the gws CLI. For the JSON structure (slides, layouts, text frames) see the Python Slides docs.

VFS.md

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

Rendered
Raw

Virtual Filesystem

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

VFS Layout

`/<path>`

/<path>
  owned/     # presentations you created
    <YYYY-MM-DD>_<title>__<presentation-id>.gslide.json
  shared/    # presentations others shared with you
    <YYYY-MM-DD>_<title>__<presentation-id>.gslide.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.
<presentation-id> is the Google Slides presentation id.
shared/ holds presentations shared with you by others; ones you own and shared with others are still in owned/.

A .gslide.json 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   # deletes it from Drive for good
rm -f <path>                       # ignores a missing file

Only .gslide.json files can be removed; owned/ and shared/ cannot.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 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 `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 |

## VFS Layout

### `/<path>`

```text
/<path>
  owned/     # presentations you created
    <YYYY-MM-DD>_<title>__<presentation-id>.gslide.json
  shared/    # presentations others shared with you
    <YYYY-MM-DD>_<title>__<presentation-id>.gslide.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.
- `<presentation-id>` is the Google Slides presentation id.
- `shared/` holds presentations shared with you by others; ones you own
  and shared with others are still in `owned/`.

A `.gslide.json` matches the Google Slides API `presentations.get`
response:

```jsonc
{
  "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:

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

Delete, on a `write` path:

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

Only `.gslide.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>.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 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 `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.

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.

The Python Google Slides docs list when each search answers and what it can miss.

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Node

Browser

Config

Mount mode

VFS.md

Virtual Filesystem

VFS Layout

`/<path>`

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Integration

​Node

​Browser

​Config

​Mount mode

​VFS.md

​Virtual Filesystem

​VFS Layout

/<path>

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Integration

Node

Browser

Config

Mount mode

VFS.md

Virtual Filesystem

VFS Layout

`/<path>`

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Integration