name: google-drive
description: Manage Google Drive files and folders. List, search, upload, download files, create folders, and manage sharing. Use when working with Google Drive file management.
metadata:
author: odyssey4me
version: "0.1.0"
license: MIT

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:

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:

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.

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.

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.

# 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.

# 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.

# 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.

# 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.

# 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.

# 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.

# 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.

# Share as reader (default)
python scripts/google-drive.py share FILE_ID --email [email protected]

# Share as writer
python scripts/google-drive.py share FILE_ID --email [email protected] --role writer

# Share as commenter
python scripts/google-drive.py share FILE_ID --email [email protected] --role commenter

# Share without sending notification
python scripts/google-drive.py share FILE_ID --email [email protected] --no-notify

# Output as JSON
python scripts/google-drive.py share FILE_ID --email [email protected] --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.

# 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.

# 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

python scripts/google-drive.py check

Find recent PDF files

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

Search for documents by name

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

Download a file

# 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

# 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 [email protected] --role writer

Organize files into folders

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

Combine operators with and or or:

# 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

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:

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.