google-drive

What this skill does

## 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:**
```
/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 an