Google Drive

Google Drive

Use gws drive to search, list, upload, download, copy, and share files and folders, plus manage shared drives, permissions, and revisions. The CLI wraps the Drive v3 API.

Prerequisites

• If this deployment is managed/hosted, the Google credential is already provisioned at sign-in — gws is installed and authenticated, so skip the setup flow below and run gws directly. Scopes are fixed at sign-in on a managed deployment: when a call fails with scope required or HTTP 401, tell the user which action needs a scope their account wasn't granted, instead of trying to set anything up. (The scope list below still describes which verb needs which scope.)
• gws installed and authenticated. If gws is not on PATH OR gws auth status reports no authenticated user, do NOT silently call setup. Instead, in a single short reply to the user:
  1. State plainly what's missing — e.g. "Google Workspace access isn't set up on this machine yet" or "your Google sign-in has expired."
  2. Ask one sentence: "Want me to walk you through setting it up?" Wait for the user's answer.
  3. If they say yes, call read_skill with name google-workspace-setup and run that skill's onboarding flow turn-by-turn. If they say no or ask to defer, acknowledge briefly and stop — do not retry the original request.
• Apply the same flow when any gws drive ... call fails mid-task with command not found / ENOENT, HTTP 401, "no credentials", or "scope required". Don't report the failure as a dead end — surface the missing prerequisite and ask if the user wants to set it up before moving on.
• OAuth scopes the user picked at login must cover the verbs the agent will use:
  • drive.file — see and modify only files the agent creates or that the user explicitly opens (narrowest, recommended for untrusted agents)
  • drive.readonly — read all of the user's files and metadata
  • drive — full read + write across the user's entire Drive

Selecting a Google account

The connected Google accounts (each with its tag, email, and config dir) are listed in your system context under "Connected Google accounts". To target a specific account, prefix the command with its config dir:

GOOGLE_WORKSPACE_CLI_CONFIG_DIR="<configDir>" gws drive files list

Selection rule: one account connected → just use it. Two or more:

• The user named or clearly implied one account (a tag, an email, or unambiguous context) → use only that account.
• A read/lookup/search the user didn't tie to an account (e.g. listing events, searching mail, finding a doc) → run it against every connected account (one gws call per config dir) and aggregate, labeling each result by its tag and email. Don't pick just one, and don't ask — the user wants the whole picture across accounts.
• A write (send, create, edit, delete) with no account named → ASK which account first; never guess.

If no accounts are connected yet, fall back to the setup flow in Prerequisites (read_skill with google-workspace-setup). On a managed/hosted deployment an account is always connected, so this case doesn't arise.

When to Use

• The user asks Gini to find, list, upload, download, share, copy, move, rename, or delete files in Drive.
• Pulling a file's metadata or share link to drop into another workflow.
• Creating or managing folders and shared drives.
• Adjusting permissions on a file or folder (role: reader|commenter|writer|fileOrganizer|organizer).

When NOT to Use

• Reading or writing the body of a Google Doc, Sheet, or Slides deck — use google-docs (or the analogous Sheets/Slides skill) for content edits; Drive only handles files-as-objects (metadata, sharing, bytes).
• Personal cross-device notes — use apple-notes or obsidian instead of dropping a .txt in Drive.
• Agent-internal ephemeral state — use the memory tool, not a Drive file.
• Large bulk downloads where the user already has rclone or a sync client configured — Drive's native client is more reliable for multi-GB transfers.
• Project task tracking or structured data — Drive holds the files; the schema lives in Docs/Sheets/Forms or an issue tracker.

Quick Reference

The Drive surface is the auto-generated v3 API (gws drive files list, gws drive permissions create, gws drive drives list, …) plus a +upload helper that handles multipart uploads with MIME-type detection.

Search and list

Drive search uses the q parameter with operators like name contains, mimeType =, '<FOLDER_ID>' in parents, modifiedTime >, sharedWithMe, trashed = false. Quote string literals inside q with single quotes (and JSON-escape if needed).

# 10 most-recently-modified files
gws drive files list --params '{"pageSize":10,"orderBy":"modifiedTime desc"}'

# Files in a specific folder
gws drive files list --params '{"q":"'''<FOLDER_ID>''' in parents and trashed = false"}'

# Spreadsheets only
gws drive files list \
  --params '{"q":"mimeType = '''application/vnd.google-apps.spreadsheet'''"}'

# By name fragment
gws drive files list --params '{"q":"name contains '''Q1 budget'''"}'

# Stream every page as NDJSON
gws drive files list --params '{"pageSize":100}' --page-all 2>/dev/null | jq -r '.files[].name'

When piping gws into jq, drop stderr first with 2>/dev/null — gws prints a Using keyring backend: keyring preamble there that would otherwise contaminate the JSON (never 2>&1).

Useful Workspace MIME types:

Upload

# Helper: auto-detects MIME, defaults filename to local path
gws drive +upload ./report.pdf
gws drive +upload ./report.pdf --parent <FOLDER_ID>
gws drive +upload ./data.csv --name 'Sales Data.csv'

# Raw API equivalent
gws drive files create \
  --json '{"name":"report.pdf","parents":["<FOLDER_ID>"]}' \
  --upload ./report.pdf

Download and export

# Download a binary file (PDF, image, etc.) by ID
gws drive files get --params '{"fileId":"<FILE_ID>","alt":"media"}' -o ./report.pdf

# Export a Google Doc to PDF / Word / plain text (10 MB limit per export)
gws drive files export \
  --params '{"fileId":"<DOC_ID>","mimeType":"application/pdf"}' \
  -o ./doc.pdf

Create a folder

gws drive files create --json '{
  "name": "Quarterly reports",
  "mimeType": "application/vnd.google-apps.folder"
}'

Share / permissions

# List existing permissions
gws drive permissions list --params '{"fileId":"<FILE_ID>"}'

# Grant a single user write access (no email notification)
gws drive permissions create \
  --params '{"fileId":"<FILE_ID>","sendNotificationEmail":false}' \
  --json '{"role":"writer","type":"user","emailAddress":"alice@example.com"}'

# Anyone with the link can view
gws drive permissions create \
  --params '{"fileId":"<FILE_ID>"}' \
  --json '{"role":"reader","type":"anyone"}'

Copy, move, rename, delete

gws drive files copy --params '{"fileId":"<SRC_ID>"}' --json '{"name":"Copy of report"}'
gws drive files update --params '{"fileId":"<FILE_ID>","addParents":"<NEW_FOLDER>","removeParents":"<OLD_FOLDER>"}'
gws drive files update --params '{"fileId":"<FILE_ID>"}' --json '{"name":"New name.pdf"}'
gws drive files delete --params '{"fileId":"<FILE_ID>"}'

Shared drives

Generate a fresh UUID per call, e.g. uuidgen. drives.create uses requestId as an idempotency token — reusing the same value collides.

gws drive drives list
gws drive drives create --params '{"requestId":"<REQUEST_ID>"}' --json '{"name":"Marketing"}'

Rules

1. Drive folder IDs and file IDs look identical but behave differently. A folder is just a file with mimeType: application/vnd.google-apps.folder. Always confirm the mimeType before treating an ID as a container.
2. Don't add a redundant text confirmation before files.create, +upload, files.update, files.delete, permissions.create, or permissions.delete. The runtime's terminal_exec approval gate is the user's safety net. When the user's command is clear ("upload report.pdf to Drive," "share Q4-plan with alice@acme.com as editor"), execute. Do ask one clarifying question when the command is ambiguous — multiple files match a name, the user didn't specify a target folder, or the user didn't name a reader/writer/owner role.
3. Be conservative with permissions. type: anyone exposes a file to the public internet — always confirm with the user before creating an "anyone with the link" share, and prefer type: user with a specific emailAddress when possible.
4. To delete: prefer trashing first (files.update with {"trashed": true}) over files.delete, which is permanent and bypasses the trash. Only use files.delete if the user explicitly said "permanently delete".
5. For editing the content of a Google Doc, do not download-then-re-upload — that breaks revision history and concurrent editing. Use google-docs to call the Docs API directly. Drive is the file/permissions surface; Docs/Sheets/Slides own content edits.
6. For personal cross-device notes, prefer apple-notes or obsidian over creating throwaway Drive files. For agent-internal ephemeral state, use the memory tool.
7. When uploading, +upload infers MIME type from the file extension. For ambiguous content (e.g. CSV that should land as a Google Sheet), use the raw files.create API with explicit mimeType instead.
8. Drive search with --page-all can pull thousands of rows quickly. Cap with --page-limit when prototyping so the agent does not iterate forever on a user's full Drive.

For flags not shown here, run gws drive --help or gws drive <verb> --help (e.g. gws drive +upload --help).