Rclone Manager

A powerful Python CLI tool that simplifies rclone operations with an intuitive interface for managing file transfers, mounting cloud storage, serving files, and automating sync tasks.

Features

📤 Upload/Download: Interactive file transfers with overwrite protection
🔗 Mount Remotes: Mount cloud storage as local directories with FUSE
🌐 Serve Files: Share local/remote files via HTTP, WebDAV, or FTP
🔄 Sync Pairs: Automate recurring sync tasks with configurable modes (11 modes)
☁️ Multi-Cloud: Support for Google Drive, Mega, Google Photos, and all rclone backends
📊 Status Dashboard: View active mounts with live transfer stats and sync pairs
🛠️ Storage Utils: Checksum verification, deduplication, space usage, copy-between remotes
🖥️ Web UI: Browser-based file manager (optional Streamlit)
🧪 Tested: 86 unit tests + 4 integration tests, CI pipeline

Supported Storage Providers

Google Drive (including shared drives)
Mega
Google Photos
Any rclone-supported backend (S3, Dropbox, OneDrive, etc.)

Prerequisites

Python 3.10+
rclone installed and configured
uv package manager (recommended)
fzf (optional, recommended for fuzzy search)
Windows only: WinFsp required for rman mount (kernel driver for FUSE support)

Installation

Clone the repository:

git clone https://github.com/Onehand-Coding/rclone-manager.git
cd rclone-manager

Install dependencies:

uv sync

Configure rclone remotes:

rclone config

Generate default config (optional):

uv run rclone-manager generate-config

This creates configs/config.ini with example settings. Edit it to customize credentials and rclone flags.

Configuration

All configuration files live in the configs/ directory:

rclone-manager/
├── configs/
│   ├── config.ini           # Main configuration (create from .example)
│   ├── config.ini.example   # Template with defaults
│   └── sync-pairs.json      # Automated sync pair definitions

config.ini

Contains:

DEFAULT section: Log level, port, username/password for serving, bind address, XSRF/CORS toggles
rclone_flags section: Custom flags per remote type (mega, drive, google photos)
filters section: Global exclude/include patterns for transfers

Key security defaults (all configurable):

Setting	Default	Description
`BIND_ADDRESS`	`127.0.0.1`	Bind serve/Web UI to localhost only
`ENABLE_XSRF_PROTECTION`	`true`	Cross-site request forgery protection
`ENABLE_CORS`	`true`	CORS restricted to origin
`PASSWORD`	(required)	No default — must be explicitly set

Credentials for rclone serve are passed via environment variables (RCLONE_USER/RCLONE_PASS) — never exposed on the command line or in process listings.

sync-pairs.json

Defines automated sync tasks with modes like upload-only, download-only, sync, and two-way bisync.

Filters

Global exclude/include patterns are applied to all upload, download, and sync operations.

Default exclude patterns:

.git/, .venv/, __pycache__/
*.pyc, *.pyo, .DS_Store, Thumbs.db
*.tmp, *.swp, .cache/, node_modules/

Manage filters:

# Interactive filter management
uv run rclone-manager filters

# Add temporary excludes during upload/download
# Prompts for patterns like: *.log, temp/, .git/

Per-pair filters (in sync-pairs.json):

{
  "name": "Work Docs",
  "local": "/home/user/Work",
  "remote": "drive:Backup/Work",
  "mode": "upload_only",
  "filters": {
    "exclude": ["*.tmp", "drafts/"]
  }
}

Usage

Core Commands

Upload Files

uv run rclone-manager upload [--overwrite]

Interactive upload with file/folder selection and remote destination choice.

Download Files

uv run rclone-manager download [--overwrite]

Interactive download from remote storage.

Sync Between Remotes

uv run rclone-manager sync [--dry-run] [--preview] [--force]

Direct sync between two remote storages (no local download).

⚠️ Warning: sync is destructive — files on the destination that don't exist in the source will be deleted.

Options:

--dry-run — Show what would be transferred without making changes
--preview — Show files that would be copied/deleted/overwritten, then ask for confirmation
--force — Skip confirmation (use with caution!)

Examples:

# Preview what would happen (recommended first)
uv run rclone-manager sync --preview

# Dry run to test without changes
uv run rclone-manager sync --dry-run

# Force sync without confirmation (scripted use)
uv run rclone-manager sync --force

Mount & Serve

Mount Remote

uv run rclone-manager mount

Mount a remote as a local directory (FUSE).

Unmount

uv run rclone-manager unmount

Unmount active rclone mounts.

Serve Remote

uv run rclone-manager serve-remote

Serve remote storage over HTTP, WebDAV, or FTP.

Serve Local

uv run rclone-manager serve-local

Serve local directories over the network.

Automation

Sync Pairs

# Interactive menu
uv run rclone-manager sync-pairs

# Direct actions
uv run rclone-manager sync-pairs add
uv run rclone-manager sync-pairs list
uv run rclone-manager sync-pairs run
uv run rclone-manager sync-pairs remove

Sync Modes:

upload_only: Copy local → remote (safe, no deletions)
download_only: Copy remote → local (safe, no deletions)
upload_delete: Sync local → remote (deletes extra remote files)
download_delete: Sync remote → local (deletes extra local files)
two_way: Bidirectional sync using rclone bisync

Status

uv run rclone-manager status

Show active mounts with transfer stats and configured sync pairs.

Utilities

Browse Remote

uv run rclone-manager ls

Navigate and list remote directory contents.

Checksum Verification

uv run rclone-manager checksum

Verify file integrity between local and remote.

Deduplicate

uv run rclone-manager dedupe

Find and remove duplicate files on a remote.

Space Usage

uv run rclone-manager space

Show quota and storage usage for remotes.

Copy Between Remotes

uv run rclone-manager copy-between

Copy files directly between two remotes.

Two-Way Sync (bisync)

uv run rclone-manager bisync

Bidirectional sync between two remotes.

Web UI

uv run rclone-manager web-ui

Launch browser-based file manager.

Configuration Management

uv run rclone-manager config

Manage rclone flags in config.ini interactively.

Manage Filters

uv run rclone-manager filters

Interactively manage global exclude/include patterns.

Navigation Guide

Fuzzy Search (fzf)

When fzf is installed and USE_FZF = true in config.ini, all selection interfaces use fuzzy search:

Type to filter: Start typing to narrow down items instantly
Multi-select: Press Tab or Shift+Tab to select multiple items
Navigate: Use arrow keys or Ctrl+j/Ctrl+k
Confirm: Press Enter to confirm selection
Cancel: Press Esc or Ctrl+c to cancel

Legacy Numbered List (fallback)

If fzf is not installed or USE_FZF = false, the classic numbered-list interface is used:

Single item: 1 (select item 1)
Multiple items: 1,2,3 (select items 1, 2, and 3)
Go up: .. (navigate to parent directory)
Select current: . or d (select current directory/path)

Examples

Upload a folder to Google Drive

uv run rclone-manager upload
# Navigate to your folder, select Google Drive remote, choose destination

Mount Google Drive as local directory

uv run rclone-manager mount
# Select remote, choose mount point, access via ~/mnt/<name>

Set up automated sync pair

uv run rclone-manager sync-pairs add
# Name: "Work Docs"
# Local: /home/user/Documents/Work
# Remote: drive:Backup/Work
# Mode: upload_only
# Run anytime with: uv run rclone-manager sync-pairs run

Check status of mounts and syncs

uv run rclone-manager status

Troubleshooting

Common Issues

Remote not found: Run rclone config to set up remotes
Mount fails: Ensure FUSE is installed (sudo apt install fuse on Linux)
Permission denied: Check file permissions and rclone remote access
Network issues: Verify firewall settings for serving functionality

Performance Tips

Use VFS cache mode for better streaming performance
Adjust cache size based on available disk space
Use --overwrite flag carefully to avoid unnecessary transfers

Contributing

Fork the repository
Create a feature branch
Make your changes
Submit a pull request

License

MIT License - see LICENSE file for details.

Acknowledgments

Built on top of rclone
Uses Rich for terminal UI

Note: This tool requires a properly configured rclone installation. Credentials for serving are passed via environment variables (not CLI args), and all services bind to 127.0.0.1 by default. Configure XSRF protection and CORS via config.ini. Set PASSWORD explicitly — there is no default fallback.

Name		Name	Last commit message	Last commit date
Latest commit History 105 Commits
.github/workflows		.github/workflows
configs		configs
docs/superpowers		docs/superpowers
src/rclone_manager		src/rclone_manager
tests		tests
.gitignore		.gitignore
CONTEXT.md		CONTEXT.md
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

Rclone Manager

Features

Supported Storage Providers

Prerequisites

Installation

Configuration

config.ini

sync-pairs.json

Filters

Usage

Core Commands

Upload Files

Download Files

Sync Between Remotes

Mount & Serve

Mount Remote

Unmount

Serve Remote

Serve Local

Automation

Sync Pairs

Status

Utilities

Browse Remote

Checksum Verification

Deduplicate

Space Usage

Copy Between Remotes

Two-Way Sync (bisync)

Web UI

Configuration Management

Manage Filters

Navigation Guide

Fuzzy Search (fzf)

Legacy Numbered List (fallback)

Examples

Upload a folder to Google Drive

Mount Google Drive as local directory

Set up automated sync pair

Check status of mounts and syncs

Troubleshooting

Common Issues

Performance Tips

Contributing

License

Acknowledgments

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages