CrossFTPCrossFTP Commander - Command Line Tool

CrossFTP Commander is a command line tool based on CrossFTP engine to handle data transfer, sync and various other operations. It also helps do file and database backup and schedulings with easy. It has small memory footprint (core library size is about 4MB), and can be integrated in the shell script or system scheduler. The supported protocols include FTP, SFTP, FTPS, WebDav, Amazon S3, and Google Storage protocols.

CrossFTP Commander is a component of CrossFTP Enterprise. With CrossFTP Enterprise license on your machine, you can choose to run either tool.

LinuxMac OS Xwindows Download Portable Package

Evaluate
Buy

The following is the manual for the commands available in the CrossFTP Commander.

addSite/listSites/editSite/deleteSite

  • Data Handling

copy/move/delete/sync/encrypt/decrypt

  • Configuration

registerLicense/releaseLicense/config

Site and Site ID

Each site defines the FTP/Cloud protocols and its host, etc. information. Each site has a unique ID, and Commander uses that unique ID to reference and connect to the site.

CrossFTP GUI client and CrossFTP commander share the same site repository, so that you can create it or look for it in either application.

Create a site

To create a new site, you can either use CrossFTP to create it in the GUI (Sites -> Site Manager), or you can use addSite command to create it.

Get site ID

Site ID is the unique ID for a site. MyComputer is the reserved site ID representing the local machine.

To get a site's ID, you can use 1 of the following 2 approaches:

1. Get ID from CrossFTP GUI. Go Sites -> Site Manager, and select the site, and choose Copy Site ID from the popup menu, as shown in the following figure:

Copy Site ID

Fig. 1. Copy Site ID in Site Manager

2. Get site ID from Commander's listSites command, see command help for listListes.

addSite/listSites/editSite/deleteSite

This set of command is to manage the list of sites that can be used for the data handling. You can either to use CrossFTP GUI or Commander to create sites you needed. The following is the usage for the action:

usage: commander [--action
       <addSite/listSites/editSite/deleteSite>]
       [--configDir <PATH_TO_CONFIG_DIRECTORY>]
       [--enableLocalEncryption <true/false>]
[--help] [--host <Hostname>] [--localEncryptionPassword <Password>]
[--password <Password/SecretKey>] [--port <PortNumber>] [--protocol <Protocol>] [--siteId <SiteID>] [--username <UserName/AccessKey>]
--action <addSite> Input the action type
--configDir <PATH_TO_CONFIG_DIRECTORY> Config home's path
--enableLocalEncryption <true/false> Whether to enable local encryption
--help Show the command line usage for an action
--host <Hostname> Hostname of the site
--localEncryptionPassword <Password> Local encryption password
--password <Password/SecretKey> Password (FTP/WebDav) or secret key (S3/Amazon/Glacier /Google Storage)
--port <PortNumber> Port number
--protocol <Protocol> Protocol of the site
--siteId <SiteID> ID name of the site
--username <UserName/AccessKey> User name (FTP/WebDav) or Access key (S3/Amazon Glacier /Google Storage)

The protocol of the site can be ftp/ftps_ssl_implicit/ftps_ssl/ftps/sftp/webdav_http/webdav/s3_http/s3 /gs_http/gs/glacier_http/glacier.

addSite Example:

addSite adds a new site into the CrossFTP commander repository. The following is an example for the addSite action: We want to add a site with name 'site1', username 'username', password 'pass', protocol FTP, and host 'www.example.com'.

./commander.sh -action addSite --siteId site1  --protocol ftp 
--username username --password pass --host www.example.com
            

Here is another example of adding S3 site with access key and secrete:

./commander.sh -action addSite --siteId siteS3  --protocol s3
--username s3AccessKey --password s3Secrete
            

listSites Example:

listSites lists all sites in the CrossFTP commander's site repository. The result of listSites has 2 columns: Site ID and Host. Each site will have one row in the result.

./commander.sh -action listSites

editSite Example:

editSite helps to edit an existing site in the CrossFTP commander's site repository. Any option provided on the command line will be used to update the existing site's value. For example, the following example will update siteS3's password in the repository.

./commander.sh -action editSite --siteId siteS3 --password pass

deleteSite examples:

deleteSite helps to delete an existing site in the repository. For example:

./commander.sh -action deleteSite --siteId siteS3

 

copy/move/delete operations

Copy

Copy action helps to copy source file/directory to the target file/directory. Move action is similar to copoy while it will remove the source file/directory after the successful data transfer. Delete action helps to remove source file/directory. The following is the usage for these actions:

usage: commander [--action <copy/move/delete>]
       [--configDir <PATH_TO_CONFIG_DIRECTORY>]
       [--dryRun] [--help] [--siteLocalSite]
[--sourceDir <DirectoryPath>] [--sourceFile <FilePath>]
[--sourceSite <SiteID>] [--targetDir <DirectoryPath>] [--targetFile
<FilePath>] [--targetSite <SiteID>] [--threadNumber <ThreadNumber>]
--action <copy> Input the action type
--configDir <PATH_TO_CONFIG_DIRECTORY> Config home's path
--dryRun Test the input arguments only
but do not run the queue
--help Show the command line usage for an action
--siteLocalSite Use the site-local-site type
transfer to transfer between
incompatible protocols
--sourceDir <DirectoryPath> Full path of the source directory
--sourceFile <FilePath> Full path of the source file
--sourceSite <SiteID> ID name of the source site, or MyComputer for the local computer
--targetDir <DirectoryPath> Full path of the target directory
--targetFile <FilePath> Full path of the target file
--targetSite <SiteID> ID name of the target site,
or MyComputer for the local computer
--threadNumber <ThreadNumber> Number of threads

The following is an example of the copy directory action: we want to copy the local computer's '/Library/Internet Plug-Ins' directory to the site 'site1' directory '/target':

./commander.sh --action copy --sourceSite MyComputer --sourceDir 
/Library/Internet Plug-Ins --targetSite site1 --targetDir /target
            

The following is an example of the copy file action: we want to copy the local computer's /Library/Fonts/Arial.ttf to the site site1's file /backup/Fonts/Arial.ttf.

./commander.sh --action copy --sourceSite MyComputer --sourceFile 
/Library/Fonts/Arial.ttf --targetSite site1 --targetFile /backup/Fonts/Arial.ttf

Move

Move operation helps to move a file/directory from one place to another. After move, the source file will be deleted and put to the target location.

The following is an example of move directory action: we want to move the local computer's '/Library/Internet Plug-Ins' directory to the site 'site1' directory '/target':

./commander.sh --action move --sourceSite MyComputer --sourceDir 
/Library/Internet Plug-Ins --targetSite site1 --targetDir /target
            

The following is an example of the move file action: we want to move the local computer's /Library/Fonts/Arial.ttf to the site site1's file /backup/Fonts/Arial.ttf.

./commander.sh --action move --sourceSite MyComputer --sourceFile 
/Library/Fonts/Arial.ttf --targetSite site1 --targetFile /backup/Fonts/Arial.ttf

delete

Delete option delete a file/directory in the source site. After delete, the file/directory will be DELETED on the site and cannot be recovered.

The following is an example of the delete file action: we want to delete the site site1's file /backup/Fonts/Arial.ttf.

./commander.sh --action delete --sourceSite site1 --sourceFile 
/backup/Fonts/Arial.ttf

The following is an example of the delete directory action: we want to delete the site site1's directory /backup/Fonts.

./commander.sh --action delete --sourceSite site1 --sourceDir 
/backup/Fonts

sync

Sync action helps to do synchronizations between any two directories. It has similar functionality as CrossFTP GUI's directory synchronization. The following is the usage for the sync action.

usage: commander [--action <sync>]
       [--caseSensitive <([true]/false)>]
[--compareContent <(true/[false])>] [--configDir
<PATH_TO_CONFIG_DIRECTORY>] [--deleteUnnessary <(true/[false])>]
[--dryRun] [--excludePattern <exclude pattern(s)>] [--followSymLink
<(true/[false])>] [--help] [--ignoreDate <([true]/false)>]
[--includePattern <include pattern(s)>] [--includeSubDir <([true]/false)>] [--lastModifiedWithin <number of day(s)>]
[--mirrorDir <[L2R]/R2L/Both>] [--overwriteWhenMirror
<([true]/false)>] [--siteLocalSite] [--sourceDir <DirectoryPath>]
[--sourceSite <SiteID>] [--targetDir <DirectoryPath>] [--targetSite
<SiteID>] [--threadNumber <ThreadNumber>]
--action <sync> Input the action type
--caseSensitive <([true]/false)> Whether the path comparison is case sensitive
(true/false), and default value is true
--compareContent <(true/[false])> Use content checksum as criteria when comparing two
files, and default value is false
--configDir <PATH_TO_CONFIG_DIRECTORY> Config home's path
--deleteUnnessary <(true/[false])> Whether to delete the target file if source file is
missing, and default value is false
--dryRun Test the input arguments only but do not run the queue
--excludePattern <exclude pattern(s)> Patterns to exclude in the synchronization. It is a comma-separated list of patterns of files that must be excluded.
--followSymLink <(true/[false])> Whether to follow symbolic link (true/false), and
default value is false
--help Show the command line usage
for an action
--ignoreDate <([true]/false)> Do not use the date as criteria when comparing two files, and default value is
true
--includePattern <include pattern(s)> Patterns to include in the
synchronization. It is a
comma-separated list of patterns of files that must be included.
--includeSubDir <([true]/false)> Include the sub directory
(true/false), and default
value is true
--lastModifiedWithin <number of day(s)> Compare files within the specified time period
--mirrorDir <[L2R]/R2L/Both> L2R (left to right) /R2L (right to left) /Both direction (<->). Default
value is L2R.
--overwriteWhenMirror <([true]/false)> Whether to overwrite the target file if two files are
not same, and default value is true
--siteLocalSite Use the site-local-site type
transfer to transfer between
incompatible protocols
--sourceDir <DirectoryPath> Full path of the source directory
--sourceSite <SiteID> ID name of the source site, or MyComputer for the local
computer
--targetDir <DirectoryPath> Full path of the target directory
--targetSite <SiteID> ID name of the target site, or MyComputer for the local
computer
--threadNumber <ThreadNumber> Number of threads

Here is an simple example to sync the left source directory on local computer to the right target directory.

./commander.sh --action sync --sourceSite MyComputer --sourceDir 
/pathToSourceDir --targetSite site1 --targetDir /parthToTargetDir 
--mirrorDir L2R

If you want to exclude certain sub directories, you need to use --excludePattern flag. To understand the exclude and include patterns in sync, you need to firstly understand the concept of pattern in CrossFTP. Patterns are used for the inclusion and exclusion of files. '*' matches zero or more characters, '?' matches one character.

In general, patterns are considered relative paths, relative to the base directory (your synchronized directory ). Only files found below that base directory are considered. So while a pattern like ../foo.html is possible, it will not match anything when applied since the base directory's parent is never scanned for files.

Examples:

*.html  matches  .html, x.html and FooBar.html, but not FooBar.xml (does not end with .html).

?.html  matches  x.html, A.html, but not .html or xyz.html (both don't have one character before .html).

Combinations of *'s and ?'s are allowed.

Matching is done per-directory. This means that first the first directory in the pattern is matched against the first directory in the path to match. Then the second directory is matched, and so on. For example, when we have the pattern /?abc/*/*.html and the path /xabc/foobar/test.html, the first ?abc is matched with xabc, then * is matched with foobar, and finally *.html is matched with test.html. They all match, so the path matches the pattern.

To make things a bit more flexible, we add one extra feature, which makes it possible to match multiple directory levels. This can be used to match a complete directory tree, or a file anywhere in the directory tree. To do this, ** must be used as the name of a directory. When ** is used as the name of a directory in the pattern, it matches zero or more directories. For example: /test/** matches all files/directories under /test/, such as /test/x.html, or /test/foo/bar/xyz.html, but not /xyz.xml.

There is one "shorthand": if a pattern ends with / or \, then ** is appended. For example, mypackage/test/ is interpreted as if it were mypackage/test/**.

Example patterns:

**/CVS/* Matches all files in CVS directories that can be located anywhere in the directory tree.
Matches:
      CVS/Repository
      org/apache/CVS/Entries
      org/apache/jakarta/tools/ant/CVS/Entries
      
But not:
      org/apache/CVS/foo/bar/Entries (foo/bar/
      part does not match)
      
org/apache/jakarta/** Matches all files in the org/apache/jakarta directory tree.
Matches:
      org/apache/jakarta/tools/ant/docs/index.html
      org/apache/jakarta/test.xml
      
But not:
      org/apache/xyz.java
      
(jakarta/ part is missing).
org/apache/**/CVS/* Matches all files in CVS directories that are located anywhere in the directory tree under org/apache.
Matches:
      org/apache/CVS/Entries
      org/apache/jakarta/tools/ant/CVS/Entries
      
But not:
      org/apache/CVS/foo/bar/Entries
      
(foo/bar/ part does not match)
**/test/** Matches all files that have a test element in their path, including test as a filename.

When these patterns are used in inclusion and exclusion, you have a powerful way to select just the files you want.

  • Include, exclude - the patterns for you to include or exclude in the synchronization. It is a comma-separated list of patterns of files that must be included/excluded. When both inclusion and exclusion are used, only files/directories that match at least one of the include patterns and don't match any of the exclude patterns are used. If no include pattern is given, all files are assumed to match the include pattern (with the possible exception of the default excludes). The default excludes are empty in CrossFTP.

The following is an example to do sync: we want to sync the local computer's '/Library/Internet Plug-Ins' directory to the site 'site1' directory '/target', with mirror direction left to right, delete unnecessary file, and the include file pattern is /pattern1,/pattern2, and the exclude pattern is /pattern3,/pattern4.

./commander.sh --action sync --sourceSite MyComputer --sourceDir 
/Library/Internet Plug-Ins --targetSite site1 --targetDir /target 
--mirrorDir L2R --deleteUnnessary true --includePattern 
/pattern1,/pattern2 
--includePattern /pattern1,/pattern2            

 

encrypt/decrypt

These actions can help to encrypt/decrypt the files that was encrypted in CrossFTP GUI tool when site's local encryption config is toggled. The following is the usage for these actions:

usage: commander [--action <encrypt/decrypt>] [--file <FILE>]
       [--help] [--password <PASSWORD>]
--action <encrypt/decrypt> Input the action type
--file <FILE> Encrytped/decrypted FILE path
--help Show the command line usage for an action
--password <PASSWORD> Input the encryption PASSWORD

The following is an example for the decrypt action: we want to decrypt the file '/file to be decrypted.aes', with password pass.

./commander.sh --action decrypt --file /file to be decrypted.aes 
--password pass

 

registerLicense/releaseLicense

These actions are used to register the license onto the computer, or release the license from the computer. The following is the usage for registerLicense:

usage: commander [--action <registerLicense>] [--help]
       [--licenseCode <LICENSE_CODE>]
--action <registerLicense> Input the action type
--help Show the command line usage for an action
--licenseCode <LICENSE_CODE> Input the license code

Here is the example to register CrossFTP Commander with license code LIC_CODE:

./commander.sh --action registerLicense --licenseCode LIC_CODE

Here is the example to release a license from CrossFTP Commander:

./commander.sh --action releaseLicense

config

The config action is used to manage the global options for the CrossFTP Commander, which includes configurations like Email notification, etc. The following is the usage for this action:

usage: commander [--action <config>] [--configDir
<PATH_TO_CONFIG_DIRECTORY>] [--emailFrom <Email>] [--emailSubject <Subject of Email>] [--emailTo <Email(s)>]
[--enableEmailNotification <true/[false]>] [--help]
[--smptEnableStartTls <true/[false]>] [--smtpEnableUserAuth <true/[false]>] [--smtpHost <host>] [--smtpPassword <password>]
[--smtpPort <port number>] [--smtpUsername <username>]
[--smtpUseTls <true/[false]>]
--action <config> Input the action type
--configDir <PATH_TO_CONFIG_DIRECTORY> Config home's path
--emailFrom <Email> From address for the Email message
--emailSubject <Subject of Email> Subject line for the Email message
--emailTo <Email(s)> To address(es) for the Email message
--enableEmailNotification <true/[false]> Enable the Email
notification or not
--help Show the command line usage for an action
--smptEnableStartTls <true/[false]> Enable the STARTTLS for SMTP
--smtpEnableUserAuth <true/[false]> Enable the user
authentication for SMTP
--smtpHost <host> SMTP server's host
--smtpPassword <password> SMTP server's
authentication password
--smtpPort <port number> SMTP server's port number
--smtpUsername <username> SMTP server's
authentication username
--smtpUseTls <true/[false]> SMTP server use TLS/SSL over transfer protocol

The following is an example for the config action: we want to enable the Email notification in CrossFTP Commander, with Email from 'userfrom@gmail.com', Email to 'userto1@gmail.com,userto2@gmail.com', Email subject 'Test email subject', SMTP host 'www.smtphost.com', SMTP port 25, SMTP username user, SMTP password pass:

./commander.sh --action config --enableEmailNotification true 
--emailFrom userfrom@gmail.com --emailTo 
userto1@gmail.com,userto2@gmail.com 
--emailSubject Test email subject --smtpHost www.smtphost.com 
--smtpPort 25 --smtpEnableUserAuth true --smtpUsername user 
--smtpPassword pass     

 

Monitoring and Debug

CrossFTP Commander provides logs, error status/message, and notifications to allow you to monitor and debug the data processing of CrossFTP.

  • Logs

The log file for the transfers are available in the CrossFTP_CONFIG_HOME's log* files. You can check these files to identify potential issues. To modify the log settings, you can modify the logging.prop file in CrossFTP config home directory. You can specify the location of CrossFTP's config home through configDir parameter, or it is displayed when CrossFTP Commander runs.

  • Error status/message

Normally CrossFTP Commander exits with 0 status code, which means the item queue's execution is successfully. When there is some item failed to be transferred during the session, CrossFTP Commander will exit with -1 status code, and print out the items which met error during the execution. The format of the output item is a CSV line defined here.

  • Notifications

If enable Email notification is set as true, CrossFTP Commander will send out Email notifications when the CrossFTP Commander session finishes. The detail content of the Email notification is available here.

 

Awards & Reviews