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:
n → new remote- Name: e.g.,
gdrive
- Storage type: type
drive (NOT google cloud storage — different product)
client_id / client_secret — leave blank- Scope:
1 (full) or 2 (read-only) or 3 (file-only)
- Leave
service_account_file blank
- Edit advanced config:
n
- Use auto config:
y — opens browser for OAuth
- Configure as Shared Drive:
n (unless using a Team/Shared Drive)
- Confirm
y, quit with q
To verify: rclone about <remote>: should return quota info.
Safety Rules for Destructive Operations
| Command | What it does | Risk |
|---|
rclone sync SRC DST | Makes DST identical to SRC | Deletes files on DST not in SRC |
rclone move SRC DST | Copies then deletes from SRC | Data loss if DST write fails |
rclone delete REMOTE:PATH | Deletes files matching filters | Permanent |
rclone purge REMOTE:PATH | Deletes folder + contents | Permanent, recursive |
rclone backend drop REMOTE: | Empties Drive trash | Irrecoverable |
Always:
- Run with
--dry-run first and show the plan to the user.
- Get explicit confirmation before running for real.
- For
sync, prefer --backup-dir to retain deleted versions.
- 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
| Command | Output | Best for |
|---|
rclone ls | <size> <path> per line | Flat file list |
rclone lsd | Directories only | Top-level folder overview |
rclone lsl | Long format with modtime | Human browsing |
rclone lsf | Path only, one per line | Shell pipelines |
rclone lsjson | JSON objects | Claude processing, jq filtering |
rclone tree | Tree view | Visual structure |
rclone ncdu | Interactive TUI | User-driven exploration |
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
| Action | Command |
|---|
| List remotes | rclone listremotes |
| Check quota | rclone about gdrive: |
| Top-level folders | rclone lsd gdrive: |
| Files in folder | rclone ls gdrive:path |
| List as JSON | rclone lsjson gdrive:path |
| Interactive browser | rclone ncdu gdrive: |
| Read a file | rclone cat gdrive:path/file.txt |
| Upload | rclone copy ~/local gdrive:remote -P |
| Download | rclone copy gdrive:remote ~/local -P |
| Search by name | rclone lsf gdrive: -R --include "*.pdf" |
| Compare local/remote | rclone check ~/local gdrive:remote |
| Folder size | rclone size gdrive:path |
| Mirror (DESTRUCTIVE) | rclone sync ~/src gdrive:dst --dry-run |
| Share link | rclone link gdrive:path/file.pdf |
| List Shared Drives | rclone backend drives gdrive: |
| Shared-with-me items | rclone lsd gdrive: --drive-shared-with-me |
| Trashed items | rclone ls gdrive: --drive-trashed-only |
| Empty trash | rclone backend drop gdrive: |
| Mount | rclone mount gdrive: ~/mnt/gdrive --vfs-cache-mode full --daemon |
| Reauthorize | rclone config reconnect gdrive: |
Global flags worth knowing:
| Flag | Purpose |
|---|
-P / --progress | Show transfer progress |
--dry-run | Simulate without changes |
-v / -vv | Verbose / debug logging |
--transfers N | Parallel file transfers (default 4) |
--exclude "*.tmp" | Skip matching files |
--include "*.pdf" | Include only matching files |
--max-age 7d | Only files newer than 7 days |
--backup-dir PATH | Keep overwritten/deleted files |
--tpslimit 10 | Cap Drive API calls per second |
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
| Symptom | Cause | Fix |
|---|
command not found: rclone | Not installed | brew install rclone |
didn't find section in config file | Wrong remote name | rclone listremotes to check |
Failed to get oauth token | Expired refresh token | rclone config reconnect gdrive: |
directory not found | Path typo or missing : | Double-check <remote>:<path> |
quota exceeded | Drive full or 750 GB/day hit | Wait 24h or free space |
userRateLimitExceeded (403) | Too many API calls | Add --tpslimit 10 |
exportSizeLimitExceeded | Google Doc too large to export | Split the doc or use --drive-export-formats pdf |
mount: command not found | Homebrew rclone lacks mount | Install from rclone.org or use nfsmount |
| Slow transfers | Default 4 parallel streams | Try --transfers 8 --checkers 16 |
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)