Filen CLI Filen Cloud Dienste UG

Filen CLI

The Filen CLI provides a set of useful tools for interacting with the cloud:

• Accessing your Filen Drive in a stateless environment or interactive mode
• Syncing locations with the cloud (just like the Desktop app)
• Mounting a network drive
• Running a WebDAV mirror server of your personal drive, or multiple drives in proxy mode
• Running an S3 mirror server

> [!Note] > Please report bugs on our issues page!
> Feature requests can be submitted on features.filen.io.

Installation and updates

You can download the latest binaries from the release page, or execute the install script (Linux and macOS):

curl -sL https://filen.io/cli.sh | bash

Docker images are also available as filen/cli (see below).

The Filen CLI includes an automatic updater that checks for a new release every time the CLI is invoked (after checking for updates, it will not check again for the next 10 minutes). Invoke the CLI with the --skip-update flag to skip checking for updates, or use the --force-update flag to check for updates even if it was recently checked. Use the --auto-update flag to skip the confirmation prompt and update automatically (the CLI will still abort after updating).

You can always install any version using filen install , filen install latest or filen install canary.

The CLI is also available as an NPM package, which can be installed with npm install --global @filen/cli and then invoked as filen. The NPM repository always contains the latest canary releases (see below).

Canary releases

If you want to be among the first to try out new features and fixes, you can enable canary releases, which are early releases meant for a subset of users to test before they are declared as stable. To enable or disable canary releases, invoke the CLI with the command filen canary.

Usage

$ filen [options...]

Options:

• --help, -h: display usage information
• --verbose, -v: display additional information
• --quiet, -q: hide things like progress bars and additional logs
• --email and --password (optionally --two-factor-code , -c ): specify credentials
• --log-file : write logs to a file

Authenticating

There are several ways to authenticate:

• Invoke the CLI and specify your Filen email and password. You'll have the option to save them in a local encrypted configuration file, which you can delete later using filen logout.
• Invoke the CLI with the --email and --password (optionally --two-factor-code) arguments set.
• Put your credentials in the FILEN_EMAIL and FILEN_PASSWORD (optionally FILEN_2FA_CODE) environment variables.
• Store your Filen email and password in a file named .filen-cli-credentials where you invoke the CLI. Put your email and password in separate lines, in plain text (optionally 2FA code in third line).
• Export an "auth config" (which includes your Filen email, password and other details) using filen export-auth-config. This will produce a file named .filen-cli-auth-config, which the CLI will detect when placed in the data directory or the current working directory. This option can be useful especially for clustered WebDAV/S3 servers, where otherwise too many login requests result in rate limiting.

If you have 2FA enabled and don't specify a 2FA code, you will be prompted for it.

Data directory

The data directory is where configuration files, credentials, cache etc. are stored and read from. By default, it is %APPDATA%/filen-cli (Windows), ~/Library/Application Support/filen-cli (macOS) or $XDG_CONFIG_HOME/filen-cli or ~/.config/filen-cli (Unix). If there is a directory named .filen-cli at the home directory ~, it is used instead (for instance, the install script installs to this location). You can overwrite the location using the --data-dir flag or the FILEN_CLI_DATA_DIR environment variable.

Access your Filen Drive

$ filen [options...] 

Options:

• --root , -r : list items inside a directory (pass -l for more detailed output)
• cat : print content of a text file
• head / tail : print first / last 10 lines of a text file (pass -n 3 for only 3 lines etc.)
• mkdir : create a directory
• rm : delete a file or directory (--no-trash to delete permanently)
• stat : display information about a file or directory
• statfs: display information about your Filen cloud drive
• whoami: print the current user
• mv / cp : move or copy a file to a path (parent directory or file)

There are also non-standard commands specific to Filen:

• download : download a file or directory from the cloud into a local destination
• upload : upload a local file into the cloud at a specified path
• write : write text to a file
• open : open a file locally in the associated application
• edit : edit a file locally in the associated application (save and close to re-upload)
• view : view a directory in the Web Drive (you can also invoke filen drive to quickly open the Web Drive)
• favorites / recents: display favorites or recents
• favorite / unfavorite : favorite or unfavorite a file or directory

Interactive mode

Invoke the Filen CLI without any specified commands to enter interactive mode. There you can specify paths as absolute (starting with /) or relative to the current working directory (supports . and ..).

Additional available commands:

• help: display available commands
• cd : navigate to a different path
• ls: list items inside current directory
• exit: exit interactive mode

Trash

• filen trash: view trash items
• filen trash restore: restore a trash item
• filen trash delete: permanently delete a trash item
• filen trash empty: permanently delete all trash items

Public Links

• filen links: view all public links
• filen links : create, view, edit or delete a public link for the given path

Exporting notes

• filen export-notes : Exports all Notes to the specified path. If the specified directory doesn't exist, it will be created. If it is not empty, a subdirectory will be created with the name "filen-notes-export-". Richtext notes are exported as HTML. Checklist notes are converted to markdown.

Syncing

$ filen sync [sync pairs...] [--continuous]

Invoke filen sync to sync any locations with your Filen Drive. This is the same functionality you get with the Desktop app.

You must specify the sync pairs ([sync pairs...] above) as follows:

• (central registry) filen sync: Read the sync pairs from syncPairs.json (inside the data dir). This file must contain JSON of the type¹ {local: string, remote: string, syncMode: string, alias?: string, disableLocalTrash?: boolean, ignore?: string[], excludeDotFiles?: boolean}[]. syncMode can be twoWay, localToCloud, localBackup, cloudToLocal or cloudBackup (see here on what that means). Note that since this is a JSON file, backslashes (\) in strings need to be escaped, e. g. "C:\\some\\path").
• (custom registry) filen sync : Read the sync pairs from a custom JSON file (same type as above).
• (aliases) filen sync mypair myotherpair: Sync the sync pairs from the central registry that were given the aliases mypair and myotherpair.
• (literal pair) filen sync /local/path:twoWay:/cloud/path: Sync the local path /local/path with the cloud path /cloud/path in two-way sync.
• (shorthand for two-way pairs) filen sync /local:/cloud: Sync /local with /cloud in two-way sync.
• (other sync modes and abbreviations) filen sync /local1:localToCloud:/cloud1 /local2:ltc:/cloud2: Sync /local1 with /cloud1 (and /local2 with /cloud2) in local-to-cloud sync (other abbreviations are tw = twoWay, ltc = localToCloud, lb = localBackup, ctl = cloudToLocal, cb = cloudBackup).
• (disable local trash) filen sync /local:/cloud --disable-local-trash: Disable local trash

You can set the --continuous flag to keep syncing (instead of only syncing once).

Network drive mounting

$ filen mount [mount point]

Invoke filen mount to mount a network drive that mirrors your Filen Drive. The default mount point is X: (Windows) / /tmp/filen (UNIX).

On Windows, WinFSP needs to be installed. On Linux, FUSE3 needs to be installed. On macOS, FUSE-T or macFUSE needs to be installed.

For more information, see also FilenCloudDienste/filen-network-drive.

WebDAV server

You can use the Filen CLI to start a WebDAV server that acts as a mirror server of your Filen Drive.

For more information, see also FilenCloudDienste/filen-webdav.

Single user

$ filen webdav --w-user <...> --w-password <...> [options...]

Invoke filen webdav to start a local WebDAV server that mirrors your personal Filen Drive. This might be useful for allowing local applications to access your Filen Drive via WebDAV.

You must specify login credentials for connecting to the server using the --w-user and --w-password options (these credentials should be different from your Filen account credentials).

Options:

• --w-https: run the server on HTTPS instead of HTTP (using a self-signed certificate)
• --w-hostname: which hostname the server should be started on (default is 0.0.0.0)
• --w-port: which port the server should be started on (default is 80 or 443)
• --w-auth-scheme: the authentication scheme the server should use, "basic" or "digest" (default is basic)
• --w-threads: enables clustering, number of threads to use for the server (default is no clustering; explicitly set to 0 to set by CPU core count). If you experience rate-limiting using this, using an auth config might help.

Proxy mode

$ filen webdav-proxy [options...]

Invoke the filen webdav-proxy to start a WebDAV server that allows any user to connect using their Filen account credentials and access their own Filen Drive. This might be useful when hosting a proxy server for multiple users. Digest auth is not available for proxy mode.

Important: In proxy mode, the password has to be formatted as password=yoursecretpassword&twoFactorAuthentication= (you can also leave out the &twoFactorAuthentication=... part if 2FA is disabled for your account).

Options: --w-https, --w-hostname, --w-port, --w-threads as above

S3 server

$ filen s3 --s3-access-key-id <...> --s3-secret-access-key <...> [options...]

Invoke filen s3 to start an S3 server that acts as a mirror server of your Filen Drive. You must specify credentials (Access Key ID and Secret Access Key) for connecting to the server using the --s3-access-key-id and --s3-secret-access-key options (these credentials should be different from your Filen account credentials).

Important: When connecting to the S3 server, you need to enable s3ForcePathStyle and set the region to filen.

For more information, including on S3 compatibility, see also FilenCloudDienste/filen-s3.

Options:

• --s3-https: run the server on HTTPS instead of HTTP (using a self-signed certificate)
• --s3-hostname: which hostname the server should be started on (default is 0.0.0.0)
• --s3-port: which port the server should be started on (default is 80 or 443)
• --s3-threads: enables clustering, number of threads to use for the server (default is no clustering; explicitly set to 0 to set by CPU core count). If you experience rate-limiting using this, using an auth config might help.

Using Docker

You can run the CLI in a Docker container using the filen/cli image.

For example, to run a WebDAV/S3 server in a container, you can use a Docker Compose file similar to this:

services:
  filen-webdav:
    image: filen/cli:latest
    ports:
      - 80:80
    command: >
      --email <...>
      --password <...>
      webdav
      --w-user <...>
      --w-password <...>

Footnotes

1. This is a TypeScript type definition, where ? means an optional field. ↩