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

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.

Re-encryption Commands

Rotate the AES-GCM encryption key used by the Connectors or UNS modules. These commands re-wrap every encrypted row in place under a new key and update the on-disk secrets file atomically.

Stop the server first

The reencrypt commands write directly to the SQLite files. The MaestroHub server must be stopped before you run them — running both at once will corrupt the database.

Where the ./data/ paths resolve

The ./data/... defaults below are relative to the directory admin-cli runs from. Two common cases:

• Binary install — MaestroHub keeps SQLite databases and the secrets directory under ~/maestrohub/data/ (i.e. $HOME/maestrohub/data/). Pass absolute paths: --db ~/maestrohub/data/connectors.db --secrets-dir ~/maestrohub/data/secrets.
• Docker — both live inside the volume mounted at /data. Inside the container the paths are /data/data/connectors.db and /data/data/secrets/. Run admin-cli via docker exec (or in a one-shot container against the same volume).

If you launch admin-cli from the directory that contains the data/ subfolder, the defaults work as-is.

Each subcommand:

1. Backs up the target database to <db>.before-reencrypt-<timestamp>
2. Re-encrypts every row inside a single SQL transaction
3. Verifies that every row decrypts under the new key
4. Persists the new key to <secrets-dir>/<module>_encryption_key

If any step fails the operation aborts. The transaction guarantees the database is left unchanged if step 2 errors; if step 3 fails, restore from the backup before restarting the server.

Common flags:

Flag	Description	Default
--db	Path to the module's SQLite file	./data/<module>.db
--old-key	Current encryption key (16/24/32 bytes ASCII or base64)	Read from <secrets-dir>/<module>_encryption_key
--new-key	New encryption key (16/24/32 bytes ASCII or base64)	Freshly generated random AES-256
--secrets-dir	Directory holding the persisted secrets files	./data/secrets
--key-file	Override the secrets file name	<module>_encryption_key

Re-encrypt Connectors

Re-wrap encrypted_secrets in connections and connections_history.

admin-cli reencrypt connectors [flags]

Examples:

Generate a fresh random AES-256 key, rewrap, and persist:

admin-cli reencrypt connectors \
  --db ./data/connectors.db \
  --secrets-dir ./data/secrets

Rotate to an explicit key (e.g. supplied by your KMS):

admin-cli reencrypt connectors \
  --db ./data/connectors.db \
  --secrets-dir ./data/secrets \
  --new-key "$(cat /path/to/new-key.b64)"

Re-encrypt UNS

Re-wrap encryptedSecrets in uns_settings and uns_settings_history.

admin-cli reencrypt uns [flags]

Example:

admin-cli reencrypt uns \
  --db ./data/uns.db \
  --secrets-dir ./data/secrets

Recovery

If verification (step 3) fails, the database has been re-encrypted but cannot be read under the new key. Restore from the backup before restarting the server:

mv ./data/connectors.db.before-reencrypt-<timestamp> \
   ./data/connectors.db

After a successful re-encryption, restart MaestroHub. It picks up the new key from the secrets file on next boot — no further configuration needed.

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.