Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
cmdftp(1)		    General Commands Manual		     cmdftp(1)

       cmdftp -	command	line File Transfer Protocol client

       cmdftp [	[OPTIONS] ] hostname

       cmdftp 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 de-
       fault, failure to login causes the program to quit; the number of  man-
       ual 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

       There  are  many	 more options that control how cmdftp behaves: see OP-
       TIONS 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.

       -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

       -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

       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

       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

       TMPDIR an  alternative directory	where cmdftp temporary files should be

       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  lo-
       cal  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.

       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:

       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  re-
	      motely 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

	      aliases for q command

       <TAB>  tab-completion for filenames.

       *      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

       **     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.

       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

       -      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.

       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:

       login the\ spaced\ user
       password	\x64eadly\040habit

       login with\\backslash
       password	\tcrazy_tabs_in_pass\t

       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.

	      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  ar-
	      rives, cmdftp will abort.

	      this signal is ignored.

       all other
	      signals are left to their	default	handlers during	execution.

       cmdftp  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.

       cmdftp 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.

       Please report any bugs you might	find, using the	trackers  at  savannah
       or sending email	directly to the	AUTHOR.

       Claudio Fontana <>


       ~/.netrc	- autologin file

       ftp(1), ftpd(8),	netrc, RFC 959

Claudio	Fontana			  2009-02-13			     cmdftp(1)


Want to link to this manual page? Use this URL:

home | help