jmcore.cli_common

jmcore.cli_common

Common CLI components for JoinMarket NG.

This module provides reusable CLI helper functions to reduce duplication across jmwallet, maker, and taker CLIs.

Architecture: - Resolver functions: Take CLI args + settings and return resolved values - Setup functions: Common initialization (logging, settings, etc.) - Mnemonic loading: Unified mnemonic resolution from multiple sources

The CLI parameter definitions remain in each CLI module for now, but the resolution logic is centralized here. This approach: - Avoids typer dependency in jmcore - Allows each CLI to customize parameter names/help text if needed - Centralizes the complex resolution logic that was duplicated

Usage: from jmcore.cli_common import ( resolve_backend_settings, resolve_mnemonic, resolve_tor_settings, setup_cli, )

@app.command()
def my_command(
    network: Annotated[str | None, typer.Option("--network")] = None,
    rpc_url: Annotated[str | None, typer.Option("--rpc-url")] = None,
    ...
):
    settings = setup_cli(log_level, data_dir=data_dir)
    backend = resolve_backend_settings(settings, network=network, rpc_url=rpc_url, ...)

Classes

ResolvedBackendSettings dataclass

Resolved backend settings ready for use.

Source code in jmcore/src/jmcore/cli_common.py

@dataclass
class ResolvedBackendSettings:
    """Resolved backend settings ready for use."""

    network: str
    bitcoin_network: str
    backend_type: str
    rpc_url: str
    rpc_user: str
    rpc_password: str
    neutrino_url: str
    neutrino_add_peers: list[str]
    data_dir: Path
    scan_start_height: int | None = None
    neutrino_tls_cert: str | None = None
    neutrino_auth_token: str | None = None

Attributes

backend_type: str instance-attribute

bitcoin_network: str instance-attribute

data_dir: Path instance-attribute

network: str instance-attribute

neutrino_add_peers: list[str] instance-attribute

neutrino_auth_token: str | None = None class-attribute instance-attribute

neutrino_tls_cert: str | None = None class-attribute instance-attribute

neutrino_url: str instance-attribute

rpc_password: str instance-attribute

rpc_url: str instance-attribute

rpc_user: str instance-attribute

scan_start_height: int | None = None class-attribute instance-attribute

ResolvedMnemonic dataclass

Resolved mnemonic and BIP39 passphrase.

Note: bip39_passphrase is the optional BIP39 passphrase (13th/25th word), NOT the password used to decrypt an encrypted mnemonic file.

Source code in jmcore/src/jmcore/cli_common.py

@dataclass
class ResolvedMnemonic:
    """Resolved mnemonic and BIP39 passphrase.

    Note: bip39_passphrase is the optional BIP39 passphrase (13th/25th word),
    NOT the password used to decrypt an encrypted mnemonic file.
    """

    mnemonic: str
    bip39_passphrase: str
    source: str  # Where the mnemonic came from (for logging)
    creation_height: int | None = None  # Block height at wallet creation time

Attributes

bip39_passphrase: str instance-attribute

creation_height: int | None = None class-attribute instance-attribute

mnemonic: str instance-attribute

source: str instance-attribute

ResolvedTorSettings dataclass

Resolved Tor settings ready for use.

Source code in jmcore/src/jmcore/cli_common.py

@dataclass
class ResolvedTorSettings:
    """Resolved Tor settings ready for use."""

    socks_host: str
    socks_port: int
    control_enabled: bool
    control_host: str
    control_port: int
    cookie_path: Path | None

Attributes

control_enabled: bool instance-attribute

control_host: str instance-attribute

control_port: int instance-attribute

cookie_path: Path | None instance-attribute

socks_host: str instance-attribute

socks_port: int instance-attribute

Functions

create_backend(backend_settings: ResolvedBackendSettings, *, wallet_name: str | None = None, creation_height: int | None = None) -> Any

Create a backend instance based on resolved settings.

Args: backend_settings: Resolved backend settings wallet_name: Wallet name for descriptor_wallet backend creation_height: Block height at wallet creation time (used as scan start hint)

Returns: Backend instance (DescriptorWalletBackend or NeutrinoBackend)

Raises: ValueError: If backend type is invalid ImportError: If backend module not available

Source code in jmcore/src/jmcore/cli_common.py

def create_backend(
    backend_settings: ResolvedBackendSettings,
    *,
    wallet_name: str | None = None,
    creation_height: int | None = None,
) -> Any:
    """
    Create a backend instance based on resolved settings.

    Args:
        backend_settings: Resolved backend settings
        wallet_name: Wallet name for descriptor_wallet backend
        creation_height: Block height at wallet creation time (used as scan start hint)

    Returns:
        Backend instance (DescriptorWalletBackend or NeutrinoBackend)

    Raises:
        ValueError: If backend type is invalid
        ImportError: If backend module not available
    """
    # Import backends lazily to avoid circular imports
    from jmwallet.backends.descriptor_wallet import DescriptorWalletBackend
    from jmwallet.backends.neutrino import NeutrinoBackend

    backend_type = backend_settings.backend_type

    backend: DescriptorWalletBackend | NeutrinoBackend
    if backend_type == "neutrino":
        backend = NeutrinoBackend(
            neutrino_url=backend_settings.neutrino_url,
            network=backend_settings.bitcoin_network,
            scan_start_height=backend_settings.scan_start_height,
            add_peers=backend_settings.neutrino_add_peers,
            tls_cert_path=backend_settings.neutrino_tls_cert,
            auth_token=backend_settings.neutrino_auth_token,
        )
    elif backend_type == "descriptor_wallet":
        if not wallet_name:
            raise ValueError("wallet_name required for descriptor_wallet backend")
        backend = DescriptorWalletBackend(
            rpc_url=backend_settings.rpc_url,
            rpc_user=backend_settings.rpc_user,
            rpc_password=backend_settings.rpc_password,
            wallet_name=wallet_name,
        )
    else:
        raise ValueError(
            f"Invalid backend type: {backend_type}. Valid options: descriptor_wallet, neutrino"
        )

    if creation_height is not None:
        backend.set_wallet_creation_height(creation_height)

    return backend

generate_descriptor_wallet_name(mnemonic: str, network: str, passphrase: str = '') -> str

Generate a deterministic wallet name from mnemonic fingerprint.

Args: mnemonic: BIP39 mnemonic network: Network name (mainnet, testnet, etc.) passphrase: BIP39 passphrase

Returns: Wallet name in format "jm-{fingerprint}-{network}"

Source code in jmcore/src/jmcore/cli_common.py

def generate_descriptor_wallet_name(
    mnemonic: str,
    network: str,
    passphrase: str = "",
) -> str:
    """
    Generate a deterministic wallet name from mnemonic fingerprint.

    Args:
        mnemonic: BIP39 mnemonic
        network: Network name (mainnet, testnet, etc.)
        passphrase: BIP39 passphrase

    Returns:
        Wallet name in format "jm-{fingerprint}-{network}"
    """
    from jmwallet.backends.descriptor_wallet import (
        generate_wallet_name,
        get_mnemonic_fingerprint,
    )

    fingerprint = get_mnemonic_fingerprint(mnemonic, passphrase)
    return generate_wallet_name(fingerprint, network)

load_mnemonic_from_file(path: Path, password: str | None = None, auto_prompt: bool = True, max_prompt_attempts: int = 3) -> str

Load mnemonic from a file (plain text or Fernet encrypted).

Args: path: Path to mnemonic file password: Password for decrypting the file (NOT BIP39 passphrase) auto_prompt: If True, prompt for password when encrypted file is detected max_prompt_attempts: When interactively prompting for a password, how many times to retry on wrong-password errors before giving up. A value of 1 disables retry. Only applies to the interactive prompt path: explicit password arguments and passwords coming from the MNEMONIC_PASSWORD env var still fail fast on mismatch.

Returns: The mnemonic phrase

Raises: FileNotFoundError: If file doesn't exist ValueError: If file format is invalid or decryption fails

Source code in jmcore/src/jmcore/cli_common.py

def load_mnemonic_from_file(
    path: Path,
    password: str | None = None,
    auto_prompt: bool = True,
    max_prompt_attempts: int = 3,
) -> str:
    """
    Load mnemonic from a file (plain text or Fernet encrypted).

    Args:
        path: Path to mnemonic file
        password: Password for decrypting the file (NOT BIP39 passphrase)
        auto_prompt: If True, prompt for password when encrypted file is detected
        max_prompt_attempts: When interactively prompting for a password, how
            many times to retry on wrong-password errors before giving up.
            A value of 1 disables retry. Only applies to the interactive
            prompt path: explicit ``password`` arguments and passwords coming
            from the MNEMONIC_PASSWORD env var still fail fast on mismatch.

    Returns:
        The mnemonic phrase

    Raises:
        FileNotFoundError: If file doesn't exist
        ValueError: If file format is invalid or decryption fails
    """
    if not path.exists():
        raise FileNotFoundError(f"Mnemonic file not found: {path}")

    content = path.read_bytes()

    # Try to decode as plain text first
    try:
        text = content.decode("utf-8")
        # Check if it looks like a valid mnemonic (words separated by spaces)
        words = text.strip().split()
        if len(words) in (12, 15, 18, 21, 24) and all(w.isalpha() for w in words):
            return text.strip()
    except UnicodeDecodeError:
        pass

    # If not plain text, assume it's Fernet encrypted
    prompt_used = False
    if not password:
        password = os.environ.get("MNEMONIC_PASSWORD")
    if not password:
        if auto_prompt:
            password = _prompt_for_password(path)
            prompt_used = True
        else:
            raise ValueError(
                f"Mnemonic file appears to be encrypted. "
                f"Set MNEMONIC_PASSWORD env, wallet.mnemonic_password in config, "
                f"or use interactive prompt: {path}"
            )

    # Retry budget: only honoured for passwords the user is typing interactively
    # so that scripted callers with an explicit password/env var still fail
    # fast (issue #456 applies to the TUI's manual prompt path).
    attempts_remaining = max_prompt_attempts if prompt_used else 1
    mnemonic: str | None = None
    last_error: ValueError | None = None

    while attempts_remaining > 0:
        try:
            mnemonic = _decrypt_fernet_mnemonic(content, password, path)
            break
        except ValueError as e:
            last_error = e
            attempts_remaining -= 1
            # Only retry wrong-password errors from the interactive prompt.
            if not prompt_used or attempts_remaining <= 0:
                raise
            if "decryption failed" not in str(e).lower():
                # Corruption or encoding error -- pointless to retry.
                raise
            try:
                import typer

                typer.echo(f"Decryption failed. {attempts_remaining} attempt(s) remaining.")
            except ImportError:
                print(f"Decryption failed. {attempts_remaining} attempt(s) remaining.")
            password = _prompt_for_password(path)

    if mnemonic is None:
        # Should not happen because the loop either breaks or raises, but keep
        # type checkers happy and surface the last error.
        assert last_error is not None
        raise last_error

    # Basic validation
    words = mnemonic.split()
    if len(words) not in (12, 15, 18, 21, 24):
        raise ValueError(
            f"Invalid mnemonic: expected 12-24 words, got {len(words)}. "
            f"File may be corrupted or in wrong format: {path}"
        )

    return mnemonic

log_resolved_settings(backend: ResolvedBackendSettings, tor: ResolvedTorSettings | None = None, directory_servers: list[str] | None = None, mnemonic_source: str | None = None) -> None

Log resolved settings for debugging/transparency.

Args: backend: Resolved backend settings tor: Resolved Tor settings (optional) directory_servers: Resolved directory servers (optional) mnemonic_source: Source of mnemonic (optional)

Source code in jmcore/src/jmcore/cli_common.py

def log_resolved_settings(
    backend: ResolvedBackendSettings,
    tor: ResolvedTorSettings | None = None,
    directory_servers: list[str] | None = None,
    mnemonic_source: str | None = None,
) -> None:
    """
    Log resolved settings for debugging/transparency.

    Args:
        backend: Resolved backend settings
        tor: Resolved Tor settings (optional)
        directory_servers: Resolved directory servers (optional)
        mnemonic_source: Source of mnemonic (optional)
    """
    logger.info(f"Network: {backend.network}")
    if backend.bitcoin_network != backend.network:
        logger.info(f"Bitcoin network: {backend.bitcoin_network}")
    logger.info(f"Backend: {backend.backend_type}")

    if backend.backend_type == "neutrino":
        logger.info(f"Neutrino URL: {backend.neutrino_url}")
    else:
        logger.info(f"RPC URL: {backend.rpc_url}")
        if backend.rpc_user:
            logger.info(f"RPC user: {backend.rpc_user}")

    if tor:
        logger.info(f"Tor SOCKS: {tor.socks_host}:{tor.socks_port}")
        if tor.control_enabled:
            logger.info(f"Tor control: {tor.control_host}:{tor.control_port}")

    if directory_servers:
        logger.info(f"Directory servers: {len(directory_servers)} configured")

    if mnemonic_source:
        logger.info(f"Mnemonic loaded from: {mnemonic_source}")

resolve_backend_settings(settings: JoinMarketSettings, *, network: NetworkType | str | None = None, bitcoin_network: NetworkType | str | None = None, backend_type: str | None = None, rpc_url: str | None = None, rpc_user: str | None = None, rpc_password: str | None = None, neutrino_url: str | None = None, neutrino_tls_cert: str | None = None, neutrino_auth_token: str | None = None, data_dir: Path | None = None) -> ResolvedBackendSettings

Resolve backend settings with priority: CLI > Settings (env + config) > Defaults.

Args: settings: JoinMarketSettings instance network: CLI override for network bitcoin_network: CLI override for bitcoin network backend_type: CLI override for backend type rpc_url: CLI override for RPC URL rpc_user: CLI override for RPC user rpc_password: CLI override for RPC password neutrino_url: CLI override for Neutrino URL neutrino_tls_cert: CLI override for Neutrino TLS certificate path neutrino_auth_token: CLI override for Neutrino API auth token data_dir: CLI override for data directory

Returns: ResolvedBackendSettings with all values resolved

Source code in jmcore/src/jmcore/cli_common.py

def resolve_backend_settings(
    settings: JoinMarketSettings,
    *,
    network: NetworkType | str | None = None,
    bitcoin_network: NetworkType | str | None = None,
    backend_type: str | None = None,
    rpc_url: str | None = None,
    rpc_user: str | None = None,
    rpc_password: str | None = None,
    neutrino_url: str | None = None,
    neutrino_tls_cert: str | None = None,
    neutrino_auth_token: str | None = None,
    data_dir: Path | None = None,
) -> ResolvedBackendSettings:
    """
    Resolve backend settings with priority: CLI > Settings (env + config) > Defaults.

    Args:
        settings: JoinMarketSettings instance
        network: CLI override for network
        bitcoin_network: CLI override for bitcoin network
        backend_type: CLI override for backend type
        rpc_url: CLI override for RPC URL
        rpc_user: CLI override for RPC user
        rpc_password: CLI override for RPC password
        neutrino_url: CLI override for Neutrino URL
        neutrino_tls_cert: CLI override for Neutrino TLS certificate path
        neutrino_auth_token: CLI override for Neutrino API auth token
        data_dir: CLI override for data directory

    Returns:
        ResolvedBackendSettings with all values resolved
    """
    # Resolve network
    if network is not None:
        resolved_network = network.value if isinstance(network, NetworkType) else network
    else:
        resolved_network = settings.network_config.network.value

    # Resolve bitcoin network (defaults to network if not specified)
    if bitcoin_network is not None:
        resolved_bitcoin_network = (
            bitcoin_network.value if isinstance(bitcoin_network, NetworkType) else bitcoin_network
        )
    elif settings.network_config.bitcoin_network is not None:
        resolved_bitcoin_network = settings.network_config.bitcoin_network.value
    else:
        resolved_bitcoin_network = resolved_network

    # Resolve backend type
    resolved_backend_type = (
        backend_type if backend_type is not None else settings.bitcoin.backend_type
    )

    # Resolve RPC settings
    resolved_rpc_url = rpc_url if rpc_url is not None else settings.bitcoin.rpc_url
    resolved_rpc_user = rpc_user if rpc_user is not None else settings.bitcoin.rpc_user

    # Handle SecretStr for password
    if rpc_password is not None:
        resolved_rpc_password = rpc_password
    else:
        pwd = settings.bitcoin.rpc_password
        resolved_rpc_password = pwd.get_secret_value() if isinstance(pwd, SecretStr) else str(pwd)

    # Resolve Neutrino URL
    resolved_neutrino_url = (
        neutrino_url if neutrino_url is not None else settings.bitcoin.neutrino_url
    )

    # Resolve Neutrino add peers
    resolved_neutrino_add_peers = settings.get_neutrino_add_peers()

    # Resolve data directory (used both as the resolved value AND as a base
    # for resolving relative neutrino paths below).
    resolved_data_dir = data_dir if data_dir is not None else settings.get_data_dir()

    # Resolve Neutrino TLS cert path. Relative paths (e.g. "neutrino/tls.cert")
    # are resolved against the data directory so a single config.toml works
    # regardless of where the data dir lives.
    resolved_neutrino_tls_cert = _resolve_data_dir_path(
        neutrino_tls_cert if neutrino_tls_cert is not None else settings.bitcoin.neutrino_tls_cert,
        resolved_data_dir,
    )

    # Resolve Neutrino auth token (string, not a path).
    resolved_neutrino_auth_token = (
        neutrino_auth_token
        if neutrino_auth_token is not None
        else settings.bitcoin.neutrino_auth_token
    )

    # If only an auth token *file* is configured, read it now so the backend
    # never has to know where the data dir lives. Relative paths are resolved
    # against the data directory. A missing file is not an error: the default
    # path may simply not exist on insecure/legacy neutrino-api deployments.
    if not resolved_neutrino_auth_token and settings.bitcoin.neutrino_auth_token_file:
        token_path_str = _resolve_data_dir_path(
            settings.bitcoin.neutrino_auth_token_file, resolved_data_dir
        )
        if token_path_str is not None:
            token_path = Path(token_path_str)
            if token_path.is_file():
                try:
                    resolved_neutrino_auth_token = token_path.read_text().strip() or None
                except OSError as exc:
                    logger.warning(
                        f"Could not read neutrino auth token from {token_path_str}: {exc}"
                    )
            else:
                logger.debug(f"Neutrino auth token file not found at {token_path_str}; skipping")

    # neutrino-api serves HTTPS (with a self-signed certificate) whenever API
    # authentication is enabled. When a token is present but the URL is still
    # plain HTTP, upgrade it so requests don't fail with "client sent an HTTP
    # request to an HTTPS server". The backend pins the certificate on first
    # use (trust-on-first-use), so no manual cert wiring is required.
    if resolved_neutrino_auth_token and resolved_neutrino_url.startswith("http://"):
        upgraded_url = "https://" + resolved_neutrino_url.removeprefix("http://")
        logger.info(
            f"Neutrino auth token detected; upgrading URL from "
            f"{resolved_neutrino_url} to {upgraded_url}"
        )
        resolved_neutrino_url = upgraded_url

    return ResolvedBackendSettings(
        network=resolved_network,
        bitcoin_network=resolved_bitcoin_network,
        backend_type=resolved_backend_type,
        rpc_url=resolved_rpc_url,
        rpc_user=resolved_rpc_user,
        rpc_password=resolved_rpc_password,
        neutrino_url=resolved_neutrino_url,
        neutrino_add_peers=resolved_neutrino_add_peers,
        data_dir=resolved_data_dir,
        scan_start_height=settings.wallet.scan_start_height,
        neutrino_tls_cert=resolved_neutrino_tls_cert,
        neutrino_auth_token=resolved_neutrino_auth_token,
    )

resolve_bip39_passphrase(bip39_passphrase: str | None = None, prompt: bool = False) -> str

Resolve BIP39 passphrase from argument or prompt.

Args: bip39_passphrase: Direct passphrase value prompt: Whether to prompt interactively

Returns: Resolved passphrase (empty string if none)

Source code in jmcore/src/jmcore/cli_common.py

def resolve_bip39_passphrase(
    bip39_passphrase: str | None = None,
    prompt: bool = False,
) -> str:
    """
    Resolve BIP39 passphrase from argument or prompt.

    Args:
        bip39_passphrase: Direct passphrase value
        prompt: Whether to prompt interactively

    Returns:
        Resolved passphrase (empty string if none)
    """
    if bip39_passphrase:
        return bip39_passphrase

    if prompt:
        try:
            import typer

            return typer.prompt(
                "Enter BIP39 passphrase (leave empty for none)",
                default="",
                hide_input=True,
            )
        except ImportError:
            import getpass

            return getpass.getpass("Enter BIP39 passphrase (leave empty for none): ")

    return ""

resolve_directory_servers(settings: JoinMarketSettings, *, directory_servers: str | None = None, network: str | None = None) -> list[str]

Resolve directory servers with priority: CLI > Settings > Network defaults.

Args: settings: JoinMarketSettings instance directory_servers: CLI override (comma-separated) network: Network to use for defaults (if not in settings)

Returns: List of directory server addresses

Source code in jmcore/src/jmcore/cli_common.py

def resolve_directory_servers(
    settings: JoinMarketSettings,
    *,
    directory_servers: str | None = None,
    network: str | None = None,
) -> list[str]:
    """
    Resolve directory servers with priority: CLI > Settings > Network defaults.

    Args:
        settings: JoinMarketSettings instance
        directory_servers: CLI override (comma-separated)
        network: Network to use for defaults (if not in settings)

    Returns:
        List of directory server addresses
    """
    if directory_servers:
        return [s.strip() for s in directory_servers.split(",") if s.strip()]

    if settings.network_config.directory_servers:
        return settings.network_config.directory_servers

    # Use network-specific defaults
    from jmcore.settings import DEFAULT_DIRECTORY_SERVERS

    effective_network = network or settings.network_config.network.value
    return DEFAULT_DIRECTORY_SERVERS.get(effective_network, [])

resolve_mnemonic(settings: JoinMarketSettings, *, mnemonic: str | None = None, mnemonic_file: Path | None = None, password: str | None = None, bip39_passphrase: str | None = None, prompt_bip39_passphrase: bool = False, required: bool = True) -> ResolvedMnemonic | None

Resolve mnemonic from various sources with priority.

Mnemonic priority: 1. --mnemonic argument 2. --mnemonic-file argument 3. MNEMONIC_FILE environment variable 4. MNEMONIC environment variable 5. Config file wallet.mnemonic_file setting 6. Default wallet path (~/.joinmarket-ng/wallets/default.mnemonic)

BIP39 passphrase priority: 1. --bip39-passphrase argument 2. BIP39_PASSPHRASE environment variable 3. Config file wallet.bip39_passphrase setting 4. Interactive prompt (if --prompt-bip39-passphrase is set) 5. Empty string (default - no passphrase)

For encrypted mnemonic files, the password is resolved as: 1. Config file wallet.mnemonic_password setting (or password param) 2. MNEMONIC_PASSWORD environment variable 3. Interactive prompt (if auto_prompt is enabled)

Args: settings: JoinMarketSettings instance mnemonic: CLI mnemonic string mnemonic_file: CLI mnemonic file path password: Password for encrypted mnemonic file (NOT BIP39 passphrase) bip39_passphrase: BIP39 passphrase (13th/25th word, NOT file encryption password) prompt_bip39_passphrase: Whether to prompt for BIP39 passphrase interactively required: Whether mnemonic is required (raises error if not found)

Returns: ResolvedMnemonic or None if not required and not found

Raises: ValueError: If required but not found, or if loading fails

Source code in jmcore/src/jmcore/cli_common.py

def resolve_mnemonic(
    settings: JoinMarketSettings,
    *,
    mnemonic: str | None = None,
    mnemonic_file: Path | None = None,
    password: str | None = None,
    bip39_passphrase: str | None = None,
    prompt_bip39_passphrase: bool = False,
    required: bool = True,
) -> ResolvedMnemonic | None:
    """
    Resolve mnemonic from various sources with priority.

    Mnemonic priority:
    1. --mnemonic argument
    2. --mnemonic-file argument
    3. MNEMONIC_FILE environment variable
    4. MNEMONIC environment variable
    5. Config file wallet.mnemonic_file setting
    6. Default wallet path (~/.joinmarket-ng/wallets/default.mnemonic)

    BIP39 passphrase priority:
    1. --bip39-passphrase argument
    2. BIP39_PASSPHRASE environment variable
    3. Config file wallet.bip39_passphrase setting
    4. Interactive prompt (if --prompt-bip39-passphrase is set)
    5. Empty string (default - no passphrase)

    For encrypted mnemonic files, the password is resolved as:
    1. Config file wallet.mnemonic_password setting (or password param)
    2. MNEMONIC_PASSWORD environment variable
    3. Interactive prompt (if auto_prompt is enabled)

    Args:
        settings: JoinMarketSettings instance
        mnemonic: CLI mnemonic string
        mnemonic_file: CLI mnemonic file path
        password: Password for encrypted mnemonic file (NOT BIP39 passphrase)
        bip39_passphrase: BIP39 passphrase (13th/25th word, NOT file encryption password)
        prompt_bip39_passphrase: Whether to prompt for BIP39 passphrase interactively
        required: Whether mnemonic is required (raises error if not found)

    Returns:
        ResolvedMnemonic or None if not required and not found

    Raises:
        ValueError: If required but not found, or if loading fails
    """
    resolved_mnemonic: str | None = None
    source = ""
    mnemonic_file_path: Path | None = None  # Track file path for .meta loading

    # Resolve the encryption password once for all file-based paths so that
    # ``wallet.mnemonic_password`` from config.toml works no matter whether
    # the file path came from --mnemonic-file, MNEMONIC_FILE env, the config,
    # or the default wallet location. Without this fallback an explicit
    # --mnemonic-file (as used by the systemd unit template documented in
    # docs/README-maker.md) silently bypasses the config password and falls
    # through to an interactive prompt, which fails under systemd.
    # See issue #498.
    effective_password = password
    if effective_password is None and settings.wallet.mnemonic_password:
        effective_password = settings.wallet.mnemonic_password.get_secret_value()

    # Priority 1: Direct mnemonic argument
    if mnemonic:
        resolved_mnemonic = mnemonic
        source = "--mnemonic argument"

    # Priority 2: Mnemonic file argument
    elif mnemonic_file:
        resolved_mnemonic = load_mnemonic_from_file(mnemonic_file, effective_password)
        mnemonic_file_path = mnemonic_file
        source = f"--mnemonic-file ({mnemonic_file})"

    # Priority 3: MNEMONIC_FILE environment variable
    elif env_file := os.environ.get("MNEMONIC_FILE"):
        env_path = Path(env_file)
        resolved_mnemonic = load_mnemonic_from_file(env_path, effective_password)
        mnemonic_file_path = env_path
        source = f"MNEMONIC_FILE env ({env_path})"

    # Priority 4: MNEMONIC environment variable
    elif env_mnemonic := os.environ.get("MNEMONIC"):
        resolved_mnemonic = env_mnemonic
        source = "MNEMONIC env"

    # Priority 5: Config file wallet.mnemonic_file
    elif settings.wallet.mnemonic_file:
        config_path = Path(settings.wallet.mnemonic_file)
        resolved_mnemonic = load_mnemonic_from_file(config_path, effective_password)
        mnemonic_file_path = config_path
        source = f"config file ({config_path})"

    # Priority 6: Default wallet path
    else:
        default_wallet = settings.get_data_dir() / "wallets" / "default.mnemonic"
        if default_wallet.exists():
            resolved_mnemonic = load_mnemonic_from_file(default_wallet, effective_password)
            mnemonic_file_path = default_wallet
            source = f"default wallet ({default_wallet})"

    if resolved_mnemonic is None:
        if required:
            raise ValueError(
                "No mnemonic provided. Use --mnemonic-file, "
                "MNEMONIC env, or set wallet.mnemonic_file in config."
            )
        return None

    # Resolve BIP39 passphrase
    # Priority: CLI arg > env var > config > prompt > empty
    resolved_passphrase = ""
    if bip39_passphrase:
        resolved_passphrase = bip39_passphrase
    elif env_passphrase := os.environ.get("BIP39_PASSPHRASE"):
        resolved_passphrase = env_passphrase
    elif settings.wallet.bip39_passphrase is not None:
        resolved_passphrase = settings.wallet.bip39_passphrase.get_secret_value()
    elif prompt_bip39_passphrase:
        # Lazy import typer only when needed for prompting
        try:
            import typer

            resolved_passphrase = typer.prompt(
                "Enter BIP39 passphrase (leave empty for none)",
                default="",
                hide_input=True,
            )
        except ImportError:
            # Fall back to getpass if typer not available
            import getpass

            resolved_passphrase = getpass.getpass("Enter BIP39 passphrase (leave empty for none): ")

    # Load wallet metadata (creation_height) from companion .meta file
    creation_height: int | None = None
    if mnemonic_file_path is not None:
        try:
            from jmwallet.cli.mnemonic import load_mnemonic_meta

            meta = load_mnemonic_meta(mnemonic_file_path)
            raw_creation_height = meta.get("creation_height")
            if isinstance(raw_creation_height, int) and not isinstance(raw_creation_height, bool):
                if raw_creation_height >= 0:
                    creation_height = raw_creation_height
                    logger.debug(f"Loaded wallet creation height: {creation_height}")
                else:
                    logger.warning(
                        f"Ignoring negative creation_height in metadata: {raw_creation_height}"
                    )
            elif raw_creation_height is not None:
                logger.warning(
                    f"Ignoring non-integer creation_height in metadata: {raw_creation_height!r}"
                )
        except Exception as exc:
            logger.debug(f"Could not load mnemonic metadata: {exc}")

    return ResolvedMnemonic(
        mnemonic=resolved_mnemonic,
        bip39_passphrase=resolved_passphrase,
        source=source,
        creation_height=creation_height,
    )

resolve_tor_settings(settings: JoinMarketSettings, *, socks_host: str | None = None, socks_port: int | None = None, control_host: str | None = None, control_port: int | None = None, cookie_path: Path | None = None, disable_control: bool = False) -> ResolvedTorSettings

Resolve Tor settings with priority: CLI > Settings > Defaults.

Args: settings: JoinMarketSettings instance socks_host: CLI override for SOCKS host socks_port: CLI override for SOCKS port control_host: CLI override for control host control_port: CLI override for control port cookie_path: CLI override for cookie path disable_control: Whether to disable Tor control

Returns: ResolvedTorSettings with all values resolved

Source code in jmcore/src/jmcore/cli_common.py

def resolve_tor_settings(
    settings: JoinMarketSettings,
    *,
    socks_host: str | None = None,
    socks_port: int | None = None,
    control_host: str | None = None,
    control_port: int | None = None,
    cookie_path: Path | None = None,
    disable_control: bool = False,
) -> ResolvedTorSettings:
    """
    Resolve Tor settings with priority: CLI > Settings > Defaults.

    Args:
        settings: JoinMarketSettings instance
        socks_host: CLI override for SOCKS host
        socks_port: CLI override for SOCKS port
        control_host: CLI override for control host
        control_port: CLI override for control port
        cookie_path: CLI override for cookie path
        disable_control: Whether to disable Tor control

    Returns:
        ResolvedTorSettings with all values resolved
    """
    resolved_socks_host = socks_host if socks_host is not None else settings.tor.socks_host
    resolved_socks_port = socks_port if socks_port is not None else settings.tor.socks_port

    # Control port settings
    control_enabled = not disable_control and settings.tor.control_enabled

    resolved_control_host = control_host if control_host is not None else settings.tor.control_host
    resolved_control_port = control_port if control_port is not None else settings.tor.control_port

    resolved_cookie_path: Path | None = None
    if cookie_path is not None:
        resolved_cookie_path = cookie_path
    elif settings.tor.cookie_path:
        resolved_cookie_path = Path(settings.tor.cookie_path)

    return ResolvedTorSettings(
        socks_host=resolved_socks_host,
        socks_port=resolved_socks_port,
        control_enabled=control_enabled,
        control_host=resolved_control_host,
        control_port=resolved_control_port,
        cookie_path=resolved_cookie_path,
    )

setup_cli(log_level: str | None = None, data_dir: Path | None = None) -> JoinMarketSettings

Common CLI setup: reset settings cache, configure logging, return settings.

Log level priority: CLI argument > settings (env/config) > default "INFO"

When data_dir is provided (typically from a CLI --data-dir flag), the JOINMARKET_DATA_DIR environment variable is set to that path BEFORE settings are loaded. This ensures that <data_dir>/config.toml is read, that wallet.mnemonic_file defaults resolve to that data directory, and that any other env-driven defaults (paths, etc.) point at the user-specified data directory.

Args: log_level: Log level override from CLI (None means use settings) data_dir: Optional CLI override for data directory. When provided, JOINMARKET_DATA_DIR is set in os.environ so that all subsequent settings-loading code paths agree on the same data directory.

Returns: JoinMarketSettings instance with all sources loaded

Source code in jmcore/src/jmcore/cli_common.py

def setup_cli(
    log_level: str | None = None,
    data_dir: Path | None = None,
) -> JoinMarketSettings:
    """
    Common CLI setup: reset settings cache, configure logging, return settings.

    Log level priority: CLI argument > settings (env/config) > default "INFO"

    When ``data_dir`` is provided (typically from a CLI ``--data-dir`` flag),
    the ``JOINMARKET_DATA_DIR`` environment variable is set to that path
    BEFORE settings are loaded. This ensures that ``<data_dir>/config.toml``
    is read, that ``wallet.mnemonic_file`` defaults resolve to that data
    directory, and that any other env-driven defaults (paths, etc.) point at
    the user-specified data directory.

    Args:
        log_level: Log level override from CLI (None means use settings)
        data_dir: Optional CLI override for data directory. When provided,
            ``JOINMARKET_DATA_DIR`` is set in ``os.environ`` so that all
            subsequent settings-loading code paths agree on the same data
            directory.

    Returns:
        JoinMarketSettings instance with all sources loaded
    """
    if data_dir is not None:
        # Honour the user's CLI choice across every code path that reads
        # JOINMARKET_DATA_DIR (settings, paths, subprocesses, etc.).
        os.environ["JOINMARKET_DATA_DIR"] = str(data_dir)

    # Apply an early logging configuration before loading settings so that
    # informational messages emitted while parsing config.toml (e.g.
    # "Loaded config from ...") honor the caller's intended log level.
    # Priority for this early pass: CLI arg > LOGGING__LEVEL env > INFO default.
    early_level = log_level or os.environ.get("LOGGING__LEVEL") or "INFO"
    setup_logging(early_level)

    reset_settings()
    settings = get_settings()

    # Resolve log level: CLI > settings > default
    effective_log_level = log_level if log_level is not None else settings.logging.level
    setup_logging(effective_log_level)

    return settings

setup_logging(level: str = 'INFO') -> None

Configure loguru logging with consistent format.

Args: level: Log level (TRACE, DEBUG, INFO, WARNING, ERROR)

Source code in jmcore/src/jmcore/cli_common.py

def setup_logging(level: str = "INFO") -> None:
    """
    Configure loguru logging with consistent format.

    Args:
        level: Log level (TRACE, DEBUG, INFO, WARNING, ERROR)
    """
    logger.remove()
    logger.add(
        sys.stderr,
        format=(
            "<green>{time:YYYY-MM-DD HH:mm:ss}</green> | "
            "<level>{level: <8}</level> | "
            "<cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - "
            "<level>{message}</level>"
        ),
        level=level.upper(),
        colorize=True,
    )