# CrossFTP Commander

**CrossFTP Commander** is a command-line tool based on the CrossFTP engine for data transfer, sync, and related operations. It can also help with [file and database backup and scheduling](https://www.crossftp.com/commander-backup.htm). It has a small memory footprint (core library size is about 4MB) and can be integrated in shell scripts or a system scheduler. Supported protocols include FTP, SFTP, FTPS, WebDav, Amazon S3, and Google Storage.

CrossFTP Commander is a component of CrossFTP Enterprise. With a CrossFTP Enterprise license on your machine, you can choose to run either the GUI or Commander. For AI clients (Cursor and other MCP hosts), see [CrossFTP Commander MCP](mcp.md).

**On this page:** [Site and Site ID](#site-and-site-id) · [Site management](#addsiteListsitesEditsiteDeletesite) · [copy/move/delete](#copymovedelete-operations) · [sync](#sync) · [encrypt/decrypt](#encryptdecrypt) · [License](#registerLicensereleaseLicense) · [config](#config) · [Monitoring](#monitoring-and-debug)

---

## Site and Site ID

Each site defines the FTP/cloud protocol and host information. Each site has a unique ID; Commander uses that ID to reference and connect to the site.

CrossFTP GUI and CrossFTP Commander share the same site repository, so you can create or look up sites in either application.

Use `--configDir` with an **absolute** path to your CrossFTP config home (bookmarks, license, logs). Commander does not expand `~`. If you set a custom bookmark master password in Site Manager, set the environment variable `CROSSFTP_BOOKMARKS_MASTER_PASSWORD` before running Commander; otherwise site and transfer actions fail with a clear error (no GUI password prompt).

### Create a site

Create a site in CrossFTP (*Sites → Site Manager*), or use the [addSite](#addsiteListsitesEditsiteDeletesite) command.

### Get site ID

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

1. **From CrossFTP GUI:** *Sites → Site Manager*, select the site, then choose **Copy Site ID** from the popup menu.
2. **From Commander:** use `listSites` (see below).

### addSite/listSites/editSite/deleteSite

Manage sites used for data handling. You can create sites in the GUI or with Commander.

```text
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)
```

Protocol values: `ftp`, `ftps_ssl_implicit`, `ftps_ssl`, `ftps`, `sftp`, `webdav_http`, `webdav`, `s3_http`, `s3`, `gs_http`, `gs`, `glacier_http`, `glacier`.

#### addSite example

Add a site named `site1`, username `username`, password `pass`, protocol FTP, host `www.example.com`:

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

Add an S3 site with access key and secret:

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

#### listSites example

Lists all sites. Output has two columns: Site ID and Host.

```bash
./commander.sh --action listSites
```

#### editSite example

Any option on the command line updates that field on the existing site. Example — update `siteS3` password:

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

#### deleteSite example

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

---

## copy/move/delete operations

**Copy** copies a source file/directory to a target. **Move** is like copy but removes the source after a successful transfer. **Delete** removes a source file/directory.

```text
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                               Validate arguments and
                                           build the transfer
                                           request without
                                           enqueue or transfer
    --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
```

### Copy examples

Copy local directory `/Library/Internet Plug-Ins` to site `site1` directory `/target`:

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

Copy local file `/Library/Fonts/Arial.ttf` to site `site1` as `/backup/Fonts/Arial.ttf`:

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

### Move examples

Move local directory to remote:

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

Move local file to remote:

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

### Delete examples

Delete removes the path on the source site and cannot be recovered.

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

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

---

## sync

Sync synchronizes two directories (same idea as CrossFTP GUI directory synchronization).

```text
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                                Validate arguments
                                            and run a GUI-
                                            equivalent sync
                                            compare preview
                                            (prints planned
                                            upload/download/
                                            delete/mkdir
                                            actions); does not
                                            enqueue or transfer
    --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
```

Simple left-to-right sync:

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

### Include / exclude patterns

Patterns select files relative to the synchronized base directory. `*` matches zero or more characters; `?` matches one character. `**` as a directory name matches zero or more directories. A pattern ending with `/` or `\` is treated as if `**` were appended.

| Pattern | Matches |
|---------|---------|
| `**/CVS/*` | Files in any `CVS` directory (e.g. `CVS/Repository`, `org/apache/CVS/Entries`) |
| `org/apache/jakarta/**` | Everything under `org/apache/jakarta/` |
| `org/apache/**/CVS/*` | `CVS` files under `org/apache` |
| `**/test/**` | Paths that contain a `test` segment |

When both include and exclude are set, a path must match at least one include and no exclude. If no include is given, all files match the include (default excludes are empty in CrossFTP).

Example with include/exclude and delete-unnecessary:

```bash
./commander.sh --action sync --sourceSite MyComputer --sourceDir \
  "/Library/Internet Plug-Ins" --targetSite site1 --targetDir /target \
  --mirrorDir L2R --deleteUnnessary true --includePattern \
  /pattern1,/pattern2 --excludePattern /pattern3,/pattern4
```

Dry-run sync preview (no transfer):

```bash
./commander.sh --dryRun --action sync --sourceSite MyComputer \
  --sourceDir /pathToSourceDir --targetSite site1 --targetDir \
  /pathToTargetDir --mirrorDir L2R
```

---

## encrypt/decrypt

Encrypt or decrypt files that were encrypted when a site's local encryption config is enabled in the GUI.

```text
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
```

```bash
./commander.sh --action decrypt --file "/file to be decrypted.aes" \
  --password pass
```

---

## registerLicense/releaseLicense

Register a license on the computer, or release it.

```text
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
```

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

```bash
./commander.sh --action releaseLicense
```

---

## config

Manage global Commander options such as email notification.

```text
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
```

```bash
./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

### Logs

Transfer logs are under the CrossFTP config home (`log*` files). Adjust logging via `logging.prop` in that directory. Config home is set with `--configDir`, or printed when Commander runs.

### Error status / message

Commander exits with status `0` when the queue completes successfully. If any item fails, it exits with `-1` and prints failed items as CSV lines (see [email notification notes](http://crossftp.blogspot.com/2014/06/email-notification-support-in-crossftp.html)).

### Notifications

If email notification is enabled, Commander sends email when the session finishes. Details are described in the same blog post linked above.
