Rclone — API Surface#

API types#

• CLI (primary user-facing interface, ~60+ commands via cobra)
• REST/HTTP JSON-RPC (remote control daemon: rclone rcd, rclone rc)
• C Library (librclone — shared/static, same JSON-RPC protocol)
• Protocol servers (rclone as backend: WebDAV, SFTP, FTP, HTTP, NFS, S3, DLNA, restic, Docker volume)
• Backend plugin API (internal Go interface — fs.Fs — for storage backends)

CLI#

Framework#

Cobra (github.com/spf13/cobra) with pflag. All commands self-register via init() into a global root command in cmd/cmd.go. cmd/all/all.go blank-imports every command package.

Command structure#

File operations

Listing / inspection

Verification

Filesystem ops

Mount (FUSE)

Serve (rclone as a server)

Remote control

Config management

Utility

Flag patterns#

Global flags (apply to every command) are defined in fs/config/configflags/configflags.go and bound to fs.ConfigInfo:

• --config — path to rclone.conf
• --quiet / -q — suppress output
• --verbose / -v — increase verbosity
• --transfers N — parallel file transfers (default 4)
• --checkers N — parallel checkers (default 8)
• --retries N — retry count on failure
• --bwlimit SPEC — bandwidth throttle (e.g. 10M:off)
• --stats DURATION — stats reporting interval
• --filter / --include / --exclude — filter rules
• --dry-run / -n — simulate without modifying
• --delete-before / --delete-during / --delete-after — sync deletion timing
• --checksum / -c — compare by hash not modtime+size
• --progress / -P — show real-time transfer progress
• --dump-headers / --dump-bodies — HTTP debugging
• --bind — outgoing interface binding
• --disable FEATURE,... — disable specific backend features
• --dscp — DSCP value for QoS

Backend-specific flags are declared as fs.Option slices in each backend’s RegInfo and appear as --backendname-optionname flags automatically via configflags.

Remote Control JSON-RPC API (rclone rcd / rclone rc)#

Transport and format#

• HTTP server; default address localhost:5572
• Requests: POST /operations/list (preferred) or GET /operations/list?param=val
• Body: JSON object of parameters
• Response: JSON object or {"error": "...","status": N}
• Auth: optional basic auth (--rc-user / --rc-pass) or bearer token (--rc-token)
• --rc-no-auth disables authentication (dangerous)

Router: chi (github.com/go-chi/chi/v5). Routes are GET|HEAD|POST|OPTIONS /* all dispatched to a single handler that looks up the path in rc.Calls registry.

Endpoint catalog#

All endpoints are self-registered by packages calling rc.Add(rc.Call{Path: "...", Fn: fn}) in their init() functions. They are grouped by namespace:

operations/ — file and filesystem operations

sync/ — synchronization operations

core/ — runtime control

config/ — configuration management

fscache/ — Fs instance cache

job/ — async job management

mount/ — FUSE mount management (when available)

serve/ — protocol server management

vfs/ — VFS cache management (for mounted/served remotes)

options/ — runtime option inspection/modification

debug/ — runtime profiling

rc/ — meta-endpoints

pluginsctl/ — Web GUI plugins

cache/ — cache backend-specific (when cache remote used)

Async job mode#

Any endpoint can be called with _async: true parameter. The call returns immediately with a job ID; the actual operation runs in a background goroutine. Job status is polled via job/status. This enables long-running transfers via the JSON-RPC API without blocking the HTTP connection.

Authentication#

• Basic auth: --rc-user + --rc-pass flags
• HTTP bearer token: --rc-token
• No auth: --rc-no-auth (local-only use)
• Web GUI mode: auto-generates random password if none specified
• Endpoints can declare AuthRequired: true to require auth even when no-auth mode is set

C Library API (librclone)#

Build target: go build --buildmode=c-shared -o librclone.so github.com/rclone/rclone/librclone

Exported C functions (4 total):

void RcloneInitialize(void);
void RcloneFinalize(void);

struct RcloneRPCResult {
    char *Output;  // JSON string — caller must free
    int   Status;  // HTTP status code (200 = OK)
};

struct RcloneRPCResult RcloneRPC(char *method, char *input);

The RcloneRPC function is a thin shim over the same rc.Calls registry used by rclone rcd. Method is a string like "operations/list", input is a JSON object string. This design ensures the embedded library API is identical to the daemon API — no separate binding layer to maintain.

Bindings exist for Python (python-rclone), PHP, and mobile platforms. All use this same C API.

Protocol Servers (via rclone serve)#

Each protocol server wraps the vfs.VFS abstraction over any rclone remote:

All serve commands accept --addr, --user, --pass, and TLS flags via lib/http. VFS cache settings (--vfs-cache-mode) control write-back behavior.

Backend Plugin API (internal Go)#

The internal extension point for adding storage backends. Each backend implements fs.Fs and self-registers:

// In backend/mybackend/mybackend.go
func init() {
    fs.Register(&fs.RegInfo{
        Name:        "mybackend",
        Description: "My Storage Backend",
        NewFs:       NewFs,
        Options:     []fs.Option{{Name: "api_key", Help: "...", Required: true}},
        Config:      configFn, // optional OAuth flow
    })
}

The NewFs(ctx, name, root string, m configmap.Mapper) (fs.Fs, error) factory receives a config mapper populated from the config file, env vars, and CLI flags. No backend ever reads flags directly.

Optional capabilities are advertised via the Features struct (not via additional interface assertions):

return f, fs.ErrorIsFile
// Features: f.Features().Copy != nil → supports server-side copy

This plugin mechanism is compile-time only: all backends are linked in at build time via blank imports in backend/all/all.go. There is no runtime plugin loading.

API style summary#

The unifying design principle: one registry pattern, three access modes. The same rc.Calls map is callable via rclone rc (CLI to daemon), POST /operations/... (HTTP to daemon), and RcloneRPC() (in-process C call). Similarly, the same fs.Registry global is consulted whether the user types rclone copy s3:..., calls operations/copyfile via JSON-RPC, or invokes RcloneRPC("operations/copyfile", ...) from Python.