rclone.js

Rclone.js

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

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

Installation

npm install rclone.js

After installation, the latest binary of rclone is also fetched based on your system environment.

If a custom version of rclone binary is needed, use RCLONE_EXECUTABLE environment variable to set the path to that custom binary.

Usage

Node.js

Except selfupdate, which is used to update rclone binary, all API functions return a child process whose events we can listen to. Optional flags can be passed as an object to the last argument of the function call. Except removing the -- prefix, there is no other conversion to the flag name. JSON values are stringified before passed to rclone.

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

const rclone = require("rclone.js");

const ls = 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:

const rclone = require("rclone.js").promises;

(async function() {
  const results = await rclone.ls("source:", {
    "max-depth": 1,
    // Spawn options:
    "env": {
      RCLONE_CONFIG: "~/.config/rclone/rclone.conf",
    },
    "shell": "/bin/sh",
  });

  console.log(results);
})();

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

const rclone = require("rclone.js");

rclone("newcommand", "source:", "target:", {
  "flag": true,
});

(async function() {
  const results = await rclone.promises("newcommand", "source:", "target:", {
    "flag": true,
  });

  console.log(results);
})();

CLI

This simple CLI calls the JS API above and outputs stdout and stderr.

$ npx rclone --version
rclone 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

Custom command

The CLI also supports executing a custom JS-based command to further extend usage outside of what the official rclone offers:

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

The custom JS file just needs to export a function that takes the arguments and flags parsed from the CLI. It can either return a child process, or a Promise. For a child process, its stdout and stderr are piped to the caller process.

Inside the function, this is set to rclone.js module.

const { spawn } = require("child_process");

module.exports = function echo(arg1, arg2, flags = {}) {
  return spawn("echo", [arg1, arg2, JSON.stringify(flags)]);
}

The custom module is loaded through require, so it has some nice advantages when locating module:

• Does not need to specify .js extension, custom is same as custom.js.
• Considers both foobar.js and foobar/index.js.
• Can be extended through NODE_PATH environment variable.
• Can also use module from node_modules by its name.

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

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

For a "real-life" example, check out selfupdate, which overrides the built-in selfupdate command to download rclone executable if it has not been downloaded yet. Consecutive runs just call selfupdate API.

For publishing a custom rclone command as NPM package, consider prefixing the package name with rclone- so it's clearer and not conflicting.

Example Custom Commands

• rclone-archive: Tracking https://github.com/rclone/rclone/issues/2815.