wiki:archive/libtorrent.rakshasa.no/RTorrentCommands

Context Navigation

This is a mirror for the old http://libtorrent.rakshasa.no/ site based on the archives from the wayback machine.

If you find any broken links please let me know via mail.

Commands

This is a list of commands supported by rtorrent. Under each command, its parameters are listed, where Bold means it is required and italic that it is optional. Commands that are italic are nor available through XMLRPC.

See RTorrentCommandsRaw for a complete list.

System

system.listMethods

Returns a list of all available commands.

system.client_version

system.library_version

Returns the client or library version.

system.pid

Returns the process id.

system.hostname

Returns the hostname.

system.get_cwd

system.set_cwd, cwd = directory

Change the current working directory using the chdir system call.

system.set_umask = numask

Set the process's file mode creation mask to numask through the umask system call.

Generic

download_list = view

view: Select the view to use. An empty string equals "default".

Returns a list of the info-hashes of downloads in view', encoded in capital letter hexadecimal.

execute_log = log_file

Log the output of commands called by "execute" to log_file. If no parameter is passed, then logging is disabled.

load, load_verbose, load_raw, load_raw_start, load_raw_verbose, load_start, load_start_verbose = [uri|file|data], …

[uri|file|data]: A string either representing an URI, file path including '*' as wildcards, or raw torrent data.

…: Any number of download commands to be called upon successful creation of the torrent. These will be called before the torrent is started.

Load a torrent and call download commands once done. Creation of the torrent is done lazily, thus no download is created during this call.

verbose Print error messages to the log.
raw The argument passed is the raw torrent data to be loaded.
start Start the torrent.

close_on_ratio = min_ratio, min_upload, max_ratio, …

stop_on_ratio = min_ratio, min_upload, max_ratio, …

…: Any number of commands to be executed on the stopped/closed torrent.

For rTorrent 0.8.4 please see RTorrentRatioHandling.

For versions before 0.8.4:

Stop/Close torrents when they reach the given upload ratio min_ratio in percent. If the optional min_upload is given, require a total upload amount of this many bytes as well. If the optional max_ratio is given, stop the torrent when reaching this ratio regardless of the total upload amount. Exclude certain torrent by pressing Shift+I in the downlist list. Intended for use with the schedule option.

stop_on_ratio = 100, 20M, 300, d.erase=

get_check_hash

set_check_hash, check_hash = true

Perform hash check on torrents that have finished downloading.

get_directory

set_directory, directory = "./"

Set the default download directory for newly loaded torrents.

get_name

set_name = "session name"

Name of this rtorrent session, for display in the main title or XMLRPC clients.

get_session

set_session, session = ""

Session management will be enabled and the torrent files for all open downloads will be stored in this directory. Only one instance of rtorrent can be used per session directory. An empty string will disable the session directory.

Network

encryption = …

Set how rtorrent should deal with encrypted Bittorrent connections. By default, encryption is disabled, equivalent to specifying the option none. Alternatively, any number of the following options may be specified:

allow_incoming (allow incoming encrypted connections)
try_outgoing (use encryption for outgoing connections)
require (disable unencrypted handshakes)
require_RC4 (also disable plaintext transmission after the initial encrypted handshake)
enable_retry (if the initial outgoing connection fails, retry with encryption turned on if it was off or off if it was on)
prefer_plaintext (choose plaintext when peer offers a choice between plaintext transmission and RC4 encryption, otherwise RC4 will be used)

get_bind

set_bind, bind = ["0.0.0.0"|"example.com"]

Bind listening socket and outgoing connections to this network interface address.

get_http_proxy

set_http_proxy, http_proxy = "http://example.com"

Use a http proxy. Disable with an empty string.

get_ip

set_ip, ip = ["0.0.0.0"|"example.com"]

Set the address reported to the tracker.

get_random_open

set_random_open, port_random = true

If set, when opening the listening port a random port in port_range will be selected. Else the lowest available in the range will be used.

get_port_range

set_port_range, port_range = range

range = "6881-6999": Port numbers in the range <0,2¹⁶>, as a string.

Set the port range that may be used for the listening port.

User-Interface

view_add = name

Create a new view.

view_sort = name

view_sort = name,seconds

Sort a view according the the criteria set by view_sort_current. If the optional argument is supplied, the view is not sorted if a change happened during the last n seconds. This command is meant to be used with schedule.

view_filter = name,command

Set the command to be used when filtering downloads. The command should return a value, where non-zero values indicates the download should be in the list. An empty command results in no filtering being done.

// d.get_state is 0 for stopped torrents, 1 for started.
view_filter = stopped,not=$d.get_state=

view_filter = seeding,"and=d.get_state=,d.get_complete="

view_filter_on = …

...

view_sort_new = name,command

view_sort_current = name,command

Same as view_filter, except it requires commands that take two download targets. This takes the C++ STL requirements on sorting operators, so the operator must use strict weak ordering (e.g. less than, not less or equal to) and non-zero results are ordered first.

view_sort_new = started,less=d.get_name=

get_key_layout

set_key_layout, key_layout = [qwerty|azerty|qwertz|dvorak]

Change the key-bindings.

Tools

Various commands useful for scripting.

cat = …

Concatenate any number of object as a string.

# Sets the base directory to '~/download/<info_hash>'.
d.set_directory_base = $cat=~/download/\,$d.get_hash=

if = …

branch = …

A series of if/else statements. Every even arguments are conditionals and odd arguments are branches to be executed, except the last one which is always a branch.

The branch is returned by the 'if; command unless it is a string starting with an '$', in which case the branch is executed and the result returned.

To work around certain limitations in the current parsing code, a 'branch' command was added that executes all strings as commands thus not needing a '$'.

if (cond1) { branch1 }
<cond1>,<branch1>

if (cond1) { branch1 } else if (cond2) { branch2 } else { branch3 }
<cond1>,<branch1>,<cond2>,<branch2>,<branch3>

on_start = test1,"if=$d.get_custom1=,\\$d.set_custom2=$d.get_custom1=,\\$d.set_custom2=foo"

Download

All download commands except d.multicall take the info-hash of the target download, encoded in capital letter hexadecimal, as the first argument.

d.multicall, call_download = view, …

view: Select the view to use. An empty string equals "default".

…: Any number of download commands. Each command must contain '=', with optional arguments.

Returns a list of lists, where each element is a list of result from calls on one download.

> xmlrpc localhost d.multicall "started" "d.get_name=" "d.get_size_chunks="
Array of 2 items:
  Index  0 Array of 2 items:
             Index  0 String: 'Forget-me-not c001.zip'
             Index  1 Integer: 26
  Index  1 Array of 2 items:
             Index  0 String: 'Forget-me-not c002.zip'
             Index  1 Integer: 17

d.update_priorities

Put any changes to file priorities into effect. This command is relatively expensive and should therefor be called after a batch of changes to priorities has been done.

d.add_peer(String hash, String peer)

Adds a known peer to the torrent. The peer should be specified as IP:PORT. If the port is not sent in this parameter, rTorrent sets it by default to 6881.

@param hash: The hash which identifies the torrent
@param peer: The peer to be added of the form IP:PORT
@return: An int marking the result (0 means okay)

d.check_hash(String hash)

Checks the hash of a torrent.

@param hash: The hash which identifies the torrent
@return: An int marking the result (0 means okay)

d.close(String hash)

Closes a torrent and closes all its connections too.

@param hash: The hash which identifies the torrent
@return: An int marking the result (0 means okay)

d.create_link(String hash, String type, String path, String suffix)

Creates a symbolic link. The link path is the concatenation of path, the result of the type on the download and suffix. Available types are:

base_path uses the base path of the download for creating the link; if base_path is specified, then supplying the path parameter cancels the operation
base_filename uses the base filename of the download for the link and the path provided by path
tied uses the path of the .torrent file to which the download is tied for the operation

@param hash: The hash which identifies the torrent
@param type: The type described as above
@param path: The path of the link
@param suffix: The suffix to be added for the link
@return: An int marking the result (0 means okay)

File

All file commands take the info-hash of the target download, encoded in capital letter hexadecimal, as the first argument and the index of the file as the second.