Command Line Interface (CLI) App

---

The Files.com Command Line Interface (CLI) App is a great option for scripted or automated transfers between a local machine and Files.com.

Because it works through the standard Command Line, the CLI app is easy to script from a variety of environments without having to use our SDKs. With that said, if you are already using a programming language where we offer an SDK, the SDK may offer a higher level of integration for your application.

The CLI App is cross-platform (Windows/macOS/Linux) and supports fast, concurrent file transfers.

The CLI App uses the Files.com RESTful APIs via the HTTPS protocol (port 443) to securely communicate and transfer files so, when used interactively or from a script, no firewall changes should be required in order to allow connectivity.

The CLI App also includes the Files.com Agent. The Agent uses an inbound port, 58550 by default, to receive transmissions from the Files.com platform, so firewall changes are required when using the Agent.

The CLI supports all file Operations including list, download, upload, move, rename, delete, etc. But equally important is that it supports operations on every resource available in Files.com including Users, Permissions, Groups, Remote Servers, Behaviors, etc.

Example code for how to use the CLI with any resource can be found in the Files.com Developer Documentation. Click CLI in the top right to enable CLI example code.

Click here to download the CLI App.

On that page, you'll need to pick your exact operating system to download the correct version.

No installation is necessary. The app is a self contained app which can be stored anywhere on your computer.

The CLI Application supports logging into the system with your username and password (and two-factor authentication, if enabled) or by providing your API key.

To log in to the CLI App with your username and password, you must first configure the CLI App with information about your Files.com account:

files-cli config set --subdomain="MYCOMPANY" --username="MYUSERNAME"

When prompted, enter your password.

Once you've specified your subdomain information and username, you do not need to specify it again for subsequent uses of the CLI App. For later uses, you can login using the following command, which will prompt you for your password:

files-cli login

If your account requires Two-Factor Authentication, you will be prompted for the second factor after you submit your password. Once you are logged in, subsequent uses of the CLI App will perform those actions using your credentials and permissions until you log out.

When using an API Key with the CLI App, supply the API Key information on the command line using the --api-key option:

files-cli --api-key="YOUR_API_KEY" folders list-for

Using an API Key to authenticate will not trigger a Two-Factor Authentication challenge, even if you normally require one to log into the web interface.

Your login session will expire automatically after a period of time. The CLI App will expire your session after 6 hours or your session will expire based on the settings of your authentication system, whichever is sooner.

To log out of your session manually, use:

files-cli logout

The Command Line Interface (CLI) App allows you to access multiple Files.com accounts by specifying a different profile for each account.

To set up profiles for your Files.com accounts, use the following commands:

files-cli config set --subdomain="MYFIRSTCOMPANY" --username="FIRSTUSERNAME" --profile="firstaccount"
files-cli config set --subdomain="MYSECONDCOMPANY" --username="SECONDUSERNAME" --profile="secondaccount"

To execute commands for a specific account, use the --profile option in your command. For example:

files-cli folders list-for /path/to/folder/in/account1/ --profile="firstaccount"
files-cli folders list-for /path/to/folder/in/account2/ --profile="secondaccount"

You can also configure API Keys for profiles:

files-cli config set --api-key="API_KEY_ONE" --profile="firstaccount"
files-cli config set --api-key="API_KEY_TWO" --profile="secondaccount"

If the --profile option is not specified then all configuration and operations will use your default profile setting.

You can view the account profiles that have been configured by using this command:

files-cli config show

For help with the CLI App, you can use the --help option to access more information about how to use the CLI App and its various functions.

For example, to see the list of available commands:

files-cli --help

You can access help about a particular command by appending the --help option to the command. For example, to find out more about the folders command, use:

files-cli folders --help

To list the contents of a folder in your Files.com account, use the command:

files-cli folders ls /path/to/folder

To upload a single file, use the command:

files-cli upload /local/path/to/file.txt /remote/path/to/file.txt

or

files-cli upload /local/path/to/file.txt /remote/path/to/folder/

To upload a single folder, use the command:

files-cli upload /local/path/to/folder/ /remote/path/to/folder/

You can also upload multiple files and folders by using wildcard characters to specify the files or folders that should be targeted for the upload action.

To upload multiple files, use the command:

files-cli upload *.txt /remote/path/to/folder/

or

files-cli upload /path/to/*/subfolder/*.txt /remote/path/to/folder/

To upload the contents of multiple folders into a single destination folder use the command:

files-cli upload /local/path/to/*/ /remote/path/to/folder/

or

files-cli upload */ /remote/path/to/folder/

or

files-cli upload /path/to/first/folder/ /path/to/second/folder/ /path/to/third/folder/ /remote/path/to/folder/

Wildcards cannot be used to upload or download into multiple destination folders. The contents of the source folders will be merged into the destination folder whenever wildcards are used.

For example, let's say you have three source folders, named C:\Source\FolderOne, D:\Source\FolderTwo, and E:\AnotherSource\FolderThree. You want to upload these folders to Files.com into a folder named Destination, so that you end up with destination folders named Destination/FolderOne, Destination/FolderTwo and Destination/FolderThree.

Using a wildcard isn't possible as the contents of the source folders will be merged into the destination folder.

Instead, you need to perform a separate upload, or download, for each destination like this:

files-cli upload C:\Source\FolderOne Destination\FolderOne
files-cli upload D:\Source\FolderTwo Destination\FolderTwo
files-cli upload E:\AnotherSource\FolderThree Destination\FolderThree

To download a file, use the command:

files-cli download /remote/path/to/file.txt /local/path/to/file.txt

or

files-cli download /remote/path/to/file.txt /local/path/to/folder/

To download a folder, use the command:

files-cli download /remote/path/to/folder/ /local/path/to/folder/

The download operation will attempt to download each file as quickly as possible by breaking the file into multiple pieces, or chunks, and transferring those chunks in parallel.

Although chunking speeds up file transfers, some remote systems are unable to support this capability, causing failed or partial transfers.

If you have problems downloading files from a Files.com folder which is stored on a Remote Server Mount, you can disable file chunking by using the --download-files-as-single-stream flag.

files-cli download /remote/path/to/folder/ /local/path/to/folder/ --download-files-as-single-stream

The --download-files-as-single-stream flag will cause the download to be slower but more resilient for downloads from a Remote Server Mount folder.

You can see the connection information, showing the number of open data connections, the number of open API connections, and the network throughput, by using the --connection-metrics flag.

files-cli upload /local/path/to/folder/ /remote/path/to/folder/ --connection-metrics
files-cli download /remote/path/to/folder/ /local/path/to/folder/ --connection-metrics

To create folders, use this command:

files-cli folders create --path=“/path/to/folder/to/be/created”

If you are running scripted operations, you can have the CLI send a report of the operation including the Success/Failure status as well as a log of every run. To do this add the flag --send-logs-to-cloud.

To view the operation logs in the web interface, type "External logs" in the search box at the top of every page and then click on the matching result.

To facilitate file-syncing workflows, the sync operation can be used.

This sync uses rules very similar to Files.com's Remote Server sync feature, using only filename and size to determine whether a file needs to be synced. It does not currently use information such as modified date or checksum for this purpose. Due to the wide variety of remote server types supported (and our plans to support hundreds more via an open integration platform coming soon), this is the only methodology we've been able to design that works 100% consistently across all files on Files.com, including files that may potentially be stored on a remote server.

Here is a push (upload) example for syncing files from a local Documents folder to a Files.com folder of the same name:

files-cli sync push --local-path="Documents" --remote-path="Documents" --send-logs-to-cloud

Here is a pull (download) example for syncing files to a local Documents folder from a Files.com folder of the same name:

files-cli sync pull --remote-path="Documents" --local-path="Documents" --send-logs-to-cloud

The sync operation also provides some useful options.

To configure the sync so that the source file will be deleted after it has been successfully transferred to its destination, use the --delete-source flag.

files-cli sync pull --remote-path="path/to/source/folder" --local-path="path/to/local/destination/folder" --send-logs-to-cloud --delete-source

You can configure the sync so that the source file will be moved after it has been successfully transferred to its destination, using the --move-source flag. The move will occur in the source location.

For a sync push, the source location for the move will be the local system where you are running the files-cli:

files-cli sync push --local-path="path/to/local/source/folder" --remote-path="path/to/destination/folder" --move-source="path/to/local/archive/folder" --send-logs-to-cloud

For a sync pull, the source location for the move will be the Files.com platform:

files-cli sync pull --remote-path="path/to/source/folder" --local-path="path/to/local/destination/folder" --move-source="path/to/archive/folder" --send-logs-to-cloud

You can configure the sync to ignore certain files or folders using the --ignore flag. Place the file and folder name patterns to be ignored into a comma separated string:

files-cli sync push --local-path="path/to/local/source/folder" --remote-path="path/to/destination/folder" --ignore='*.exe,*.msi,Archive/,secret/' --send-logs-to-cloud

You can configure the sync to include only specified files or folders patterns using the --include flag. Place the file and folder name patterns to be included into a comma separated string:

files-cli sync push --local-path="path/to/local/source/folder" --remote-path="path/to/destination/folder" --include='*.txt,*.pdf' --send-logs-to-cloud

Files that are uploaded or downloaded, including those that were transferred using a sync operation, typically gain an updated timestamp when they arrive at their destination, reflecting the date and time of when the file arrived on the destination system.

You can preserve the original timestamp by using the --times flag. When using the --times flag, the files will arrive at their destination with the same timestamp as they possessed at their source location. This is useful when archiving, or backing up, data so that you can determine if a file at the source location has been modified or updated when compared to the copy at the destination location.

files-cli sync pull --local-path="Documents" --remote-path="Documents" --send-logs-to-cloud --times

Before attempting a sync operation, you might want to observe the actions that will be taken without any actual data being transferred. The --dry-run flag can be used to show you which files would have been affected by the operation.

files-cli sync pull --local-path="Documents" --remote-path="Documents" --send-logs-to-cloud --times --dry-run

The upload, download, and sync operations will attempt to transfer multiple files in parallel. Up to 75 files at a time will be attempted.

Your local operating system, local file system, or local network file system, may have different limits for the number of files that can be opened or transferred concurrently. To decrease or increase the number of concurrent files for the operation, use the --concurrent-connection-limit flag.

files-cli sync push --local-path="Documents" --remote-path="Documents" --send-logs-to-cloud --times --concurrent-connection-limit=3

The upload, download, and sync operations will automatically attempt to retry each file transfer two more times, for a total of three attempts.

The CLI App is capable of automatically resuming a transfer from the interruption point, but this also depends on the capabilities of the both sides of the transfer.

If the source or destination is a Remote Server Mount then that type of Remote Server may not support resuming from the interruption point. If the Remote Server doesn't support it then the CLI will be forced to restart a file transfer from the beginning. The CLI App will always attempt to resume from the interruption point, then fall back to restarting from the beginning of the file if the resume fails.

Generally speaking, Remote Server Mounts to modern cloud object storage solutions, such as Amazon S3, Azure Blob, and Google Cloud Storage, should support resuming from the interrupt point. Remote Server Mounts to legacy solutions, such as FTP, SFTP, WebDAV, and Sharepoint, will most likely not support resuming from the interrupt point and will force the CLI to restart from the beginning of the file.

If you are using a local network attached file system, where the network connection to the file storage might not be fully stable, you can configure a higher number of retries using the --retry-count flag.

files-cli sync push --local-path="M:\NetworkShare1\Documents" --remote-path="Documents" --send-logs-to-cloud --times --retry-count=10

If you have administrator privileges for your Files.com account, you can use the CLI App to perform administrator actions.

For example, you can create a user account with this command:

files-cli users create --username="amy" --password="S0meRea11yLongP@ssw0rd" --authentication-method="password" --name="Amy Anybody" --company="Amy’s Company Name" --notes="Some notes about Amy." --user-root="/users/amy"

You can also configure various items, such as Folder Settings, using the CLI App.

For example, you can configure automatic new user folders using the following command:

files-cli behaviors create --path="/path/to/folder" --behavior="create_user_folders" --value='{ "permission":"full", "additional_permission":"bundle", "existing_users":false, "group_id":1, "new_folder_name":"username", "subfolders":[]}'

As an administrator, you can manage user accounts within your Files.com site using the CLI App.

files-cli users list

files-cli users list --ids="1111,2222,3333"

files-cli users create --username="amy" --password="S0meRea11yLongP@ssw0rd" --authentication-method="password" --name="Amy Anybody" --company="Amy’s Company Name" --notes="Some notes about Amy." --user-root="/users/amy"

files-cli users update --id=12345 --password="NewP@ssw0rd" --email="my_new_email@company.com"

files-cli users update --id=12345 --disabled=true

files-cli users update --id=12345 --disabled=false

files-cli users delete --id=12345

As an administrator, you can manage the Groups within your Files.com site using the CLI App.

files-cli groups list

files-cli groups list --ids="1111,2222,3333"

files-cli groups create --name="External Partners" --notes="Some notes about this group."

files-cli groups update --id=1111 --name="Updated Group Name" --notes="Updated notes about this group."

files-cli groups delete --id=1111

files-cli group-users create --group-id=1111 --user-id=12345

files-cli group-users delete --id=1111 --group-id=1111 --user-id=12345

By default, the CLI App will output its data in table format.

You can configure the output format by using the --format option. For example, to specify that the output should be formatted in JSON format, use the option --format json.

Available output formats are:

• table
• table-dark
• table-bright
• json
• csv

Here are some examples:

files-cli folders list-for /path/to/folder --format=csv

files-cli folders create --path="/path/to/folder/to/be/created" --format=json

files-cli users list --format=table-dark

If an error occurs during an operation, the CLI app will exit with a non-zero status and then output JSON format of the error to STDOUT. You can use this in scripts to detect certain errors and respond accordingly.

You can save the output of the operation to a file by using the --output flag. This is useful for saving a log of the actions taken by the operation.

files-cli upload /local/path/to/folder/ /remote/path/to/folder/ --output="log.txt"

You can also format the output by using the --output-format flag and specifying either text, csv, or json as the format type. The default format type is csv.

files-cli upload /local/path/to/folder/ /remote/path/to/folder/ --output="log.txt "--output-format=text

When communicating with our Support team, you may be asked to provide a debug log to assist with troubleshooting. You can use the --debug flag to generate a debug log.

files-cli upload /local/path/to/folder/ /remote/path/to/folder/ --debug="debuglog.txt"