Introduction

Normally, retawq tries to handle all network activity in a completely automated way: you only enter a URL, e.g. with the keyboard command "g", and the program connects to a server and handles the network commands and responses as appropriate for the respective protocol. But in some cases, you might want to "customize" the sequence of network commands manually, e.g. because you want to access a server which requires special commands or special sequences of commands to get a certain job done. That's what the "custom connections" feature is for. It provides a functionality similar to that of the usual, old, shell-like FTP clients.

Please note that this feature is very young - introduced in version 0.2.6 - and might not yet work as expected.

To use custom connections, start the program in console runmode with the command-line option "--console". You are provided with a text prompt on a "raw" text console which doesn't use any curses library support, similar to usual shell-like FTP clients. At the prompt, you can enter textual commands like "open", "get", "help" or "quit".

Opening a Connection

To open a connection to a server, enter the command "open" with one argument. Deviating from usual shell-like FTP clients, the argument isn't a bare server name but instead a URL which consists of a scheme and the actual server name and, optionally, a port number. If no explicit scheme is given, FTP is assumed here. Some example commands: "open foo.org", "open ftp://foo.org", "open ftp.foo.org", "open ftp.foo.org:42", "open ftps://ftp.foo.org/".

The following schemes are currently "known" for custom connections:

• The scheme "ftp" is supported; this behaves similar to the usual shell-like FTP clients. If no explicit port number is given, the default FTP port (21) is used.
• If the compile-time configuration option OPTION_TLS has been enabled: 1. The scheme "ftps" is supported; if no explicit port number is given, the default ftps port (990) is used; with this scheme, a TLS/SSL handshake is automatically performed as soon as the connection to the server has been established. 2. With the normal "ftp" scheme, you can start a TLS/SSL handshake at any later time manually using an "auth" command.

When a connection has been established, you usually want to enter the commands "user" and "pass", followed by some sequence of "cd", "ls" and "get" or other commands. When you are done with a connection, use a "close" command.

Tasks

Deviating from most shell-like FTP clients, retawq allows you to operate on several connections at the same time for extra comfort and flexibility. In console runmode, each (control) connection is represented by a "task". Each task is identified by a unique "task identification number" ("task ID"). The task ID of the current task (if any) is indicated in the prompt string.

Whenever you open a new connection, e.g. with an "open" command, a new task is created. To get a list of all currently existing tasks or information about specific tasks, use the command "info". To switch to a different task, select it with the command "task". If the current task is busy and you want to get a prompt, press the key "&". (Mnemonic: that's the key which you use at the end of a line in a normal shell to execute a job in the background.)

Commands

The below textual commands are available for the handling of custom connections. Some commands may or must have arguments; commands and any arguments are separated by space characters; if a command requires a certain number of arguments, this is mentioned in parentheses. At run-time, you can get a list of available commands by using the command "help" without arguments, and you can get short information about specific commands by using the command "help" with the respective commands as arguments. You'll notice that some usual commands like "put" are currently missing - they will be implemented in a future version.

Many servers accept some of the commands only if you are logged in as a "real" (non-anonymous) user - especially commands which change something on the server file system, e.g. delete, mkdir, rmdir.

Commands may be abbreviated as far as they don't become ambiguous; for example, the command "quote" may be abbreviated to "quo", but not further ("qu", "q") because this could be mixed up with "quit".

To discard the current input for a command in console runmode, press ctrl-c.

• account - send your "account" information to the server (1 argument); this is necessary with some servers if you want to put/upload files to them; you might have to use this command right after a "pass" command or at some point before a "put" command
• ascii - set the file transfer type for the current connection to ASCII (0 arguments)
• auth - start a TLS/SSL handshake on the current connection (0..1 arguments); this command is only available if the compile-time configuration option OPTION_TLS has been enabled. If you have opened a connection using the URL scheme "ftp" (not "ftps"!), you can start the handshake at any later time manually with this command. If you don't provide an argument, the handshake is either performed as specified with the run-time configuration option "ftps-method" or, by default, autodetected. Alternatively, you can explicitly provide a single-letter argument which corresponds to FTP commands and "ftps-method" identifiers as follows:
  • "p": "AUTH TLS", "PROT P"; authtls
  • "c": "AUTH TLS", "PROT C"; authtls-dataclear (so the data connection won't be protected with this method)
  • "s": "AUTH SSL"; authssl
  If any problem occurs in the sequence of the FTP commands which establish TLS, the control connection probably becomes unusable, so you should close it and open a new one.
• binary - set the file transfer type for the current connection to binary (0 arguments)
• cd - change the remote current working directory to the given directory (1 argument)
• cdup - change to the remote parent directory (0 arguments); this has quite the same effect as "cd .."
• close - close the current connection (if no arguments are given) resp. close all connections whose task IDs are given as arguments
• delete - delete the given remote file (1 argument)
• download - download the content from the URL which is given in the first argument and store it in a local file (1..2 arguments); the file name can be provided in the optional second argument; if no explicit file name is given, retawq tries to extract a file name from the URL - if that's not possible, you get a "too few arguments" error message and can re-enter the command with an explicit file name. The download is performed in a new task, so you can observe its progress with the command "info" or stop it with the command "close". Unlike the command "get", the command "download" performs an automated download similar to the command-line option "--download" and the keyboard command "ctrl-d"; this has the following consequences: 1. you can use any URL which would be allowed with the keyboard command "ctrl-d", so you aren't restricted to FTP; 2. you can't "customize" the operation and can't get at a prompt for such a download task; 3. there's no need to open a connection manually with an explicit prior "open" command.
• get - receive one file from the server and save it in a local file (1..2 arguments); the first argument must be the remote file name, the optional second argument is a local file name; if the second argument is missing, the file name part from the first argument is used if possible, or you get a "too few arguments" error message and can re-enter the command with an explicit file name. If a local file with the name already exists, you're asked whether you want to overwrite or append (or cancel); enter one of the letters which are provided in parentheses - any other input is interpreted as "cancel" - and press Return. If you want to append, you presumably want use the command "restart" before "get".
• hash - if no argument is given, toggle the printing of hashmarks ("#") on/off; by default, hashmark printing is off; when turned on, one hashmark is printed for every "chunk" of data that is transferred in the current connection, which usually means 1024 transferred bytes; if the argument is a question mark ("?"), the current hashmark mode is shown without modification; if a numerical argument of at least 256 is given, this is interpreted as the new "chunk size" and hashmark printing is turned on; otherwise, hashmark printing is turned off (0..1 arguments)
• help - print a list of all available commands (if no arguments are given) resp. print short information about all commands which are given as arguments; alias for this command: "?" (as in other shell-like FTP clients)
• info - show information about all existing tasks (if no arguments are given) resp. about the tasks whose task IDs are given as arguments; the information for each task consists of one or two lines: the first line mentions the ID number, the label (if any), the state (busy/automated), TLS protection and the server URL; a second line might describe the current state of the connection, similar to the information in the bottom line of the screen in curses-like runmode - for custom connections, it usually says "Exchanging messages" plus the last server status code (FTP server reply code).
• label - mark a task with a "label" (an arbitrary string which doesn't begin with a digit and doesn't contain whitespace characters); the first argument is the label string; the optional second argument is the task ID of the task to which the label shall be attached; if no task ID is given, the label is attached to the current task. The labels can help you to find certain tasks in long task lists faster and can be memorized more easily than the somewhat abstract task ID numbers. (Thus further uses of labels are planned for future releases.)
• lcd - change the local current working directory (0..1 arguments); if no argument is given, the working directory is changed back to the original directory which was current when the program was started; if one argument is given, this is used as the new current working directory; if you only want to find out what the current working directory is without modifying it, you can use "lcd ."; all tasks use the same local current working directory, so you don't have to enter this command for every new task
• ls - list the contents of the current remote working directory (if no argument is given) or the contents of the given directory; depending on the server, you might be able to use list options like "-aL"
• mkdir - make (create) the given remote directory (1 argument)
• open - open a connection to a server which is specified via URL; this creates a new task; read the section "Opening a Connection" above for an extensive discussion of this command (1 argument)
• pass - send a password to the server for login (0..1 arguments); this must usually be done right after a "user" command, and most FTP servers require these commands to occur in this order without any other commands in between. If you don't mind anyone near you reading the password on the screen, you can enter the password directly as an argument to the "pass" command; otherwise, use the "pass" command without any arguments and you're prompted separately for the password, where all entered characters appear as disguising "*" characters on the screen. If the username was "anonymous", the password must usually be "guest" or "anonymous" or look like an e-mail address. - If a server produces very long multi-line messages when you login or whenever you change the remote directory etc., it might help if you stick a dash ("-") immediately in front of the password; many servers understand this and produce much shorter messages afterwards.
• pwd - print the remote current working directory (0 arguments)
• quit - quit the program immediately (0 arguments); aliases for this command: "bye", "exit" (as in other shell-like FTP clients)
• quote - send a verbatim FTP command to the server; this allows you to send arbitrary FTP commands, even those which retawq doesn't know anything about. The FTP command is neither modified nor analyzed; the disadvantage is that retawq can't know what's going on, so it can only recognize the time at which the server sent a complete response back and prompt you for the next command; e.g. you can't use quoted commands to start a file transmission because retawq would have to extract the IP address and port number for the data connection from the text; similarly you can't use quoted commands to start a TLS/SSL handshake.
• restart - set the server's file transfer restart marker to the given value (1 argument); this command usually must be followed by a command like "get" to initiate an actual file transfer
• rmdir - remove (delete) the given remote directory (1 argument)
• site - send a site-specific command to the server (1 or more arguments); the possible site-specific commands depend on the server; you might be able to get further information with a command like "site help" or "quote help site"; one particularly useful site command is "site chmod", which might allow you to change the access permissions of a remote file
• task - switch to (select) the given task (1 argument); if the given task is currently "busy", you don't get a prompt but you can use the key "&" as described in the section "Tasks" above
• user - send the given argument as a username to the server for login; if you don't provide an argument, "anonymous" is sent; please note that you aren't automatically prompted for a password afterwards - use the "pass" command manually if necessary; this whole feature is about custom connections, so it tries to do as little as possible automatically (0..1 arguments)
• version - show retawq's version number
• ! (exclamation mark) - execute a shell command; for security reasons, this only works if the respective feature has been enabled with the compile-time configuration option OPTION_EXECEXT. This command is similar to the keyboard command "!". Especially, the first argument can be an "options" argument introduced with a colon (":"); but since console runmode doesn't have anything like a "current document" notion, you can only use the options "o", "e" and "h" here. If you use one of the options for reading the output of the shell command, a new task is created for this, so you can switch to a different task if the shell command is busy for a longer time and you don't want to wait; otherwise, the shell command is executed "asynchronously in the background" and its output is discarded.