> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Docs

> Virtualize Google Docs documents from Node or the browser.

`GDocsVFS` mounts the Google Docs an account can see: each document becomes a
`.gdoc.json` file holding the Docs API's JSON, split into the documents it owns
and those shared with it. Set up the credentials as in [Google Workspace setup](https://docs.mirage.strukto.ai/home/setup/google.md).

## Install

```bash theme={null}
npm install @struktoai/mirage-node
```

## Configure

```ts theme={null}
import { GDocsVFS, MountMode, Workspace } from '@struktoai/mirage-node'

const docs = new GDocsVFS({
  clientId: process.env.GOOGLE_CLIENT_ID!,
  clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
  refreshToken: process.env.GOOGLE_REFRESH_TOKEN!,
})
const ws = new Workspace({ '/gdocs': docs }, { mode: MountMode.READ })

const result = await ws.shell("ls /gdocs/owned && jq -r '.title' /gdocs/owned/2026-*.gdoc.json")
console.log(result.stdoutText)
await ws.close()
```

`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

**timeout** `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.

**accessToken** `string | function`

OAuth access token, or a function (sync or async) that returns one. Takes precedence over `clientId` and `refreshToken`.

**clientId** `string`

Google OAuth client ID. Required with `refreshToken` when `accessToken` is unset; mirage then mints and renews access tokens itself.

**clientSecret** `string`

Google OAuth client secret, sent with the refresh-token grant. Omit it for a PKCE client.

**refreshToken** `string`

User's OAuth refresh token. Required with `clientId` when `accessToken` is unset.

**refreshFn** `function`

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** `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 Docs API with the
`https://www.googleapis.com/auth/documents` 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

```text theme={null}
/gdocs/
  owned/
    2026-11-14_Meeting_Notes__1Xk9rT2bQ.gdoc.json
  shared/
    2026-10-02_Design_Review__1Pq7sV4mN.gdoc.json
```

* `owned/` holds the documents the account owns, shared or not; `shared/`
  holds those others shared with it.
* A file is named `<YYYY-MM-DD>_<title>__<document-id>.gdoc.json`. The date
  is the last modified day and is left out when Drive gives none.
* A file holds the Docs API's JSON for the document, with every tab.

## Behavior

* **Shared Drives:** a document 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 documents 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 document for good, not to
  the trash. `owned/` and `shared/` cannot be removed.
* **Edits:** writing text into a document, and raw API calls, go through the
  [`gws`](https://docs.mirage.strukto.ai/typescript/cli/gws) CLI.

## Browser

The same `GDocsVFS` 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.

```bash theme={null}
npm install @struktoai/mirage-browser
```

```ts theme={null}
import { GDocsVFS, MountMode, Workspace } from '@struktoai/mirage-browser'

const docs = new GDocsVFS({
  accessToken: async () => (await fetch('/api/google-token')).text(),
})
const ws = new Workspace({ '/gdocs': docs }, { mode: MountMode.READ })
```

* `/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. `examples/browser/vfs/gdocs/gdocs_pkce.ts` shows the sign-in
  flow.
* `refreshFn` sends each refresh to a backend instead of Google's token
  endpoint.

## Integration

Google Docs answers these commands through its own API, so fewer files are
read. See [Integration](https://docs.mirage.strukto.ai/home/integration/overview.md).

* `grep -r` and `rg` with `-w`: Drive full-text search names the documents to
  read. Every one is read when the search fails or finds nothing, and when
  the word may be in any document's JSON whatever the text says: a word with
  a digit, a Docs API name or value (`paragraph`, `NORMAL_TEXT`), or a word
  every document carries (`https`, `arial`). Drive indexes a write some time
  after it lands and searches the document'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 tab title, an id) or only inside a word that styling splits
  (`snow` in bold inside `snowman`). `walkLimit: -1` in the mount's
  `"@all"` [command limit](https://docs.mirage.strukto.ai/home/limits.md#command-output) turns the search off and
  reads every file.

## VFS.md

The [VFS.md](https://docs.mirage.strukto.ai/home/setup/vfs-md.md) an agent reads with Google Docs mounted at
`/<path>`. `<mode>` is the mount's mode: `read`, `write` or `exec`. The
commands shown are those of a `write` mount.

> [tab] Rendered
>
> **Virtual Filesystem**
>
> | Path | Description |
> | - | - |
> | `/<path>` | `gdocs`, `<mode>` |
>
> **VFS Layout**
>
> **`/<path>`**
>
> ```text theme={null}
> /<path>
>   owned/     # docs you created
>     <YYYY-MM-DD>_<title>__<doc-id>.gdoc.json
>   shared/    # docs others shared with you
>     <YYYY-MM-DD>_<title>__<doc-id>.gdoc.json
> ```
>
> * `<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 docs others shared; docs owned and shared out stay
>   in `owned/`.
> * A file is the Docs API `documents.get` response with every tab under
>   `.tabs[].documentTab`, nested through `.childTabs`; there is no
>   top-level `.body`. 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 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 `gdocs` 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.

> [tab] Raw
>
> ````markdown theme={null}
> ---
> name: workspace-filesystem
> description: The virtual filesystem layout of this workspace.
> ---
>
> # Virtual Filesystem
>
> | Path | Description |
> | --- | --- |
> | `/<path>` | `gdocs`, `<mode>` |
>
> ## VFS Layout
>
> ### `/<path>`
>
> ```text
> /<path>
>   owned/     # docs you created
>     <YYYY-MM-DD>_<title>__<doc-id>.gdoc.json
>   shared/    # docs others shared with you
>     <YYYY-MM-DD>_<title>__<doc-id>.gdoc.json
> ```
>
> - `<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 docs others shared; docs owned and shared out stay
>   in `owned/`.
> - A file is the Docs API `documents.get` response with every tab under
>   `.tabs[].documentTab`, nested through `.childTabs`; there is no
>   top-level `.body`. 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 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 `gdocs` 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.
> ````


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.