[[libtorrentMirror]]

= 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 [wiki: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 [wiki: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^16^>, 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.


= Peer Connection =

=== p.multicall = info_hash, dummy_argument, ... ===

See "d.multicall".


= Tracker =

=== t.multicall = info_hash, dummy_argument, ... ===

See "d.multicall".

=== t.get_group ===
=== t.get_id ===
=== t.get_type ===
=== t.get_url ===

=== t.get_min_interval ===
=== t.get_normal_interval ===

=== t.get_scrape_complete ===
=== t.get_scrape_downloaded ===
=== t.get_scrape_incomplete ===
=== t.get_scrape_time_last ===

=== t.is_enabled ===
=== t.set_enabled = [true|false] ===
=== t.is_open ===