gdrive-fetcher

Reusable CLI for fetching configured Google Drive files, folders, and Gmail messages.

Setup

Create the Google client app

This CLI uses a local OAuth desktop flow because it reads user-owned Google Drive and Gmail data with your consent.

1. Open the Google Cloud console and create or select a project.
2. Go to APIs & Services > Library and enable the APIs you need:
   • Google Drive API: required for Drive file metadata, folder traversal, file downloads, and Google Sheets export.
   • Google Docs API: required when Google Docs are converted to Markdown.
   • Gmail API: required for emailSyncs.
3. Go to Google Auth Platform or APIs & Services > OAuth consent screen and configure the consent screen:
   • Use Internal if this is only for your Google Workspace organization.
   • Use External for personal Gmail accounts or users outside your org.
   • Add yourself as a test user if the app is external and still in testing.
4. Go to Google Auth Platform > Clients or APIs & Services > Credentials.
5. Create an OAuth client:
   • Application type: Desktop app
   • Name: any local label, such as gdrive-fetcher
6. Download the OAuth client JSON.

Google's own setup docs cover the same flow for Workspace OAuth credentials, Drive API quickstarts, and Gmail API quickstarts.

Save credentials and log in

gdrive-fetcher set-console-app --file ./google-oauth-client.json
gdrive-fetcher login

Credentials are stored under ~/.config/gdrive-fetcher/.

If you already logged in before adding Gmail targets, run gdrive-fetcher login --force once so the cached token includes Gmail readonly access.

Config

Create gdrive-fetcher.config.json:

{
  "fileSyncs": [
    {
      "key": "budget",
      "name": "Budget",
      "fileId": "https://docs.google.com/spreadsheets/d/example/edit",
      "outputPath": "data/Budget.xlsx"
    }
  ],
  "folderSyncs": [
    {
      "key": "notes",
      "name": "Notes",
      "driveFolderId": "https://drive.google.com/drive/folders/example",
      "outputDir": "notes",
      "recursive": true
    }
  ],
  "emailSyncs": [
    {
      "key": "sales-emails",
      "name": "Sales Emails",
      "query": "label:sales newer_than:1y",
      "outputDir": "emails/sales",
      "format": "md",
      "maxResults": 500
    }
  ]
}

Usage

gdrive-fetcher fetch --config ./gdrive-fetcher.config.json
gdrive-fetcher fetch --only budget,notes
gdrive-fetcher fetch --files-only
gdrive-fetcher fetch --folders-only
gdrive-fetcher fetch --emails-only

Google Docs are saved as Markdown, Google Sheets are exported as .xlsx, and uploaded Drive files are downloaded as-is. Gmail messages can be saved as .eml or .md by setting format; eml is the default. Unsupported Google-native files are skipped with a warning.