FileBrowser provides a minimal CLI for setup and user management.

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.

Version

Check version information:

BASH 
1

./filebrowser version

User Management

Add or update user:

BASH 
1

./filebrowser set -u username,password

With custom config:

BASH 
1

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

Create admin user:

BASH 
1

./filebrowser set -u username,password -a

Access Rule Management

Create or update access rules via CLI:

Allow user access:

BASH 
1

./filebrowser set rule -f /mnt/storage -p /secret -r user -v username -allow -c config.yaml

Deny user access:

BASH 
1

./filebrowser set rule -f /mnt/storage -p /secret -r user -v username -c config.yaml

Allow group access:

BASH 
1

./filebrowser set rule -f /mnt/storage -p /departments/sales -r group -v sales -allow -c config.yaml

Deny all users:

BASH 
1

./filebrowser set rule -f /mnt/storage -p /restricted -r all -c config.yaml

Rule command options:

  • -f - Real filesystem path (e.g. /mnt/storage)
  • -p - Index path (e.g. /secret)
  • -r - 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 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 set -u admin,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
5

docker run -it \
  -v $(pwd)/database.db:/home/filebrowser/database.db \
  -v $(pwd)/config.yaml:/home/filebrowser/config.yaml \
  --entrypoint="" \
  gtstef/filebrowser sh

Inside container:

BASH 
1
2

./filebrowser set -u admin,newpass -c config.yaml
exit

One-Line Docker Commands

Password reset:

BASH 
1
2
3
4
5
6

docker run -it --rm \
  -v $(pwd)/database.db:/home/filebrowser/database.db \
  -v $(pwd)/config.yaml:/home/filebrowser/config.yaml \
  --entrypoint="" \
  gtstef/filebrowser \
  ./filebrowser set -u admin,newpassword -c config.yaml

Create user:

BASH 
1
2
3
4
5
6

docker run -it --rm \
  -v $(pwd)/database.db:/home/filebrowser/database.db \
  -v $(pwd)/config.yaml:/home/filebrowser/config.yaml \
  --entrypoint="" \
  gtstef/filebrowser \
  ./filebrowser set -u newuser,password -c config.yaml

Common Operations

Password Reset

BASH 
1

./filebrowser set -u admin,newpassword -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 set -u joe,password -c config.yaml

Promote User to Admin

BASH 
1

./filebrowser set -u joe,newpassword -a -c config.yaml

Initial Admin Setup

After first install:

BASH 
1
2
3
4
5
6

# Option 1: Use CLI
./filebrowser set -u admin,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:

TEXT 
1
2
3

FileBrowser version: v0.10.0
Built: 2025-01-15
Go version: go1.23

filebrowser set

Add or update users, or manage access rules.

User Management Syntax:

BASH 
1

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

User Management Options:

  • -u - Username and password (comma-separated)
  • -a - Make user admin
  • -c - Config file path

User Management Examples:

BASH 
1
2
3
4
5
6
7
8

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

# Create admin
./filebrowser set -u admin,secure-pass -a -c config.yaml

# Reset password
./filebrowser set -u john,newpass -c config.yaml

Access Rule Management Syntax:

BASH 
1

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

Access Rule Options:

  • -f - Real filesystem path (required)
  • -p - Index path (required)
  • -r - 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 file path

Access Rule Examples:

BASH 
1
2
3
4
5
6
7
8

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

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

# Deny all users
./filebrowser set rule -f /mnt/storage -p /private -r all -c config.yaml

Troubleshooting

For common issues and solutions, see the Troubleshooting guide.

Next Steps