Filen Sync
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
Prerequisites
Filen CLI requires Node.js 18+.
Install Node.js
Arch Linux:
sudo pacman -S nodejs npm
# Or use nvm for version management (recommended):
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install --lts
Ubuntu / Debian:
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt install -y nodejs
Rocky Linux / RHEL:
sudo dnf install -y nodejs npm
# Or via NodeSource for latest LTS:
curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash -
sudo dnf install -y nodejs
macOS:
brew install node
# Or via nvm -- follow Homebrew's post-install output to add nvm to your shell
# before running the next command:
brew install nvm
nvm install --lts
Install Filen CLI
All platforms (after Node.js is installed):
npm install -g @filen/cli
Verify installation:
filen-cli --version
filen-cli --help
Update to the latest version:
npm update -g @filen/cli
Uninstall:
npm uninstall -g @filen/cli
2. Authentication
Log in and store encrypted credentials locally. You will be prompted for your Filen email and password. Two-factor authentication (2FA) is supported.
filen-cli login
Log in non-interactively using environment variables (useful for scripts):
FILEN_EMAIL="you@example.com" FILEN_PASSWORD="yourpassword" filen-cli whoami
Show the currently authenticated account:
filen-cli whoami
Log out and remove stored credentials from disk:
filen-cli logout
Credentials are stored in an encrypted local config file, typically at:
- Linux:
~/.config/filen-cli/ - macOS:
~/Library/Application Support/filen-cli/
3. Navigating Remote Storage
List files and folders in the root of your Filen drive:
filen-cli ls
List a specific remote path:
filen-cli ls /Documents
filen-cli ls /Backups/2026
List with detailed metadata (size, modified date):
filen-cli ls -l /Documents
List recursively (all subdirectories):
filen-cli ls -r /Documents
4. Uploading
Upload a single local file to a remote directory:
filen-cli upload localfile.txt /remote/path/
Upload and rename the file on the remote:
filen-cli upload report.pdf /Documents/Q1-Report.pdf
Upload a directory recursively:
filen-cli upload ./project/ /Backups/project --recursive
Upload multiple files using a glob pattern (shell expansion):
filen-cli upload *.log /Logs/
5. Downloading
Download a single remote file to a local path:
filen-cli download /remote/file.txt ./localfile.txt
Download a remote directory recursively:
filen-cli download /Backups/project ./local-project --recursive
Download to the current directory:
filen-cli download /Documents/notes.md .
6. File Operations
Create a new remote directory:
filen-cli mkdir /remote/newdir
filen-cli mkdir /Documents/2026/Q1
Delete a remote file or directory:
filen-cli rm /remote/file.txt
filen-cli rm /remote/old-folder # deletes directory and all contents
Move or rename a remote file or directory:
filen-cli mv /remote/old-name.txt /remote/new-name.txt
filen-cli mv /Documents/file.txt /Archive/file.txt
Copy a remote file or directory:
filen-cli cp /remote/source.txt /remote/backup.txt
filen-cli cp /Documents/folder /Archive/folder
7. Syncing
Sync is the core power feature. It mirrors your local filesystem to the cloud (or bidirectionally). Think of it as rsync with end-to-end encryption baked in.
One-Way Sync (Local → Remote)
Pushes local changes to remote. Remote-only files are not touched.
filen-cli sync ./local-folder /remote-folder
Two-Way Sync
Changes on either side are propagated to the other. Conflicts resolve by last-write-wins unless configured otherwise.
filen-cli sync ./local-folder /remote-folder --two-way
Dry Run (Preview Only)
See exactly what would be uploaded, downloaded, or deleted – without making any changes.
filen-cli sync ./local-folder /remote-folder --dry-run
filen-cli sync ./local-folder /remote-folder --two-way --dry-run
Always do a dry run before syncing a new directory for the first time.
Watch Mode (Continuous Sync)
Monitors the local directory for changes using filesystem events and syncs immediately.
filen-cli sync ./local-folder /remote-folder --watch
filen-cli sync ./local-folder /remote-folder --two-way --watch
Run in the background (Linux/macOS):
nohup filen-cli sync ./local-folder /remote-folder --watch &
disown
Exclude Files from Sync
filen-cli sync ./project /Backups/project --exclude "*.tmp" --exclude "node_modules/"
Delete on Sync (Mirror Mode)
Deletes remote files that no longer exist locally. Use with caution.
filen-cli sync ./local-folder /remote-folder --delete
8. Storage and Account
Show total storage usage and quota:
filen-cli storage
Show recent account activity and events (uploads, downloads, shares):
filen-cli events
Show the last N events:
filen-cli events --limit 20
9. Sharing
Create a public share link for a remote file or directory:
filen-cli share /remote/path/file.txt
filen-cli share /Documents/report.pdf
Create a password-protected share link:
filen-cli share /remote/path --password "securepassword"
Set an expiry on a share link:
filen-cli share /remote/file.txt --expires 7d # expires in 7 days
Revoke an existing share:
filen-cli unshare /remote/path
10. 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-cli sync "$LOCAL_PATH" "$REMOTE_PATH" --dry-run
filen-cli sync "$LOCAL_PATH" "$REMOTE_PATH"
echo "Backup complete."
Systemd Timer for Automated Sync (Linux)
Create the service file at ~/.config/systemd/user/filen-sync.service:
[Unit]
Description=Filen Cloud Sync
After=network-online.target
[Service]
Type=simple
ExecStart=/usr/bin/filen-cli sync %h/Documents /Backups/Documents --two-way
Restart=on-failure
RestartSec=30
[Install]
WantedBy=default.target
Create the timer at ~/.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
11. Troubleshooting
| Problem | Likely Cause | Fix |
|---|---|---|
command not found: filen-cli | npm global bin not in PATH | Add $(npm bin -g) or ~/.npm-global/bin to $PATH in your shell config |
| Login fails / 2FA error | Wrong credentials or 2FA timing | Re-run filen-cli login; ensure your TOTP clock is synced |
| Sync stalls on large files | Network timeout or memory | Check connection; try syncing fewer files at once |
| Permission denied on local path | Running as wrong user | Check directory ownership with ls -la |
ENOENT error on upload | Local path does not exist | Verify the path: ls ./your-path |
Check versions if something is broken:
filen-cli --version
node --version
npm --version
Reinstall cleanly:
npm uninstall -g @filen/cli
npm install -g @filen/cli