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"
Get Instant Access to Files.com
The button below will take you to our Free Trial signup page. Click on the white "Start My Free Trial" button, then fill out the short form on the next page. Your account will be activated instantly. You can dive in and start yourself or let us help. The choice is yours.
Start My Free Trial