6.2. Command-Line Client-Shell¶
A command-line shell is provided to access remote file transfer servers using an interactive interface.
On Unix and Linux systems, the client-shell is available as:
On Windows systems, the client-shell is available as:
All Unix/Linux and Windows versions provide the same command-line arguments and shell commands. We use the generic client-shell name for both types of executable files.
All commands to be executed in the client’s shell are prefixed with:
The focus of our product is on providing tools for non-interactive file transfers. The client-shell is provided as a tool to help with troubleshooting or administrative tasks, without requiring an external tool.
In the case that you are using or planning to use the client-shell for production, your feedback and comments are welcome. They help us improve the client-shell and extend the scope of its usage.
If you need an interactive file transfer client with a graphical user interface, we suggest trying a better suited FTP/FTPS/SFTP/SCP client such as FileZilla, WinSCP or Cyberduck.
The configuration options required to connect to a remote server (IP, port, username, password, etc.) are available in the shell as options and on the command-line as arguments.
To open a connection for user john outside the client-shell:
client-shell --username john
To show all available command-line arguments outside the client-shell:
To set the username as john inside the client-shell:
> set username john
To show all available options inside the client-shell:
When the client-shell is started, you will see a prompt such as:
SFTPPlus (3.0.0) file transfer client shell >
After that, you can start entering client-shell commands. To show all available commands, use:
To find more details about a command, use:
> help COMAND_NAME
For example, to show more details about the command open, use:
> help open
Command names are case-insensitive. You can abbreviate the command names, as long as the abbreviation does not conflict with another command name. Shell options are case-sensitive.
For example, the following inputs will trigger the same command, namely connect:
> connect > CONNECT > Connect > con
When an abbreviation matches multiple commands, you will get an error:
> c Abbreviation has multiple commands: close connect
Connections to remote servers are started using the open command and closed using the close command. After a connection is made, the shell can be used to issue file transfer commands, such as mkdir, rmdir, rm, mv, put, get, etc.
Let’s exemplify a connection to a SFTP server using connection options specified as command-line arguments. The following will open the connection, list the content of a folder, close the connection, and then exit the client-shell:
client-shell sftp://firstname.lastname@example.org:10022 \ --ssh-server-fingerprint=06:cb:46:2b:9a:9a:c4:10:54:f0:ea:2f:b6:05:cb:a0 \ --ssh-private-key=test_data/ssh/test-ssh-rsa-1024 > open > ls > close > exit
The next example shows the same connection, with connection options specified using shell options:
client-shell > set protocol sftp > set address sftp-acct1.example.com > set port 10022 > set username john > set ssh_private_key test_data/ssh/test-ssh-rsa-1024 > set ssh_server_fingerprint 06:cb:46:2b:9a:9a:c4:10:54:f0:ea:2f:b6:05:cb > open > ls > close > exit
To handle paths with spaces, quote them using single quotes (‘). Double quotes (‘’) and backslash escaping (like some\\ space) are not supported.
Below is an example for moving a file between paths with spaces:
client-shell > # Don't forget to set connection options. > open > mv 'source dir/source file' 'destination dir/target file' > close > exit
The client-shell provides the equivalent put / upload commands for uploading a file and the corresponding get / download commands for downloading a file:
client-shell > set protocol sftp > set address sftp-acct1.example.com > set port 10022 > set username john > set password pass-for-johnny > set ssh_server_fingerprint 06:cb:46:2b:9a:9a:c4:10:54:f0:ea:2f:b6:05:cb > open > > # Uploading a local file with a new name on the remote destination. > put path/to/local.file destination/remote.file > # Uploading a local file with the same name on the remote destination. > upload path/to/local.file > > # Downloading a remote file with a new name on the local destination. > get path/to/remote.file destination/local.file > # Downloading a remote file with the same name on the local destination. > download path/to/remote.file > close > exit
During a client-shell session, you can issue commands to connect to more than one server. But only a single connection is active at one time. Opening a new connection will automatically close a previous connection.
The next example shows a single shell session inside which two connections are made to different servers:
client-shell > set protocol sftp > set address sftp-acct1.example.com > set port 10022 > set username john > set ssh_private_key test_data/ssh/test-ssh-rsa-1024 > set ssh_server_fingerprint 06:cb:46:2b:9a:9a:c4:10:54:f0:ea:2f:b6:05:cb > open > ls > close > set protocol sftp > set address sftp-vendors2.example.com > set port 22 > set username actpd > set password sd!ds21p > open > ls > close
The client-shell can read commands and options from a plain text file. We call this a batch file.
Each command in a batch file should be put on a separate line. Lines starting with # are considered comments and ignored. Empty lines are also ignored.
After processing the last line, the client-shell will exit.
Here is an example of a batch file to connect to a remote server and list the content of its root directory:
# Server for accounting. This is a comment. set protocol sftp set address sftp-acct1.example.com set port 10022 set username john set ssh_private_key test_data/ssh/test-ssh-rsa-1024 set ssh_server_fingerprint 06:cb:46:2b:9a:9a:c4:10:54:f0:ea:2f:b6:05:cb open # List root directory. A comment which is ignored. ls close
To run the client-shell in batch mode, use:
client-shell --batch path/to/batch/file
The SFTPPlus client-side implementation will emit all events relating to the client-side activity. The events can be used for logging or for hooks in other managed file transfer workflows.
See below for client-side events relating to a file that does not exist:
| > get file_does_not_exist.pdf 60053 2017-08-14 14:06:43 Process Process 0.0.0.0:0 Successfully opened "file_does_not_exist.pdf" for reading on "ftp". | 60036 2017-08-14 14:06:43 Process Process 0.0.0.0:0 Failed to close "file_does_not_exist.pdf" on location "ftp". Was opened for reading. ['550 File not found']
See below for the corresponding server-side events from a third-party server:
| (000020)8/14/2017 14:06:43 PM - support_team (127.0.0.1)> RETR file_does_not_exist.pdf | (000020)8/14/2017 14:06:43 PM - support_team (127.0.0.1)> 550 File not found