.\" Copyright (c) 2010\-2017 Plowshare Team
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 3 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, see
.\" <http://www.gnu.org/licenses/>.

.TH "plowdown" "1" "April 2, 2017" "GPL" "Plowshare for Bash 4"

.SH NAME
plowdown \- Simple download manager for file sharing websites

.SH SYNOPSIS
.B plowdown
[\fIOPTIONS\fP]...
[\fIMODULE_OPTIONS\fP]...
\fIURL\fP|\fIFILE\fP...

.SH DESCRIPTION
.B plowdown
is a command-line tool designed for automatic download on file-sharing websites.
It acts like a web browser, retrieving pages and filling HTML forms (including captchas).

.\" ****************************************************************************
.\" * Options                                                                  *
.\" ****************************************************************************
.SH OPTIONS

.SS Common options
.TP
.BI -i, " " --interface= IFACE
If your machine has several network interfaces, force using \fIIFACE\fR interface.
.TP
.B -m, --mark-downloaded
Mark downloaded links in (regular) file arguments.
.TP
.BI -o, " " --output-directory= DIRECTORY
Directory where files will be saved. Default is current directory.
.TP
.BI -r, " " --max-retries= N
Set maximum retries for download failures. Apply on module exit status: \fB3\fR (network error), \fB7\fR (captcha error).
Default option value is 2 (i.e. 3 tries) and applies for one single URL download.
.TP
.BI -t, " " --timeout= SECS
Cancel download after \fISECS\fR seconds of waits. Apply on module exit status: \fB10\fR (temporary unavailable error). \
This error can be returned in various cases: unallowed parallel download, daily downloads limit reached, remote hoster overloaded. \
Default option value is disabled (no timeout, infinite) and applies for one single URL download.
.TP
.B -x, --no-overwrite
Do not overwrite existing files. Existing file will be preserved and filename will be suffixed with .1, .2, and so on. \
Default option value is disabled: files are overwritten (whatever their size) or resumed (if module supports it).
.TP
.BI "   " " " --cache= METHOD
Cache policy regarding module storage space. \
Each module is able to save data (credentials, authentication session, or tokens)
in order to be reused later.
Available values:
.RS
\fBnone\fR: module storage file is deleted before each URL processing.
Temporary directory is used.
.RE
.RS
\fBsession\fR (default): module storage file is deleted at the end of plowdown execution.
Temporary directory is used.
.RE
.RS
\fBshared\fR: module storage file is global and located (in \fI~/.config/plowshare/storage/\fR).
It can be accessed by any other instance of plow* scripts.
Warning: There is no atomicity (or file locking) on concurrent access.

Example: Multiple links download using a premium account.
If supported by module, login stage could be performed once.
.RE
.SS Captcha options
.TP
.BI "   " " " --9kweu= KEY
Use 9kw.eu service to solve captchas.
.TP
.BI "   " " " --antigate= KEY
Use Antigate.com service to solve captchas.
.TP
.BI "   " " " --captchabhood= USER:PASSWORD
Use Captcha Brotherhood service to solve captchas.
.TP
.BI "   " " " --captchacoin= KEY
Use CaptchaCoin service to solve captchas.
.TP
.BI "   " " " --deathbycaptcha= USER:PASSWORD
Use Death by Captcha service to solve captchas.
.TP
.BI "   " " " --captchamethod= METHOD
Force specific captcha solving method (if unspecified it is autodetected). Available values:
.RS
\fBimgur\fR: upload image to Imgur.com service, print image url in console and prompt for manual entering. Useful for NAS and embedded devices.
.RE
.RS
\fBnone\fR: abort if captcha solving is requested (even if automatic solving service is available).
.RE
.RS
\fBonline\fR: use captcha solving website only (9kweu, Antigate, CaptchaBrotherhood, CaptchaCoin or DeathByCaptcha account required).
.RE
.RS
\fBfb\fR: display image in framebuffer console and prompt for manual entering. Looks for framebuffer viewers: fbi, fim.
\fIFRAMEBUFFER\fR environment variable can contain device file. Default is \fI/dev/fb0\fR.
.RE
.RS
\fBnox\fR: display image in console (text) and prompt for manual entering. Looks for ascii viewers: img2txt, aview, tiv.
.RE
.RS
\fBx11\fR: display image in an X11 window and prompt for manual entering. Looks for viewers: display, feh, sxiv, qiv.
\fIDISPLAY\fR environment variable must not be empty.
.RE
.TP
.BI "   " " " --captchaprogram= PROGRAM
Call external program or script for solving captchas. Provided executable can be located in \fIPATH\fR environment variable.

Three arguments are given:
.RS
\fB$1\fR
module name (lowercase). For example: \fImediafire\fR.
.RE
.RS
\fB$2\fR
image filename (with full path).
.RE
.RS
\fB$3\fR
hint or captcha type (string). For example: \fIrecaptcha\fR, \fIsolvemedia\fR or \fIdigits-4\fR.

Return value (on stdout) and exit status:
.RE
.RS
\fB0\fR: solving success. Captcha Word(s) must be echo'ed.
.RE
.RS
\fB2\fR: external solver is not able to solve requested captcha. Let plowdown continue solving it normally (will consider \fB--captchamethod\fR if specified).
.RE
.RS
\fB7\fR: external solver failed.
Note: this exit code is eligible with retry policy (\fB-r\fR/\fB--max-retries\fR).

Note: plowdown legacy exit errors can also be returned, for example: \fB1\fR (fatal) or \fB3\fR (network).
.RE
.SS Tuning settings
.TP
.BI "   " " " --min-space= LIMIT
Define threshold amount of available disk space before quitting plowdown. You must specify a suffix. Suffixes are:
.RS
\fBM\fR  for megabytes (MB i.e. 1000^2),
.RE
.RS
\fBG\fR  for gigabytes (GB i.e. 1000^3),
.RE
.RS
\fBMi\fR or \fBm\fR  for mebibytes (MiB i.e. 1024^2),
.RE
.RS
\fBGi\fR  for gibibytes (GiB i.e. 1024^3).
.RE
.TP
.BI "   " " " --max-rate= SPEED
Limit download speed in bytes per second. Suffixes are:
.RS
\fBk\fR  for kilobytes (kB i.e. 1000),
.RE
.RS
\fBM\fR  for megabytes (MB i.e. 1000^2),
.RE
.RS
\fBK\fR or \fBKi\fR  for kibibytes (KB or KiB i.e. 1024),
.RE
.RS
\fBm\fR or \fBMi\fR  for mebibytes (mB or MiB i.e. 1024^2).
.RE
.TP
.BI "   " " " --min-rate= SPEED
Limit download minimum speed in bytes per second (for a delay of 30 seconds). Suffixes are the same than \fB--max-rate\fR.
.TP
.BI "   " " " --temp-directory= DIRECTORY
Directory for temporary files: final link download, cookies, images, ...
.TP
.B "   " --temp-rename
Append .part suffix to filename while file is being downloaded. Download resume will not work with this option.
.TP
.B "   " --skip-final
Don't process final link (returned by module download function), just skip it. This is applied for each input URL.
If you are using this option, you should need
.B --run-after
or
.B --printf
too.

Note: Depending hosters, final (generated) link may have restrictions: validity timeout (few hours), access
limitation (usually one unique HTTP GET request for anonymous users), same IP address, etc.
.TP
.BI "   " " " --run-before= PROGRAM
Call external program or script before new link processing (before calling module download function). Provided executable can be located in \fIPATH\fR environment variable.
Messages can be sent to stderr, stdout is trashed.

Three arguments are given:
.RS
\fB$1\fR
module name (lowercase). For example: \fImediafire\fR.
.RE
.RS
\fB$2\fR
download URL.
.RE
.RS
\fB$3\fR
cookie (empty) file given to download module function.

Exit status:
.RE
.RS
\fB0\fR: script success. plowdown continue normally.
.RE
.RS
\fB2\fR: script explicitly requests skipping current link.

Note: Any other script exit status like \fB1\fR (fatal) or \fB3\fR (network) will be ignored (an error message will be reported).
.RE
.TP
.BI "   " " " --run-after= PROGRAM
Call external program or script after final link successful download. Provided executable can be located in \fIPATH\fR environment variable.
Messages can be sent to stderr, stdout is trashed.

Five arguments are given:
.RS
\fB$1\fR
module name (lowercase). For example: \fImediafire\fR.
.RE
.RS
\fB$2\fR
download URL.
.RE
.RS
\fB$3\fR
cookie file fulfilled by download module function.
.RE
.RS
\fB$4\fR
final URL.
.RE
.RS
\fB$5\fR
final filename.

Exit status:
.RE
.RS
\fB0\fR: script success. plowdown continue normally.

Note: Any other (non zero) exit status will be ignored (an error message will be reported).
.RE
.TP
.BI "   " " " --printf= FORMAT
Print results (on stdout) in a given format (for each successful download). Default format string is \fI"%F%n"\fR. Interpreted sequences are:
.RS
.TP
\fI%%\fR
raw % character
.TP
\fI%c\fR
final cookie filename (with output directory if specified). Name template is \fBplowdown-cookies-NNNN.txt\fR.
.TP
\fI%C\fR
\fB%c\fR or empty string if module does not require it
.TP
\fI%d\fR
download (final) url
.TP
\fI%D\fR
same as \fB%d\fR but url is escaped for JSON usage
.TP
\fI%f\fR
destination (local) filename
.TP
\fI%F\fR
destination (local) filename (with output directory if specified)
.TP
\fI%m\fR
module name
.TP
\fI%n\fR
newline
.TP
\fI%s\fR
destination (local) file size (positive integer in bytes).
Important: Empty string is returned when \fB--skip\-final\fR switch is specified.
.TP
\fI%t\fR
tabulation character
.TP
\fI%u\fR
download (source) url
.TP
\fI%U\fR
same as \fB%u\fR but url is escaped for JSON usage
.RE
.SS Logging options
.TP
.BI -v, " " --verbose= LEVEL
Set output verbosity level:
.RS
\fB0\fR  none,
.RE
.RS
\fB1\fR  errors,
.RE
.RS
\fB2\fR  notice (default behavior),
.RE
.RS
\fB3\fR  debug,
.RE
.RS
\fB4\fR  report (very noisy, log HTML pages).
.RE
.TP
.B -q, --quiet
Alias for \fB-v0\fR. Do not print any debug messages.
.SS Miscellaneous options
.TP
.B "   " --no-color
Disables log messages (stderr only) output coloring.
.TP
.B "   " --fallback
If no module is found for link, simply download it (HTTP GET).
.TP
.B "   " --no-curlrc
Do not use curl config file (~/.curlrc).
.TP
.BI "   " " " --curlrc= FILE
Force using an alternate curl configuration file. Replaces ~/.curlrc if it exists. This option has no effect when
.B --no\-curlrc
is defined.
.TP
.B "   " --no-plowsharerc
Do not consider any configuration file.
.TP
.BI "   " " " --plowsharerc= FILE
Force using an alternate configuration file (instead of per-user or systemwide plowshare.conf). This option has no effect when
.B --no\-plowsharerc
is defined.
.TP
.B "   " --modules
Display all supported module names (one per line) and exit. Useful for wrappers.
.SS Generic program information
.TP
.B -h, --help
Display main help and exit.
.TP
.B -H, --longhelp
Display complete help (with module options) and exit.
.TP
.B "   " --version
Output version information and exit.

.\" ****************************************************************************
.\" * Modules options                                                          *
.\" ****************************************************************************
.SH "MODULE OPTIONS"

.SS Common options
.TP
.BI -a, " " --auth= USER:PASSWORD
Use premium account.
.TP
.BI -b, " " --auth-free= USER:PASSWORD
Use free account.
.TP
.BI -p, " " --link-password= PASSWORD
Used for password-protected files.
.P
All switches are not implemented nor required for all modules. See long help message for detailed modules option list.

.\" ****************************************************************************
.\" * Notes                                                                    *
.\" ****************************************************************************
.SH NOTES

.SS
Command line authentication string format
Complete login must have
.I USER:PASSWORD
format. The first semi-colon character is the separator. So,
.I PASSWORD
can contain a semi-colon character without any trouble.
.TP
Don't forget to single-quote string if your password contain shell expandable characters (like space, $ or &).

.\" ****************************************************************************
.\" * Files                                                                    *
.\" ****************************************************************************
.SH "FILES"
.TP
.I /etc/plowshare.conf
Systemwide configuration file.
.TP
.I ~/.config/plowshare/plowshare.conf
This is the per-user configuration file.
.PP
The file format is described in
.BR plowshare.conf (5).
.TP
.I ~/.config/plowshare/exec/
Additional directory considered when searching for executable. \
See \fB--captchaprogram\fR, \fB--run-before\fR and \fB--run-after\fR switches.
.TP
.I ~/.config/plowshare/modules.d/
User directory considered when searching for modules at startup
(plowdown will try to open \fB~/.config/plowshare/modules.d/*/config\fR). One file per module (hoster).
.TP
.I ~/.config/plowshare/storage/
Directory used for storing data (one file per module) among sessions. See \fB--cache=shared\fR switch.

.\" ****************************************************************************
.\" * Environment Variables                                                    *
.\" ****************************************************************************
.SH "ENVIRONMENT VARIABLES"
The following environment variables may affect plowdown:
.TP
.I DISPLAY
The X11 display server address is considered to display captchas. See \fB--captchamethod=x11\fR documentation below.
.TP
.I FRAMEBUFFER
This variable is considered to display captchas. See \fB--captchamethod=fb\fR documentation below.
.TP
.I HOME
Search for user configuration directory in \fB~/.config/plowshare\fR (see FILES section above).
If found, \fB~/.curlrc\fR will be used (use \fB--no-curlrc\fR to disable it).
.TP
.I PLOWSHARE_CURL
Specifies an alternate curl command (\fB$PATH\fR search is considered). If not defined, \fBcurl\fR is used.
.TP
.I PLOWSHARE_JS
Specifies an alternate js command (\fB$PATH\fR search is considered). If not defined, \fBjs\fR is used.
.TP
.I PLOWSHARE_DEBIAN_JS
When set to \fByes\fR javascript is enabled, otherwise it is blocked per #791467. Note that arbitrary javascript downloaded from the Internet will be run without any sandboxing if this is enabled.
.TP
.I XDG_CONFIG_HOME
The directory to store user configuration files. If not defined, \fB~/.config\fR is assumed.

.\" ****************************************************************************
.\" * Exit codes                                                               *
.\" ****************************************************************************
.SH "EXIT CODES"

Possible exit codes are:
.IP 0
Success.
.IP 1
Fatal error. Upstream site updated or unexpected result.
.IP 2
No available module (provided URL is not supported).
.IP 3
Network error. Mostly curl related.
.IP 4
Authentication failed (bad login/password).
.IP 5
Timeout reached (refer to \fB-t\fR/\fB--timeout\fR command-line option).
.IP 6
Maximum tries reached (refer to \fB-r\fR/\fB--max-retries\fR command-line option).
.IP 7
Captcha generic error.
.IP 8
System generic error.
.IP 10
Link alive but temporarily unavailable.
.IP 11
Link alive but requires a password.
.IP 12
Link alive but requires some authentication (private or premium link).
.IP 13
Link is dead.
.IP 14
Can't download link because file is too big (need permissions).
.IP 15
Unknown command line parameter or incompatible options.
.PP
If
.B plowdown
is invoked with multiple links or link-list files and one or several errors occur, the first error code is returned added with 100.

.\" ****************************************************************************
.\" * Authors / See Also                                                       *
.\" ****************************************************************************
.SH AUTHORS
Plowshare was initially written by Arnau Sanchez. See the AUTHORS file for a list of some of the many other contributors.

Plowshare is (C) 2010-2017 The Plowshare Team
.SH "SEE ALSO"
.BR plowup (1),
.BR plowdel (1),
.BR plowlist (1),
.BR plowprobe (1),
.BR plowshare.conf (5),
.BR plowmod (1).