Command Line Interface (CLI)

The UDMG Server Command Line Interface (CLI) is a set of commands built into the udmg-server binary. The CLI performs administrative actions that run locally on the UDMG Server host, such as starting the service, applying database migrations, managing the license key, administering Users, and rotating encryption keys.

Unlike the UDMG Admin UI or the UDMG REST API, which connect to a running server over the network, the CLI operates directly against the UDMG Server's configuration and database. Most commands therefore require access to the same Configuration File used by the server.

warning

The udmg-server CLI is intended for local administration and recovery operations performed on the host where UDMG Server is installed. It is not a remote client.

Commands

CLI commands perform specific administrative actions against a UDMG Server installation.

The available commands are listed below, grouped by function.

Category	Command	Description	Authentication
Server	start	Start UDMG Server.	None
Configuration	test	Validate the Configuration File.	None
License	license enroll	Validate and store a new license key.	None
	license status	Show the current license status.	None
Database	migrate	Run UDMG Server database migrations.	None
	migrations	Dump UDMG Server database migration files.	None
User Administration	password-reset	Reset a Secondary Domain's default Domain Administrator password.	None
	user-lock	Lock a User to disable its login.	User password
	user-unlock	Unlock a previously locked User.	User password
	user-mnemonic	Generate or view a mnemonic recovery phrase for a User.	User password
Encryption Key Rotation	passphrase-backup	Back up the master passphrase key.	None
	passphrase-restore	Restore the master passphrase key from backup.	None
	rotate-k0	Rotate the K0 encryption key (root key).	None
	rotate-master-key	Rotate the master encryption key (K1).	None

info

In addition to the commands above, the CLI provides two standard helper commands, help and completion, described under Standard Commands.

info

There is no stop or restart command. UDMG Server's lifecycle is handled by the host's service manager. See Stopping and Restarting UDMG Server.

Command Line Syntax

The following command line syntax is used for issuing CLI commands with the udmg-server binary:

udmg-server <command> [global options] [command-specific options]

Command Line Entry	Description
udmg-server	The UDMG Server binary, which executes all CLI commands.
command	The command that performs a specific administrative action.
global options	Options available for all (or most) commands.
command-specific options	Options specific to that command.

info

The examples use the bare udmg-server command, which assumes the binary is on your PATH. If it is not, run it with its full path or add the install directory to your PATH (by default /opt/udmg/bin on Linux and C:\Program Files\Stonebranch\UDMG Server on Windows).

Global Options

The CLI provides the following global options, all of them optional:

• Config: the --config option is accepted by every command that connects to the database or starts the server.
• Help and Version: available everywhere.

Config

Description	Path to the UDMG Server Configuration File. If omitted, configuration is loaded from Environment Variables.
Command Line Switch	-c | --config
Environment Variable	UDMG_CONFIG_FILE
Required	No
Default	(none)
Example	Linux: --config /opt/udmg/etc/udmg-server.hcl Windows: --config "C:\Program Files\Stonebranch\UDMG Server\udmg-server.hcl"

Help

Description	Provides help information for the CLI or for a specific command.
Command Line Switch	-h | --help
Environment Variable	N/A
Required	No
Default	(none)
Example	udmg-server license enroll -h

Version

Description	Displays version information for UDMG Server.
Command Line Switch	-v | --version
Environment Variable	N/A
Required	No
Default	(none)
Example	udmg-server --version

Command Reference

All commands run on both Linux and Windows.

start

Starts the UDMG Server service. Loads the configuration, validates it, prepares the work directory, and starts all configured listeners and services.

warning

start runs in the foreground and must keep running for as long as the server needs to be available. Run it under the host's service manager (a systemd unit on Linux or a Windows service) or a supervising script, rather than launching it by hand, so the process is kept alive and restarted automatically.

Command line syntax

udmg-server start [--config <path>]

Command-specific options

This command takes only the global --config option.

Example

Linux

udmg-server start --config /opt/udmg/etc/udmg-server.hcl

Windows

udmg-server start --config "C:\Program Files\Stonebranch\UDMG Server\udmg-server.hcl"

Stopping and Restarting UDMG Server

There is no stop or restart subcommand. Once started, UDMG Server is stopped or restarted through the host's service manager, or with Ctrl+C when it is running in the foreground.

Stop the server:

Linux

sudo systemctl stop udmg-server

Windows (PowerShell)

Stop-Service -Name udmg-server

Restart the server:

Linux

sudo systemctl restart udmg-server

Windows (PowerShell)

Restart-Service -Name udmg-server

On Windows, you can also manage the service from the Services console. For service setup, see Linux Host and Windows Host.

test

Validates a UDMG Server Configuration File without starting the server. If the file contains errors, the command reports each problem with its file, line, and column, along with the surrounding lines for context. Use this to check a configuration before deploying or restarting.

Unlike the other commands, test takes the Configuration File path with -f / --file (not -c / --config), and the UDMG_CONFIG_FILE environment variable is honored as a fallback. test fails if neither is set.

Command line syntax

udmg-server test [--file <path>]

Command-specific options

Option	Description	Required	Default
-f | --file	Path to the Configuration File to validate. If omitted, the UDMG_CONFIG_FILE environment variable is used.	No, but only if UDMG_CONFIG_FILE is set	(none)

Example

Linux

udmg-server test --file /opt/udmg/etc/udmg-server.hcl

Windows

udmg-server test --file "C:\Program Files\Stonebranch\UDMG Server\udmg-server.hcl"

license enroll

Validates and stores a new license key for this UDMG Server instance. The license is read from the file specified by --license, or from standard input if the flag is omitted.

Once validated, the license is persisted to the database and takes effect immediately, with no restart required. In a clustered deployment, all Cluster Nodes are notified and reload their license state automatically.

info

The license key is a single signed token. The file (or piped input) must contain only that token, with no surrounding text. If your license arrived as a file with Customer:, Environment:, License Expiry:, and License Key: header lines, include only the key value itself.

Command line syntax

udmg-server license enroll [--license <path>] [--config <path>]

Command-specific options

Option	Description	Required	Default
--license	Path to the license file.	No	Read from stdin

Examples

Enroll a license from a file:

Linux

udmg-server license enroll --license /path/to/license.key

Windows

udmg-server license enroll --license C:\path\to\license.key

Pipe a license from another command:

Linux

cat /path/to/license.key | udmg-server license enroll

Windows

type C:\path\to\license.key | udmg-server license enroll

Pass the license inline from a variable:

Linux

echo "$LICENSE" | udmg-server license enroll

Windows (CMD)

echo %LICENSE% | udmg-server license enroll

Enroll using a custom Configuration File:

Linux

udmg-server license enroll --license /path/to/license.key --config /opt/udmg/etc/udmg-server.hcl

Windows

udmg-server license enroll --license C:\path\to\license.key --config "C:\Program Files\Stonebranch\UDMG Server\udmg-server.hcl"

license status

Connects to the database, validates the stored license key, and prints a summary of the current license state, including customer, environment, issue date, and expiry information.

Command line syntax

udmg-server license status [--config <path>]

Command-specific options

This command takes only the global --config option.

Example

Linux

udmg-server license status --config /opt/udmg/etc/udmg-server.hcl

Windows

udmg-server license status --config "C:\Program Files\Stonebranch\UDMG Server\udmg-server.hcl"

migrate

Applies any pending UDMG Server database migrations. A migration applies required changes to the database schema, typically needed when upgrading to a more recent UDMG Server version. Run this after upgrading and before starting the service.

UDMG Server will apply pending migrations automatically on startup unless the auto_migrate argument has been disabled in the Configuration File.

danger

The migrate command modifies the UDMG Server database schema and is not rolled back automatically. Back up the database before running migrate, and do not interrupt the command once it starts.

Command line syntax

udmg-server migrate [--config <path>]

Command-specific options

This command takes only the global --config option.

Example

Linux

udmg-server migrate --config /opt/udmg/etc/udmg-server.hcl

Windows

udmg-server migrate --config "C:\Program Files\Stonebranch\UDMG Server\udmg-server.hcl"

migrations

Dumps the SQL files for any migrations that still need to be applied to a dump directory inside the work directory, without executing them. Useful for reviewing or troubleshooting. Do not apply the scripts without contacting Stonebranch support.

Command line syntax

udmg-server migrations [--config <path>]

Command-specific options

This command takes only the global --config option.

Example

Linux

udmg-server migrations --config /opt/udmg/etc/udmg-server.hcl

Windows

udmg-server migrations --config "C:\Program Files\Stonebranch\UDMG Server\udmg-server.hcl"

password-reset

Resets the password of the default Domain Administrator User (udmg.domain-admin) for the specified Secondary Domain. If --password is not provided, the command prompts for the new password interactively.

warning

This command resets the Domain Administrator password directly and does not require UDMG User authentication.

Command line syntax

udmg-server password-reset --domain <name> [--password <password>] [--config <path>]

Command-specific options

Option	Description	Required	Default
--domain	Name of the Secondary Domain whose default Domain Administrator (udmg.domain-admin) password is reset.	Yes	(none)
--password	New password for the default Domain Administrator User. If omitted, the command prompts for it.	No	Prompt

Example

Linux

udmg-server password-reset --domain example --config /opt/udmg/etc/udmg-server.hcl

Windows

udmg-server password-reset --domain example --config "C:\Program Files\Stonebranch\UDMG Server\udmg-server.hcl"

user-lock

Locks a User, disabling its login while preserving all of the User's data and permissions. Used to enforce exclusive use of LDAP or SSO for access, while retaining a secure fallback for system recovery.

Authentication is required: provide the password, or with --mnemonic the recovery phrase, of the User being locked, which by default is the System Administrator (udmg.sys-admin).

warning

Locking the only Admin with access can prevent administrative login. Before locking a User, confirm an alternative access path exists (LDAP, SSO, another Admin, or a recovery mnemonic). A locked User can be re-enabled with user-unlock.

Command line syntax

udmg-server user-lock [--username <name>] [--domain <name>] [--mnemonic <phrase>] [--config <path>]

Command-specific options

Option	Description	Required	Default
--username	Username to lock.	No	udmg.sys-admin
--domain	Domain name.	No	primary
--mnemonic	Mnemonic recovery phrase, used as an alternative to password authentication.	No	Prompt for password

Examples

Lock the default System Administrator User:

udmg-server user-lock

Lock a specific User:

udmg-server user-lock --username john.doe --domain primary

Lock using mnemonic authentication instead of a password:

udmg-server user-lock --mnemonic "word1 word2 ... word24"

user-unlock

Unlocks a User that was previously locked, re-enabling its login. Intended for emergency recovery scenarios when LDAP or SSO is unavailable.

Authentication is required: provide the password, or with --mnemonic the recovery phrase, of the User being unlocked, which by default is the System Administrator (udmg.sys-admin).

Command line syntax

udmg-server user-unlock [--username <name>] [--domain <name>] [--mnemonic <phrase>] [--config <path>]

Command-specific options

Option	Description	Required	Default
--username	Username to unlock.	No	udmg.sys-admin
--domain	Domain name.	No	primary
--mnemonic	Mnemonic recovery phrase, used as an alternative to password authentication.	No	Prompt for password

Examples

Unlock the default System Administrator User:

udmg-server user-unlock

Unlock a specific User:

udmg-server user-unlock --username john.doe --domain primary

Unlock using mnemonic authentication instead of a password:

udmg-server user-unlock --mnemonic "word1 word2 ... word24"

user-mnemonic

Generates or views a BIP39 mnemonic recovery phrase for a User. The mnemonic recovery phrase can be used as an alternative authentication method for emergency recovery operations such as unlocking a locked User.

Authentication is required: provide the password of the User, which by default is the System Administrator (udmg.sys-admin).

warning

A mnemonic recovery phrase grants access to the User. Store it securely. Generating a new phrase invalidates the existing one.

Command line syntax

udmg-server user-mnemonic [--username <name>] [--domain <name>] [--generate] [--config <path>]

Command-specific options

Option	Description	Required	Default
--username	Username to generate or view the mnemonic for.	No	udmg.sys-admin
--domain	Domain name.	No	primary
--generate	Generate a new mnemonic recovery phrase even if one already exists.	No	false

Examples

Generate a new mnemonic (if none exists) or view the existing mnemonic for the default System Administrator User:

udmg-server user-mnemonic

Generate a new mnemonic for the default System Administrator User, replacing any existing one:

udmg-server user-mnemonic --generate

Generate a new mnemonic for a specific User:

udmg-server user-mnemonic --username john.doe --domain primary --generate

passphrase-backup

Backs up the master passphrase key to the specified output file. Keep this backup secure: it is required to restore access to encrypted data.

Command line syntax

udmg-server passphrase-backup --output <path> [--config <path>]

Command-specific options

Option	Description	Required	Default
-f | --output	Output file path for the passphrase backup.	Yes	(none)

Example

Linux

udmg-server passphrase-backup --output /secure/udmg-passphrase.bak --config /opt/udmg/etc/udmg-server.hcl

Windows

udmg-server passphrase-backup --output C:\secure\udmg-passphrase.bak --config "C:\Program Files\Stonebranch\UDMG Server\udmg-server.hcl"

passphrase-restore

Restores the master passphrase key from a backup file created with passphrase-backup. Unless --force is supplied, the command prompts for confirmation before overwriting an existing passphrase.

danger

Restoring overwrites the existing passphrase. If the backup does not match the data currently in the database, encrypted data may become unreadable. Restore only a backup that matches the current database. See Disaster Recovery for the full recovery workflow.

info

This command requires no UDMG User authentication and needs the current K0 key (UDMG_SECURITY_PASSPHRASE_KEY) available to validate the backup.

Command line syntax

udmg-server passphrase-restore --input <path> [--force] [--config <path>]

Command-specific options

Option	Description	Required	Default
-i | --input	Input file path of the passphrase backup to restore.	Yes	(none)
-f | --force	Restore without prompting for confirmation.	No	false

Example

Linux

udmg-server passphrase-restore --input /secure/udmg-passphrase.bak --config /opt/udmg/etc/udmg-server.hcl

Windows

udmg-server passphrase-restore --input C:\secure\udmg-passphrase.bak --config "C:\Program Files\Stonebranch\UDMG Server\udmg-server.hcl"

rotate-k0

Rotates the K0 encryption key (the root key used to encrypt the master key, K1) without data loss. Use this when changing the K0 key for security reasons, transitioning from the hardcoded key to an environment variable, or when the K0 key may have been compromised. See Encryption Key Rotation for background.

By default, data is re-encrypted on first access. Use --reencrypt to immediately re-encrypt all data.

danger

An incorrect K0 rotation can make all encrypted data permanently unrecoverable. Do not run rotate-k0 in isolation; follow the complete procedure in Rotate K0 (Root Key).

info

This command requires no UDMG User authentication and needs the current K0 key, supplied with --old-key or via the UDMG_SECURITY_PASSPHRASE_KEY environment variable.

Command line syntax

udmg-server rotate-k0 --new-key <hex> [--old-key <hex>] [--reencrypt] [--force] [--skip-validation] [--config <path>]

Command-specific options

Option	Description	Required	Default
--new-key	New K0 key in hex format (32 bytes / 64 hex characters).	Yes	(none)
--old-key	Current K0 key in hex format. If omitted, the key from the UDMG_SECURITY_PASSPHRASE_KEY environment variable is used.	No, but only if UDMG_SECURITY_PASSPHRASE_KEY is set	(none)
--reencrypt	Force immediate re-encryption of all data.	No	false
--force	Skip the confirmation prompt.	No	false
--skip-validation	Skip validation of existing credentials during re-encryption.	No	false

Example

Rotate to a new K0 key, replacing the value below with your own 64-character hex key:

udmg-server rotate-k0 --new-key 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

rotate-master-key

Rotates the master encryption key (K1) used to encrypt sensitive data. Generates a new master key and increments the key version. Existing data is re-encrypted with the new key on first access, or immediately if --reencrypt is supplied.

warning

This is a sensitive operation. Before rotating, back up the passphrase with passphrase-backup and follow the procedure in Encryption Key Rotation. Immediate re-encryption (--reencrypt) may significantly impact system performance on large databases; prefer a maintenance window.

info

This command requires no UDMG User authentication and needs the current K0 key (UDMG_SECURITY_PASSPHRASE_KEY) available to re-encrypt the master key.

Command line syntax

udmg-server rotate-master-key [--reencrypt] [--force] [--skip-validation] [--config <path>]

Command-specific options

Option	Description	Required	Default
--reencrypt	Force immediate re-encryption of all data.	No	false
--force	Skip the confirmation prompt.	No	false
--skip-validation	Skip validation of existing credentials during re-encryption.	No	false

Example

Linux

udmg-server rotate-master-key --config /opt/udmg/etc/udmg-server.hcl

Windows

udmg-server rotate-master-key --config "C:\Program Files\Stonebranch\UDMG Server\udmg-server.hcl"

Standard Commands

The following commands are provided automatically by the CLI framework and are not specific to UDMG. They behave the same as in other command-line tools built on the same framework.

help

Displays help for the CLI or for a specific command, including its description, usage, available flags, and subcommands. This is equivalent to passing the --help (-h) flag.

Command line syntax

udmg-server help [command]

Examples

Show top-level help (lists all commands):

udmg-server help

Show help for a specific command or subcommand:

udmg-server help license enroll

completion

Generates a shell autocompletion script for the specified shell, so that pressing Tab completes udmg-server subcommands and flags. The supported shells are bash, zsh, fish, and powershell.

Command line syntax

udmg-server completion <shell>

info

This command only prints the completion script to standard output; it does not install or enable anything on its own. To use completion, load the script into your shell as shown below.

Enabling completion

The exact steps depend on your shell. Using bash as an example, enable completion in the current shell only (temporary):

source <(udmg-server completion bash)

Or enable it for all users, persistently (requires the bash-completion package):

udmg-server completion bash | sudo tee /etc/bash_completion.d/udmg-server > /dev/null

After enabling it, type udmg-server and press Tab twice to list the available commands.

For setup instructions specific to your shell, run:

udmg-server completion <shell> --help

(for example, udmg-server completion zsh --help).

Return Codes

The following return codes can be returned by a command:

Return Code	Description
0	Completed successfully.
1	An error occurred (for example, invalid arguments, configuration error, or a failure while processing the request). The error detail is written to standard error.