Repository files navigation

The JavaScript API to the "Swiss army knife of cloud storage"rclone.

Besides providing a way to install rclone on different platforms, a CLI anda JavaScript API are included.

npm install rclone.js

After installation, the latest binary ofrclone is also fetched based onyour system environment.

If a custom version ofrclone binary is needed, useRCLONE_EXECUTABLEenvironment variable to set the path to that custom binary.

Exceptselfupdate, which is used to updaterclone binary, all API functionsreturn a child process whose events we can listen to. Optional flags can bepassed as an object to the last argument of the function call. Except removingthe-- prefix, there is no other conversion to the flag name. JSON values arestringified before passed torclone.

Each API functions can also take options for the spawned child process. Seehttps://nodejs.org/api/child_process.html#child_processspawncommand-args-optionsfor their documentation.

constrclone=require("rclone.js");constls=rclone.ls("source:",{"max-depth":1,// Spawn options:"env":{RCLONE_CONFIG:"~/.config/rclone/rclone.conf",},"shell":"/bin/sh",});ls.stdout.on("data",(data)=>{console.log(data.toString());});ls.stderr.on("data",(data)=>{console.error(data.toString());});

There is also a Promise-based API:

constrclone=require("rclone.js").promises;(asyncfunction(){constresults=awaitrclone.ls("source:",{"max-depth":1,// Spawn options:"env":{RCLONE_CONFIG:"~/.config/rclone/rclone.conf",},"shell":"/bin/sh",});console.log(results);})();

When the officialrclone adds new command that has not been provided here,we can still use the command through the default exported functions, passingthe command name as first argument:

constrclone=require("rclone.js");rclone("newcommand","source:","target:",{"flag":true,});(asyncfunction(){constresults=awaitrclone.promises("newcommand","source:","target:",{"flag":true,});console.log(results);})();

This simple CLI calls the JS API above and outputsstdout andstderr.

$ npx rclone --versionrclone v1.54.0- os/arch: darwin/amd64- go version: go1.15.7

$ npx rclone ls source: --max-depth 1          -1 2020-12-12 10:01:44        -1 Documents          -1 2020-12-11 16:24:20        -1 Pictures

The CLI also supports executing a custom JS-based command to further extendusage outside of what the officialrclone offers:

$ npx rclone echo.js arg1 --string value arg2 --boolean

The custom JS file just needs to export a function that takes the arguments andflags parsed from the CLI. It can either return a child process, or aPromise.For a child process, itsstdout andstderr are piped to the caller process.

Inside the function,this is set torclone.js module.

const{ spawn}=require("child_process");module.exports=functionecho(arg1,arg2,flags={}){returnspawn("echo",[arg1,arg2,JSON.stringify(flags)]);}

The custom module is loaded throughrequire, so it has some nice advantageswhenlocating module:

• Does not need to specify.js extension,custom is same ascustom.js.
• Considers bothfoobar.js andfoobar/index.js.
• Can be extended throughNODE_PATH environment variable.
• Can also use module fromnode_modules by its name.

With that, there are a few things custom commands can be used:

• Wraps existing API to add new functionality, such asarchive.
• Defines a module with the same name as existing API to extend it with newflags and/or backends.

For a "real-life" example, check outselfupdate, whichoverrides the built-inselfupdate command to download rclone executable if ithas not been downloaded yet. Consecutive runs just callselfupdate API.

For publishing a customrclone command as NPM package, consider prefixing thepackage name withrclone- so it's clearer and not conflicting.

• rclone-archive:Trackingrclone/rclone#2815.