Filen

Think of Filen as a remote filesystem where only you hold the key. The CLI is your ssh into that encrypted vault -- full terminal-based access to upload, download, sync, and manage your storage, with all data encrypted client-side before it leaves your machine. The server never sees plaintext.

1. Installation

A single curl-based installer is the fastest way to get the CLI. The script places the binary on your PATH automatically.

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

Verify installation:

filen --version
filen --help

Update to any specific version or to latest:

filen install latest
filen install canary
filen install <version>

The data directory stores credentials, config, and cache. On Linux it defaults to $XDG_CONFIG_HOME/filen-cli or ~/.config/filen-cli. If ~/.filen-cli exists, that takes precedence (the install script uses this location). Override with:

filen --data-dir /path/to/dir <cmd>
# or
FILEN_CLI_DATA_DIR=/path/to/dir filen <cmd>

2. Authentication

Five ways to authenticate:

Method	How
Interactive prompt	Run any command; enter email and password when prompted; optionally save credentials
CLI flags	filen --email <email> --password <password> [--two-factor-code <2fa>]
Environment variables	FILEN_EMAIL, FILEN_PASSWORD, optionally FILEN_2FA_CODE
Credentials file	.filen-cli-credentials with email, password, and optional 2FA code on separate lines
Auth config export	filen export-auth-config -- place the exported file where you invoke the CLI

The auth config export is unencrypted but skips the internal login request on each invocation. Use it to avoid rate-limiting in clustered WebDAV or S3 setups.

Show the currently authenticated account:

filen whoami

Remove saved credentials:

filen logout

Export API key (for use with Filen Rclone):

filen export-api-key

3. Navigating Remote Storage

List files and folders in the root of your Filen drive:

filen ls

List a specific remote path:

filen ls /Documents
filen ls /Backups/2026

List with detailed metadata (size, modified date):

filen ls --long /Documents

Print file contents:

filen cat /remote/file.txt

Print first or last N lines of a file:

filen head /remote/file.txt -n 20
filen tail /remote/file.txt -n 20

Show metadata about a file or directory:

filen stat /remote/file.txt

Show information about your entire Filen cloud drive:

filen statfs

View recently used files and directories:

filen recents

View all favourited items:

filen favorites

4. Uploading

Upload a single local file to a remote directory:

filen upload localfile.txt /remote/path/

Upload and rename the file on the remote:

filen upload report.pdf /Documents/Q1-Report.pdf

Upload multiple files using a glob pattern (shell expansion):

filen upload *.log /Logs/

Write plain text directly to a remote file (creates if it does not exist):

filen write /remote/notes.txt "some content here"

5. Downloading

Download a single remote file to a local path:

filen download /remote/file.txt ./localfile.txt

Download a remote directory:

filen download /Backups/project ./local-project

Download to the current directory:

filen download /Documents/notes.md .

6. File Operations

Create a new remote directory:

filen mkdir /remote/newdir
filen mkdir /Documents/2026/Q1

Delete a remote file or directory (moves to trash by default):

filen rm /remote/file.txt
filen rm /remote/old-folder

Delete permanently, bypassing trash:

filen rm /remote/file.txt --no-trash

Move or rename a remote file or directory:

filen mv /remote/old-name.txt /remote/new-name.txt
filen mv /Documents/file.txt /Archive/file.txt

Copy a remote file or directory:

filen cp /remote/source.txt /remote/backup.txt
filen cp /Documents/folder /Archive/folder

Favourite or unfavourite an item:

filen favorite /remote/path
filen unfavorite /remote/path

Open or edit a remote file locally (edit re-uploads on save and close):

filen open /remote/file.txt
filen edit /remote/file.txt

Export all Notes to a local directory:

filen export-notes ~/filen-notes

7. Syncing

Sync mirrors your local filesystem to the cloud. It is the same engine used by the desktop app.

Sync Modes

Mode	Abbreviation	Behaviour
twoWay	tw	Changes on either side propagate to the other
localToCloud	ltc	Local changes pushed to cloud; cloud-only files untouched
localBackup	lb	Local to cloud; remote deletions not propagated
cloudToLocal	ctl	Cloud changes pulled to local; local-only files untouched
cloudBackup	cb	Cloud to local; local deletions not propagated

Basic Sync

Inline pair, defaults to two-way:

filen sync /local/path:/cloud/path

Explicit mode in the pair:

filen sync /local1:twoWay:/cloud1 /local2:ltc:/cloud2

Sync Pairs File

Store pairs in ~/.config/filen-cli/syncPairs.json:

[
  {
    "local": "/home/user/Documents",
    "remote": "/Backups/Documents",
    "syncMode": "localToCloud",
    "alias": "docs",
    "disableLocalTrash": false,
    "excludeDotFiles": true,
    "ignore": ["*.tmp", "node_modules/"]
  }
]

Run all pairs defined in the file:

filen sync

Run by alias:

filen sync docs

Use a custom pairs file:

filen sync /path/to/custom-pairs.json

Continuous Sync

Keep syncing on a loop instead of running once:

filen sync /local/path:/cloud/path --continuous

Disable Local Trash

filen sync /local/path:/cloud/path --disable-local-trash

8. Network Drive Mount

Mount your Filen drive as a local filesystem. Requires FUSE3 on Linux:

sudo pacman -S fuse3        # Arch
sudo apt install fuse3      # Ubuntu/Debian
sudo dnf install fuse3      # Rocky/RHEL

Mount at the default path (/tmp/filen on Linux):

filen mount

Mount at a custom path:

filen mount /mnt/filen

Unmount with fusermount3 -u /mnt/filen or umount /mnt/filen.

9. WebDAV Server

Run a WebDAV server that exposes your Filen drive to local applications.

Single-User Mode

filen webdav --w-user <user> --w-password <password>

Flag	Default	Description
--w-user	required	Username for WebDAV authentication
--w-password	required	Password for WebDAV authentication
--w-hostname	0.0.0.0	Hostname to bind to
--w-port	80 or 443	Port to bind to
--w-https	off	Use HTTPS with a self-signed certificate
--w-threads	none	Enable clustering; 0 = one thread per CPU core
--w-auth-scheme	basic	Authentication scheme: basic or digest

Proxy Mode (Multi-User)

Any Filen account holder can connect using their own credentials:

filen webdav-proxy --w-port 1900

In proxy mode the password field must be formatted as:

password=yoursecretpassword&twoFactorAuthentication=<OTP_OR_RECOVERY_CODE>

Drop the &twoFactorAuthentication=... part if 2FA is disabled. Digest auth is not available in proxy mode.

10. S3 Server

Run an S3-compatible server that mirrors your Filen drive.

filen s3 --s3-access-key-id <id> --s3-secret-access-key <key>

Flag	Default	Description
--s3-access-key-id	required	Access Key ID
--s3-secret-access-key	required	Secret Access Key
--s3-hostname	0.0.0.0	Hostname to bind to
--s3-port	80 or 443	Port to bind to
--s3-https	off	Use HTTPS with a self-signed certificate
--s3-threads	none	Enable clustering; 0 = one thread per CPU core

When connecting clients, set s3ForcePathStyle = true and region to filen.

11. Trash Management

Command	Description
filen trash	List all 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

12. Public Links

Command	Description
filen links	List all public links
filen links <path>	Create, view, edit, or delete a link for a file or directory

13. Updates

The CLI checks for new releases on every invocation and will not recheck for 10 minutes after a successful check.

Flag	Behaviour
--force-update	Check even if recently checked
--skip-update	Skip the update check entirely
--auto-update	Update without a confirmation prompt

Enable or disable canary releases:

filen canary

14. Automation and Scripting

Backup Script Example

#!/bin/bash
# daily backup of ~/Documents to Filen

set -e

TIMESTAMP=$(date +%Y-%m-%d)
LOCAL_PATH="$HOME/Documents"
REMOTE_PATH="/Backups/Documents/$TIMESTAMP"

echo "starting Filen backup: $TIMESTAMP"
filen sync "$LOCAL_PATH:localToCloud:$REMOTE_PATH"
echo "backup complete."

Systemd Timer for Automated Sync (Linux)

Create ~/.config/systemd/user/filen-sync.service:

[Unit]
Description=Filen Cloud Sync
After=network-online.target

[Service]
Type=simple
ExecStart=/usr/bin/env filen sync %h/Documents:localToCloud:/Backups/Documents --continuous
Restart=on-failure
RestartSec=30

[Install]
WantedBy=default.target

Create ~/.config/systemd/user/filen-sync.timer:

[Unit]
Description=Run Filen Sync every 6 hours

[Timer]
OnBootSec=5min
OnUnitActiveSec=6h
Persistent=true

[Install]
WantedBy=timers.target

Enable and start:

systemctl --user daemon-reload
systemctl --user enable --now filen-sync.timer
systemctl --user status filen-sync.timer

15. Troubleshooting

Problem	Likely Cause	Fix
command not found: filen	Binary not in PATH	Add ~/.filen-cli to $PATH in your shell config
Login fails / 2FA error	Wrong credentials or clock drift	Re-authenticate; ensure your TOTP clock is synced
Sync stalls on large files	Network timeout or memory pressure	Check connection; reduce batch size
Permission denied on local path	Wrong user	Check ownership with ls -la
Rate limiting on WebDAV/S3	Too many auth requests	Use filen export-auth-config and pass the file to the server

Check versions when something is broken:

filen --version

Reinstall cleanly:

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

---

Cheatsheet

Auth

Task	Command
Show current account	filen whoami
Log out	filen logout
Export auth config	filen export-auth-config
Export API key	filen export-api-key

Filesystem

Task	Command
List root	filen ls
List with metadata	filen ls --long /path
Print file	filen cat /path/file.txt
Head / tail	filen head /file -n 20 / filen tail /file -n 20
Stat file	filen stat /path
Drive info	filen statfs
Make directory	filen mkdir /path/newdir
Move / rename	filen mv /from /to
Copy	filen cp /src /dst
Delete (trash)	filen rm /path
Delete (permanent)	filen rm /path --no-trash
Write text to file	filen write /path/file.txt "content"
Edit file locally	filen edit /path/file.txt
Recent files	filen recents
Favourites	filen favorites

Transfer

Task	Command
Upload file	filen upload ./file.txt /remote/
Upload glob	filen upload *.log /Logs/
Download file	filen download /remote/file.txt ./local/
Download directory	filen download /remote/dir ./local-dir
Export notes	filen export-notes ~/filen-notes

Sync

Task	Command
Two-way sync (once)	filen sync /local:/remote
Local to cloud (once)	filen sync /local:ltc:/remote
Cloud to local (once)	filen sync /local:ctl:/remote
Continuous sync	filen sync /local:/remote --continuous
Run pairs from file	filen sync
Run by alias	filen sync <alias>

Mount

Task	Command
Mount (default path)	filen mount
Mount (custom path)	filen mount /mnt/filen
Unmount	fusermount3 -u /mnt/filen

WebDAV

Task	Command
Single-user server	filen webdav --w-user <u> --w-password <p>
HTTPS single-user	filen webdav --w-user <u> --w-password <p> --w-https --w-port 443
Proxy mode	filen webdav-proxy --w-port 1900
Clustered (auto threads)	filen webdav --w-user <u> --w-password <p> --w-threads 0

S3

Task	Command
Start S3 server	filen s3 --s3-access-key-id <id> --s3-secret-access-key <key>
HTTPS S3 server	filen s3 --s3-access-key-id <id> --s3-secret-access-key <key> --s3-https
Clustered (auto threads)	filen s3 --s3-access-key-id <id> --s3-secret-access-key <key> --s3-threads 0

Trash and Links

Task	Command
List trash	filen trash
Restore trash item	filen trash restore
Empty trash	filen trash empty
List public links	filen links
Manage link for path	filen links /remote/path

Updates

Task	Command
Install latest	filen install latest
Install canary	filen install canary
Toggle canary channel	filen canary
Force update check	filen --force-update <cmd>
Skip update check	filen --skip-update <cmd>