Published: October 8, 2025
Last updated: July 24, 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

# 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

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

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
5

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

Inside container:

BASH 
1
2

./filebrowser user set admin --password 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:stable \
  ./filebrowser user set admin --password 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:stable \
  ./filebrowser user set newuser --password password -c config.yaml

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:

TEXT 
1
2
3

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

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