Skip to main content
GSlidesVFS mounts the Google Slides an account can see: each presentation becomes a .gslide.json file holding the Slides API’s JSON, split into the presentations it owns and those shared with it. Set up the credentials as in Google Workspace setup.

Install

Configure

accessToken replaces the client and refresh token with a token or a function that returns one. A MountMode.WRITE mount also allows mv and rm.

Fields

number
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.
string | function
secret
OAuth access token, or a function (sync or async) that returns one. Takes precedence over clientId and refreshToken.
string
Google OAuth client ID. Required with refreshToken when accessToken is unset; mirage then mints and renews access tokens itself.
string
secret
Google OAuth client secret, sent with the refresh-token grant. Omit it for a PKCE client.
string
secret
User’s OAuth refresh token. Required with clientId when accessToken is unset.
function
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.
string
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.

Authentication

Credentials come from the first of:
  1. accessToken, a token or a function, sync or async, that returns one.
  2. clientId and refreshToken, with clientSecret unless the client uses PKCE. Mirage trades the refresh token for access tokens on its own, or hands it to refreshFn when set, so the secret can stay on a backend.
The mount needs the Google Slides API with the https://www.googleapis.com/auth/presentations scope, and the Drive API with the https://www.googleapis.com/auth/drive scope, since the listing comes from Drive. A read-only mount can use the readonly variants of both scopes.

Layout

  • owned/ holds the presentations the account owns, shared or not; shared/ holds those others shared with it.
  • A file is named <YYYY-MM-DD>_<title>__<presentation-id>.gslide.json. The date is the last modified day and is left out when Drive gives none.
  • A file holds the Slides API’s JSON for the presentation: its slides, layouts and text.

Behavior

  • Shared Drives: a presentation in a Shared Drive has no owner, so it is listed under shared/, as on the gdrive mount.
  • Date globs: a glob on the date prefix, such as 2026-05-*, asks Drive only for the presentations modified on those days.
  • Incomplete listings: Drive may skip part of the account’s files and say so. The short listing is still shown, and the next ls lists again.
  • Rename: on a write mount, mv to a new name in the same folder changes the title. The date and the id must stay, and the title is spelled as the listing spells it (spaces become _).
  • Delete: on a write mount, rm deletes the presentation for good, not to the trash. owned/ and shared/ cannot be removed.
  • Edits: creating presentations, batch updates and raw API calls go through the gws CLI.

Browser

The same GSlidesVFS comes from @struktoai/mirage-browser. In a page, an accessToken function fetches a fresh token from a backend, so the client secret never reaches the browser.
  • /api/google-token stands for a backend endpoint that returns an access token.
  • A PKCE OAuth client needs no secret: clientId and refreshToken alone mount it.
  • refreshFn sends each refresh to a backend instead of Google’s token endpoint.

Integration

Google Slides answers these commands through its own API, so fewer files are read. See Integration.
  • grep -r and rg with -w: Drive full-text search names the presentations to read. Every one is read when the search fails or finds nothing, and when the word may be in any presentation’s JSON whatever the text says: a word with a digit, a Slides API name or value (pageElements, SLIDE), or a word every presentation carries (https, arial). Drive indexes a write some time after it lands and searches the presentation’s text, so it can leave out one whose JSON holds the word only in another value (a font, a link or image address, a layout name, an id) or only inside a word that styling splits (snow in bold inside snowman). walkLimit: -1 in the mount’s "@all" command limit turns the search off and reads every file.

VFS.md

The VFS.md an agent reads with Google Slides mounted at /<path>. <mode> is the mount’s mode: read, write or exec. The commands shown are those of a write mount.
Virtual FilesystemVFS Layout/<path>
  • <YYYY-MM-DD> is the file’s modifiedTime, so a date glob such as 2026-05-* narrows the query; <title> turns spaces and characters outside [A-Za-z0-9_.-] into _, at most 100 characters.
  • shared/ holds presentations others shared; presentations owned and shared out stay in owned/.
  • A file is the Slides API presentations.get response, one .slides[] entry per slide. All text: [.. | .textRun? // empty | .content] | add.
  • On a write path, rm a file to delete it from Drive, or mv it to a new <title> with the same folder, date and id to rename it.
Supported Unix Commands for VFSUnix commands work on each path as on a local filesystem, as far as the path supports them:Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:Run man <cmd> or <cmd> --help for one command’s usage.