Run

mininterface.run(env_or_list=None, ask_on_empty_cli=False, title='', config_file=True, add_verbosity=True, ask_for_missing=True, interface=None, args=None, options=None, **kwargs)

The main access, start here. Wrap your configuration dataclass into run to access the interface. An interface is chosen automatically, with the preference of the graphical one, regressed to a text interface for machines without display. Besides, if given a configuration dataclass, the function enriches it with the CLI commands and possibly with the default from a config file if such exists. It searches the config file in the current working directory, with the program name ending on .yaml, ex: program.py will fetch ./program.yaml.

Parameters:

Name	Type	Description	Default
env_or_list	Type[EnvClass] | list[Type[Command]] | None	dataclass Dataclass with the configuration. Their values will be modified with the CLI arguments. list of Commands let you create multiple commands within a single program, each with unique options. None You need just the dialogs, no CLI/config file parsing.	None
ask_on_empty_cli	bool	If program was launched with no arguments (empty CLI), invokes self.form() to edit the fields. (Withdrawn when ask_for_missing happens.) @dataclass class Env: number: int = 3 text: str = "" m = run(Env, ask_on_empty=True) $ program.py # omitting all parameters # Dialog for `number` and `text` appears $ program.py --number 3 # No dialog appears	False
title	str	The main title. If not set, taken from prog or program name.	''
config_file	Path | str | bool	File to load YAML to be merged with the configuration. You do not have to re-define all the settings in the config file, you can choose a few. If set to True (default), we try to find one in the current working dir, whose name stem is the same as the program's. Ex: program.py will search for program.yaml. If False, no config file is used.	True
add_verbosity	bool	Adds the verbose flag that automatically sets the level to logging.INFO (-v) or logging.DEBUG (-vv). import logging logger = logging.getLogger(__name__) m = run(Env, add_verbosity=True) logger.info("Info shown") # needs `-v` or `--verbose` logger.debug("Debug not shown") # needs `-vv` # $ program.py --verbose # Info shown $ program.py --verbose Info shown	True
ask_for_missing	bool	If some required fields are missing at startup, we ask for them in a UI instead of program exit. @dataclass class Env: required_number: int m = run(Env, ask_for_missing=True) $ program.py # omitting --required-number # Dialog for `required_number` appears	True
interface	Type[Mininterface] | Literal['gui'] | Literal['tui'] | Literal['text'] | None	Which interface to prefer. By default, we use the GUI, the fallback is the TUI. You may write "gui" or "tui" literal or pass a specific Mininterface type, see the full list of possible interfaces. If not set, we look also for an environment variable MININTERFACE_INTERFACE and in the config file.	None
args	Optional[Sequence[str]]	Parse arguments from a sequence instead of the command line.	None
options	Optional[MininterfaceOptions]	Default options. These might be further modified by the 'mininterface' section in the config file.	None

Kwargs: The same as for argparse.ArgumentParser.

Returns:

Type	Description
Mininterface[EnvClass]	An interface, ready to be used.

You cay context manager the function by a with statement. The stdout will be redirected to the interface (ex. a GUI window).

from dataclasses import dataclass
from mininterface import run

@dataclass
class Env:
    my_number: int = 4

with run(Env) as m:
    print(f"Your important number is {m.env.my_number}")
    boolean = m.is_yes("Is that alright?")