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 no firewall changes should be required in order to allow connectivity.

Downloading and Installing

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.

Support For All Operations, Not Just File Operations

Of course the CLI supports 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.

Authenticating and Logging In

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.

Password Authentication

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.

API Key Authentication

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.

Logging Out

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

CLI App Help

For help with the CLI App, you can use the help or --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 or --help option to the command. For example, to find out more about the folders command, use:

files-cli folders help

Listing folders

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

files-cli folders ls /path/to/folder

Uploading files and folders

To upload a 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 folder, use the command:

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

Downloading files and folders

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/

Creating folders

To create folders, use this command:

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

Sending Operation/Run Logs to the Cloud

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.

The operation logs will be made available in the web interface at Settings > Logs > External logs.

Syncing Files

To facilitate file-syncing workflows, the --sync flag can be used with the upload or download command to specify that only new files be transferred.

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 upload Documents Documents --sync --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 download Documents Documents --sync --send-logs-to-cloud

Administrator actions

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":[]}'

Formatting the output

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

Detecting and Handling Errors

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.

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

©2022 Files.com. All right reserved

FILES.COM

  • Start My Free Trial
  • Pricing
  • Docs
  • API and SDKs
  • Contact

CONTACT & SUPPORT

support@files.com

(800) 286-8372

Monday–Friday

9am–8pm Eastern