CLI Reference
cv4pve-admin includes a built-in command-line interface for administrative tasks that can be performed without accessing the web UI.
Run the commands from the installation directory: they run in the container of the application. Use --help to list all available commands:
docker compose run --rm cv4pve-admin --helpEach command also supports --help for details on its options:
docker compose run --rm cv4pve-admin user --helpdocker compose run --rm cv4pve-admin user reset-password --help--version prints the version of the application.
A command first initialises the application: the database must be reachable, and the initialisation applies pending database updates. The command then runs, prints its result and exits without starting the web server. The exit code is 0 on success and 1 on error.
A command can run while the web application is running: the tasks in progress in the web application are left as they are.
User commands
Section titled “User commands”| Option | Applies to | Required | Description |
|---|---|---|---|
-u, --username <username> |
all user commands | no, default admin@local |
User the command works on |
-p, --password <password> |
reset-password |
yes | New password |
The new password must satisfy the password rules of the application. Otherwise reset-password lists what is wrong and changes nothing.
| Command | Description |
|---|---|
user reset-password -u <user> -p <password> |
Set a new password for the user |
user enable -u <user> |
Enable a disabled user account: the user can sign in again |
user disable -u <user> |
Disable a user account: the user can no longer sign in |
user unlock -u <user> |
Unlock a locked out user account and reset its count of failed sign-in attempts |
user disable-2fa -u <user> |
Turn off two-factor authentication for the user, who then signs in with the password only |
A user name that does not exist is reported as Error: User '<name>' not found. The built-in system users cannot be modified from the command line.
Troubleshooting
Section titled “Troubleshooting”Reset a forgotten admin password
Section titled “Reset a forgotten admin password”If you are locked out of the web UI, reset the password via CLI.
docker compose run --rm cv4pve-admin user reset-password -u admin@local -p NewPassword123!Use a strong password and change it again from the web UI after recovering access.
Unlock a locked out account
Section titled “Unlock a locked out account”After too many failed login attempts, the account is locked. To unlock it:
docker compose run --rm cv4pve-admin user unlock -u admin@localLost authenticator device and recovery codes
Section titled “Lost authenticator device and recovery codes”A user who has lost both cannot complete the login. Turn two-factor authentication off, then the user signs in with the password and sets it up again from the profile:
docker compose run --rm cv4pve-admin user disable-2fa -u admin@localThe authenticator key and the recovery codes of the user are discarded: the next setup starts from a new QR code. A user without two-factor authentication is reported as such and nothing changes. No email is sent to the user.
For any other user an administrator can do the same from the web UI, with Disable 2FA in Security. The command line is the way out when the locked out user is the only administrator.
Disable and enable an account
Section titled “Disable and enable an account”Disable an account to block its sign-in without deleting the user, and enable it again later.
docker compose run --rm cv4pve-admin user disable -u john@localdocker compose run --rm cv4pve-admin user enable -u john@local
