google-drive-management

What this skill does

# Google Drive Management

Comprehensive Google Drive integration enabling search, file operations, folder management, permissions control, and content synchronization through the Google Drive API v3.

## Quick Start

When asked to work with Google Drive:

1. **Authenticate**: Set up OAuth2 credentials (one-time setup)
2. **Search files**: Find files by name, type, or content
3. **Read content**: Download and read file contents
4. **Create/Update**: Upload new files or modify existing ones
5. **Organize**: Create folders and move files
6. **Share**: Manage permissions and sharing

## Prerequisites

### One-Time Setup

**1. Enable Google Drive API:**
```bash
# Visit Google Cloud Console
# https://console.cloud.google.com/

# Enable Drive API for your project
# APIs & Services > Enable APIs and Services > Google Drive API
```

**2. Create OAuth2 Credentials:**
```bash
# In Google Cloud Console:
# APIs & Services > Credentials > Create Credentials > OAuth client ID
# Application type: Desktop app
# Download credentials as credentials.json
```

**3. Install Dependencies:**
```bash
pip install google-auth google-auth-oauthlib google-auth-httplib2 google-api-python-client --break-system-packages
```

**4. Initial Authentication:**
```bash
python scripts/authenticate.py
# Opens browser for Google sign-in
# Saves token.json for future use
```

See [reference/setup-guide.md](reference/setup-guide.md) for detailed setup instructions.

## Core Operations

### Search for Files

**Basic search:**
```bash
python scripts/search_files.py --query "name contains 'report'"
```

**Search patterns:**
```python
# By name
query = "name contains 'Q4 Report'"

# By type
query = "mimeType = 'application/vnd.google-apps.spreadsheet'"

# By folder
query = "'FOLDER_ID' in parents"

# Modified recently
query = "modifiedTime > '2025-01-01T00:00:00'"

# Combination
query = "name contains 'budget' and mimeType contains 'spreadsheet'"
```

**Common searches:**
```bash
# Find all PDFs
python scripts/search_files.py --type pdf

# Find files modified today
python scripts/search_files.py --modified-today

# Find files in specific folder
python scripts/search_files.py --folder "Project Documents"

# Search file content (for Google Docs/Sheets)
python scripts/search_files.py --content "quarterly review"
```

See [reference/search-patterns.md](reference/search-patterns.md) for comprehensive query syntax.

### Read File Content

**Download files:**
```bash
# Google Docs/Sheets/Slides
python scripts/download_file.py --file-id FILE_ID --format pdf
python scripts/download_file.py --file-id FILE_ID --format docx
python scripts/download_file.py --file-id FILE_ID --format xlsx

# Binary files (PDFs, images, etc.)
python scripts/download_file.py --file-id FILE_ID --output ./local-file.pdf
```

**Read Google Docs as text:**
```bash
# Export as plain text
python scripts/read_doc.py --file-id FILE_ID

# Export as markdown
python scripts/read_doc.py --file-id FILE_ID --format markdown
```

**Read Sheets data:**
```bash
# Get sheet as CSV
python scripts/read_sheet.py --file-id FILE_ID --sheet "Sheet1"

# Get specific range
python scripts/read_sheet.py --file-id FILE_ID --range "A1:D10"
```

### Create and Upload Files

**Create Google Docs:**
```bash
# Create new Doc
python scripts/create_doc.py --title "Meeting Notes" --content "..."

# Create from template
python scripts/create_from_template.py --template-id TEMPLATE_ID --title "Q4 Report"
```

**Upload files:**
```bash
# Upload any file
python scripts/upload_file.py --file ./local-file.pdf --folder-id FOLDER_ID

# Upload with metadata
python scripts/upload_file.py --file ./data.csv --name "Sales Data Q4" --description "Quarterly sales figures"
```

**Create Sheets:**
```bash
# Create with data
python scripts/create_sheet.py --title "Budget 2025" --data data.csv

# Create from scratch
python scripts/create_sheet.py --title "Tracking Sheet" --headers "Date,Task,Status,Owner"
```

### Update Files

**Update Google Docs:**
```bash
# Append content
python scripts/update_doc.py --file-id FILE_ID --append "New section..."

# Replace content
python scripts/update_doc.py --file-id FILE_ID --content "Complete new content"

# Update specific paragraph
python scripts/update_doc.py --file-id FILE_ID --find "old text" --replace "new text"
```

**Update Sheets:**
```bash
# Update range
python scripts/update_sheet.py --file-id FILE_ID --range "A1:B10" --values data.csv

# Append rows
python scripts/update_sheet.py --file-id FILE_ID --append --values new_data.csv
```

### Folder Management

**Create folders:**
```bash
# Create folder
python scripts/create_folder.py --name "Project Alpha" --parent PARENT_ID

# Create nested structure
python scripts/create_folder.py --path "Projects/2025/Q1/Project Alpha"
```

**Move files:**
```bash
# Move to folder
python scripts/move_file.py --file-id FILE_ID --folder-id FOLDER_ID

# Move multiple files
python scripts/move_files.py --files file1_id,file2_id,file3_id --folder-id FOLDER_ID
```

**List folder contents:**
```bash
# List files in folder
python scripts/list_folder.py --folder-id FOLDER_ID

# Recursive listing
python scripts/list_folder.py --folder-id FOLDER_ID --recursive
```

### Permissions and Sharing

**Share files:**
```bash
# Share with specific user
python scripts/share_file.py --file-id FILE_ID --email [email protected] --role writer

# Share with anyone with link
python scripts/share_file.py --file-id FILE_ID --anyone --role reader

# Share with domain
python scripts/share_file.py --file-id FILE_ID --domain company.com --role commenter
```

**Permission roles:**
- `owner` - Full control
- `organizer` - Can organize files (Drive folders)
- `fileOrganizer` - Can organize files
- `writer` - Can edit
- `commenter` - Can comment
- `reader` - View only

**List permissions:**
```bash
# View who has access
python scripts/list_permissions.py --file-id FILE_ID
```

**Revoke access:**
```bash
# Remove permission
python scripts/revoke_permission.py --file-id FILE_ID --email [email protected]
```

## Common Workflows

### Workflow 1: Sync Project Files

**Scenario:** Keep local project synced with Drive folder

```bash
# Download entire folder
python scripts/sync_folder.py --folder-id FOLDER_ID --local ./project --download

# Upload changes
python scripts/sync_folder.py --folder-id FOLDER_ID --local ./project --upload

# Bidirectional sync
python scripts/sync_folder.py --folder-id FOLDER_ID --local ./project --sync
```

### Workflow 2: Batch Process Documents

**Scenario:** Convert all Docs in folder to PDF

```bash
# Export all docs
python scripts/batch_export.py --folder-id FOLDER_ID --format pdf --output ./exports/
```

### Workflow 3: Organize Files by Type

**Scenario:** Move files to type-specific folders

```bash
# Auto-organize
python scripts/organize_files.py --source-folder FOLDER_ID --by-type
```

### Workflow 4: Backup Drive Content

**Scenario:** Create local backup of Drive files

```bash
# Full backup
python scripts/backup_drive.py --output ./backup/ --include-versions

# Incremental backup
python scripts/backup_drive.py --output ./backup/ --since-last-backup
```

### Workflow 5: Search and Process

**Scenario:** Find all spreadsheets with "budget" and export data

```bash
# Search and process
python scripts/search_and_process.py \
  --query "name contains 'budget' and mimeType contains 'spreadsheet'" \
  --action export \
  --format csv \
  --output ./budgets/
```

## File Type Reference

### MIME Types

**Google Workspace:**
```python
MIME_TYPES = {
    'doc': 'application/vnd.google-apps.document',
    'sheet': 'application/vnd.google-apps.spreadsheet',
    'slide': 'application/vnd.google-apps.presentation',
    'form': 'application/vnd.google-apps.form',
    'folder': 'application/vnd.google-apps.folder',
}
```

**Export formats:**
```python
EXPORT_FORMATS = {
    'doc': ['pdf', 'docx', 'odt', 'rtf', 'txt', 'html', 'epub'],
    'sheet': ['pdf', 'xlsx', 'ods', 'csv', 'tsv', 'html'],
    'slide': ['pdf', 'p