Authentication and Profiles

Authenticate with a username and password, including two-factor authentication when required, or with an API key. Profiles keep the connection settings for different users and sites separate, so the same machine can run commands against more than one account.

Password Authentication

The CLI App will prompt you for your site name, username and password when you use it. These will be remembered until you logout or your session expires.

To pre-configure the CLI App with a specific username and password, you can provide the CLI App with information about your Files.com account:

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

When prompted, enter your password.

If your site has a Custom Domain configured and you want to connect to it rather than the files.com subdomain, specify the fully qualified domain name (FQDN) with the --endpoint flag:

files-cli config set --endpoint="https://files.mycompany.com" --username="MYUSERNAME"

Once you've specified your subdomain or endpoint 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 on the command line with 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.

A user API key identifies a user; a site-wide API key does not. This matters when a command assigns ownership. For a GPG key import, --user-id=0 selects the authenticated user with a user session or user API key. With a site-wide API key, supply the owner's user ID explicitly.

Logging Out

Your login session expires automatically after 6 hours, or sooner if your authentication system's settings dictate a shorter timeout.

To manually log out of your session, use:

files-cli logout

Profiles

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

This is useful when you need to access multiple accounts within a single Files.com site or when you have accounts across multiple Files.com sites, such as a Production site, Test site, and Child site.

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"

When you omit the --profile option, configuration and operations use your default profile.

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

files-cli config show

Updating Profiles

Use config set to update a profile. Use config reset with a field flag to clear that field instead; for example, files-cli config reset --api-key --profile="firstaccount" clears the saved API key for that profile.

For example, you can update the settings of a named profile using the following command:

files-cli config set --subdomain="UPDATED_SITE_NAME" --username="UPDATED_USERNAME" --api-key="UPDATED_API_KEY" --profile="firstaccount"

Profile Configuration File

The CLI App stores its configuration within a hidden file on your local system.

The file is located at %HOME%\.config\files-cli on Windows based systems and at $HOME/.config/files-cli on Linux and Mac based systems.

Do not edit this file directly unless directed to by our Support team.

You can factory-reset the CLI App to a blank starting state by deleting, renaming, or moving this configuration file.