rclone-sync

SKILL.md

---
name: rclone-sync
description: "Sync files between local directories and Google Drive using rclone. Provides bidirectional sync, copy, move, and backup operations. Use for transferring files between local and cloud, syncing directories, or managing cloud storage. Keywords: rclone, sync, backup, Google Drive, cloud storage, transfer files, gdrive, copy to drive."
version: 1.1.0
metadata:
  polly:
    auth:
      - env: POLLY_GDRIVE_TOKEN
        type: oauth2
        integration_id: google-drive
        description: Google Drive access for rclone
        scopes:
          - https://www.googleapis.com/auth/drive
    primaryEnv: POLLY_GDRIVE_TOKEN
---

# Rclone Sync Skill

Manage file transfers between local directories and Google Drive using rclone.

## Prerequisites

### 1. Nango Integration
A `google-drive` integration must exist in Nango **before** this skill can authenticate. The integration requires:
- **Provider:** `google-drive`
- **Integration ID:** `google-drive`
- **Scopes:** `https://www.googleapis.com/auth/drive`
- **OAuth params:** `access_type=offline`, `prompt=consent` (required to receive a refresh token)

If the integration is missing, `manage_auth(action="connect", integration_id="google-drive")` will return `setup_required`. An admin must create the integration first.

### 2. rclone Binary
Install rclone to `~/.local/bin` (no root required):
```bash
bash ~/skills/installed/rclone-sync/scripts/install-deps.sh
```
This only needs to be run once. Confirm with: `~/.local/bin/rclone version`

## Authentication Setup

Once the Nango integration exists, connect your Google Drive account:
```bash
manage_auth(action="connect", integration_id="google-drive")
```

**Token lifetime:** Access tokens expire in ~1 hour. If rclone returns a 401 error, re-run the above command to refresh. Ensure the Nango integration uses `access_type=offline` + `prompt=consent` to receive a refresh token for automatic renewal.

## Quick Start

Use the wrapper script directly (it handles all auth and config automatically):

```bash
GDRIVE=~/skills/installed/rclone-sync/scripts/rclone-gdrive.sh

# List Drive root
$GDRIVE lsd gdrive: --max-depth 1

# Copy file to Drive
$GDRIVE copy ./file.txt "gdrive:/folder/"

# Sync local folder TO Drive
$GDRIVE sync ./folder "gdrive:/backup/" --dry-run   # preview first
$GDRIVE sync ./folder "gdrive:/backup/"              # then execute
```

## Core Operations

### List Files
```bash
# List directories in root
$GDRIVE lsd gdrive: --max-depth 1

# List files in folder
$GDRIVE ls "gdrive:/My Folder/"
```

### Copy Files
```bash
# Upload single file
$GDRIVE copy ./report.pdf "gdrive:/Documents/"

# Upload directory (recursive)
$GDRIVE copy ./photos "gdrive:/Photos/" --progress

# Download file
$GDRIVE copy "gdrive:/Documents/report.pdf" ./
```

### Sync (Important: Read First!)

**Sync makes the destination MATCH the source.** Files in the destination not in the source will be DELETED. Always dry-run first.

```bash
# Dry run (safe — shows what would happen, changes nothing)
$GDRIVE sync ./folder "gdrive:/backup/" --dry-run

# Then actually sync
$GDRIVE sync ./folder "gdrive:/backup/"
```

### Move and Stream
```bash
# Move file to Drive (removes local copy)
$GDRIVE move ./file.txt "gdrive:/folder/"

# Upload from stdin
cat file.html | $GDRIVE rcat "gdrive:/polly/file.html"

# View file contents
$GDRIVE cat "gdrive:/document.txt"
```

### Storage Management
```bash
# Check storage usage
$GDRIVE about gdrive:

# Empty trash
$GDRIVE cleanup gdrive:
```

## Filters and Options

```bash
# Exclude specific paths
$GDRIVE sync ./folder "gdrive:/backup/" --exclude ".git/**" --exclude "node_modules/**"

# Bandwidth limit
$GDRIVE sync ./folder "gdrive:/backup/" --bwlimit 1M

# Show progress
$GDRIVE copy ./large-file.zip "gdrive:/" --progress
```

## Troubleshooting

| Error | Cause | Fix |
|---|---|---|
| `rclone not found` | Binary not installed | Run `scripts/install-deps.sh` |
| `401 Unauthorized` | Access token expired | Re-run `manage_auth(connect)` |
| `Failed to load config` | Token format issue | Wrapper handles this automatically in v1.1.0+ |
| `setup_required` on connect | Nango integration missing | Ask admin to create `google-drive` integration in Nango |

## Reference Files

- [references/commands.md](references/commands.md) - Full command reference