Skip to main content
Homarr includes a CLI tool for administrative tasks like password resets, user management, and database maintenance.

​
Installation & Usage

The CLI is included with Homarr. Run commands using: 
docker exec -it homarr homarr-cli <command> [options]

​
Available Commands

​
reset-password

Reset a user’s password and invalidate all their sessions. A new secure random password is automatically generated. Usage: 
homarr-cli reset-password --username <username>
homarr-cli reset-password -u <username>
Options:
  • --username, -u (required) - Username of the user whose password should be reset
Example: 
docker exec -it homarr homarr-cli reset-password --username john
Output: 
All sessions for user john have been deleted
You can now login with the new password
New password for user john: X7k9P2mR5nQ8wL3vF6hJ4t
  • Only works with credentials provider users
  • All existing sessions are terminated
  • The new password is 48 characters long and randomly generated
  • Save the password immediately - it won’t be shown again
Requirements:
  • Credentials authentication provider must be enabled (AUTH_PROVIDERS includes credentials)
  • User must exist in the database with provider set to credentials
Error Cases: 
# If credentials provider is not enabled:
Credentials provider is not enabled

# If user doesn't exist:
User john not found

​
recreate-admin

Create a new admin user when no credentials admin exists. Useful for account recovery or initial setup issues. Usage: 
homarr-cli recreate-admin --username <username>
homarr-cli recreate-admin -u <username>
Options:
  • --username, -u (required) - Username for the new admin account
Example: 
docker exec -it homarr homarr-cli recreate-admin --username admin
Output: 
We created a new admin user for you. Please keep in mind, that the admin group of it has a temporary name. You should change it to something more meaningful.
	Username: admin
	Password: R9kL2mV5nT8wQ3xF6hP4jY
	Group: cm3x7k9p2r5nq8wl3vf6hj
  • Only creates an admin if NO credentials admin currently exists
  • Creates a temporary admin group with a random ID - rename it in the UI
  • Save the password immediately - it won’t be shown again
Requirements:
  • Credentials authentication provider must be enabled
  • No existing credentials users with admin permissions
  • Username must be valid according to Homarr’s username schema
  • Username must not already exist in the database
Error Cases: 
# If credentials provider is not enabled:
Credentials provider is not enabled

# If a credentials admin already exists:
Credentials admin user exists

# If username is already taken:
User with this name already exists

# If username is invalid:
Invalid username:
- Username must be at least 3 characters
- Username can only contain letters, numbers, and underscores
Post-Creation Steps:
  1. Log in with the generated credentials
  2. Navigate to Settings → Groups
  3. Rename the temporary group (shows as random ID) to something meaningful like “Administrators”
  4. Consider creating additional admin users
  5. Change the admin password from the UI

​
fix-usernames

Convert all credentials usernames to lowercase for consistency. This is useful after migrating from an older version or if username case issues exist. Usage: 
homarr-cli fix-usernames
Options: None - this command runs automatically on all credentials users. Example: 
docker exec -it homarr homarr-cli fix-usernames
Output: 
Changed username from John to john
Changed username from AdminUser to adminuser
All usernames have been fixed
  • Only affects credentials provider users
  • Users will need to log in with lowercase usernames after this runs
  • Does not affect OIDC or LDAP users
Requirements:
  • Credentials authentication provider must be enabled
Error Cases: 
# If credentials provider is not enabled:
Credentials provider is not enabled
Use Cases:
  • After upgrading from older Homarr versions
  • Fixing inconsistent username casing in the database
  • Standardizing usernames before migrating authentication providers

​
Common Workflows

​
Recovering Lost Admin Access

  1. Check if any admin exists: 
    # Check the database for admin users
  2. If no admin exists, create one: 
    docker exec -it homarr homarr-cli recreate-admin -u admin
  3. Save the generated password and log in
  4. Create additional admins through the UI

​
Resetting a User’s Password

  1. Reset the password: 
    docker exec -it homarr homarr-cli reset-password -u john
  2. Provide the new password to the user
  3. User logs in and can change password in Settings

​
Cleaning Up Usernames

  1. Run the username fix: 
    docker exec -it homarr homarr-cli fix-usernames
  2. Notify users to use lowercase usernames
  3. Verify users can log in with new lowercase usernames

​
Troubleshooting

Ensure you’re running the command inside the Homarr container:
# Wrong:
homarr-cli reset-password -u admin

# Correct:
docker exec -it homarr homarr-cli reset-password -u admin
The command only works when credentials authentication is enabled. Check your .env:
AUTH_PROVIDERS="credentials"
Or add credentials alongside other providers:
AUTH_PROVIDERS="credentials,oidc"
For reset-password:
  • Verify username is correct (case-sensitive)
  • Ensure user exists and uses credentials provider
  • Check the database for the user:
# Using SQLite:
sqlite3 /appdata/db/db.sqlite "SELECT name, provider FROM user;"
For recreate-admin:
  • This is a safety measure to prevent accidental admin creation
  • If you lost admin access, use reset-password on an existing admin
  • If genuinely no admin exists but you get this error, check group permissions in the database

​
Database Requirements

All CLI commands require:
  1. Valid database connection (via environment variables)
  2. Database migrations completed
  3. Credentials authentication provider enabled (for user management commands)
Verify your database configuration:
.env
DB_DRIVER='better-sqlite3'
DB_URL='/appdata/db/db.sqlite'
AUTH_PROVIDERS="credentials"

​
Security Considerations

  • Generated passwords are 48 characters long and cryptographically secure
  • Password resets invalidate all existing sessions immediately
  • Admin creation includes safety checks to prevent unauthorized access
  • CLI access requires container/system access - secure your Docker host
Anyone with access to run CLI commands has administrative control over Homarr. Restrict Docker/system access appropriately.

​
Command Help

Get help for any command: 
homarr-cli --help
homarr-cli reset-password --help
homarr-cli recreate-admin --help
homarr-cli fix-usernames --help

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us