A simple qBittorrent remote command-line client based on the bash, curl and jq binaries for a Linux-compatible environment (including Cygwin and Termux). It uses the last WebUI API https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1)

The file bin/qbc is a bash-script which invokes a bash-subshell after an authorization to the server. Usage:

qbc [(-k | -c CERTFILE)] [-l USERNAME] [-p PASSWORD] URL [BASH_OPT1] [BASH_OPT2] ...

The option -k implies an insecure https connection. The option -c is for pointing the self-signed cerificate of qBittorrent Web UI. The default value for USERNAME is "admin". If PASSWORD parameter is set to "-" then the password will be asked from stdin. The expected value for URL is either "http://host[:port]", or "https://host[:port]". Alternatively, there is a possibility to use presets specific for each connection defined in ~/.qbcrc file (see .qbcrc_template).

In the invoked subshell a number of bash functions are defined which realize a client functionality (see the function description below). All these functions can be called through the qbc options in the bash syntax, for example:

qbc -p 'adminadmin' http://localhost:8080 -c "qbprefedit -s web_ui_max_auth_fail_count 10"

It is very convenient to use ssh- or mosh-access with the qbc installed on the qBittorrent server itself. To add a torrent file remotely one can use a stdin redirection of ssh-command:

ssh user@host qbc -p "'adminadmin'" "'http://localhost:8080'" -c "'qbadd -f -'" <filename.torrent

(or) cat filename.torrent | ssh user@host qbc -p "'adminadmin'" "'http://localhost:8080'" -c "'qbadd -f -'"

Any bug reports, improvements, forks, alternative shell function systems are welcome.

The code is tested on:

bash 5.0.18

curl 7.73.0

jq 1.6

qBittorrent 4.3.4.1 (WebUI API 2.8.1)

All functions have the prefix qb-. If the name of a function is started by "qbtor" then it works only if a specific torrent is selected (i.e., the variable QBhash is set to the hash of the torrent). To select a torrent one can use the function qbselect.

qbc usage help

Usage: qbhelp [(list | [-u] FUNCTION)]

Usage: FUNCTION (-h|--help)

Options:

list - list of available FUNCTIONs

-u FUNCTION - the usage of FUNCTION

FUNCTION - the help for FUNCTION

Prints the versions of used software

Usage: qbversion [(app|api|build [qt|libtorrent|boost|openssl|bitness])]

Shows the general network status of the server

Usage: qbnetwork

Shows the value of specified preference property, or print all preferences

Usage: qbpref [(-r PREF_PROPERTY | PREF_PROPERTY_1 [PREF_PROPERTY_2 ...])]

With the "-r" option the function returns the raw value of a property

Sends new values of specified preference properties

Usage: qbprefedit [-s] [-n] PREF_PROPERTY_1 NEW_VALUE_1 [PREF_PROPERTY_2 NEW_VALUE_2 ...]

The option -n prevents an additional check the values from the server after the request. The option "-s" forces "-n" and also prevents any output or user confirmations except (may be) error messages

To change the WebUI password by a secure way (from stdin) just omit the NEW_VALUE_1 argument in "qbprefedit web_ui_password". A change of web_ui_password property together with another options is not supported.

Shows editable options not included into the preferences:alternative speed mode, existing categories and tags

Usage: qbmenu [-r] [altspeed|categories|tags]

Option "-r" for a raw output of requested values

Changes alternative speed mode, categories and tags

Usage: qbmenuedit altspeed (true|false|toggle)

Usage: qbmenuedit categories -d NAME #(remove a category)

Usage: qbmenuedit categories NAME PATH #(create or edit a category)

Usage: qbmenuedit tags [-d] NAME #(create or remove a tag)

Adds a torrent by a URL (use quotes), or by a torrent FILE.

Usage: qbadd ( -u 'URL'| -f FILE) [ARG_1=VALUE_1] [ARG_2=VALUE_2] ...

If FILE='-' then the content of a torrent file will be read from stdin.

If URL='-' then one line with the url will be read from stdin.

The available ARGs are listed in WebUI API https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1)#add-new-torrent

List of torrents with a short info.

Usage: qblist [-r] [--jqselect FILTER] [--jqsort FILTER] [--jq FORMAT] [INDEX_1] [INDEX_2]

Option -r: raw output

Without options prints info of all torrents. The torrents are sorted by the addition time and indexed by numbers

Arguments INDEX_1 and INDEX_2 determine an interval of torrents to be shown

Advanced options: --jqselect and --jqsort for inserting "select" and "sort_by" jq-filters. E.g.,

qblist --jqselect '(.category=="My Category")' --jqsort '(.name)|reverse'

Advanced option: --jq enables a possibility to define an own jq-format for output lines

E.g., the following command prints hashes and names of torrents which have the tag "My tag":

qblist --jqselect '(.tags|split(", ")|.[]|select(.=="My tag"))' --jq '.hash+"/"+.name'

The default format of qblist is defined in the variable

QBlistjq='(.index|tostring)+". "+.name+", "+(.progress*100|trunc|tostring)+"% of "+(.size /1048576|trunc|tostring)+"Mb, state:"+.state'

Pause, resume, recheck, reannounce, force start and priority change of the torrents

Usage: qbdo COMMAND [-i [--jqselect FILTER] [INDEX_1] [INDEX_2]]

COMMAND=pause, resume, recheck, reannounce, setForceStart, increasePrio, decreasePrio, topPrio, bottomPrio

With the option "-i" the function does the action for the torrents within the qblist index interval, "-i" without INDEX_1 and INDEX_2 does the global action

Advanced option: --jqselect for inserting the "select" jq-filter. For example:

qbdo pause -i --jqselect '(.state=="downloading")'

Without "-i" the function does the action for the selected torrent (see qbselect --help)

Selects the torrent with the specified index from qblist

Usage: qbselect [-s| [-r] [--jq FORMAT]] [INDEX]

Option -s: silent mode

Option -r: raw output

Advanced option: --jq enables a possibility to define an own jq-format for output info on the selected torrent

The deafult format is defined in the variable

QBselectjq='.name+", "+(.progress*100|trunc|tostring)+"% of "+(.size /1048576|trunc|tostring)+"Mb, "+.state+", "+(.dlspeed/1024|trunc|tostring)+" Kb/s"'

Remove the selected torrent.

Usage: qbtordel [-s] [-d]

Option "-s" is for a silent removing without an interactive confirmation. # qbtordel: Option "-d" is for removing also the downloaded data

Get the specified information of the selected torrent, or print it completely

Usage: qbtorinfo [(-r INFO_PROPERTY | INFO_PROPERTY_1 [INFO_PROPERTY_2 ...])]

Get editable properties of the selected torrent, or print all editable properties

Usage: qbtormenu [(-r VAR | VAR_1 [VAR_2 ...])]

The option "-r" is for the raw output of a property

Change an editable property of the selected torrent

Usage: qbtormenuedit PROPERTY VALUE # if the PROPERTY is a single-valued

Usage: qbtormenuedit PROPERTY VALUE_1 VALUE_2 ... # if the PROPERTY is a multi-valued object

Usage: qbtormenuedit tags [-d] TAG # add or delete("-d") the TAG

Scaled piece states string

Usage: qbtorblock [-n [NUMBER_OF_BLOCKS]] [(-o FILE_INDEX | -i FILE_INDEX1 [FILE_INDEX2])]

Print a fixed number of symbols showing the state of pieces blocks of the selected torrent.

Without the "-n" options the number of blocks equals to $COLUMNS (of the current terminal).

If the option "-n" is present then the default number equals to the number of pieces of the torrent (so block=piece).

The meaning of symbols:

"#" - completely downloaded block

"+" - partially downloaded block

"v" - downloading block

"-" - not downloaded (empty) block

The option "-o" specifies the index of a file, whose only pieces will be shown.

The option "-i" specifies the qbtorcontent interval of file indices (alphabetical and generic) whose pieces will be shown among other pieces. The pieces of files outside the interval will be marked by the dot (".")

See "qbtorcontent --help" for a more info on generic and alphabetical indices

Get the specified general properties of the selected torrent, or print all of them

Usage: qbtorgeneral [(-r GEN_PROPERTY | GEN_PROPERTY_1 [GEN_PROPERTY_2 ...])]

Trackers info of the selected torrent

Usage: qbtortrack

Edit trackers of the selected torrent

Usage: qbtortrackedit (-d URL | URL_1 [URL_2])

Options:

-d URL - Delete the tracker URL

URL_1 [URL_2] - Add the tracker URL_1, or replace URL_2 by URL_1

List of connected peers of the selected torrent with a short info

Usage: qbtorpeer [--jqselect FILTER] [--jqsort FILTER] [--jq FORMAT]

Advanced options: --jqselect and --jqsort for inserting "select" and "sort_by" jq-filters. E.g,

qbtorpeer --jqselect '(.progress>0)' --jqsort '(.dl_speed)'

The default --jqsort value is '(.progress)'

Advanced option: --jq enables a possibility to define an own jq-format for output lines. E.g.,

qbtorpeer --jqsort '(.progress)|reverse' --jq '.ip+":"+(.port|tostring)'

The default format of qbtorcontent is defined in the variable

QBtorpeerjq='(.progress*100 | trunc | tostring)+"% "+.ip+" "+.country_code+" "+(.dl_speed /1024 |trunc|tostring)+"Kb/s "+.client+"("+.connection+")"'

The available fields: .client,.connection,.country,.country_code,.dl_speed,.downloaded,.files,.flags,.flags_desc,.ip,.port,.progress,.relevance,.up_speed,.uploaded

Add a peer

Usage: qbtorpeeradd PEER

Alphabetically sorted list of the names and priorities of files of the selected torrent with a short info

Usage: qbtorcontent [--jqselect FILTER] [--jqsort FILTER] [--jq FORMAT] [INDEX_1] [INDEX_2]

Without option prints info of all files with alphabetical (0,1,2,...) and generic ([0],[1],[2]...) indices.

The generic indices do not depend on renaming of files, they are shown in square brackets.

The alphabetical indices depend on the names, they may be more convenient than generic ones.

E.g., the record "3[1]. /Folder/file2 ..." means that the generic index of file2 is [1], while it's alphabetical index is 3.

Arguments INDEX_1 and INDEX_2 are either alphabetical (without brackets), or generic (in square brackets) indices of the same type. They determine an interval of files to be shown

Advanced options: --jqselect and --jqsort for inserting "select" and "sort_by" jq-filters. E.g,

qbtorcontent --jqselect '(.priority==7)' --jqsort '(.progress)|reverse'

Advanced option: --jq enables a possibility to define an own jq-format for output lines. E.g.,

qbtorcontent --jqsort '(.gen_index)' --jq '"["+(.gen_index|tostring)+"] "+.name'

The default format of qbtorcontent is defined in the variable

QBtorcontentjq='(.alph_index|tostring)+"["+(.gen_index|tostring)+"]. "+.name+" <prio:"+(.priority|tostring)+">, "+(.progress*100|trunc|tostring)+"% of "+(.size /1048576|trunc|tostring)+"Mb, "+(.availability*100|trunc|tostring)+"% online"'

Change the names and priorities of files of the selected torrent

Usage: qbtorcontentedit filename NEW_NAME INDEX [OFFSET]

rename the file with INDEX

OFFSET is the number of directory levels up for the new name of the file (default=1)

Usage: qbtorcontentedit dirname NEW_NAME [INDEX] [DIR_INDEX] [OFFSET]

rename a directory in the path of the file with INDEX

DIR_INDEX is the number of directory levels from the file to the targeted directory (default=1)

OFFSET is the number of directory levels up for the new name of the directory (default=1)

Usage: qbtorcontentedit prio NEW_PRIORITY [INDEX_1] [INDEX_2]

qbtorcontentedit prio without arguments INDEX_1 and INDEX_2 does a global change of file priorities

qbtorcontentedit prio with arguments INDEX_1 INDEX_2 sets a new priority to the files in the specified interval, the same as in qbcontent

See "qbcontent --help" for more info on generic and alphabetical indices

Get the full info of the specified file of the selected torrent

Usage: qbtorfile INDEX [(-r PROPERTY | PROPERTY_1 [PROPERTY_2 ...])]

INDEX can be either alphabetic or generic

For example, "qbtorfile [n] -r alph_index" gives the alphabetic index of the generic index [n], while "qbtorfile n -r gen_index" does the reverse transformation

Try "qbtorcontent --help" for a more info on generic and alphabetical indices