OneDrive Source - Cloudstic CLI

The OneDrive source backs up files from Microsoft OneDrive using the Microsoft Graph API. Cloudstic supports both full and incremental backups.

Source Types

Cloudstic provides two OneDrive source types:

onedrive: Full scan (lists all files on every backup)
onedrive-changes: Incremental (uses Delta API, recommended)

Use onedrive-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 Microsoft:

cloudstic backup -source onedrive

You’ll see:

Opening browser for authorization...

After signing in and granting permissions, the OAuth token is saved to your config directory and automatically reused for future backups.

Incremental Backups (Recommended)

Use the Delta API for faster backups:

cloudstic backup -source onedrive-changes

Configuration Options

Source Flags

Flag	Description	Environment Variable
`-source onedrive`	Full scan source	`CLOUDSTIC_SOURCE`
`-source onedrive-changes`	Incremental source (recommended)	`CLOUDSTIC_SOURCE`

Authentication

Environment Variable	Description
`ONEDRIVE_CLIENT_ID`	Custom Azure AD app client ID (optional)
`ONEDRIVE_TOKEN_FILE`	Path to OAuth token file (default: `<config-dir>/onedrive_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 OneDrive

Back up your entire OneDrive:

cloudstic backup -source onedrive-changes

Backup with Exclusions

Exclude specific folders or file types:

cloudstic backup -source onedrive-changes \
  -exclude "Screenshots/" \
  -exclude "*.tmp" \
  -exclude "Camera Roll/"

Backup with Tags

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

Dry Run

See what would be backed up:

cloudstic backup -source onedrive-changes -dry-run

Authentication Methods

Cloudstic supports two authentication methods for OneDrive:

1. Built-in OAuth Client (Default)

How it works:

First run

Cloudstic opens your browser to Microsoft’s login page.

Token saved

The OAuth token is saved to onedrive_token.json in your config directory.

Automatic renewal

Tokens are automatically refreshed when expired.

Permissions requested:

Files.Read: Read your files
Files.Read.All: Read all files you have access to
User.Read: Read your profile (for account identification)
offline_access: Maintain access when you’re not using the app

2. Custom Azure AD App (Advanced)

For organizational use, register your own Azure AD application:

Go to Azure Portal > Azure Active Directory > App registrations
Click “New registration”
Name: “Cloudstic Backup”
Redirect URI: http://localhost (Public client/native)

Configure API permissions

Add delegated permissions:

Files.Read
Files.Read.All
User.Read
offline_access

Grant admin consent if required by your organization.

Copy client ID

Copy the “Application (client) ID” from the Overview page.

Set environment variable

export ONEDRIVE_CLIENT_ID="your-client-id-here"
cloudstic backup -source onedrive-changes

OAuth Flow Details

First Backup

When you run your first backup:

Browser opens: Cloudstic starts a local HTTP server and opens your browser
Microsoft login: You sign in to your Microsoft account
Consent screen: Grant permissions to Cloudstic
Automatic callback: The authorization code is captured automatically
Token exchange: Cloudstic exchanges the code for an access token
Token saved: Token is saved to onedrive_token.json in your config directory
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:

macOS: ~/Library/Application Support/cloudstic/onedrive_token.json
Linux: ~/.config/cloudstic/onedrive_token.json
Windows: %AppData%\cloudstic\onedrive_token.json

Customize the location:

export ONEDRIVE_TOKEN_FILE=/path/to/token.json

How It Works

Full Scan (`onedrive`)

Get root item

Fetch the root folder of your OneDrive.

Iterative DFS

Use depth-first search to traverse the folder tree.

List children

For each folder, list all child items via Microsoft Graph API.

Apply exclusions

Filter items based on exclude patterns.

Emit items

Process files and folders, computing paths from parent relationships.

Incremental Scan (`onedrive-changes`)

First backup

Performs a full scan and captures a delta link (change token).

Subsequent backups

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

Apply changes

Updates the snapshot with changes, removing deleted files.

Save new delta link

Stores the new delta link for the next backup.

File Identification

OneDrive files are identified by their Microsoft Graph item ID:

Item ID: 01BYE5RZ6QN3ZWBTUFOFD3GSPGOHDJD36K
Name: report.pdf
Path: Documents/report.pdf (computed from parent relationships)

Content Deduplication

Cloudstic uses content-based hashing to avoid re-uploading unchanged files:

Files are hashed using FastCDC chunking
Unchanged chunks are skipped during upload
Only new or modified chunks are stored

Source Information

Each snapshot records:

Type: onedrive or onedrive-changes
Account: User principal name (e.g., user@outlook.com)
Path: onedrive://

Performance Considerations

Full Scan Performance

First backup: 10-50 files/second (limited by API rate limits)
API calls: ~1 request per folder + pagination
Bottleneck: Network latency and API throttling

Incremental Performance

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

API Rate Limits

Microsoft Graph API has throttling limits:

Requests per second: Varies by workload type
Retry-After: Honor the Retry-After header on 429 responses

Cloudstic automatically retries on throttling errors (HTTP 429 and 503).

OneDrive Specifics

OneNote Notebooks

OneNote notebooks are represented as “package” items in OneDrive and are not backed up because:

They’re stored in a proprietary format
They’re not downloadable via the /content endpoint
Sections and pages are not individual files

To back up OneNote content, export notebooks to PDF or other formats manually before backing up.

Folder Structure

OneDrive maintains a hierarchical folder structure. Cloudstic:

Preserves the original folder hierarchy
Computes full paths from parent references
Stores items under their canonical path

Deleted Files

Deleted files are automatically tracked when using onedrive-changes:

The Delta API reports deletions
Cloudstic removes deleted files from the snapshot
Files are not restored from the recycle bin

Common Use Cases

Personal Backup

# Backup your entire OneDrive
cloudstic backup -source onedrive-changes \
  -tag "personal" \
  -tag "onedrive"

Exclude Photos

Skip camera uploads and screenshots:

cloudstic backup -source onedrive-changes \
  -exclude "Pictures/Camera Roll/" \
  -exclude "Pictures/Screenshots/" \
  -tag "documents"

Selective Backup

Back up only important folders:

cloudstic backup -source onedrive-changes \
  -exclude "Music/" \
  -exclude "Videos/" \
  -exclude "Pictures/" \
  -tag "documents-only"

Automated Backups

Schedule automated backups:

#!/bin/bash
# /usr/local/bin/onedrive-backup.sh

export CLOUDSTIC_STORE=s3:my-backup-bucket
export ONEDRIVE_TOKEN_FILE=/etc/cloudstic/onedrive_token.json

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

Add to crontab:

0 2 * * * /usr/local/bin/onedrive-backup.sh

Troubleshooting

Authentication Failed

Error: oauth2: cannot fetch token

Solutions:

Delete the token file and re-authenticate:

# macOS
rm ~/Library/Application\ Support/cloudstic/onedrive_token.json
# Linux
rm ~/.config/cloudstic/onedrive_token.json
cloudstic backup -source onedrive-changes

Check that you have internet connectivity
Verify your Microsoft account credentials

Token Expired

Error: token expired and refresh failed

Solutions:

Delete the token and re-authenticate
Ensure offline_access permission was granted
Check that the token file is not corrupted

Throttling

Error: 429 Too Many Requests

Solutions:

Cloudstic automatically retries with exponential backoff
Wait a few minutes and try again
For frequent backups, ensure you’re using onedrive-changes

Permission Denied

Error: 403 Forbidden

Solutions:

Ensure you granted the required permissions during OAuth
For custom Azure AD apps, verify API permissions are configured correctly
Grant admin consent if required by your organization

Slow Backups

If backups are taking too long:

Switch to onedrive-changes for incremental backups
Add exclude patterns to skip unnecessary folders
Check API throttling: OneDrive may be rate limiting your requests
Schedule during off-peak hours

Environment Variables

Set default OneDrive configuration:

export CLOUDSTIC_SOURCE=onedrive-changes
export ONEDRIVE_TOKEN_FILE=~/.config/cloudstic/onedrive_token.json  # Linux default

# For custom Azure AD apps
export ONEDRIVE_CLIENT_ID="your-client-id"

# Now run backup
cloudstic backup

Personal vs. Business Accounts

Personal Accounts (outlook.com, live.com, hotmail.com)

Cloudstic supports personal Microsoft accounts out of the box:

cloudstic backup -source onedrive-changes

Business/Education Accounts (Office 365, Microsoft 365)

For organizational accounts:

Check with IT: Some organizations restrict third-party app access
Use custom Azure AD app: Register your own app (see above)
Request admin consent: May be required for organizational accounts

If you encounter permission errors with a business account, contact your IT administrator to enable third-party app access or register a custom Azure AD application.

OneDrive for Business

OneDrive for Business accounts work the same way as personal accounts, but:

You may need admin consent for API permissions
Some organizations block third-party apps entirely
SharePoint sites are not included (OneDrive only)

To back up SharePoint sites, use OneDrive for Business sync folders or contact your administrator for API access.

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 OneDrive

​Backup with Exclusions

​Backup with Tags

​Dry Run

​Authentication Methods

​1. Built-in OAuth Client (Default)

​2. Custom Azure AD App (Advanced)

​OAuth Flow Details

​First Backup

​Subsequent Backups

​Token Location

​How It Works

​Full Scan (onedrive)

​Incremental Scan (onedrive-changes)

​File Identification

​Content Deduplication

​Source Information

​Performance Considerations

​Full Scan Performance

​Incremental Performance

​API Rate Limits

​OneDrive Specifics

​OneNote Notebooks

​Folder Structure

​Deleted Files

​Common Use Cases

​Personal Backup

​Exclude Photos

​Selective Backup

​Automated Backups

​Troubleshooting

​Authentication Failed

​Token Expired

​Throttling

​Permission Denied

​Slow Backups

​Environment Variables

​Personal vs. Business Accounts

​Personal Accounts (outlook.com, live.com, hotmail.com)

​Business/Education Accounts (Office 365, Microsoft 365)

​OneDrive for Business

​Next Steps

Google Drive Source

Custom OAuth Credentials

Scheduling Backups

Restore Files

Source Types

Basic Usage

First-Time Setup

Incremental Backups (Recommended)

Configuration Options

Source Flags

Authentication

Optional Flags

Examples

Backup OneDrive

Backup with Exclusions

Backup with Tags

Dry Run

Authentication Methods

1. Built-in OAuth Client (Default)

2. Custom Azure AD App (Advanced)

OAuth Flow Details

First Backup

Subsequent Backups

Token Location

How It Works

Full Scan (`onedrive`)

Incremental Scan (`onedrive-changes`)

File Identification

Content Deduplication

Source Information

Performance Considerations

Full Scan Performance

Incremental Performance

API Rate Limits

OneDrive Specifics

OneNote Notebooks

Folder Structure

Deleted Files

Common Use Cases

Personal Backup

Exclude Photos

Selective Backup

Automated Backups

Troubleshooting

Authentication Failed

Token Expired

Throttling

Permission Denied

Slow Backups

Environment Variables

Personal vs. Business Accounts

Personal Accounts (outlook.com, live.com, hotmail.com)

Business/Education Accounts (Office 365, Microsoft 365)

OneDrive for Business

Next Steps