gdrive

Browse, search, and manage Google Drive files and folders. Use when the user shares a drive.google.com URL, asks what is in a folder, wants a file found, downloaded, uploaded, updated in place, moved,

SKILL.md

GitHub

Google Drive

Work with the Drive files and folders the user names or links to. Most commands take a file ID — the segment after /d/ or /folders/ in a https://drive.google.com/... URL.

[!CAUTION]

mutate empty-trash permanently deletes every trashed file and cannot be undone. Never run it, or any other destructive command, unless the user asks explicitly.

Setup and Authentication

gdrive auth status is the only way to tell whether you are logged in. Do not run --help, search the filesystem or environment for tokens, check another plugin's login, or run an operational command before logging in. Follow these steps exactly.

1. Register and check. Run this skill's script with auth status. It downloads the CLI, registers gdrive on the agent's PATH (not the user's shell), and reports whether you are logged in:

<path/to/this/skill>/scripts/gdrive auth status
# Windows (PowerShell)
& "<path\to\this\skill>\scripts\gdrive.cmd" auth status

Every later call is just gdrive. Never ask the user to run it; they cannot. If it reports Logged in, you are ready.

2. Log in for the user. Start this as a background command:

gdrive auth login

It prints an authorization URL and exits on its own once the user approves. Read the URL from the task's log, open it in the user's browser or hand them the link, then stop and wait. Confirm with gdrive auth status.

Usage

Do every Drive operation — listing, searching, downloading, uploading, sharing — through gdrive. Every command sits under one of two namespaces:

  • readonly browses, searches, reads, and exports without changing anything.
  • mutate uploads, edits, creates, deletes, and changes permissions.

So the commands read gdrive readonly ls and gdrive mutate upload. Run gdrive --help, or gdrive <namespace> <command> --help, to confirm the exact flags of any command below.

The split exists so the namespace can be allowlisted as a prefix. A terminal permission rule can admit every readonly command outright and still prompt before anything mutates, which only holds if you never reach for a command outside its namespace.

Two rules the CLI's own help will not tell you:

  • Reach for readonly first, and never run a mutate command the user did not ask for. Deleting a file and widening a sharing setting are both one-way doors: a delete costs the user their data, and a share can expose it to people they never intended.
  • Check where a file is going before you move it. Moving a file out of a shared folder silently strips the access everyone else had through that folder, and nothing in the output will tell you it happened.

Recipes

Browse and search (readonly):

gdrive readonly ls                          # list root (unlimited by default)
gdrive readonly ls FOLDER_ID --max 50       # limit results to 50 items
gdrive readonly ls --trashed                # list trashed items
gdrive readonly search --name-contains "quarterly report"
gdrive readonly search --content-contains "annual budget"   # search inside file content
gdrive readonly search --parent-id FOLDER_ID --modified-after 2024-01-01T00:00:00Z --type spreadsheet
gdrive readonly search --name-contains "quarterly report" --include-trashed
gdrive readonly recent --max 10
gdrive readonly starred
gdrive readonly info FILE_ID
gdrive readonly capabilities FILE_ID
gdrive readonly capabilities FILE_ID --filter canEdit,canComment   # narrow the output
gdrive readonly url FILE_ID                 # print web URL
gdrive readonly tree FOLDER_ID              # recursive folder tree
gdrive readonly count FOLDER_ID             # count items in folder

File operations:

gdrive readonly download FILE_ID --out /tmp/file.pdf   # download without converting
gdrive mutate upload /tmp/file.txt --parent FOLDER_ID
gdrive mutate upload /tmp/notebook.ipynb --mime-type "application/vnd.google.colaboratory" --parent FOLDER_ID
gdrive mutate update FILE_ID /tmp/updated.ipynb        # replace content, keep ID/link/permissions
gdrive mutate mkdir "New Folder" --parent FOLDER_ID
gdrive mutate create-shortcut FILE_ID FOLDER_ID        # shortcut inherits the original name
gdrive mutate cp FILE_ID "Copy of File" --parent FOLDER_ID
gdrive mutate mv FILE_ID NEW_PARENT_ID
gdrive mutate rename FILE_ID "New Name"
gdrive readonly export FILE_ID /tmp/doc.md --format md    # Docs to pdf/docx/txt/md/html
gdrive readonly export FILE_ID /tmp/sheet.tsv --format tsv # Sheets to pdf/xlsx/csv/tsv
gdrive readonly export FILE_ID /tmp/deck.pdf --format pdf  # Slides to pdf/pptx/txt
gdrive mutate trash FILE_ID
gdrive mutate untrash FILE_ID
gdrive mutate empty-trash --confirm

Sharing and permissions:

[!WARNING]

mutate share --type anyone makes a file readable by anyone with the link. Only use it when the user asks for a public link in so many words.

gdrive mutate share FILE_ID --email user@example.com --role writer
gdrive mutate share FILE_ID --email user@example.com --role reader --notify=false
gdrive readonly permissions FILE_ID
gdrive mutate remove-permission FILE_ID PERMISSION_ID
gdrive readonly audit-permissions FOLDER_ID            # recursive permission audit

Comments:

gdrive readonly list-comments FILE_ID
gdrive readonly list-comments FILE_ID --author user@example.com
gdrive readonly list-comments FILE_ID --mentioned user@example.com
gdrive readonly list-comments FILE_ID --assignee user@example.com
gdrive mutate add-comment FILE_ID 'Nice work!'
gdrive mutate reply-comment FILE_ID COMMENT_ID "Done"
gdrive mutate resolve-comment FILE_ID COMMENT_ID "Resolved."

Other:

gdrive readonly quota
gdrive readonly revisions FILE_ID
gdrive readonly shared-drives
gdrive mutate batch -f ops.json

Watching Drive activity:

readonly watch runs an event-driven background watcher that reacts to Drive activity. It defaults to events mode, which uses the Workspace Events API and Pub/Sub and needs a configured GCP project, resolved automatically or through --project_id. Fall back to polling when that setup is unavailable.

gdrive readonly watch --watch_actions=commented,edited
gdrive readonly watch --watch_mode=poll --watch_actions=commented,edited
gdrive readonly watch --mime_type=docs --watch_actions=commented,edited
gdrive readonly watch --actor user@example.com --watch_actions=commented,edited

Pass --json to stream newline-delimited event objects to stdout, which is what a pipeline or a sidecar wants:

gdrive readonly watch --json --watch_actions=commented | while read -r EVENT_JSON; do
  echo "Received: ${EVENT_JSON}"
done

Commands

Command Description
readonly ls List files with auto-pagination (unlimited by
: : default; pass --max N to limit results; :
: : supports --trashed) :
readonly count Count files in folder with pagination
readonly search Search files (supports --trashed)
readonly info Get file info
readonly url Print web URL
readonly download Download file
mutate upload Upload file (supports --mime-type)
mutate update Update file content in-place (preserves ID,
: : link, permissions; supports --mime-type) :
mutate mkdir Create folder
mutate create-shortcut Create a shortcut to a file in a folder
mutate cp Copy file (supports --parent)
mutate mv Move file
mutate rename Rename file
readonly export Export Google Workspace document (supports
: : --format=pdf / docx / xlsx / pptx / :
: : csv / tsv / txt / md / html) :
mutate trash Trash file
mutate untrash Restore file
mutate empty-trash Empty trash
mutate share Share file (--notify=false to suppress
: : email) :
readonly permissions List permissions
mutate remove-permission Remove permission
readonly audit-permissions Recursive permission audit
readonly capabilities List file capabilities (supports --filter)
readonly recent Recent files
readonly starred Starred files
readonly quota Show quota
readonly revisions List file revisions
readonly shared-drives List shared drives
readonly tree Display folder tree
readonly list-comments List comments (supports --author,
: : --mentioned, --assignee) :
mutate add-comment Add a comment
mutate reply-comment Reply to a specific comment thread
mutate resolve-comment Resolve a comment thread
mutate batch Execute batch ops
readonly watch Start a background watcher for Drive activity

Tips

  • readonly ls paginates across every page and is unlimited by default (--max 0). Pass --max N on a large or unfamiliar folder so the listing does not flood your context window.
  • Omit the file extension when searching for a native Google file by exact name. Write readonly search --name-exact "Q3 Budget", not "Q3 Budget.gsheet". Extensions belong only in exact-name searches for uploads such as report.pdf.
  • --mime-type overrides the extension-based detection on mutate upload and mutate update. A .ipynb file has to be registered as application/vnd.google.colaboratory to render as a Colab notebook and to resolve when referenced elsewhere.
  • readonly capabilities --filter returns only the capabilities you name, which keeps large responses out of your context. canEdit, canComment, and canShare are the common ones. The full set is in the Drive API file resource.
  • mutate reply-comment and mutate resolve-comment want the thread ID, which is the ID of the original comment, not the ID of a reply.
  • mutate add-comment and mutate reply-comment check access when the comment text contains Drive links. The command fails when an @mentioned user cannot open a linked file, and warns on stderr when another collaborator cannot. Pass --ignore-sharing-checks to skip the check.
  • In events mode, watch prints Drive Event Watcher Active and then [Discovery] Created WES subscription: ... for each file it picks up. Treat those two lines as the confirmation that the subscription took.
  • Always pass --mime_type when watching one kind of document, so discovery and subscriptions stay scoped: docs, sheets, slides, folder, colab, or pdf.

Global Flags

  • --json — output as JSON (works with all read commands)
  • -v, --version — print the CLI build version