.\" Copyright (c) 2010\-2014 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 "plowup" "1" "July 30, 2014" "GPL" "Plowshare for Bash 4"

.SH NAME
plowup \- Simple upload manager for file sharing websites

.SH SYNOPSIS
.B plowup
[\fIOPTIONS\fP]...
[\fIMODULE_OPTIONS\fP]...
\fIMODULE\fP
\fIURL\fP|\fIFILE\fP[\fI:DESTNAME\fP]...

.SH DESCRIPTION
.B plowup
is a command-line tool designed for automatic upload on file-sharing websites.
It acts like a web browser, retrieving pages and filling HTML forms.

Currently supported hosting sites list is available in README file.

Anonymous upload is not allowed by all sites, some of them may require authentication.
See specific module options below.

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

.SS Common options
.TP
.BI -i, " " --interface= IFACE
If your machine has several network interfaces, force using \fIIFACE\fR interface.
.TP
.BI -r, " " --max-retries= N
Set maximum retries for upload failures. Apply on module exit value: \fB1\fR (fatal error), \fB3\fR (network error), \fB7\fR (captcha error).
Default option value is 0 (no retry) and applies for one single upload.
.TP
.BI -t, " " --timeout= SECS
Cancel upload download after \fISECS\fR seconds of waits. Apply on module exit value: \fB10\fR (temporary unavailable error).
This error mainly occurs on remote upload operations.
Default option value is disabled (no timeout, infinite) and applies for one single upload.
.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 item processing.
Temporary directory is used.
.RE
.RS
\fBsession\fR (default) : module storage file is deleted at the end of plowup 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 file upload 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. 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.
.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 plowup 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: plowup legacy exit errors can also be returned, for example: \fB1\fR (fatal) or \fB3\fR (network).
.RE
.SS Tuning settings
.TP
.BI "   " " " --max-rate= SPEED
Limit upload maximum 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 upload 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: cookies, images, ...
.TP
.BI "   " " " --name= FORMAT
Format destination filename (applies on each file argument). Can be useful is you want to append or prepend a string to all your files.
Default string is: \fI"%f"\fR. Interpreted sequences are:
.RS
.TP
\fI%%\fR
raw % character
.TP
\fI%f\fR
destination (remote) filename
.TP
\fI%g\fR
destination (remote) filename (without extension)
.TP
\fI%G\fR
destination (remote) filename (without extension, greedy)
.TP
\fI%h\fR
MD5 hash (32-digit hexadecimal number, lowercase letters)
.TP
\fI%l\fR
source (local) filename
.TP
\fI%m\fR
module name
.TP
\fI%s\fR
file size (in bytes)
.TP
\fI%x\fR
extension (without dot character) of %f (not greedy)
.RE
.TP
.BI "   " " " --printf= FORMAT
Print results (on stdout) in a given format (for each successful upload). Default string is: \fI"%D%A%u%n"\fR. Interpreted sequences are:
.RS
.TP
\fI%%\fR
raw % character
.TP
\fI%a\fR
admin url or admin code (rare case)
.TP
\fI%A\fR
empty if %a is empty, or alias to \fB"#ADM %a%n"\fR.
.TP
\fI%d\fR
delete url
.TP
\fI%D\fR
empty if %d is empty, or alias to \fB"#DEL %d%n"\fR.
.TP
\fI%f\fR
destination (remote) filename
.TP
\fI%l\fR
source (local) filename
.TP
\fI%m\fR
module name
.TP
\fI%n\fR
newline
.TP
\fI%s\fR
filesize (in bytes)
.TP
\fI%t\fR
tabulation character
.TP
\fI%u\fR
download url
.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-curlrc
Do not use curl config file (~/.curlrc).
.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 -d, " " --description= DESCRIPTION
Set file description.
.TP
.BI "   " " " --folder= FOLDER
Folder to upload files into. Usually a (leaf) folder name (no hierarchy assumed).
.TP
.BI -p, " " --link-password= PASSWORD
Protect your files with a password. May require premium account.
.TP
.BI "   " " " --email-from= EMAIL
<From> field for notification email.
.TP
.BI "   " " " --email-to= EMAIL
<To> field for notification email.
.SS Advanced options
.TP
.B "   " --async
Asynchronous remote upload (only start upload, don't wait for link).
.TP
.B "   " --private
Do not allow others to download the file.
.P
All switches are not implemented nor required for all modules.
See long help message for detailed modules option list.

.\" ****************************************************************************
.\" * Examples                                                                 *
.\" ****************************************************************************
.SH EXAMPLES

.SS 1) Upload a single file anonymously
.EX
$ plowup bayfiles /tmp/foo.bar
.sp 1
# Add a text description
$ plowup \-d "Important document" megashares /path/myfile.tex
.sp 1
# Abort slow upload (if rate is below limit during 30 seconds)
$ plowup \-\-min\-rate 100k mediafire /path/bigfile.zip
.EE
.SS 2) Upload a single file with authentication
.EX
# Change destination filename
$ plowup \-a 'myuser:mypassword' turbobit /path/myfile.txt:anothername.txt
.EE
.SS 3) Remote upload
Note: URL fetching is rarely implemented by modules.

.EX
# Feature dedicated to premium members
$ plowup \-a myuser:mypassword rapidgator \\
    http://www.somewherefarbeyond.com/somefile
.sp 1
# Change destination filename
$ plowup \-a myuser:mypassword rapidgator \\
    http://www.somewherefarbeyond.com/somefile:anothername
.EE

.\" ****************************************************************************
.\" * Files                                                                    *
.\" ****************************************************************************
.SH "FILES"
.TP
.I /etc/plowshare.conf
Systemwide configuration file.
.TP
.I ~/.config/plowshare/plowshare.conf
This is the per-user configuration file. 
.TP
.I ~/.config/plowshare/exec/
Additional directory considered when searching for executable. See \fB--captchaprogram\fR switch.
.TP
.I ~/.config/plowshare/storage/
Directory used for storing data (one file per module) among sessions.
See \fB--cache=shared\fR switch.
.PP
The file format is described in
.BR plowshare.conf (5).

.\" ****************************************************************************
.\" * 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 module name does not exist).
.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
Feature (upload service) seems temporarily unavailable from upstream (user account may be temporarily banned).
.IP 12
Authentication required (example: anonymous users can't do remote upload).
.IP 14
Can't upload too big file (hoster limitation or requires more permissions).
.IP 15
Unknown command line parameter or incompatible options.
.IP 16
Asynchronous remote upload started (can't predict final status).
.PP
If
.B plowup
is invoked with multiple 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-2014 The Plowshare Team
.SH "SEE ALSO"
.BR plowdown (1),
.BR plowdel (1),
.BR plowlist (1),
.BR plowprobe (1),
.BR plowshare.conf (5).