gws-reader

Google Workspace Reader

Read files from Google Drive and convert their content to clean markdown. Supports Google Docs, Sheets, and Slides. Searches across all Drives including Shared Drives.

When to Use

• User asks to read, view, or fetch a Google Doc, Sheet, or Slides file
• User asks to search or find files on Google Drive
• /ckw:drive command needs to search or read files
• /ckw:import-reference --from-drive needs to fetch content before importing
• Any CKW agent needs Google Workspace content as context

Prerequisites

Check 1: gws CLI installed

which gws

If not found:

The Google Workspace CLI (gws) is required but isn't installed.

Install:
  npm install -g @googleworkspace/cli

Then authenticate:
  gws auth setup
  gws auth login

After setup, run this command again.

Stop here — do not attempt any operations without gws.

Check 2: Authentication valid

gws drive files list --params '{"pageSize": 1}' 2>&1

If the response contains "401" or "authError":

Your Google Workspace session has expired. Re-authenticate:
  gws auth login

Then try again.

Stop here — do not attempt operations with expired auth.

Mode: Search

Find files by name across all Drives (including Shared Drives).

Step 1: Execute search

gws drive files list --params '{"q": "name contains '\''SEARCH_TERM'\''", "includeItemsFromAllDrives": true, "supportsAllDrives": true, "corpora": "allDrives", "pageSize": 10, "fields": "files(id,name,mimeType,modifiedTime,parents)"}'

To search within a specific Shared Drive (if user specifies):

gws drive files list --params '{"q": "name contains '\''SEARCH_TERM'\''", "driveId": "DRIVE_ID", "includeItemsFromAllDrives": true, "supportsAllDrives": true, "corpora": "drive", "pageSize": 10, "fields": "files(id,name,mimeType,modifiedTime,parents)"}'

To list available Shared Drives:

gws drive drives list

Escaping apostrophes: if SEARCH_TERM contains an apostrophe, escape it as \' inside the query (e.g., O'Brien → O\'Brien) — otherwise the Drive q string terminates early and the search fails or returns wrong results.