cmdftp(1)cmdftp(1)NAMEcmdftp - command line File Transfer Protocol client
SYNOPSIScmdftp [ [OPTIONS] ] hostname
DESCRIPTIONcmdftp is an alternative client for the File Transfer Protocol.
It is quite different from the default ftp(1) client, because it always
uses passive mode for all data transfers, has a syntax that mimics the
shell, has local and remote mode, supports multiple and recursive file
transfers, has more complex commands like copy and move, permits remote
and local text file viewing and editing, is able to detect network
failures and resume the operation, may resume broken downloads between
sessions, has tab completion like the shell for both local and remote
file names, and has large file support.
The ftp host to connect to must be specified on invocation ( parameter
hostname ).
First of all, the client will attempt autologin, using information pro‐
vided in ~/.netrc ; if it fails, or the autologin feature has been dis‐
abled ( -n ), a user/password pair must be manually entered. By
default, failure to login causes the program to quit; the number of
manual login attempts can be altered with the -a option.
The cmdftp prompt appears as soon as the login operation completes, and
informs the user that the client is ready to receive commands: see COM‐
MANDS: LIST section. The current directory is shown in the prompt if
option -P has not been specified.
The prompt does not appear at all if the quiet option ( -q ) has been
specified.
There are many more options that control how cmdftp behaves: see
OPTIONS section for a full list and description.
Additionally, this client can interface with other programs using envi‐
ronment variables: see ENVIRONMENT section.
This program can be easily automated: see USAGE_NOTES section for tips
and notes about the cmdftp netrc parser.
OPTIONS-h show command line options and exit. If your system supports
long options, then long option equivalents are shown.
-v show version information and exit
-p FTP_PORT
specify the remote TCP port of the server (def:21)
-b BUFFER_SIZE
specify the size in KB of the transfer buffer (def:64)
-t TIMEOUT_SEC
broken connection check timeout in seconds (def:30)
-a N_ATTEMPTS
max number of manual login attempts before giving up
-q be quiet (suppress copyright message, warnings and transfer
progress)
-D show debug output for FTP commands and responses
-m disable manual login. Rely on autologin only.
-n disable autologin (~/.netrc). Rely on manual login only.
-g disable output paging
-d disable forced ignore of dot-files
-P disable path in prompt
ENVIRONMENT
PAGER refers to command p; sets the pager for file viewing and ls out‐
put. If the variable is not set, the output is simply not
paged.
EDITOR refers to command e, and is required to be able to edit local
and remote files from cmdftp. If no editor is set in the EDITOR
variable, the e command will not be available.
HOME refers to the autologin feature, and is required to be able to
use ~/.netrc (to find your home directory actually). It should
be already set on your system. Note: double check ~/.netrc file
permissions!
TMPDIR an alternative directory where cmdftp temporary files should be
stored.
COMMANDS: NOTES
You will see that a lot of the commands resemble in names and behaviour
similar Unix commands and shell builtins. However there are differences
both in names and behaviour, and expecially on parameter passing (num‐
ber of parameters are fixed in cmdftp), and in the fact that no command
options are allowed.
For example, the Unix cp command has an omonymous cp equivalent command
in cmdftp; however, cmdftp cp command behaves like cp -r, and source
and target must be always specified using exactly two parameters (which
may contain wildcards).
Commands implementation do not generally rely on external software. The
FTP (remote) implementation of the commands has been abstracted so
local implementation has been achieved with cost near zero. This has
the additional benefit of making cmdftp also suited as a very small
rescue tool usable even on broken Unix systems.
The e command (edit file) is an exception because it needs a text edi‐
tor (and an EDITOR env variable set) to work.
There is also an exception in the form of the local dir command (get
pretty list - introduced recently). This command tries to run "/bin/ls
-l". However on failure (you do not have /bin/ls) it uses the consuete
internal implementation of the ls command and returns a normal (not
pretty) list.
COMMANDS: LIST
h displays a slightly less descriptive version of this list
l switch to local mode, following commands refer to local
r switch to remote mode, following commands refer to remote
pwd prompt working directory. Resembles /bin/pwd command.
cd PATH
change working directory to PATH. Resembles cd shell builtin.
md PATH
make new directory PATH. Resembles /bin/mkdir command. Alias:
mkdir
rd PATH
remove empty directory PATH. Resembles /bin/rmdir command.
Alias: rmdir
rm MASK
delete regular files matching MASK, skip directories. Resembles
/bin/rm command.
ls list current directory contents. Resembles /bin/ls command given
with no parameters.
ls MASK
list files/dirs matching MASK. Resembles /bin/ls -d command.
dir pretty list of files in current directory. Resembles /bin/ls -l
command given with no parameters. Local implementation really
spawns /bin/ls in this case, and reverts to a normal (not
pretty) list if /bin/ls is not present.
cp SRC TRG
copy SRC to TRG. Resembles /bin/cp -r command.
mv SRC TRG
move SRC to TRG. Resembles /bin/mv command.
u MASK DIR
upload files/dirs matching MASK into remote DIR (recurs) * Rela‐
tive paths and completion are resolved locally in MASK, and
remotely in DIR.
d MASK DIR
download files/dirs matching MASK into local DIR (recurs) * Rel‐
ative paths and completion are resolved remotely in MASK, and
locally in DIR.
dr MASK DIR
same as above, and if local file already exists, resume **
ren MASK FROM TO
rename files matching MASK replacing the first occurrence of
FROM to TO in the base name. This is similar to rename(1) but
still different (parameter ordering, replacing only in base‐
name). Alias: rename
p FILE print contents of the FILE on the terminal. Resembles /bin/cat
command. Alias: cat
e FILE edit FILE. Requires a working editor, and an EDITOR env variable
set to that editor.
q quit client
quit|exit|bye
aliases for q command
<TAB> tab-completion for filenames.
COMMAND NOTES
* This transfer command is mode-independent. Also remember that
cmdftp commands have a fixed number of parameters, so you MUST
specify a target directory. If that dir does not exist, it is
created.
** resuming has only sense between sessions, or if you explicitly
interrupt the transfer using CTRL+C or equivalent, because
cmdftp will automatically try to resume the current command
(eventually reconnecting) if any network problems are detected.
Also, using dr command might be dangerous if used incorrecly,
because if the incomplete file is a DIFFERENT file instead (same
name, different content) the target file can be screwed up. If
you did not understand the problem just use the basic d command
and you will be fine.
USAGE_NOTES
Some tips to automate cmdftp:
- use the autologin feature and provide valid login information in
~/.netrc : see netrc page for the full file format description.
Some notes about cmdftp netrc parser follow near the end of this
section.
- use the quiet option ( -q ), although redirecting stdout and
stderr to a logfile could be useful instead
- store common command sequences in a file, then run cmdftp with
stdin redirected
- use things like cron ( crond(8), crontab(1) ) to execute cmdftp
scripts periodically.
ESCAPING
The command line parser, and the cmdftp netrc parser both recognize the
same C-like escape sequences. Those are:
\a, \b, \f, \n, \t, \v,
\xHH, (HH are hex digits) - use to specify a character
\OOO, (OOO are octal digits) - use to specify a character
Escaping other characters has the effect of getting that character.
Use to escape special meaning characters, like \ itself or the space.
Quotes have NO special meaning so don't quote your strings. Using
these sequence is expecially useful to be able to work with filenames
containing spaces, or login information containing spaces.
Note however that actively using ftp directories and file names con‐
taining spaces and other problematic characters (\n, \r) is very dis‐
couraged, since FTP servers are allowed to refuse to list them, or
refuse to process some commands on them. If you get mysterious errors,
check your filename for exotic characters.
Here is an example netrc which contains some of those escape sequences:
machine somewhere.myhost.com
login the\ spaced\ user
password \x64eadly\040habit
machine anotherhost.hisnet.org
login with\\backslash
password \tcrazy_tabs_in_pass\t
default
login anon\ymous
password guest
Again, see netrc man page to get the full netrc file format descrip‐
tion. Note that 'account' and 'macdef' are currently NOT supported.
SIGNALS
SIGINT:
sending this signal when no command is being processed causes
the program to quit. During the processing of transfer com‐
mands, it is possible to interrupt them by sending the signal
(CTRL+C for example). The client and the server will need some
seconds to return in synch, and then the cmdftp prompt will be
displayed again.
If some command has been interrupted, and again a SIGINT
arrives, cmdftp will abort.
SIGPIPE:
this signal is ignored.
all other
signals are left to their default handlers during execution.
EXIT STATUScmdftp exits with 0 on clean quit (quit command) or after displaying
requested information through -h and -v options, but only when all out‐
put has been successfully written to stdout. If a failure on stdout is
detected, -1 is returned instead.
In all other cases (fatal errors), exit status is > 0.
LIMITATIONScmdftp has a very simplified readline replacement: there is no history
and little support for cmdline editing.
It is very easy to force cmdftp in an infinite loop by wrong use of cp
command (infinitely copying one directory into itself). There is no
loop detection currently so beware.
cmdftp uses passive mode FTP only by choice.
cmdftp has no special proxy support. You can use real FTP proxies with
cmdftp. See ftp.proxy for example.
BUGS
Please report any bugs you might find, using the trackers at savannah
or sending email directly to the AUTHOR.
AUTHOR
Claudio Fontana <claudio@gnu.org>
HOME PAGE
http://savannah.nongnu.org/projects/cmdftp
http://www.nongnu.org/cmdftp
FILES
~/.netrc - autologin file
SEE ALSOftp(1), ftpd(8), netrc, RFC 959
Claudio Fontana 2009-02-13 cmdftp(1)
