---

title: "Remote Control / API" description: "Remote controlling rclone with its API"

Remote controlling rclone with its API

If rclone is run with the --rc flag then it starts an http server which can be used to remote control rclone using its API.

If you just want to run a remote control then see the rcd command.

Supported parameters

--rc

Flag to start the http server listen on remote requests

--rc-addr=IP

IPaddress:Port or :Port to bind server to. (default "localhost:5572")

--rc-cert=KEY

SSL PEM key (concatenation of certificate and CA certificate)

--rc-client-ca=PATH

Client certificate authority to verify clients with

--rc-htpasswd=PATH

htpasswd file - if not provided no authentication is done

--rc-key=PATH

SSL PEM Private key

--rc-max-header-bytes=VALUE

Maximum size of request header (default 4096)

--rc-user=VALUE

User name for authentication.

--rc-pass=VALUE

Password for authentication.

--rc-realm=VALUE

Realm for authentication (default "rclone")

--rc-server-read-timeout=DURATION

Timeout for server reading data (default 1h0m0s)

--rc-server-write-timeout=DURATION

Timeout for server writing data (default 1h0m0s)

--rc-serve

Enable the serving of remote objects via the HTTP interface. This means objects will be accessible at http://127.0.0.1:5572/ by default, so you can browse to http://127.0.0.1:5572/ or http://127.0.0.1:5572/* to see a listing of the remotes. Objects may be requested from remotes using this syntax http://127.0.0.1:5572/[remote:path]/path/to/object

Default Off.

--rc-files /path/to/directory

Path to local files to serve on the HTTP server.

If this is set then rclone will serve the files in that directory. It will also open the root in the web browser if specified. This is for implementing browser based GUIs for rclone functions.

If --rc-user or --rc-pass is set then the URL that is opened will have the authorization in the URL in the http://user:pass@localhost/ style.

Default Off.

--rc-enable-metrics

Enable OpenMetrics/Prometheus compatible endpoint at /metrics.

Default Off.

--rc-web-gui

Set this flag to serve the default web gui on the same port as rclone.

Default Off.

--rc-allow-origin

Set the allowed Access-Control-Allow-Origin for rc requests.

Can be used with --rc-web-gui if the rclone is running on different IP than the web-gui.

Default is IP address on which rc is running.

--rc-web-fetch-url

Set the URL to fetch the rclone-web-gui files from.

Default https://api.github.com/repos/rclone/rclone-webui-react/releases/latest.

--rc-web-gui-update

Set this flag to check and update rclone-webui-react from the rc-web-fetch-url.

Default Off.

--rc-web-gui-force-update

Set this flag to force update rclone-webui-react from the rc-web-fetch-url.

Default Off.

--rc-web-gui-no-open-browser

Set this flag to disable opening browser automatically when using web-gui.

Default Off.

--rc-job-expire-duration=DURATION

Expire finished async jobs older than DURATION (default 60s).

--rc-job-expire-interval=DURATION

Interval duration to check for expired async jobs (default 10s).

--rc-no-auth

By default rclone will require authorisation to have been set up on the rc interface in order to use any methods which access any rclone remotes. Eg operations/list is denied as it involved creating a remote as is sync/copy.

If this is set then no authorisation will be required on the server to use these methods. The alternative is to use --rc-user and --rc-pass and use these credentials in the request.

Default Off.

Accessing the remote control via the rclone rc command

Rclone itself implements the remote control protocol in its rclone rc command.

You can use it like this

$ rclone rc rc/noop param1=one param2=two
{
	"param1": "one",
	"param2": "two"
}

Run rclone rc on its own to see the help for the installed remote control commands.

rclone rc also supports a --json flag which can be used to send more complicated input parameters.

$ rclone rc --json '{ "p1": [1,"2",null,4], "p2": { "a":1, "b":2 } }' rc/noop
{
	"p1": [
		1,
		"2",
		null,
		4
	],
	"p2": {
		"a": 1,
		"b": 2
	}
}

Special parameters

The rc interface supports some special parameters which apply to all commands. These start with _ to show they are different.

Running asynchronous jobs with _async = true

Each rc call is classified as a job and it is assigned its own id. By default jobs are executed immediately as they are created or synchronously.

If _async has a true value when supplied to an rc call then it will return immediately with a job id and the task will be run in the background. The job/status call can be used to get information of the background job. The job can be queried for up to 1 minute after it has finished.

It is recommended that potentially long running jobs, eg sync/sync, sync/copy, sync/move, operations/purge are run with the _async flag to avoid any potential problems with the HTTP request and response timing out.

Starting a job with the _async flag:

$ rclone rc --json '{ "p1": [1,"2",null,4], "p2": { "a":1, "b":2 }, "_async": true }' rc/noop
{
	"jobid": 2
}

Query the status to see if the job has finished. For more information on the meaning of these return parameters see the job/status call.

$ rclone rc --json '{ "jobid":2 }' job/status
{
	"duration": 0.000124163,
	"endTime": "2018-10-27T11:38:07.911245881+01:00",
	"error": "",
	"finished": true,
	"id": 2,
	"output": {
		"_async": true,
		"p1": [
			1,
			"2",
			null,
			4
		],
		"p2": {
			"a": 1,
			"b": 2
		}
	},
	"startTime": "2018-10-27T11:38:07.911121728+01:00",
	"success": true
}

job/list can be used to show the running or recently completed jobs

$ rclone rc job/list
{
	"jobids": [
		2
	]
}

Assigning operations to groups with _group = value

Each rc call has its own stats group for tracking its metrics. By default grouping is done by the composite group name from prefix job/ and id of the job like so job/1.

If _group has a value then stats for that request will be grouped under that value. This allows caller to group stats under their own name.

Stats for specific group can be accessed by passing group to core/stats:

$ rclone rc --json '{ "group": "job/1" }' core/stats
{
	"speed": 12345
	...
}

Supported commands

{{< rem autogenerated start "- run make rcdocs - don't edit here" >}}

backend/command: Runs a backend command. {#backend-command}

This takes the following parameters

• command - a string with the command name
• fs - a remote name string eg "drive:"
• arg - a list of arguments for the backend command
• opt - a map of string to string of options

Returns

• result - result from the backend command

For example

rclone rc backend/command command=noop fs=. -o echo=yes -o blue -a path1 -a path2

Returns

{
	"result": {
		"arg": [
			"path1",
			"path2"
		],
		"name": "noop",
		"opt": {
			"blue": "",
			"echo": "yes"
		}
	}
}

Note that this is the direct equivalent of using this "backend" command:

rclone backend noop . -o echo=yes -o blue path1 path2

Note that arguments must be preceded by the "-a" flag

See the backend command for more information.

Authentication is required for this call.

cache/expire: Purge a remote from cache {#cache-expire}

Purge a remote from the cache backend. Supports either a directory or a file. Params:

• remote = path to remote (required)
• withData = true/false to delete cached data (chunks) as well (optional)

Eg

rclone rc cache/expire remote=path/to/sub/folder/
rclone rc cache/expire remote=/ withData=true

cache/fetch: Fetch file chunks {#cache-fetch}

Ensure the specified file chunks are cached on disk.

The chunks= parameter specifies the file chunks to check. It takes a comma separated list of array slice indices. The slice indices are similar to Python slices: start[:end]

start is the 0 based chunk number from the beginning of the file to fetch inclusive. end is 0 based chunk number from the beginning of the file to fetch exclusive. Both values can be negative, in which case they count from the back of the file. The value "-5:" represents the last 5 chunks of a file.

Some valid examples are: ":5,-5:" -> the first and last five chunks "0,-2" -> the first and the second last chunk "0:10" -> the first ten chunks

Any parameter with a key that starts with "file" can be used to specify files to fetch, eg

rclone rc cache/fetch chunks=0 file=hello file2=home/goodbye

File names will automatically be encrypted when the a crypt remote is used on top of the cache.

cache/stats: Get cache stats {#cache-stats}

Show statistics for the cache remote.

config/create: create the config for a remote. {#config-create}

This takes the following parameters

• name - name of remote
• parameters - a map of { "key": "value" } pairs
• type - type of the new remote
• obscure - optional bool - forces obscuring of passwords
• noObscure - optional bool - forces passwords not to be obscured

See the config create command command for more information on the above.

Authentication is required for this call.

config/delete: Delete a remote in the config file. {#config-delete}

Parameters:

• name - name of remote to delete

See the config delete command command for more information on the above.

Authentication is required for this call.

config/dump: Dumps the config file. {#config-dump}

Returns a JSON object:

• key: value

Where keys are remote names and values are the config parameters.

See the config dump command command for more information on the above.

Authentication is required for this call.

config/get: Get a remote in the config file. {#config-get}

Parameters:

• name - name of remote to get

See the config dump command command for more information on the above.

Authentication is required for this call.

config/listremotes: Lists the remotes in the config file. {#config-listremotes}

Returns

• remotes - array of remote names

See the listremotes command command for more information on the above.

Authentication is required for this call.

config/password: password the config for a remote. {#config-password}

This takes the following parameters

• name - name of remote
• parameters - a map of { "key": "value" } pairs

See the config password command command for more information on the above.

Authentication is required for this call.

config/providers: Shows how providers are configured in the config file. {#config-providers}

Returns a JSON object:

• providers - array of objects

See the config providers command command for more information on the above.

Authentication is required for this call.

config/update: update the config for a remote. {#config-update}

This takes the following parameters

• name - name of remote
• parameters - a map of { "key": "value" } pairs
• obscure - optional bool - forces obscuring of passwords
• noObscure - optional bool - forces passwords not to be obscured

See the config update command command for more information on the above.

Authentication is required for this call.

core/bwlimit: Set the bandwidth limit. {#core-bwlimit}

This sets the bandwidth limit to that passed in.

Eg

rclone rc core/bwlimit rate=off
{
    "bytesPerSecond": -1,
    "rate": "off"
}
rclone rc core/bwlimit rate=1M
{
    "bytesPerSecond": 1048576,
    "rate": "1M"
}

If the rate parameter is not supplied then the bandwidth is queried

rclone rc core/bwlimit
{
    "bytesPerSecond": 1048576,
    "rate": "1M"
}

The format of the parameter is exactly the same as passed to --bwlimit except only one bandwidth may be specified.

In either case "rate" is returned as a human readable string, and "bytesPerSecond" is returned as a number.

core/gc: Runs a garbage collection. {#core-gc}

This tells the go runtime to do a garbage collection run. It isn't necessary to call this normally, but it can be useful for debugging memory problems.

core/group-list: Returns list of stats. {#core-group-list}

This returns list of stats groups currently in memory.

Returns the following values: