google-drive

Original：🇺🇸 English
Translated
1 scriptsChecked / no sensitive code detected

Manage Google Drive files and folders. List, search, upload, download files, create folders, and manage sharing. Use when working with Google Drive file management.

10installs
Sourceodyssey4me/agent-skills
Added on

NPX Install

npx skill4agent add odyssey4me/agent-skills google-drive

Tags

Translated version includes tags in frontmatter
google-drivefile-managementoauth-authenticationpython-scriptcloud-storage

SKILL.md Content

View Translation Comparison →

Google Drive

Interact with Google Drive for file management, search, and sharing.

Installation

  1. Install Python dependencies:
    bash
    pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml
  2. Download the skill from Releases or use directly from this repository.

Setup Verification

After installation, verify the skill is properly configured:
bash
python scripts/google-drive.py check
This will check:
  • Python dependencies (google-auth, google-auth-oauthlib, google-api-python-client, keyring, pyyaml)
  • Authentication configuration
  • Connectivity to Google Drive API
If anything is missing, the check command will provide setup instructions.

Authentication

Google Drive uses OAuth 2.0 for authentication. For complete setup instructions, see:
  1. GCP Project Setup Guide - Create project, enable Drive API
  2. Google OAuth Setup Guide - Configure credentials

Quick Start

  1. Create 
    ~/.config/agent-skills/google.yaml
    :
    yaml
    oauth_client:
  client_id: your-client-id.apps.googleusercontent.com
  client_secret: your-client-secret
  2. Run 
    python scripts/google-drive.py check
    to trigger OAuth flow and verify setup.

OAuth Scopes

The skill requests granular scopes for different operations:
ScopePermissionUsed For
drive.readonly
Read files and metadatalist, search, download
drive.file
Create/edit files created by appupload, create folders, share
drive.metadata.readonly
View file metadata onlyget file info

Scope Errors

If you encounter "insufficient scope" errors, revoke your token and re-authenticate:
  1. Revoke at https://myaccount.google.com/permissions
  2. Clear token: 
    keyring del agent-skills google-drive-token-json
  3. Re-run: 
    python scripts/google-drive.py check

Commands

check

Verify configuration and connectivity.
bash
python scripts/google-drive.py check
This validates:
  • Python dependencies are installed
  • Authentication is configured
  • Can connect to Google Drive API
  • Displays your email address and storage usage

auth setup

Store OAuth 2.0 client credentials for custom OAuth flow.
bash
python scripts/google-drive.py auth setup \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_CLIENT_SECRET
Credentials are saved to 
~/.config/agent-skills/google-drive.yaml
.

files list

List files in your Drive.
bash
# List recent files
python scripts/google-drive.py files list

# List with search query
python scripts/google-drive.py files list --query "name contains 'report'"

# List with max results
python scripts/google-drive.py files list --max-results 20

# List sorted by name
python scripts/google-drive.py files list --order-by "name"

# Output as JSON
python scripts/google-drive.py files list --json
Arguments:
  • --query
    : Drive search query (optional)
  • --max-results
    : Maximum number of results (default: 10)
  • --order-by
    : Sort order (default: "modifiedTime desc")
  • --json
    : Output as JSON

files search

Search for files with filters.
bash
# Search by name
python scripts/google-drive.py files search --name "quarterly report"

# Search by MIME type
python scripts/google-drive.py files search --mime-type "application/pdf"

# Search in a specific folder
python scripts/google-drive.py files search --folder FOLDER_ID

# Combine filters
python scripts/google-drive.py files search --name "budget" --mime-type "application/vnd.google-apps.spreadsheet"

# Output as JSON
python scripts/google-drive.py files search --name "report" --json
Arguments:
  • --name
    : File name to search for (partial match)
  • --mime-type
    : MIME type filter
  • --folder
    : Parent folder ID
  • --json
    : Output as JSON

files get

Get file metadata by ID.
bash
# Get file details
python scripts/google-drive.py files get FILE_ID

# Output as JSON
python scripts/google-drive.py files get FILE_ID --json
Arguments:
  • file_id
    : The file ID (required)
  • --json
    : Output as JSON

files download

Download a file from Google Drive.
bash
# Download a file
python scripts/google-drive.py files download FILE_ID --output /path/to/local/file

# Short form
python scripts/google-drive.py files download FILE_ID -o ./downloaded-file.pdf
Arguments:
  • file_id
    : The file ID (required)
  • --output
    , 
    -o
    : Output file path (required)
Note: Google Docs, Sheets, and Slides cannot be downloaded directly. Use the Google Drive web interface to export them.

files upload

Upload a file to Google Drive.
bash
# Upload a file
python scripts/google-drive.py files upload /path/to/file.pdf

# Upload to a specific folder
python scripts/google-drive.py files upload /path/to/file.pdf --parent FOLDER_ID

# Upload with custom name
python scripts/google-drive.py files upload /path/to/file.pdf --name "Quarterly Report 2024"

# Upload with specific MIME type
python scripts/google-drive.py files upload /path/to/file --mime-type "text/csv"

# Output as JSON
python scripts/google-drive.py files upload /path/to/file.pdf --json
Arguments:
  • path
    : Local file path (required)
  • --parent
    : Parent folder ID
  • --mime-type
    : MIME type (auto-detected if not provided)
  • --name
    : Name for the file in Drive
  • --json
    : Output as JSON

folders create

Create a new folder.
bash
# Create folder in root
python scripts/google-drive.py folders create "New Folder"

# Create folder inside another folder
python scripts/google-drive.py folders create "Subfolder" --parent FOLDER_ID

# Output as JSON
python scripts/google-drive.py folders create "Documents" --json
Arguments:
  • name
    : Folder name (required)
  • --parent
    : Parent folder ID
  • --json
    : Output as JSON

folders list

List contents of a folder.
bash
# List folder contents
python scripts/google-drive.py folders list FOLDER_ID

# List with max results
python scripts/google-drive.py folders list FOLDER_ID --max-results 50

# Output as JSON
python scripts/google-drive.py folders list FOLDER_ID --json
Arguments:
  • folder_id
    : The folder ID (required)
  • --max-results
    : Maximum number of results (default: 100)
  • --json
    : Output as JSON

share

Share a file with a user.
bash
# Share as reader (default)
python scripts/google-drive.py share FILE_ID --email user@example.com

# Share as writer
python scripts/google-drive.py share FILE_ID --email user@example.com --role writer

# Share as commenter
python scripts/google-drive.py share FILE_ID --email user@example.com --role commenter

# Share without sending notification
python scripts/google-drive.py share FILE_ID --email user@example.com --no-notify

# Output as JSON
python scripts/google-drive.py share FILE_ID --email user@example.com --json
Arguments:
  • file_id
    : File ID to share (required)
  • --email
    : Email address to share with (required)
  • --role
    : Permission role - reader, writer, commenter, owner (default: reader)
  • --no-notify
    : Don't send notification email
  • --json
    : Output as JSON

permissions list

List permissions for a file.
bash
# List permissions
python scripts/google-drive.py permissions list FILE_ID

# Output as JSON
python scripts/google-drive.py permissions list FILE_ID --json
Arguments:
  • file_id
    : The file ID (required)
  • --json
    : Output as JSON

permissions delete

Remove a permission from a file.
bash
# Delete a permission
python scripts/google-drive.py permissions delete FILE_ID PERMISSION_ID
Arguments:
  • file_id
    : The file ID (required)
  • permission_id
    : The permission ID to delete (required)

Examples

Verify Setup

bash
python scripts/google-drive.py check

Find recent PDF files

bash
python scripts/google-drive.py files list --query "mimeType='application/pdf'" --max-results 5

Search for documents by name

bash
python scripts/google-drive.py files search --name "project proposal"

Download a file

bash
# First, find the file ID
python scripts/google-drive.py files search --name "report.pdf"

# Then download it
python scripts/google-drive.py files download FILE_ID -o ./report.pdf

Upload and share a file

bash
# Upload the file
python scripts/google-drive.py files upload ./presentation.pdf --name "Q4 Presentation"

# Share with a colleague
python scripts/google-drive.py share FILE_ID --email colleague@example.com --role writer

Organize files into folders

bash
# Create a folder
python scripts/google-drive.py folders create "Project Documents"

# Upload files to the folder
python scripts/google-drive.py files upload ./doc1.pdf --parent FOLDER_ID
python scripts/google-drive.py files upload ./doc2.pdf --parent FOLDER_ID

# List folder contents
python scripts/google-drive.py folders list FOLDER_ID

Drive Search Query Syntax

Common search operators:
OperatorDescriptionExample
name contains
Name contains string
name contains 'report'
name =
Exact name match
name = 'Budget 2024.xlsx'
mimeType =
File type
mimeType = 'application/pdf'
'ID' in parents
In folder
'folder_id' in parents
modifiedTime >
Modified after
modifiedTime > '2024-01-01'
trashed =
Trashed status
trashed = false
starred =
Starred status
starred = true
sharedWithMe
Shared files
sharedWithMe = true
Combine operators with 
and
or 
or
:
bash
# PDF files modified this year
"mimeType = 'application/pdf' and modifiedTime > '2024-01-01'"

# Spreadsheets containing 'budget'
"name contains 'budget' and mimeType = 'application/vnd.google-apps.spreadsheet'"

# Files in a specific folder that are not trashed
"'folder_id' in parents and trashed = false"
For the complete reference, see drive-queries.md.

Common MIME Types

TypeMIME Type
Folder
application/vnd.google-apps.folder
Google Doc
application/vnd.google-apps.document
Google Sheet
application/vnd.google-apps.spreadsheet
Google Slides
application/vnd.google-apps.presentation
PDF
application/pdf
Word
application/vnd.openxmlformats-officedocument.wordprocessingml.document
Excel
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
PowerPoint
application/vnd.openxmlformats-officedocument.presentationml.presentation
Text
text/plain
CSV
text/csv
Image (JPEG)
image/jpeg
Image (PNG)
image/png

Troubleshooting

Check command fails

Run 
python scripts/google-drive.py check
to diagnose issues. It will provide specific error messages and setup instructions.

Authentication failed

  1. Verify your OAuth client ID and client secret are correct in 
    ~/.config/agent-skills/google.yaml
  2. Token expired or corrupted - clear and re-authenticate:
    bash
    keyring del agent-skills google-drive-token-json
python scripts/google-drive.py check

Permission denied

Your OAuth token may not have the necessary scopes. Revoke access at https://myaccount.google.com/permissions, clear your token, and re-authenticate.

Cannot download Google Docs

Google Docs, Sheets, and Slides are not binary files - they cannot be downloaded directly. Use the Google Drive web interface to export them to a downloadable format (PDF, DOCX, etc.).

Import errors

Ensure dependencies are installed:
bash
pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml

Rate limiting

Drive API has quota limits. If you hit rate limits, wait a few minutes before retrying. For high-volume usage, consider requesting quota increases in the Google Cloud Console.

API Scopes

This skill requests the following OAuth scopes:
  • https://www.googleapis.com/auth/drive.readonly
    - Read files and metadata
  • https://www.googleapis.com/auth/drive.file
    - Create, modify, delete files created by the app
  • https://www.googleapis.com/auth/drive.metadata.readonly
    - View file metadata only
These scopes provide file management capabilities while following the principle of least privilege.

Security Notes

  • OAuth tokens are stored securely in your system keyring
  • Client secrets are stored in 
    ~/.config/agent-skills/google-drive.yaml
    with file permissions 600
  • No passwords are stored - only OAuth tokens
  • Tokens refresh automatically when using the skill
  • Browser-based consent ensures you approve all requested permissions
Always review OAuth consent screens before granting access to your Google Drive.