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:

```bash
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).

```bash
# 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:

| Type | mimeType |
|------|----------|
| Folder | `application/vnd.google-apps.folder` |
| Doc | `application/vnd.google-apps.document` |
| Sheet | `application/vnd.google-apps.spreadsheet` |
| Slides | `application/vnd.google-apps.presentation` |
| Form | `application/vnd.google-apps.form` |

### Upload

```bash
# 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