Prerequisites

Required Python package: pydrive2 must be installed.

bash

# Install with pip
pip install pydrive2

# OR with uv
uv pip install pydrive2

Authentication: Credentials must be configured at ~/.gdrivelm/. See references/auth_setup.md for initial setup.

Configuration

Helper script path:

code

/Users/wz/.claude/plugins/marketplaces/warren-claude-code-plugin-marketplace/claude-context-orchestrator/snippets/local/productivity/google-drive/scripts/gdrive_helper.py

Authentication files (use ~/.gdrivelm/ - expands to home directory):

•Credentials: ~/.gdrivelm/credentials.json
•Settings: ~/.gdrivelm/settings.yaml
•Token: ~/.gdrivelm/token.json (auto-generated)

Load references/auth_setup.md for detailed authentication configuration.

Helper Script Usage

Use scripts/gdrive_helper.py for common operations to avoid rewriting authentication and upload/download code.

Import and Use Functions

python

import sys
sys.path.insert(0, '/Users/wz/.claude/plugins/marketplaces/warren-claude-code-plugin-marketplace/claude-context-orchestrator/snippets/local/productivity/google-drive/scripts')
from gdrive_helper import authenticate, upload_file, download_file, search_files, get_metadata

# Authenticate once
drive = authenticate()

# Upload file
result = upload_file(drive, '/path/to/file.txt', title='My File')
print(f"Uploaded: {result['id']}")

# Search files
results = search_files(drive, "title contains 'report'")
for file in results:
    print(f"{file['title']} - {file['id']}")

# Download file
download_file(drive, 'FILE_ID', '/path/to/save.txt')

# Get metadata
metadata = get_metadata(drive, 'FILE_ID')
print(f"Size: {metadata['size']} bytes")

Available Helper Functions

•authenticate() - Authenticate and return Drive instance
•upload_file(drive, local_path, title=None, folder_id=None) - Upload local file
•upload_string(drive, content, title, folder_id=None, use_markdown=None) - Upload string content with auto-markdown detection
•download_file(drive, file_id, local_path) - Download file
•get_file_content(drive, file_id) - Get file content as string
•get_metadata(drive, file_id) - Get file metadata
•search_files(drive, query, max_results=None) - Search for files
•delete_file(drive, file_id, permanent=False) - Delete or trash file
•create_folder(drive, folder_name, parent_id=None) - Create folder
•list_files_in_folder(drive, folder_id) - List files in folder

CLI Usage

The helper script can be used from command line. First ensure pydrive2 is installed:

bash

# Install pydrive2 if needed (one-time setup)
pip install pydrive2
# OR with uv:
uv pip install pydrive2

# Run commands directly (no cd or venv activation needed)
python /Users/wz/.claude/plugins/marketplaces/warren-claude-code-plugin-marketplace/claude-context-orchestrator/snippets/local/productivity/google-drive/scripts/gdrive_helper.py upload /path/to/file.txt
python /Users/wz/.claude/plugins/marketplaces/warren-claude-code-plugin-marketplace/claude-context-orchestrator/snippets/local/productivity/google-drive/scripts/gdrive_helper.py search "title contains 'report'"
python /Users/wz/.claude/plugins/marketplaces/warren-claude-code-plugin-marketplace/claude-context-orchestrator/snippets/local/productivity/google-drive/scripts/gdrive_helper.py download FILE_ID /path/to/save.txt

File Type Handling

Google Drive files require different retrieval methods depending on their type:

Google Docs/Sheets/Slides (Native Google Formats)

Native Google formats require export with a specific MIME type, not direct download:

python

import sys
sys.path.insert(0, '/Users/wz/.claude/plugins/marketplaces/warren-claude-code-plugin-marketplace/claude-context-orchestrator/snippets/local/productivity/google-drive/scripts')
from gdrive_helper import authenticate

drive = authenticate()

# Extract file ID from URL
file_id = '1rX7KHFnHyoAu3KrIvQgv0gJdTvMztWJT-Pkx5x954vc'

# Create file object and fetch metadata
file = drive.CreateFile({'id': file_id})
file.FetchMetadata()

# Export with appropriate MIME type
content = file.GetContentString(mimetype='text/plain')  # For Google Docs
# content = file.GetContentString(mimetype='text/csv')  # For Google Sheets
# content = file.GetContentString(mimetype='text/plain')  # For Google Slides

print(content)

Regular Files (PDF, Images, Text, etc.)

Regular uploaded files can use direct download:

python

from gdrive_helper import authenticate, get_file_content

drive = authenticate()
content = get_file_content(drive, 'FILE_ID')

Usage Pattern: No Project Directory Required

Important: The helper scripts are globally available. You don't need to cd into a project directory:

python

# ✅ CORRECT: Import from global skill path directly
import sys
sys.path.insert(0, '/Users/wz/.claude/plugins/marketplaces/warren-claude-code-plugin-marketplace/claude-context-orchestrator/snippets/local/productivity/google-drive/scripts')
from gdrive_helper import authenticate

drive = authenticate()
# Continue with operations...

# ❌ INCORRECT: Don't try to cd into project directory
# cd ~/Desktop/zPersonalProjects/gdrivelm  # This may not exist

Common Operations

Upload File from Local Path

python

from gdrive_helper import authenticate, upload_file

drive = authenticate()
result = upload_file(drive, '/path/to/document.pdf', title='Important Document')
print(f"File ID: {result['id']}")
print(f"Link: {result['link']}")

Upload String Content

The upload_string function automatically detects markdown formatting and sets the appropriate MIME type:

python

from gdrive_helper import authenticate, upload_string

drive = authenticate()

# Auto-detects markdown based on content
markdown_content = """# My Document

This is a **markdown** formatted document with:
- Lists
- **Bold** text
- [Links](https://example.com)
"""

result = upload_string(drive, markdown_content, 'My Document')
print(f"Created: {result['title']}")  # Will be 'My Document.md'
print(f"MIME Type: {result['mimeType']}")  # Will be 'text/markdown'

# Force plain text (disable auto-detection)
plain_content = "This is plain text content"
result = upload_string(drive, plain_content, 'note.txt', use_markdown=False)

# Force markdown
result = upload_string(drive, "Simple text", 'doc', use_markdown=True)  # Will be 'doc.md'

Search Files

python

from gdrive_helper import authenticate, search_files

drive = authenticate()

# Search by title
results = search_files(drive, "title contains 'invoice'")

# Search by type
results = search_files(drive, "mimeType = 'application/pdf'")

# Complex search
query = "title contains 'report' and mimeType = 'application/pdf' and trashed = false"
results = search_files(drive, query)

for file in results:
    print(f"{file['title']} ({file['id']})")

For comprehensive search query syntax and examples, load references/search_queries.md.

Download File

python

from gdrive_helper import authenticate, download_file

drive = authenticate()
result = download_file(drive, 'FILE_ID_HERE', '/path/to/save/file.txt')
print(f"Downloaded {result['title']} to {result['local_path']}")

Get File Metadata

python

from gdrive_helper import authenticate, get_metadata

drive = authenticate()
metadata = get_metadata(drive, 'FILE_ID_HERE')

print(f"Title: {metadata['title']}")
print(f"Size: {metadata['size']} bytes")
print(f"Modified: {metadata['modified']}")
print(f"Link: {metadata['link']}")

Create Folder and Upload to It

python

from gdrive_helper import authenticate, create_folder, upload_file

drive = authenticate()

# Create folder
folder = create_folder(drive, 'My Documents')
print(f"Folder ID: {folder['id']}")

# Upload file to folder
result = upload_file(drive, '/path/to/file.txt', folder_id=folder['id'])
print(f"Uploaded to folder: {result['title']}")

Advanced Usage

For direct PyDrive2 API usage and advanced features, load references/api_reference.md.

Manual Authentication Pattern

If not using the helper script:

python

from pydrive2.auth import GoogleAuth
from pydrive2.drive import GoogleDrive

gauth = GoogleAuth(settings_file='/Users/wz/.gdrivelm/settings.yaml')
gauth.LoadCredentialsFile('/Users/wz/.gdrivelm/token.json')

if gauth.credentials is None:
    gauth.LocalWebserverAuth()
elif gauth.access_token_expired:
    gauth.Refresh()
else:
    gauth.Authorize()

gauth.SaveCredentialsFile('/Users/wz/.gdrivelm/token.json')
drive = GoogleDrive(gauth)

Batch Operations

python

from gdrive_helper import authenticate, upload_file

drive = authenticate()

files = [
    '/path/to/file1.txt',
    '/path/to/file2.pdf',
    '/path/to/file3.docx'
]

for file_path in files:
    result = upload_file(drive, file_path)
    print(f"Uploaded: {result['title']} ({result['id']})")

Search Query Patterns

Common search patterns (load references/search_queries.md for complete syntax):

•title contains 'text' - Files with title containing text
•mimeType = 'application/pdf' - PDF files only
•'root' in parents - Files in root directory
•trashed = false - Not in trash
•'me' in owners - Files you own
•modifiedDate > '2024-01-01' - Modified after date
•fullText contains 'keyword' - Search file content

Combine with and/or:

python

query = "title contains 'report' and mimeType = 'application/pdf' and trashed = false"

Bundled Resources

Scripts

•scripts/gdrive_helper.py - Reusable Python functions for all common operations

References

•references/auth_setup.md - Complete authentication configuration guide
•references/search_queries.md - Comprehensive search query syntax and examples
•references/api_reference.md - PyDrive2 API method reference with examples

Assets

•assets/settings_template.yaml - Template PyDrive2 settings file

Workflow Guidelines

•Always activate the virtual environment first before running any Google Drive code
•Use the helper script for common operations to avoid rewriting code
•Load reference files as needed for detailed syntax and advanced features
•Test with small operations first before batch processing
•Check file IDs when downloading or modifying files

Error Handling

python

from pydrive2.files import ApiRequestError
from gdrive_helper import authenticate, get_metadata

drive = authenticate()

try:
    metadata = get_metadata(drive, 'FILE_ID')
    print(metadata['title'])
except ApiRequestError as e:
    if e.error['code'] == 404:
        print("File not found")
    elif e.error['code'] == 403:
        print("Permission denied")
    else:
        print(f"API Error: {e}")
except Exception as e:
    print(f"Error: {e}")

Common Pitfalls

Pitfall 1: FileNotDownloadableError with Google Docs

Error Message:

code

pydrive2.files.FileNotDownloadableError: No downloadLink/exportLinks for mimetype found in metadata

Cause: Using get_file_content() or direct download methods on native Google formats (Docs, Sheets, Slides).

Solution: Use GetContentString(mimetype='...') to export the file:

python

# ❌ WRONG: This fails for Google Docs
from gdrive_helper import get_file_content
content = get_file_content(drive, 'GOOGLE_DOC_ID')

# ✅ CORRECT: Export with MIME type
file = drive.CreateFile({'id': 'GOOGLE_DOC_ID'})
file.FetchMetadata()
content = file.GetContentString(mimetype='text/plain')

Pitfall 2: Hardcoded Project Paths

Error Message:

code

cd: no such file or directory: /Users/wz/Desktop/zPersonalProjects/gdrivelm

Cause: Assuming the gdrivelm project directory exists in a specific location.

Solution: Import from the global skill path directly (no cd required):

python

# ✅ CORRECT: Works from any directory
import sys
sys.path.insert(0, '/Users/wz/.claude/plugins/marketplaces/warren-claude-code-plugin-marketplace/claude-context-orchestrator/snippets/local/productivity/google-drive/scripts')
from gdrive_helper import authenticate

# ❌ WRONG: Don't rely on project directory
# cd ~/Desktop/zPersonalProjects/gdrivelm && source venv/bin/activate

Pitfall 3: Extracting File IDs from URLs

Common patterns:

python

# From full URL
url = "https://docs.google.com/document/d/1rX7KHFnHyoAu3KrIvQgv0gJdTvMztWJT-Pkx5x954vc/edit"
file_id = url.split('/d/')[1].split('/')[0]  # '1rX7KHFnHyoAu3KrIvQgv0gJdTvMztWJT-Pkx5x954vc'

# From sharing URL
url = "https://drive.google.com/file/d/1ABC123xyz/view"
file_id = url.split('/d/')[1].split('/')[0]  # '1ABC123xyz'

Performance Tips

•Use helper script functions to minimize authentication overhead
•Authenticate once and reuse the drive instance
•Use specific search queries instead of listing all files
•Batch operations when uploading/downloading multiple files
•Cache file IDs for frequently accessed files

Additional Documentation

For complete setup guide and test results, see:

•Project location: ~/Desktop/zPersonalProjects/gdrivelm/
•README: ~/Desktop/zPersonalProjects/gdrivelm/README.md
•Test script: ~/Desktop/zPersonalProjects/gdrivelm/test_gdrive.py
•HTML documentation: ~/Desktop/zPersonalProjects/gdrivelm/claude_html/google_drive_api_setup.html