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