google-drive

What this skill does

# Google Drive

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

## Installation

**Dependencies**: `pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml`

## Setup Verification

After installation, verify the skill is properly configured:

```bash
$SKILL_DIR/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](https://github.com/odyssey4me/agent-skills/blob/main/docs/gcp-project-setup.md) - Create project, enable Drive API
2. [Google OAuth Setup Guide](https://github.com/odyssey4me/agent-skills/blob/main/docs/google-oauth-setup.md) - 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 `$SKILL_DIR/scripts/google-drive.py check` to trigger OAuth flow and verify setup.

On scope or authentication errors, see the [OAuth troubleshooting guide](https://github.com/odyssey4me/agent-skills/blob/main/docs/google-oauth-setup.md#troubleshooting).

## Script Usage

See [permissions.md](references/permissions.md) for read/write classification of each command.

```bash
# Setup and auth
$SKILL_DIR/scripts/google-drive.py check
$SKILL_DIR/scripts/google-drive.py auth setup --client-id ID --client-secret SECRET
$SKILL_DIR/scripts/google-drive.py auth reset
$SKILL_DIR/scripts/google-drive.py auth status

# Files
$SKILL_DIR/scripts/google-drive.py files list [--query QUERY] [--max-results N] [--order-by FIELD]
$SKILL_DIR/scripts/google-drive.py files search [--name NAME] [--mime-type TYPE] [--folder ID]
$SKILL_DIR/scripts/google-drive.py files get FILE_ID
$SKILL_DIR/scripts/google-drive.py files download FILE_ID --output PATH
$SKILL_DIR/scripts/google-drive.py files export FILE_ID [--format markdown|text|pdf] [--lines N] [--output PATH]
$SKILL_DIR/scripts/google-drive.py files upload PATH [--parent ID] [--name NAME] [--mime-type TYPE] [--convert-to MIME_TYPE]
$SKILL_DIR/scripts/google-drive.py files move FILE_ID --parent FOLDER_ID
$SKILL_DIR/scripts/google-drive.py files delete FILE_ID
$SKILL_DIR/scripts/google-drive.py files rename FILE_ID --name NAME
$SKILL_DIR/scripts/google-drive.py files copy FILE_ID [--name NAME] [--parent ID]

# Folders
$SKILL_DIR/scripts/google-drive.py folders create NAME [--parent ID]
$SKILL_DIR/scripts/google-drive.py folders list FOLDER_ID [--max-results N]

# Sharing and permissions
$SKILL_DIR/scripts/google-drive.py share FILE_ID --email EMAIL [--role ROLE] [--no-notify]
$SKILL_DIR/scripts/google-drive.py permissions list FILE_ID
$SKILL_DIR/scripts/google-drive.py permissions delete FILE_ID PERMISSION_ID

# Comments
$SKILL_DIR/scripts/google-drive.py comments list FILE_ID [--max-results N] [--include-deleted]
$SKILL_DIR/scripts/google-drive.py comments get FILE_ID COMMENT_ID
$SKILL_DIR/scripts/google-drive.py comments create FILE_ID --content TEXT [--quoted-text TEXT]
$SKILL_DIR/scripts/google-drive.py comments update FILE_ID COMMENT_ID --content TEXT
$SKILL_DIR/scripts/google-drive.py comments delete FILE_ID COMMENT_ID

# Replies
$SKILL_DIR/scripts/google-drive.py replies list FILE_ID COMMENT_ID [--max-results N] [--include-deleted]
$SKILL_DIR/scripts/google-drive.py replies get FILE_ID COMMENT_ID REPLY_ID
$SKILL_DIR/scripts/google-drive.py replies create FILE_ID COMMENT_ID --content TEXT [--action resolve|reopen]
$SKILL_DIR/scripts/google-drive.py replies update FILE_ID COMMENT_ID REPLY_ID --content TEXT
$SKILL_DIR/scripts/google-drive.py replies delete FILE_ID COMMENT_ID REPLY_ID
```

See [command-reference.md](references/command-reference.md) for full argument details and examples.

## Examples

### Verify Setup

```bash
$SKILL_DIR/scripts/google-drive.py check
```

### Find recent PDF files

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

### Search for documents by name

```bash
$SKILL_DIR/scripts/google-drive.py files search --name "project proposal"
```

### Download a file

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

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

### Export a Google Doc

```bash
# Export as markdown (default)
$SKILL_DIR/scripts/google-drive.py files export FILE_ID

# Export as plain text (useful as fallback for large docs)
$SKILL_DIR/scripts/google-drive.py files export FILE_ID --format text

# Export first 50 lines only
$SKILL_DIR/scripts/google-drive.py files export FILE_ID --format text --lines 50

# Export as PDF
$SKILL_DIR/scripts/google-drive.py files export FILE_ID --format pdf --output ./doc.pdf
```

### Upload and share a file

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

# Share with a colleague
$SKILL_DIR/scripts/google-drive.py share FILE_ID --email [email protected] --role writer
```

### Upload with format conversion

Use `--convert-to` to convert uploaded files to native Google formats:

```bash
# Upload HTML and convert to Google Docs
$SKILL_DIR/scripts/google-drive.py files upload ./report.html \
  --convert-to "application/vnd.google-apps.document"

# Upload CSV and convert to Google Sheets
$SKILL_DIR/scripts/google-drive.py files upload ./data.csv \
  --convert-to "application/vnd.google-apps.spreadsheet"
```

**Note:** For importing markdown files as Google Docs with proper formatting (frontmatter support, line spacing, bullet handling, readability checks), use the **google-docs** skill's `documents import` command instead — it provides markdown-specific conversion and post-import formatting that `--convert-to` does not.

### Permanently delete a file

```bash
$SKILL_DIR/scripts/google-drive.py files delete FILE_ID
```

### Rename a file

```bash
$SKILL_DIR/scripts/google-drive.py files rename FILE_ID --name "New Name"
```

### Copy a file

```bash
# Copy with default name ("Copy of <original>")
$SKILL_DIR/scripts/google-drive.py files copy FILE_ID

# Copy with custom name into a specific folder
$SKILL_DIR/scripts/google-drive.py files copy FILE_ID --name "Backup" --parent FOLDER_ID
```

### Organize files into folders

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

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

# List folder contents
$SKILL_DIR/scripts/google-drive.py folders list FOLDER_ID
```

### List comments on a file

```bash
$SKILL_DIR/scripts/google-drive.py comments list FILE_ID
```

### Add a comment with a mention

To mention a user, include their email with an `@` prefix in the content text.

```bash
$SKILL_DIR/scripts/google-drive.py comments create FILE_ID \
  --content "Hey @[email protected] please review this section"
```

### Reply to a comment and resolve it

```bash
$SKILL_DIR/scripts/google-drive.py replies create FILE_ID COMMENT_ID \
  --content "Fixed in latest revision" --action resolve
```

### Reopen a resolved comment

```bash
$SKILL_DIR/scripts/google-drive.py replies create FILE_ID COMMENT_ID \
  --content "Actually this still needs work" --action reopen
```

## Drive Search Query Syntax

See [drive-queries.md](references/drive-queries.md) for operators, searchable fields, and query examples.

## Common MIME Types

See [api-reference.md](references/api-reference.md) for MIME types used with `--mime-type` and search queries.