The Files.com CLI App provides convenient access to the Files.com API.
Download the latest release for Windows, macOS, or Linux from the CLI App Releases page.
For systems with Homebrew available, use the following commands:
brew tap Files-com/homebrew-tap
brew install files-cli
For Linux systems that support RPM, such as Red Hat Linux, Fedora Linux, CentOS, openSUSE, Oracle Linux, and others, use the RPM Package Manager to install the CLI App:
curl -L https://github.com/Files-com/files-cli/releases/latest/download/files-cli_linux_{ARCH}.rpm -o files-cli.rpm
sudo rpm -i ./files-cli.rpm
For Debian based systems, such as Ubuntu Linux, use the APT-based Package Manager to install the CLI App:
curl -L https://github.com/Files-com/files-cli/releases/latest/download/files-cli_linux_{ARCH}.apk -o files-cli.apk
sudo rpm -i ./files-cli.apk
Download
Download the Zip archive (*.zip
), extract the files from the archive, and place the files-cli.exe
binary file into any directory listed in your %PATH%
environment variable.
Download the compressed Tar archive (*.tar.gz
), extract the files from the archive, and place the files-cli
binary file into any directory listed in your $PATH
environment variable.
curl -L https://github.com/Files-com/files-cli/releases/latest/download/files-cli_macOS_64bit.tar.gz | tar zxv
sudo mv ./files-cli /usr/local/bin
export FILES_API_KEY="XXXX-XXXX..."
set FILES_API_KEY="XXXX-XXXX..."
files-cli folders list-for --api-key "XXXX-XXXX..."
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.
The CLI App allows you to access multiple Files.com accounts by using different profiles 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 settings.
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
Return root folder listing
files-cli folders list-for --fields path,type --format json
[{
"path": "document.docx",
"type": "file"
},
{
"path": "other",
"type": "directory"
}]
List a Folder
files-cli folders list-for /path/to/folder
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/
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/
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
.
The operation logs will be made available in the web interface at Settings > Logs > External logs.
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.
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
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":[]}'
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 (default)
- table,interactive (searchable and scrollable)
- table,dark
- table,bright
- table,light,{horizontal/vertical}
- table,markdown
- json (human-readable)
- json,raw (machine-readable)
- csv
Here are some examples:
files-cli users list --format="table,interactive"
files-cli folders list-for /path/to/folder --format csv
files-cli folders create --path “/path/to/folder/to/be/created” --format="json,raw"
files-cli users list --format="table,dark"
Set as default for profile
files-cli config set --format="table,interactive"
files-cli [command] --help
To build for testing it assumes the go package is in parallel directory.
DEVELOPMENT_BUILD ./build.sh
This will build both the compressed release version and an uncompressed executable for the 3 platforms.