Skip to main content
One OAuth client and refresh token cover every Google mount and the gws CLI. Drive becomes its folder tree, Docs, Sheets and Slides become JSON files, and Gmail becomes folders of labels and days. Google Calendar uses the same credentials.

Setup

Create a Google Cloud project, turn on the APIs, configure the consent screen, create a Desktop OAuth client and trade one sign-in for a refresh token.
  1. Open the Google Cloud console.
  2. Open the project selector and click New Project.
  3. Name it (for example “Mirage”) and click Create.
  4. Select the new project in the selector.
In the API Library, enable the API for each service in use:
  • Keep the Drive API and scope for every Google file mount.
  • The gws create commands also need Drive to place new files inside a configured folder.
  • For read-only use, pick the matching read-only scopes.
The OAuth settings live under Google Auth Platform in the console sidebar (overview).
  1. Branding: enter an app name (for example “Mirage”), a support email and a developer contact email, then save.
  2. Audience: set the user type to External and add the Google account that will sign in as a test user, then save.
  3. Data Access: click Add or Remove Scopes, add the scopes from step 2, then save.
  1. Open Clients in the sidebar (or Create OAuth client on the Overview page).
  2. Set the application type to Desktop app.
  3. Name it and click Create.
  4. Copy the Client ID and Client Secret.
Open this URL in a browser. Replace YOUR_CLIENT_ID and put the scopes from step 2 in scope, separated by %20. This one asks for Drive and Docs:
  • access_type=offline asks for a refresh token.
  • prompt=consent issues a new refresh token on every sign-in.
Sign in, click through the “unverified app” warning and grant access. The browser then goes to http://localhost:1/?code=4/0A..., a page that does not load. Copy the code value from the address bar and exchange it right away:
The JSON reply holds refresh_token. Save it.
  • Setup works in Testing. To publish, open Audience and click Publish App.
  • Mirage trades the refresh token for short-lived access tokens on its own.
  • A refresh token can still be revoked or expire; sign in again when that happens. See Google’s token expiration notes.

Connect

workspace.yaml

Layout

  • /gdrive mirrors My Drive plus one folder per Shared Drive. Docs, Sheets and Slides there read as .gdoc.json, .gsheet.json and .gslide.json.
  • /gdocs, /gsheets and /gslides split files into owned/ and shared/, named <date>_<title>__<id>, holding the API’s JSON.
  • /gmail is read only: one folder per label and day, a .gmail.json per message and a folder of its attachments.

Sample runs

On a write mount, Drive takes cp, mv, rm, mkdir and tee on regular files; a Docs, Sheets or Slides file is read only as bytes, and /gdocs, /gsheets and /gslides take mv (rename) and rm. Edit their content with the gws CLI, which also covers Forms.

SDK guides

Drive (Python)

Every config field, the VFS.md and write support.

Drive (TypeScript)

Every config field, the VFS.md and write support.

Docs (Python)

Every config field, the VFS.md and write support.

Docs (TypeScript)

Every config field, the VFS.md and write support.

Sheets (Python)

Every config field, the VFS.md and write support.

Sheets (TypeScript)

Every config field, the VFS.md and write support.

Slides (Python)

Every config field, the VFS.md and write support.

Slides (TypeScript)

Every config field, the VFS.md and write support.

Gmail (Python)

Every config field, the VFS.md and write support.

Gmail (TypeScript)

Every config field, the VFS.md and write support.