Gdrive CLI

Google Drive CLI Skill

Interact with Google Drive via rclone. This skill covers listing, uploading, downloading, searching, syncing, mounting, exporting Google Workspace files (Docs/Sheets/Slides), and handling Shared Drives and trash.

The underlying tool is rclone — a cloud storage swiss-army knife — but this skill is scoped to Google Drive. For other providers (S3, Dropbox, OneDrive, etc.) don't use this skill; run rclone directly with the appropriate remote.

Constraints

• rclone must be installed (brew install rclone on macOS).
• A Google Drive remote must be configured via rclone config. OAuth is browser-based and cannot be automated — the user must run rclone config themselves.
• Remote names are user-chosen (e.g., gdrive:, tx-gdrive:, personal:). Always run rclone listremotes first — never assume a name.
• Destructive operations (sync, move, delete, purge) can permanently erase Drive data. Run with --dry-run first and confirm before executing.
• Daily upload quota on Google Drive is 750 GB per user. Plan accordingly.
• Google Docs/Sheets/Slides have no file size and can't be downloaded as-is unless you pass --drive-export-formats to convert them.

Preflight Check

Before any Drive operation:

rclone version          # confirm install
rclone listremotes      # find the Drive remote name

If rclone is missing:

• macOS: brew install rclone
• Linux: sudo -v ; curl https://rclone.org/install.sh | sudo bash
• Windows: winget install Rclone.Rclone

If no remote is configured, guide the user through rclone config:

1. n → new remote
2. Name: e.g., gdrive
3. Storage type: type drive (NOT google cloud storage — different product)
4. client_id / client_secret — leave blank
5. Scope: 1 (full) or 2 (read-only) or 3 (file-only)
6. Leave service_account_file blank
7. Edit advanced config: n
8. Use auto config: y — opens browser for OAuth
9. Configure as Shared Drive: n (unless using a Team/Shared Drive)
10. Confirm y, quit with q

To verify: rclone about <remote>: should return quota info.

Safety Rules for Destructive Operations

Always:

1. Run with --dry-run first and show the plan to the user.
2. Get explicit confirmation before running for real.
3. For sync, prefer --backup-dir to retain deleted versions.
4. Never chain destructive commands with && without review.

Non-destructive operations (copy, ls, lsd, lsf, lsjson, about, check, cat, tree, size, ncdu) proceed without extra confirmation.

Output Format Guidance

When Claude needs to process output, prefer rclone lsjson with jq:

# Good — filtered JSON, minimal tokens
rclone lsjson gdrive:Projects | jq '.[] | select(.IsDir==false and .Size > 1000000)'

# Avoid — verbose table output wastes context
rclone lsl gdrive:Projects

Quick Reference

Global flags worth knowing:

Common Workflows

Check quota and browse

rclone about gdrive:
rclone lsd gdrive:
rclone ncdu gdrive:          # interactive

Upload files or folders

# Single file with progress
rclone copy ~/report.pdf gdrive:Reports/ -P

# Whole folder, skipping junk
rclone copy ~/project gdrive:Backups/project \
  --exclude ".git/**" --exclude "node_modules/**" -P

rclone copy is safe — it never deletes on the destination.

Download from Drive

rclone copy gdrive:Reports/report.pdf ~/Downloads/ -P
rclone copy gdrive:Reports ~/Downloads/reports -P

Search across Drive

# All PDFs recursively
rclone lsf gdrive: -R --include "*.pdf"

# Files modified in last 24 hours
rclone lsjson gdrive: -R | jq '.[] | select(.ModTime > (now - 86400 | todate))'

# Largest 10 files
rclone lsjson gdrive: -R | jq 'sort_by(.Size) | reverse | .[:10] | .[] | {name: .Name, mb: (.Size/1048576 | round)}'

Export Google Docs / Sheets / Slides

Google Workspace files have no native file — you must tell rclone what format to export them as. --drive-export-formats accepts a comma-separated priority list:

# Export Docs as .docx, Sheets as .xlsx, Slides as .pptx
rclone copy gdrive:Projects ~/local/projects \
  --drive-export-formats "docx,xlsx,pptx" -P

# Prefer PDF for everything
rclone copy gdrive:Projects ~/local/projects \
  --drive-export-formats "pdf" -P

# Markdown for Docs, CSV for Sheets
rclone copy gdrive:Notes ~/local/notes \
  --drive-export-formats "md,csv" -P

Supported export targets: docx, odt, rtf, pdf, txt, html, epub, xlsx, ods, csv, tsv, pptx, odp, svg, jpg, png.

Sync a local folder to Drive (DESTRUCTIVE)

Always two-step:

# 1. Dry-run
rclone sync ~/project gdrive:Backups/project --dry-run -v

# 2. Show output to user, get confirmation, then real run with safety net
rclone sync ~/project gdrive:Backups/project \
  --backup-dir gdrive:Backups/_versions/$(date +%Y-%m-%d) \
  --max-delete 100 \
  -P

Compare local and remote

# Hash-based check
rclone check ~/project gdrive:Backups/project

# Size-only (faster, less accurate)
rclone check ~/project gdrive:Backups/project --size-only

# Produce diff reports
rclone check ~/project gdrive:Backups/project \
  --differ diff.txt \
  --missing-on-dst missing-dst.txt \
  --missing-on-src missing-src.txt

Shared Drives

If the user is on Google Workspace, they may have Shared Drives (formerly Team Drives).

# List Shared Drives available to this account
rclone backend drives gdrive:

# To access one, either:
# (a) Reconfigure the remote with "Configure as Shared Drive? y" in rclone config
# (b) Use --drive-shared-with-me or --drive-team-drive flags ad-hoc

# Example: operate on a specific Shared Drive by ID
rclone ls gdrive: --drive-team-drive 0ABCDEF1234567890

Shared-with-me

Files other users shared with you but that don't live in your My Drive:

rclone lsd gdrive: --drive-shared-with-me
rclone copy gdrive: ~/shared-downloads --drive-shared-with-me -P

Trash management

# List trashed items
rclone ls gdrive: --drive-trashed-only

# Restore from trash (rclone backend command)
rclone backend untrash gdrive:path/to/file

# Empty trash (PERMANENT)
rclone backend drop gdrive: --dry-run      # preview first
rclone backend drop gdrive:                # execute

Mount Drive as a filesystem

Requires FUSE. On macOS: brew install --cask macfuse. Note that Homebrew's rclone formula excludes mount — install rclone from https://rclone.org/install/ for full mount support, or use nfsmount subcommand.

mkdir -p ~/mnt/gdrive
rclone mount gdrive: ~/mnt/gdrive --vfs-cache-mode full --daemon

# Unmount
umount ~/mnt/gdrive            # macOS
fusermount -u ~/mnt/gdrive     # Linux

Generate a share link

rclone link gdrive:shared/file.pdf
# Returns: https://drive.google.com/open?id=...

Bandwidth control

Useful on metered connections or to avoid hitting Drive's rate limits:

rclone copy ~/bigfolder gdrive:backup --bwlimit 5M -P
# Schedule: 1M during work hours, unlimited overnight
rclone copy ~/bigfolder gdrive:backup --bwlimit "08:00,1M 18:00,off" -P
# Cap API transactions per second
rclone copy ~/bigfolder gdrive:backup --tpslimit 10 -P

Error Handling

References

For the full flag-by-flag reference of every subcommand, including Drive-specific flags and advanced usage, read references/command-reference.md.

Behavior Scenarios

Scenario 1: Check Drive quota

Given rclone is installed and a Drive remote is configured
When the user asks about Drive storage or quota
Then run `rclone about <remote>:`
And report total, used, free, and trashed space

Scenario 2: Upload to Drive

Given a Drive remote is configured
When the user asks to upload a file or folder to Drive
Then run `rclone copy <local> <remote>:<path> -P`
And report files transferred and total size

Scenario 3: Sync local folder to Drive (destructive)

Given the user wants to mirror a local folder to Drive
When the user asks to sync or backup to Drive
Then first run `rclone sync <src> <dst> --dry-run -v`
And show planned deletions/overwrites to the user
And only execute real sync after explicit user confirmation
And prefer `--backup-dir` for recoverability

Scenario 4: Browse Drive interactively

Given a Drive remote is configured
When the user asks to explore or browse Drive
Then prefer `rclone ncdu <remote>:` for interactive use
Or use `rclone lsjson <remote>:<path> | jq` when Claude needs to process output

Scenario 5: Export Google Docs / Sheets / Slides

Given the user wants to download Google Workspace files
When the user asks to export or download Docs/Sheets/Slides
Then pass `--drive-export-formats` with appropriate targets (docx/xlsx/pptx/pdf/md/csv)
And explain that Google-native files have no size and must be exported

Scenario 6: Access Shared Drives

Given the user is on Google Workspace with Shared Drives
When the user asks to list or access a Shared Drive
Then run `rclone backend drives <remote>:` to list available Shared Drives
And either guide reconfiguration or use `--drive-team-drive <ID>` flag

Scenario 7: Shared-with-me items

Given the user wants to access files others shared with them
When the user asks about "shared with me" items
Then add `--drive-shared-with-me` flag to any list/copy command
And explain these items don't live in My Drive

Scenario 8: rclone not installed

Given rclone is not on PATH
When the user asks any Drive operation
Then report the missing install and suggest `brew install rclone` (macOS)
Or the platform-appropriate install command

Scenario 9: No Drive remote configured

Given rclone is installed but no Drive remote exists
When the user asks any Drive operation
Then explain OAuth cannot be automated
And walk through `rclone config`, emphasizing storage type `drive` (not `google cloud storage`)

Scenario 10: Hitting the 750 GB daily upload limit

Given a large upload encounters quota errors
When rclone reports `quotaExceeded` or `userRateLimitExceeded`
Then explain Drive's 750 GB/day per-user upload cap
And suggest resuming the next day, or adding `--tpslimit 10 --transfers 2`
And point out that `rclone copy` resumes correctly on re-run (skips existing)