Google Drive Source - Cloudstic CLI

The Google Drive source backs up files from Google Drive, including both My Drive and Shared Drives (formerly Team Drives). Cloudstic supports full and incremental backups using Google’s Drive API.

Source Types

Cloudstic provides two Google Drive source types:

gdrive — Full scan (lists all files on every backup)
gdrive-changes — Incremental (uses Changes API, recommended)

Use gdrive-changes for faster incremental backups. It only fetches changes since the last backup, making subsequent backups significantly faster.

Basic Usage

First-Time Setup

On your first backup, Cloudstic will open your browser to authenticate with Google:

cloudstic backup -source gdrive

You’ll see:

Opening browser for authorization...

After granting permissions, the OAuth token is saved to ~/.config/cloudstic/google_token.json and automatically reused for future backups.

Incremental Backups (Recommended)

Use the Changes API for faster backups:

cloudstic backup -source gdrive-changes

Configuration Options

Source Flags

Flag	Description	Environment Variable
`-source gdrive`	Full scan source	`CLOUDSTIC_SOURCE`
`-source gdrive-changes`	Incremental source (recommended)	`CLOUDSTIC_SOURCE`
`-drive-id <id>`	Shared Drive ID (omit for My Drive)	`CLOUDSTIC_DRIVE_ID`
`-root-folder <id>`	Root folder ID (defaults to entire drive)	`CLOUDSTIC_ROOT_FOLDER`

Authentication

Environment Variable	Description
`GOOGLE_APPLICATION_CREDENTIALS`	Path to service account credentials JSON (optional)
`GOOGLE_TOKEN_FILE`	Path to OAuth token file (default: `~/.config/cloudstic/google_token.json`)

Optional Flags

Flag	Description
`-exclude <pattern>`	Exclude pattern (gitignore syntax, repeatable)
`-exclude-file <path>`	Load exclude patterns from file
`-tag <tag>`	Tag to apply to the snapshot (repeatable)
`-dry-run`	Scan source without writing to store

Examples

Backup My Drive

Back up your entire Google Drive:

cloudstic backup -source gdrive-changes

Backup a Shared Drive

Back up a Shared Drive by ID:

cloudstic backup -source gdrive-changes \
  -drive-id "0ANj8fbyJk9BxUk9PVA"

To find a Shared Drive ID, open the drive in your browser and copy the ID from the URL: https://drive.google.com/drive/folders/[DRIVE_ID]

Backup Specific Folder

Restrict backup to a specific folder:

cloudstic backup -source gdrive-changes \
  -root-folder "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVwQA"

To find a folder ID, open the folder in Google Drive and copy the ID from the URL:

https://drive.google.com/drive/folders/[FOLDER_ID]

Backup with Exclusions

Exclude specific folders or file types:

cloudstic backup -source gdrive-changes \
  -exclude "Trash/" \
  -exclude "*.tmp" \
  -exclude "Cache/"

Backup with Tags

cloudstic backup -source gdrive-changes \
  -tag "gdrive" \
  -tag "work" \
  -tag "$(date +%Y-%m)"

Authentication Methods

Cloudstic supports two authentication methods for Google Drive:

1. OAuth 2.0 (Default, Recommended)

How it works:

First run

Cloudstic opens your browser to Google’s consent page.

Grant permissions

Allow Cloudstic to access your Google Drive (read-only).

Token saved

The OAuth token is saved to ~/.config/cloudstic/google_token.json.

Automatic renewal

Tokens are automatically refreshed when expired.

Permissions requested:

https://www.googleapis.com/auth/drive.readonly — Read-only access to your files

2. Service Account (Advanced)

For automated backups without user interaction, use a service account:

Create service account

In Google Cloud Console:

Go to IAM & Admin > Service Accounts
Create a new service account
Download the JSON key file

Grant Drive access

Share your Drive or folders with the service account email:

service-account@project-id.iam.gserviceaccount.com

Set credentials path

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
cloudstic backup -source gdrive-changes

For Shared Drives, you must have domain-wide delegation enabled and the service account must be granted access to the Shared Drive.

OAuth Flow Details

First Backup

When you run your first backup:

Browser opens — Cloudstic starts a local HTTP server and opens your browser
Google consent — You sign in and grant permissions
Automatic callback — The authorization code is captured automatically
Token exchange — Cloudstic exchanges the code for an access token
Token saved — Token is saved to ~/.config/cloudstic/google_token.json
Backup starts — Files are scanned and backed up

Subsequent Backups

Token loaded — Existing token is read from disk
Automatic refresh — If expired, the token is refreshed using the refresh token
Backup starts — No browser interaction needed

Token Location

By default, tokens are stored at:

Linux/macOS: ~/.config/cloudstic/google_token.json
Windows: %APPDATA%\cloudstic\google_token.json

Customize the location:

export GOOGLE_TOKEN_FILE=/path/to/token.json

How It Works

Full Scan (`gdrive`)

List all folders

Fetch all folders using the Drive API.

Topological sort

Sort folders so parents are processed before children.

Emit folders

Process folders in order, applying exclude patterns.

List all files

Fetch all files page-by-page.

Emit files

Process files, computing paths from parent relationships.

Incremental Scan (`gdrive-changes`)

First backup

Performs a full scan and captures a start page token.

Subsequent backups

Uses the Changes API to fetch only modified/added/deleted items since the last token.

Apply changes

Updates the snapshot with changes, removing deleted files.

Save new token

Stores the new page token for the next backup.

File Identification

Google Drive files are identified by their Drive file ID:

File ID: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVwQA
Name: report.pdf
Path: Documents/report.pdf (computed from parent relationships)

Content Deduplication

Cloudstic uses Google Drive’s SHA-256 checksums to avoid re-uploading unchanged files:

If the checksum matches, the file is skipped
Only changed files are downloaded and backed up

Source Information

Each snapshot records:

Type: gdrive or gdrive-changes
Account: Google account email (e.g., user@gmail.com)
Path: my-drive:// or <driveID>://<rootFolderID>

Performance Considerations

Full Scan Performance

First backup: 10-50 files/second (limited by API rate limits)
API calls: ~2 requests per 1000 files
Bottleneck: Network latency and API quotas

Incremental Performance

Small changes: Completes in seconds (only fetches changes)
Large changes: Proportional to number of changed files
Recommended: Use gdrive-changes for faster backups

API Rate Limits

Google Drive API has rate limits:

Queries per 100 seconds: 1000 (per user)
Queries per day: 1,000,000,000 (per project)

Cloudstic automatically retries on rate limit errors (HTTP 429).

Google Drive Specifics

Google Workspace Files

Google Workspace files (Docs, Sheets, Slides) are not backed up as binary files because:

They don’t have a native binary format
They can be exported, but formats vary
They’re stored in Google’s proprietary format

To back up Google Workspace files:

Export them to standard formats (PDF, DOCX, XLSX) manually
Store exports in a regular Drive folder
Back up the exported files

Folder Structure

Google Drive allows files to have multiple parents. Cloudstic handles this by:

Choosing the first parent when computing paths
Storing all parent IDs in metadata
Preserving the file under its primary path

Trashed Files

Trashed files are automatically excluded from backups. Only files in your Drive (not in Trash) are backed up.

Common Use Cases

Personal Backup

# Backup your entire Google Drive
cloudstic backup -source gdrive-changes \
  -tag "personal" \
  -tag "gdrive"

Shared Drive Backup

# Backup a team's Shared Drive
cloudstic backup -source gdrive-changes \
  -drive-id "0ANj8fbyJk9BxUk9PVA" \
  -tag "team-drive" \
  -tag "marketing"

Selective Folder Backup

# Backup only the "Important" folder
cloudstic backup -source gdrive-changes \
  -root-folder "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVwQA" \
  -tag "important"

Automated Backups

Use a service account for automated backups:

#!/bin/bash
export GOOGLE_APPLICATION_CREDENTIALS=/etc/cloudstic/service-account.json
export CLOUDSTIC_STORE=s3
export CLOUDSTIC_STORE_PATH=my-backup-bucket

cloudstic backup -source gdrive-changes \
  -tag "automated" \
  -tag "$(date +%Y-%m-%d)"

Troubleshooting

Authentication Failed

Error: oauth2: cannot fetch token

Solutions:

Delete the token file and re-authenticate:

rm ~/.config/cloudstic/google_token.json
cloudstic backup -source gdrive-changes

Check that you have internet connectivity
Verify Google Drive API is enabled in your project (for service accounts)

Rate Limit Exceeded

Error: googleapi: Error 429: Rate Limit Exceeded

Solutions:

Cloudstic automatically retries with exponential backoff
Wait a few minutes and try again
For frequent backups, use gdrive-changes instead of gdrive

Permission Denied

Error: googleapi: Error 403: Insufficient permissions

Solutions:

Ensure you granted the drive.readonly scope during OAuth
For Shared Drives, ensure you have access to the drive
For service accounts, share the drive/folders with the service account email

Slow Backups

If backups are taking too long:

Switch to gdrive-changes for incremental backups
Use -root-folder to limit scope
Add exclude patterns to skip unnecessary folders
Check API quotas in Google Cloud Console

Environment Variables

Set default Google Drive configuration:

export CLOUDSTIC_SOURCE=gdrive-changes
export GOOGLE_TOKEN_FILE=~/.config/cloudstic/google_token.json

# For Shared Drives
export CLOUDSTIC_DRIVE_ID="0ANj8fbyJk9BxUk9PVA"

# For service accounts
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

# Now run backup
cloudstic backup

Next Steps

OneDrive Source

Learn about backing up Microsoft OneDrive

Service Accounts

Set up service accounts for automation

Scheduling Backups

Automate backups with cron or systemd

Restore Files

Learn how to restore your backed up files

Get Started

Core Concepts

Sources

Storage Backends

Guides

​Source Types

​Basic Usage

​First-Time Setup

​Incremental Backups (Recommended)

​Configuration Options

​Source Flags

​Authentication

​Optional Flags

​Examples

​Backup My Drive

​Backup a Shared Drive

​Backup Specific Folder

​Backup with Exclusions

​Backup with Tags

​Authentication Methods

​1. OAuth 2.0 (Default, Recommended)

​2. Service Account (Advanced)

​OAuth Flow Details

​First Backup

​Subsequent Backups

​Token Location

​How It Works

​Full Scan (gdrive)

​Incremental Scan (gdrive-changes)

​File Identification

​Content Deduplication

​Source Information

​Performance Considerations

​Full Scan Performance

​Incremental Performance

​API Rate Limits

​Google Drive Specifics

​Google Workspace Files

​Folder Structure

​Trashed Files

​Common Use Cases

​Personal Backup

​Shared Drive Backup

​Selective Folder Backup

​Automated Backups

​Troubleshooting

​Authentication Failed

​Rate Limit Exceeded

​Permission Denied

​Slow Backups

​Environment Variables

​Next Steps

OneDrive Source

Service Accounts

Scheduling Backups

Restore Files

Source Types

Basic Usage

First-Time Setup

Incremental Backups (Recommended)

Configuration Options

Source Flags

Authentication

Optional Flags

Examples

Backup My Drive

Backup a Shared Drive

Backup Specific Folder

Backup with Exclusions

Backup with Tags

Authentication Methods

1. OAuth 2.0 (Default, Recommended)

2. Service Account (Advanced)

OAuth Flow Details

First Backup

Subsequent Backups

Token Location

How It Works

Full Scan (`gdrive`)

Incremental Scan (`gdrive-changes`)

File Identification

Content Deduplication

Source Information

Performance Considerations

Full Scan Performance

Incremental Performance

API Rate Limits

Google Drive Specifics

Google Workspace Files

Folder Structure

Trashed Files

Common Use Cases

Personal Backup

Shared Drive Backup

Selective Folder Backup

Automated Backups

Troubleshooting

Authentication Failed

Rate Limit Exceeded

Permission Denied

Slow Backups

Environment Variables

Next Steps