Rclone

Context

• Argument: $ARGUMENTS
• rclone: !rclone version 2>/dev/null | head -1 || echo "not installed (apt install rclone or curl https://rclone.org/install.sh | bash)"
• Configured remotes: !rclone listremotes 2>/dev/null | tr '\n' ' ' || echo "(none — run rclone config)"
• Config path: !echo "${RCLONE_CONFIG:-$HOME/.config/rclone/rclone.conf}"

rclone

Cloud storage swiss army knife. Single Go binary, no daemon, config in one rclone.conf file. Same verbs across every backend — rclone copy gdrive:foo s3:bucket/foo works because both sides speak the same internal interface.

The mental model

[local fs]  ⇄  rclone  ⇄  [any of 50+ backends]
                │
                ├─ Google Drive, S3, B2, Dropbox, OneDrive, Mega, …
                ├─ SFTP, WebDAV, FTP, HTTP
                ├─ Crypt (encrypted overlay on any other remote)
                ├─ Union (stack multiple remotes as one)
                └─ Combine (mount-point routing across remotes)

A "remote" is a named backend in rclone.conf. Paths are remote:path/inside/remote. Three special cases:

• :local: or just a local path → local filesystem (no remote prefix)
• remote: → the remote's root
• remote:bucket-or-folder/... → a path inside the remote

Universal invocation

rclone <verb> <source> <dest> [flags]

All verbs take one or two paths. Flags are global (--dry-run, --progress, --transfers N, --checkers N, --bwlimit 10M) or verb-specific.

Most-used verbs

Inspection (auto-allowed, read-only)

Transfer (copy = safe-additive; sync = destructive)

Always run a destructive verb with --dry-run first and show the user the diff before re-running without it. The first 50 actions are usually enough to see whether the direction is right.

Mutation (destructive)

Mount / serve (state-changing on the local system)

Integrity

rclone check SRC DST                     # report differing files, no transfer
rclone check SRC DST --download          # rehash both sides (slower, definitive)
rclone cryptcheck CRYPT_REMOTE PLAIN     # validate a crypt remote

check is safe (read-only). It exits non-zero on mismatch — useful in scripts.

Config

rclone config                            # interactive — usually run by the user
rclone config show [remote]              # dump (auto)
rclone config redacted [remote]          # dump with creds redacted (safer for logs)
rclone config dump                       # all remotes as JSON
rclone config create <name> <type> ...   # scriptable add — credentials in argv
rclone config password <name> field=value  # set/refresh an obscured field

Don't run interactive rclone config from inside Claude — it expects a TTY. If the user wants to add a remote, walk them through it or give them the rclone config create invocation to paste.

Useful global flags

Patterns

"Did this sync actually do the right thing?"

# 1. Dry run, capture
rclone sync ~/photos gdrive:photos --dry-run --log-file /tmp/dry.log --log-level INFO
grep -E 'NOTICE|ERROR|Would' /tmp/dry.log | head -50

# 2. If it looks right, re-run for real with --progress, and keep the log
rclone sync ~/photos gdrive:photos --progress --log-file /tmp/sync.log --log-level INFO

# 3. Verify
rclone check ~/photos gdrive:photos

"What's on this remote?"

rclone tree remote:                                    # quick structure
rclone size remote:bucket                              # total
rclone ncdu remote:bucket                              # interactive (TUI)
rclone lsjson -R remote:bucket | jq '.[] | .Path'      # scriptable

"Encrypted off-site backup"

# Assuming you've set up a crypt remote that wraps another:
# [b2-encrypted]
# type = crypt
# remote = b2-raw:my-bucket
# password = ...  filename_encryption = standard

rclone sync ~/Documents b2-encrypted:docs --progress --log-file /tmp/backup.log

Crypt remotes encrypt filenames + contents transparently — the underlying remote sees gibberish names. Losing the crypt password means losing the data. Confirm the password is backed up before relying on this.

"Mount a remote read-only for browsing"

mkdir -p ~/mnt/gdrive
rclone mount gdrive: ~/mnt/gdrive --read-only --daemon --vfs-cache-mode minimal
# When done:
fusermount -u ~/mnt/gdrive

"Move a file via remote without local disk"

rclone copyto src-remote:foo dest-remote:bar

Streams between remotes directly (server-side where supported, e.g. S3 → S3 in the same region).

Safety boundaries

When the user says "back up X to Y", default to rclone copy --dry-run first, show them what would move, then ask before running for real. Sync vs copy is the most common direction-of-arrow disaster — confirm which side is the source.

When NOT to use rclone

• Single small file, local → local: cp is simpler.
• Tar/zip archives across hosts: scp, rsync, or tar | ssh is more idiomatic.
• One-shot HTTP downloads: curl -O.
• Sharing a public read-only URL: backend-native tooling (aws s3 presign, gsutil signurl) is more capable.

rclone shines when (a) the source or dest is a cloud backend, (b) you want one verb that works across N backends, or (c) you need crypt/union/dedupe/mount features no single backend provides.

References

• references/backends.md — common backend configs (gdrive, s3, b2, sftp, crypt) with example rclone config create invocations
• references/filters.md — --filter / --include / --exclude pattern syntax with worked examples