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 Lite 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

warning

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.