Skip to main content
The Google Docs resource exposes Docs documents as a virtual filesystem mounted at some prefix such as /gdocs/. For Google OAuth setup, see Google Workspace Setup.

​
Config

import os

from mirage import MountMode, Workspace
from mirage.resource.gdocs import GDocsConfig, GDocsResource

config = GDocsConfig(
    client_id=os.environ["GOOGLE_CLIENT_ID"],
    client_secret=os.environ["GOOGLE_CLIENT_SECRET"],
    refresh_token=os.environ["GOOGLE_REFRESH_TOKEN"],
)
resource = GDocsResource(config=config)
ws = Workspace({"/gdocs": resource}, mode=MountMode.READ)

​
Filesystem Layout

/gdocs/
  owned/
    <YYYY-MM-DD>_<sanitized-title>__<doc-id>.gdoc.json
    ...
  shared/
    <YYYY-MM-DD>_<sanitized-title>__<doc-id>.gdoc.json
    ...
Example: 
/gdocs/
  owned/
    2026-04-04_Project_Plan__1AbCdEf.gdoc.json
    2026-04-10_Meeting_Notes__2BcDeFg.gdoc.json
  shared/
    2026-04-03_Design_Notes__9XyZ.gdoc.json
Documents are split into owned (documents you created) and shared (documents shared with you). The filename shape is: 
<YYYY-MM-DD>_<sanitized-title>__<document-id>.gdoc.json
If the modified date is unavailable, the date prefix is omitted. Reading a document file returns the full Google Docs API JSON for that document.

​
Cache

The Google Docs resource uses IndexCacheStore. Index entries store document IDs and metadata. There is no separate content cache — file content caching is handled by the workspace IOResult mechanism.

​
Example

import asyncio
import os

from dotenv import load_dotenv

from mirage import MountMode, Workspace
from mirage.resource.gdocs import GDocsConfig, GDocsResource

load_dotenv(".env.development")

config = GDocsConfig(
    client_id=os.environ["GOOGLE_CLIENT_ID"],
    client_secret=os.environ["GOOGLE_CLIENT_SECRET"],
    refresh_token=os.environ["GOOGLE_REFRESH_TOKEN"],
)
resource = GDocsResource(config=config)


async def main():
    ws = Workspace({"/gdocs": resource}, mode=MountMode.READ)

    # List structure
    r = await ws.execute("ls /gdocs/")
    print(await r.stdout_str())

    # List owned documents
    r = await ws.execute("ls /gdocs/owned/")
    print(await r.stdout_str())

    # Read a document
    r = await ws.execute(
        "cat /gdocs/owned/2026-04-04_Project_Plan__1AbCdEf.gdoc.json")
    print(await r.stdout_str())

    # Extract title with jq
    r = await ws.execute(
        'jq ".title"'
        " /gdocs/owned/2026-04-04_Project_Plan__1AbCdEf.gdoc.json")
    print(await r.stdout_str())

    # Search across all documents
    r = await ws.execute('rg "quarterly" /gdocs/owned/')
    print(await r.stdout_str())

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

    # Create a new document
    r = await ws.execute(
        'gws-docs-documents-create --json \'{"title":"MIRAGE Example Doc"}\'')
    print(await r.stdout_str())

    # Append text to a document
    r = await ws.execute(
        'gws-docs-write --document 1AbCdEf --text "Appended via MIRAGE."')
    print(await r.stdout_str())


if __name__ == "__main__":
    asyncio.run(main())
See examples/gdocs/gdocs.py for the full working example.

​
Shell Commands

Standard commands available on the mounted Google Docs tree:
CommandNotes
lsList owned/shared documents
catRead document JSON
head / tailFirst/last N lines
grep / rgPattern search
jqQuery JSON fields
wcLine/word/byte counts
statFile metadata
findRecursive search
treeDirectory tree view
basename / dirname / realpathPath utilities
nlNumber lines
Resource-specific commands:

​
gws-docs-documents-create

Create a new Google Docs document. 
gws-docs-documents-create --json '{"title":"MIRAGE Example Doc"}'
OptionRequiredDescription
--jsonyesJSON body with title field
Returns the created document JSON.

​
gws-docs-documents-batchUpdate

Batch update a document. 
gws-docs-documents-batchUpdate --params '{"documentId":"1AbCdEf"}' --json '{"requests":[]}'
OptionRequiredDescription
--paramsyesJSON with documentId
--jsonyesJSON with requests array
Returns the batch update response JSON.

​
gws-docs-write

Append text to a document. 
gws-docs-write --document 1AbCdEf --text "Appended via MIRAGE."
OptionRequiredDescription
--documentyesGoogle document ID
--textyesText to append
Returns the update response JSON.