Published: October 8, 2025
Last updated: October 3, 2026
Suggest an edit

FileBrowser provides a minimal CLI for setup and user management.

CLI migration (v2.0.0+)

BASH 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# User create
set -u john,pass -c cfg          →  user set john --password pass -c cfg

# User password reset
set -u john,newpass -c cfg       →  user set john --password newpass -c cfg
                                   # or: echo 'newpass' | user set john --password -c cfg

# Create admin
set -u admin,pass -a -c cfg      →  user set admin --password pass -a -c cfg

# Promote to admin (preferred — no password change)
set -u joe,newpass -a -c cfg     →  user promote joe -c cfg

# Access rules — NO CHANGE
set rule -s access -p / -r user -v admin --allow -c cfg

# Server / setup / version — NO CHANGE
filebrowser -c cfg
filebrowser setup
filebrowser version

# Initialize or migrate the database without starting the server (v2.0.7-beta+)
filebrowser init -c cfg

Available Commands

Start Server

Default command - runs the server:

BASH 
1

./filebrowser

With custom config:

BASH 
1

./filebrowser -c /path/to/config.yaml

Setup

Create new configuration file:

BASH 
1

./filebrowser setup

Generates config.yaml with defaults.

Initialize database

filebrowser init was added in v2.0.x

The command is hidden from the default help list. Its help text is “Initialize the database or migrate from a legacy database”.

BASH 
1

./filebrowser init -c /path/to/config.yaml

It loads the config (-c, or FILEBROWSER_CONFIG, default config.yaml), then:

  • Opens the SQLite database at server.database.path, or creates it when that file does not exist yet
  • Imports a legacy BoltDB database when server.database.migrateFrom points at a populated legacy file and the SQLite file is missing or empty
  • Exits without starting the HTTP server

Shut down a running server before init. Only one process can use the database.

Version

Check version information:

BASH 
1

./filebrowser version

User Management

Create or update a password-authenticated user:

BASH 
1

./filebrowser user set username --password secret -c config.yaml

Prompt for password on a TTY (omit the value):

BASH 
1

./filebrowser user set username --password -c config.yaml

Read password from stdin (scripts):

BASH 
1

echo 'secret' | ./filebrowser user set username --password -c config.yaml

Create as admin:

BASH 
1

./filebrowser user set username --password secret -a -c config.yaml

Promote an existing user to admin without changing their password:

BASH 
1

./filebrowser user promote username -c config.yaml

Deprecated (still works with stderr warning):

BASH 
1

./filebrowser set -u username,password [-a] [-c config.yaml]

Access Rule Management

Create or update access rules via CLI:

Allow user access:

BASH 
1

./filebrowser set rule -s access -p /secret -r user -v username --allow -c config.yaml

Deny user access:

BASH 
1

./filebrowser set rule -s access -p /secret -r user -v username -c config.yaml

Allow group access:

BASH 
1

./filebrowser set rule -s access -p /departments/sales -r group -v sales --allow -c config.yaml

Deny all users:

BASH 
1

./filebrowser set rule -s access -p /restricted -r all -c config.yaml

Rule command options:

  • -s / --source - Source name from config (not the filesystem path)
  • -p / --path - Index path (e.g. /secret)
  • -r / --role - Rule category: user, group, or all (for deny only)
  • -v / --value - Username or groupname (not required if -r is all)
  • --allow - Allow access (default: false, which means deny)
  • -c / --config - Config file path

Important Notes

Always shut down the server before CLI operations

Only one process can access the database at once.

BASH 
1
2
3
4
5
6
7
8

# Stop service first
systemctl stop filebrowser

# Run CLI command
./filebrowser user set admin --password newpass -c config.yaml

# Start service
systemctl start filebrowser

Docker Usage

Stop Running Container

BASH 
1

docker compose down

Run CLI in Container

BASH 
1
2
3
4

docker run -it \
  -v $(pwd)/data:/home/filebrowser/data \
  --entrypoint="" \
  ghcr.io/gtsteffaniak/filebrowser:stable sh

Inside container:

BASH 
1
2

./filebrowser user set admin --password newpass -c /home/filebrowser/data/config.yaml
exit

One-Line Docker Commands

Password reset:

BASH 
1
2
3
4
5

docker run -it --rm \
  -v $(pwd)/data:/home/filebrowser/data \
  --entrypoint="" \
  ghcr.io/gtsteffaniak/filebrowser:stable \
  ./filebrowser user set admin --password newpassword -c /home/filebrowser/data/config.yaml

Create user:

BASH 
1
2
3
4
5

docker run -it --rm \
  -v $(pwd)/data:/home/filebrowser/data \
  --entrypoint="" \
  ghcr.io/gtsteffaniak/filebrowser:stable \
  ./filebrowser user set newuser --password password -c /home/filebrowser/data/config.yaml

Mount the data directory, not a single database file. Official images keep config and the database under /home/filebrowser/data (FILEBROWSER_CONFIG). v1.5.x (stable) stores database.db there. v2.0.0+ (beta) stores database.sqlite there unless server.database.path is set. Use the beta image tag when the data directory is a v2 install.

Common Operations

Password Reset

BASH 
1
2

./filebrowser user set admin --password newpassword -c config.yaml
# or: echo 'newpassword' | ./filebrowser user set admin --password -c config.yaml

This is useful if:

  • A user forgot their password
  • A user lost access to their 2FA device and needs both password and 2FA reset
  • You need to reset an account for security reasons

Create New User

BASH 
1

./filebrowser user set joe --password password -c config.yaml

Promote User to Admin

BASH 
1

./filebrowser user promote joe -c config.yaml

To promote and reset password at the same time:

BASH 
1

./filebrowser user set joe --password newpassword -a -c config.yaml

Initial Admin Setup

After first install:

BASH 
1
2
3
4
5
6

# Option 1: Use CLI
./filebrowser user set admin --password secure-password -a -c config.yaml

# Option 2: Use environment variable
export FILEBROWSER_ADMIN_PASSWORD="secure-password"
./filebrowser -c config.yaml

Command Reference

filebrowser

Start server with optional config.

Syntax:

BASH 
1

./filebrowser [-c config.yaml]

Options:

  • -c - Config file path (default: config.yaml)

Examples:

BASH 
1
2

./filebrowser
./filebrowser -c /etc/filebrowser/config.yaml

filebrowser setup

Create default configuration file.

Syntax:

BASH 
1

./filebrowser setup

Output: Creates config.yaml in current directory.

filebrowser version

Display version information.

Syntax:

BASH 
1

./filebrowser version

Output (v1.5.x stable and v2.x beta):

TEXT 
1
2
3
4

FileBrowser Quantum - A modern web-based file manager
	Version 	 : v1.5.6-stable
	Commit 		 : <commit sha>
	Release Info 	 : https://github.com/gtsteffaniak/filebrowser/releases/tag/v1.5.6-stable

filebrowser user set

Create or update a password-authenticated user.

Syntax:

BASH 
1

./filebrowser user set <username> --password [value] [-a] [-c config.yaml]

Options:

  • --password - Password (inline value, TTY prompt when omitted, or read from stdin when piped)
  • -a / --admin - Grant admin permissions
  • -c / --config - Config file path
  • --no-input - Disable interactive prompts (fail if password value is required)

Examples:

BASH 
1
2
3
4
5
6
7
8

# Create user
./filebrowser user set john --password pass123 -c config.yaml

# Create admin
./filebrowser user set admin --password secure-pass -a -c config.yaml

# Reset password (piped)
echo 'newpass' | ./filebrowser user set john --password -c config.yaml

filebrowser user promote

Grant admin permissions without changing the password.

Syntax:

BASH 
1

./filebrowser user promote <username> [-c config.yaml]

Example:

BASH 
1

./filebrowser user promote joe -c config.yaml

filebrowser set (deprecated user syntax)

Deprecated user syntax (prints stderr warning):

BASH 
1

./filebrowser set -u username,password [-a] [-c config.yaml]

Use user set instead. This form remains available in v2.0.0 for compatibility.

filebrowser set rule

Syntax:

BASH 
1

./filebrowser set rule -s <sourceName> -p <indexPath> -r <user|group|all> [-v <value>] [--allow] [-c config.yaml]

Access Rule Options:

  • -s / --source - Source name from config (required)
  • -p / --path - Index path (required)
  • -r / --role - Rule category: user, group, or all (for deny only) (required)
  • -v / --value - Username or groupname (required when -r is user or group)
  • --allow - Allow access (default: false, which means deny)
  • -c / --config - Config file path

Access Rule Examples:

BASH 
1
2
3
4
5
6
7
8

# Allow user access to a path
./filebrowser set rule -s access -p /documents -r user -v john --allow -c config.yaml

# Deny group access
./filebrowser set rule -s access -p /restricted -r group -v guests -c config.yaml

# Deny all users
./filebrowser set rule -s access -p /private -r all -c config.yaml

Troubleshooting

For common issues and solutions, see the Troubleshooting guide.

Next Steps