mud_server.cli

Command-line interface for PipeWorks MUD Server.

Provides CLI commands for server management: - init-db: Initialize the database schema - create-superuser: Create a superuser account interactively or via environment variables - import-policy-artifact: Import a published artifact into canonical policy DB rows - run: Start the MUD server (API and web UI)

Usage:

mud-server init-db mud-server init-db –skip-policy-import mud-server create-superuser mud-server import-policy-artifact –artifact-path PATH mud-server run [–port PORT] [–host HOST]

Environment Variables:

MUD_ADMIN_USER: Username for superuser (used by init-db if set) MUD_ADMIN_PASSWORD: Password for superuser (used by init-db if set) MUD_HOST: Host to bind API server (default: 0.0.0.0) MUD_PORT: Port for API server (default: 8000, auto-discovers if in use)

Functions

get_superuser_credentials_from_env()	Get superuser credentials from environment variables.
prompt_for_credentials()	Interactively prompt for superuser credentials with password policy enforcement.
cmd_init_db(args)	Initialize the database schema.
cmd_create_superuser(args)	Create a superuser account.
cmd_import_policy_artifact(args)	Import one publish artifact into canonical DB policy state.
cmd_run(args)	Run the MUD server (API + WebUI).
main()	Main entry point for the CLI.

Module Contents

mud_server.cli.get_superuser_credentials_from_env()

Get superuser credentials from environment variables.

Returns:

Tuple of (username, password) if both MUD_ADMIN_USER and MUD_ADMIN_PASSWORD are set. None if either is missing.

Return type:

tuple[str, str] | None

mud_server.cli.prompt_for_credentials()

Interactively prompt for superuser credentials with password policy enforcement.

This function guides the user through creating secure credentials by: 1. Validating username length (2-20 characters) 2. Displaying password requirements before input 3. Validating password against the STANDARD security policy 4. Requiring password confirmation

The STANDARD password policy requires: - Minimum 12 characters - Not a commonly used password - No sequential characters (abc, 123) - No excessive repeated characters (aaa)

Returns:

Tuple of (username, password) that meet security requirements.

Raises:

SystemExit – If the user cancels (Ctrl+C) during input.

Return type:

tuple[str, str]

See also

mud_server.api.password_policy: Full policy configuration details.

mud_server.cli.cmd_init_db(args)

Initialize the database schema.

Initializes schema and, by default, imports/activates canonical world policy objects for discovered world packages. This avoids runtime reliance on startup-time legacy file bootstrap.

Returns:

0 on success, 1 on error

Return type:

int

mud_server.cli.cmd_create_superuser(args)

Create a superuser account.

Checks for MUD_ADMIN_USER and MUD_ADMIN_PASSWORD environment variables first. If not set, prompts interactively for credentials.

Returns:

0 on success, 1 on error

Return type:

int

mud_server.cli.cmd_import_policy_artifact(args)

Import one publish artifact into canonical DB policy state.

mud_server.cli.cmd_run(args)

Run the MUD server (API + WebUI).

This is the main entry point for starting the MUD server. It initializes the database if needed, then starts the API server. The WebUI is served directly by FastAPI.

Port Auto-Discovery:

If the configured port is already in use, the server will automatically find an available port in a predefined range: - API server: 8000-8099

Configuration Priority:

1. CLI arguments (–port, –host)

2. Environment variables (MUD_PORT, MUD_HOST)

3. Default values (8000 for API, 0.0.0.0 for host)

Parameters:

args (argparse.Namespace) – Parsed command-line arguments from argparse. Expected attributes: - port (int | None): API server port override - host (str | None): Host interface to bind the server

Returns:

0 on successful execution or clean shutdown (Ctrl+C) 1 on error during startup

Return type:

int

Example

# Start with default ports mud-server run

# Specify custom port mud-server run –port 9000

Note

The API server runs in the main process.

mud_server.cli.main()

Main entry point for the CLI.