Admin CLI
The MaestroHub Admin CLI (admin-cli) is a command-line tool for managing users and performing database operations. It is bundled with MaestroHub and included in the release archive. It provides break-glass access for emergency situations and administrative tasks that require direct database interaction.
Database Configuration
The Admin CLI needs to connect to the MaestroHub database to perform operations.
Database Location
By default, MaestroHub stores its database in the user's home directory:
~/maestrohub/data/
For Lite deployments, the database files are typically located at:
~/maestrohub/data/*.db
Specifying the Database
You can specify the database connection in three ways (in order of precedence):
1. Command-line flag
admin-cli --database ~/maestrohub/data/auth.db user list
2. Environment variables
The CLI checks for database connection strings in the following environment variables:
| Variable | Description |
|---|---|
DATABASE_URL | Full database connection URL |
DB_URL | Alternative connection URL |
MAESTRO_DATABASE_URL | MaestroHub-specific connection URL |
POSTGRES_URL | PostgreSQL connection URL |
SQLITE_PATH | Path to SQLite database file |
3. Auto-detection
If no database is specified, the CLI searches for SQLite files in common locations:
./maestro.db./data/maestro.db./data/auth.db/var/lib/maestro/maestro.db/etc/maestro/maestro.db
Global Flags
These flags can be used with any command:
| Flag | Short | Description |
|---|---|---|
--database | -d | Database URL or file path |
--verbose | -v | Enable verbose output |
--force | -f | Skip confirmation prompts |
--version | Display version information | |
--help | -h | Display help information |
Commands
User Commands
List Users
Display all users in the system.
admin-cli user list [--limit <number>]
Options:
| Flag | Description | Default |
|---|---|---|
--limit | Maximum number of users to display | 20 |
Example:
admin-cli user list --limit 50
Reset Password
Reset a user's password. This is the break-glass method for emergency access when email is unavailable.
admin-cli user reset-password --email <email> [--password <password>]
Options:
| Flag | Short | Description | Default |
|---|---|---|---|
--email | -e | User's email address (required) | - |
--password | -p | New password | TempPassword2024! |
Examples:
Reset with default temporary password:
admin-cli user reset-password -e admin@example.com
Reset with custom password:
admin-cli user reset-password -e admin@example.com -p "NewSecurePass123!"
Skip confirmation prompt:
admin-cli user reset-password -e admin@example.com -f
After using break-glass reset, instruct the user to change their password immediately after signing in.
Database Commands
Database Info
Display database connection information and statistics.
admin-cli db info
Output includes:
- Database type
- Connection location
- Total user count
Test Connection
Test the database connection and verify connectivity.
admin-cli db test
Use this command to verify your database configuration before running other operations.
Troubleshooting
"Cannot find database connection"
The CLI could not locate a database. Specify the database explicitly:
admin-cli -d ~/maestrohub/data/auth.db db test
"Failed to connect to database"
- Verify the database file exists (for SQLite)
- Check that the connection URL is correct (for PostgreSQL)
- Ensure the database server is running and accessible
- Verify network connectivity and firewall rules
"No user found with email"
The specified email address does not exist in the database. Use user list to verify the correct email address.