backlogops-cli 0.1__py3-none-any.whl → 0.2__py3-none-any.whl

backlogops_cli/_command_io.py

@@ -12,21 +12,60 @@ underscore in the module name keeps it out of the command listing.
 
 import argparse
 import sys
+from pathlib import Path
 from collections.abc import Callable
-from typing import Optional
+from typing import Optional, TextIO
 import argcomplete
+from backlogops_cli._migrate_warn import (
+    CliMigrateWarnHook, CliPresetMigrateWarnHook)
+from backlogops_cli.bloc_version_reporter import BloCliVersionReporter
 from backlogops import (
-    BacklogReleases, FormatRules, InputFormatConfig, OutputFormatConfig,
-    ReleaseChanges, ReleaseDateChanges, format_content_changes,
-    format_date_changes, read_available_teams, read_backlog_releases,
-    resolve_input_config, resolve_output_config, write_backlog_releases,
-    write_content_changes, write_date_changes)
+    BacklogOpsConfig, BacklogReleases, FileExistsCb, FormatRules, Levels,
+    ReleaseChanges, ReleaseDateChanges, allow_overwrite,
+    format_content_changes, format_date_changes, get_backlog_ops_config,
+    read_backlog_releases, resolve_input_config, resolve_output_config,
+    write_backlog_releases, write_content_changes, write_date_changes)
+
+
+def overwrite_callback(force: bool, in_stream: Optional[TextIO] = None,
+                       out_stream: Optional[TextIO] = None) -> FileExistsCb:
+    """Return a file-exists callback for writing CLI output files.
+
+    A writer calls the returned callback only when the target file
+    already exists. With ``force`` the overwrite is allowed silently.
+    Otherwise the user is asked on ``out_stream``/``in_stream`` and the
+    overwrite is allowed only on an explicit yes; any other answer, an
+    empty answer, or end of input refuses it with ``FileExistsError``.
+
+    Args:
+        force: Allow the overwrite without asking when True.
+        in_stream: Stream the answer is read from, or None for stdin.
+        out_stream: Stream the prompt is written to, or None for stdout.
+
+    Returns:
+        A callback suitable as ``file_exists_callback`` for the writers.
+    """
+    if force:
+        return allow_overwrite
+    reader = sys.stdin if in_stream is None else in_stream
+    writer = sys.stdout if out_stream is None else out_stream
+
+    def ask(file_name: str) -> None:
+        """Ask whether to overwrite ``file_name``; raise when refused."""
+        prompt = f'Output file {file_name} already exists. Overwrite? [y/N]: '
+        print(prompt, end='', file=writer)
+        writer.flush()
+        if reader.readline().strip().lower() in ('y', 'yes'):
+            return
+        raise FileExistsError(f'Did not overwrite existing file {file_name}.')
+    return ask
 
 
 def parsed_args(parser: argparse.ArgumentParser,
                 args: Optional[list[str]]) -> argparse.Namespace:
     """Enable shell completion and parse the command line arguments."""
     argcomplete.autocomplete(parser)
+    BloCliVersionReporter().check_if_unsupported_python()
     return parser.parse_args(args)
 
 
@@ -38,85 +77,205 @@ def add_input_args(parser: argparse.ArgumentParser) -> None:
                         help='Input format: a config file or a preset name.')
 
 
-def _input_presets(io_config: Optional[str]
-                   ) -> Optional[dict[str, InputFormatConfig]]:
-    """Return the named input presets from a presets file, if given."""
-    if io_config is None:
+def add_config_arg(parser: argparse.ArgumentParser) -> None:
+    """Add the ``-c``/``--config`` backlog-ops configuration argument.
+
+    The configuration file holds the workforce, the named input and output
+    presets, the levels and the global status map. Without ``-c`` the file
+    is discovered the same way as the GUI.
+    """
+    parser.add_argument('-c', '--config', dest='config',
+                        help='Backlog-ops configuration file (workforce, '
+                        'named presets, levels, status map). Without -c the '
+                        'file is found from $BACKLOGOPS_CFG, else '
+                        'backlogops.cfg in $BACKLOGOPS_DIR, else '
+                        '$HOME/.backlogops.cfg.')
+
+
+def _resolve_config(parsed: argparse.Namespace) -> BacklogOpsConfig:
+    """Return the backlog-ops configuration from ``-c`` or by discovery.
+
+    With ``-c`` the named file is read; an old file triggers a migration
+    warning. Without ``-c`` the file is discovered the same way as the GUI
+    (``$BACKLOGOPS_CFG``, then ``backlogops.cfg`` in ``$BACKLOGOPS_DIR``,
+    then ``$HOME/.backlogops.cfg``).
+
+    Raises:
+        ValueError: If ``-c`` names a file that does not exist.
+        RuntimeError: If no ``-c`` is given and no file is discovered.
+    """
+    config_file = parsed.config
+    if config_file is not None:
+        if not Path(config_file).is_file():
+            raise ValueError(f'Configuration file not found: {config_file}')
+        return get_backlog_ops_config(config_file, sys.stderr,
+                                      auto_ch_hook=CliMigrateWarnHook())
+    return get_backlog_ops_config(None, sys.stderr,
+                                  auto_ch_hook=CliMigrateWarnHook())
+
+
+def required_config(parsed: argparse.Namespace) -> BacklogOpsConfig:
+    """Return the configuration, reporting a missing one as a ValueError.
+
+    Used by commands that cannot work without a configuration, such as the
+    estimate command, which needs the workforce.
+    """
+    try:
+        return _resolve_config(parsed)
+    except RuntimeError as error:
+        raise ValueError(str(error)) from error
+
+
+def optional_config(parsed: argparse.Namespace) -> Optional[BacklogOpsConfig]:
+    """Return the configuration, or None with a note when none is found.
+
+    Used by commands that fall back to the built-in defaults (formats
+    inferred from the file name, no presets) when no configuration file is
+    available.
+    """
+    try:
+        return _resolve_config(parsed)
+    except RuntimeError:
+        print('No backlog-ops configuration file found; using built-in '
+              'defaults.', file=sys.stderr)
         return None
-    return read_available_teams(io_config, sys.stderr).input_configs
 
 
-def read_input(parsed: argparse.Namespace) -> BacklogReleases:
+def io_levels(config: Optional[BacklogOpsConfig]) -> Optional[Levels]:
+    """Return the configured levels from ``config``, or None.
+
+    Args:
+        config: The resolved backlog-ops configuration, or None to use the
+            default levels.
+
+    Returns:
+        The levels configured in ``config``, or None when no configuration
+        is given.
+    """
+    return config.get_levels() if config is not None else None
+
+
+def read_input(parsed: argparse.Namespace,
+               config: Optional[BacklogOpsConfig]) -> BacklogReleases:
     """Read and validate the backlog and releases from the input file.
 
     The input format is resolved from the ``--input-config`` value, which
     may be empty (inferred from the file name), a preset name looked up in
-    the presets file given by ``--io-config``, or a config file path.
+    ``config``, or a config file path. When ``config`` is given its levels
+    and its library-wide status input map are honoured while reading the
+    items; the input configuration's own status map overrides the global
+    one per name.
 
     Args:
         parsed: Parsed command line arguments holding the input options
-            added by :func:`add_input_args` and, optionally, the
-            ``--io-config`` option added by :func:`add_output_args`.
+            added by :func:`add_input_args`.
+        config: The resolved backlog-ops configuration, or None to use the
+            built-in defaults.
 
     Returns:
         The validated backlog and releases read from the input file.
     """
-    io_config = getattr(parsed, 'io_config', None)
-    presets = _input_presets(io_config)
-    config = resolve_input_config(parsed.input_config, data_file=parsed.input,
-                                  presets=presets)
-    data = read_backlog_releases(parsed.input, config)
+    presets = config.input_configs if config is not None else None
+    levels = config.get_levels() if config is not None else None
+    status_map = (config.get_status_input_map() if config is not None
+                  else None)
+    in_config = resolve_input_config(parsed.input_config,
+                                     data_file=parsed.input, presets=presets,
+                                     auto_ch_hook=CliPresetMigrateWarnHook())
+    data = read_backlog_releases(parsed.input, in_config, levels, status_map)
     data.check_consistency(sys.stderr)
     return data
 
 
+def add_force_arg(parser: argparse.ArgumentParser) -> None:
+    """Add the force flag that overwrites output files without asking."""
+    parser.add_argument('-f', '--force', dest='force', action='store_true',
+                        help='Overwrite existing output files without '
+                        'asking.')
+
+
 def add_output_args(parser: argparse.ArgumentParser) -> None:
     """Add the output-file, output-config and ordering arguments."""
     parser.add_argument('-o', '--output', dest='output', required=True,
                         help='Output data file to create.')
     parser.add_argument('-O', '--output-config', dest='output_config',
                         help='Output format: a config file or a preset name.')
-    parser.add_argument('--io-config', dest='io_config',
-                        help='Configuration file holding the named presets '
-                        '(by default the teams configuration file).')
     parser.add_argument('--releases-first', dest='releases_first',
                         action='store_true',
                         help='Write the releases before the backlog.')
+    add_force_arg(parser)
 
 
-def _output_presets(io_config: Optional[str]
-                    ) -> Optional[dict[str, OutputFormatConfig]]:
-    """Return the named output presets from a presets file, if given."""
-    if io_config is None:
-        return None
-    return read_available_teams(io_config, sys.stderr).output_configs
+def build_io_parser(description: str, *, with_input: bool = True,
+                    with_config: bool = True,
+                    with_output: bool = True) -> argparse.ArgumentParser:
+    """Create a parser with the common input, config and output options.
+
+    Most data commands read a file, take the backlog-ops configuration,
+    and write a file, so this builds the parser with those option groups
+    already added. A command adds only its own extra options to the
+    returned parser. A group is left out when its flag is False, for a
+    command that does not read (or does not write) a backlog file.
+
+    Args:
+        description: The command description shown in the help text.
+        with_input: Add the input-file and input-config options.
+        with_config: Add the ``-c`` backlog-ops configuration option.
+        with_output: Add the output-file, output-config, ordering and
+            force options.
+
+    Returns:
+        The parser with the requested common options added.
+    """
+    parser = argparse.ArgumentParser(description=description)
+    if with_input:
+        add_input_args(parser)
+    if with_config:
+        add_config_arg(parser)
+    if with_output:
+        add_output_args(parser)
+    return parser
 
 
-def _write_output(parsed: argparse.Namespace, data: BacklogReleases) -> None:
+def _write_output(parsed: argparse.Namespace,
+                  config: Optional[BacklogOpsConfig],
+                  data: BacklogReleases) -> None:
     """Write the backlog and releases to the configured output file."""
-    presets = _output_presets(parsed.io_config)
-    config = resolve_output_config(parsed.output_config,
-                                   data_file=parsed.output, presets=presets)
+    presets = config.output_configs if config is not None else None
+    out_config = resolve_output_config(parsed.output_config,
+                                       data_file=parsed.output,
+                                       presets=presets,
+                                       auto_ch_hook=CliPresetMigrateWarnHook())
     rules = FormatRules(backlog_first=not parsed.releases_first)
-    write_backlog_releases(data, parsed.output, config, rules)
+    write_backlog_releases(data, parsed.output, out_config, rules,
+                           levels=io_levels(config),
+                           file_exists_callback=overwrite_callback(
+                               parsed.force))
 
 
 def run_write(parsed: argparse.Namespace,
-              data_source: Callable[[], BacklogReleases]) -> int:
+              data_source: Callable[[Optional[BacklogOpsConfig]],
+                                    BacklogReleases]) -> int:
     """Build the data, write it to the output file, and report the result.
 
+    The configuration is resolved once from ``-c`` or by discovery, falling
+    back to the built-in defaults when none is found.
+
     Args:
         parsed: Parsed command line arguments holding the output options
-            added by :func:`add_output_args`.
-        data_source: Callable that returns the backlog and releases to
-            write. It is called inside the error handling so that reading
-            failures are reported like writing failures.
+            added by :func:`add_output_args` and the ``-c`` option added by
+            :func:`add_config_arg`.
+        data_source: Callable that receives the resolved configuration (or
+            None) and returns the backlog and releases to write. It is
+            called inside the error handling so that reading failures are
+            reported like writing failures.
 
     Returns:
         ``0`` on success, ``1`` when the data cannot be built or written.
     """
     try:
-        _write_output(parsed, data_source())
+        config = optional_config(parsed)
+        _write_output(parsed, config, data_source(config))
     except (ValueError, TypeError, KeyError, OSError) as error:
         print(f'Could not write {parsed.output}: {error}', file=sys.stderr)
         return 1
@@ -146,55 +305,72 @@ def add_changes_arg(parser: argparse.ArgumentParser) -> None:
 
 
 def build_change_parser(description: str) -> argparse.ArgumentParser:
-    """Build a parser with input, buffer, output and changes arguments."""
-    parser = argparse.ArgumentParser(description=description)
-    add_input_args(parser)
+    """Build a parser with input, config, output, buffer and changes."""
+    parser = build_io_parser(description)
     add_buffer_arg(parser)
-    add_output_args(parser)
     add_changes_arg(parser)
     return parser
 
 
-def date_report(changes: ReleaseDateChanges
+def date_report(changes: ReleaseDateChanges, file_exists_cb: FileExistsCb
                 ) -> tuple[str, Optional[Callable[[str], None]]]:
-    """Return the date change listing and a writer, None when empty."""
-    writer = None if not changes else \
-        (lambda path: write_date_changes(changes, path))
-    return format_date_changes(changes), writer
+    """Return the date change listing and a writer, None when empty.
+
+    The writer overwrites an existing changes file as decided by
+    ``file_exists_cb``.
+    """
+    def write(path: str) -> None:
+        """Write the date changes, overwriting as the callback decides."""
+        write_date_changes(changes, path, file_exists_callback=file_exists_cb)
+    return format_date_changes(changes), (write if changes else None)
 
 
-def content_report(changes: ReleaseChanges
+def content_report(changes: ReleaseChanges, file_exists_cb: FileExistsCb
                    ) -> tuple[str, Optional[Callable[[str], None]]]:
-    """Return the content change listing and a writer, None when empty."""
-    writer = None if not changes else \
-        (lambda path: write_content_changes(changes, path))
-    return format_content_changes(changes), writer
-
+    """Return the content change listing and a writer, None when empty.
 
-def run_change_command(parsed: argparse.Namespace,
-                       produce: Callable[[BacklogReleases], tuple[
-                           str, Optional[Callable[[str], None]]]]) -> int:
+    The writer overwrites an existing changes file as decided by
+    ``file_exists_cb``.
+    """
+    def write(path: str) -> None:
+        """Write the content changes, overwriting as the callback decides."""
+        write_content_changes(changes, path,
+                              file_exists_callback=file_exists_cb)
+    return format_content_changes(changes), (write if changes else None)
+
+
+def run_change_command(
+        parsed: argparse.Namespace,
+        produce: Callable[[Optional[BacklogOpsConfig], BacklogReleases],
+                          tuple[str, Optional[Callable[[str], None]]]],
+        require_config: bool = False) -> int:
     """Read, change, write the data, and emit the list of changes.
 
-    The input is read and validated, ``produce`` changes it in place and
-    returns the change listing as text together with a callback that
-    writes the same changes to a file. The changed data is written to the
-    output file, the listing is printed to stdout, and, when
-    ``--changes-file`` is given, the changes are also written to that file.
+    The configuration is resolved once, the input is read and validated,
+    ``produce`` changes it in place and returns the change listing as text
+    together with a callback that writes the same changes to a file. The
+    changed data is written to the output file, the listing is printed to
+    stdout, and, when ``--changes-file`` is given, the changes are also
+    written to that file.
 
     Args:
-        parsed: Parsed command line arguments holding the input, output
-            and ``--changes-file`` options.
-        produce: Callable that changes the data and returns the change
+        parsed: Parsed command line arguments holding the input, output,
+            ``-c`` and ``--changes-file`` options.
+        produce: Callable that receives the resolved configuration (or
+            None) and the data, changes the data, and returns the change
             listing text and a writer for the change file.
+        require_config: When True a missing configuration is reported as an
+            error instead of falling back to the built-in defaults.
 
     Returns:
         ``0`` on success, ``1`` when any step fails.
     """
     try:
-        data = read_input(parsed)
-        listing, write_changes = produce(data)
-        _write_output(parsed, data)
+        config = (required_config(parsed) if require_config
+                  else optional_config(parsed))
+        data = read_input(parsed, config)
+        listing, write_changes = produce(config, data)
+        _write_output(parsed, config, data)
         print(f'Wrote {parsed.output}')
         print(listing)
         _save_changes(parsed, write_changes)

backlogops_cli/_migrate_warn.py

@@ -0,0 +1,56 @@
+#! /usr/local/bin/python3
+"""Backward-compatibility warning hooks for the command line interface.
+
+When a command reads a file that needed backward-compatible normalization
+(Reading an Old Configuration File), one of these hooks prints the
+standard migration warning followed by command-specific instructions.
+``CliMigrateWarnHook`` is used when the old file is the backlog-ops
+configuration file and shows the ``migrate_cfg`` command for the default
+config kind. ``CliPresetMigrateWarnHook`` is used when the old file is a
+stand-alone input or output preset file and shows the ``migrate_cfg``
+command with the ``--kind`` option, because that option selects how a
+preset file is migrated. The leading underscore in the module name keeps
+it out of the command listing.
+"""
+# PYTHON_ARGCOMPLETE_OK
+
+# Copyright (c) 2026, Tom Björkholm
+# MIT License
+
+from config_as_json import MigrateCfgWarnHook
+
+
+class CliMigrateWarnHook(MigrateCfgWarnHook):
+    """Tell the user to migrate an old config file with ``migrate_cfg``."""
+
+    @classmethod
+    def migrate_instructions(cls) -> str:
+        """Return the command line migration instructions.
+
+        Returns:
+            Text that points the user at the ``migrate_cfg`` command to
+            rewrite the configuration file in the current format.
+        """
+        txt = 'Run the migrate_cfg command to write the configuration file '
+        txt += 'in the\ncurrent format, for example:\n'
+        txt += '  python3 -m backlogops_cli.migrate_cfg -i OLD.cfg '
+        txt += '-o NEW.cfg\n\n'
+        return txt
+
+
+class CliPresetMigrateWarnHook(MigrateCfgWarnHook):
+    """Tell the user to migrate an old preset file with ``migrate_cfg``."""
+
+    @classmethod
+    def migrate_instructions(cls) -> str:
+        """Return the command line preset migration instructions.
+
+        Returns:
+            Text that points the user at the ``migrate_cfg`` command with
+            the ``--kind`` option for input or output preset files.
+        """
+        txt = 'Run the migrate_cfg command with -k input or -k output to '
+        txt += 'write the\npreset file in the current format, for example:\n'
+        txt += '  python3 -m backlogops_cli.migrate_cfg -k input '
+        txt += '-i OLD.cfg -o NEW.cfg\n\n'
+        return txt

backlogops_cli/_wizard_io.py

@@ -0,0 +1,92 @@
+#! /usr/local/bin/python3
+"""Shared helpers for the configuration and preset wizard commands.
+
+Both wizard commands write a JSON configuration file built interactively
+through a ``WizardUiBridge``. They share the same command line shape (an
+output file, a switch forcing the plain console interface, and a force
+flag), the same overwrite check, and the same run-write-report flow. That
+shared logic lives here; the leading underscore in the module name keeps
+it out of the command listing.
+"""
+# PYTHON_ARGCOMPLETE_OK
+
+# Copyright (c) 2026, Tom Björkholm
+# MIT License
+
+import argparse
+import sys
+from collections.abc import Callable
+from pathlib import Path
+from config_as_json import Config
+from config_as_json.file_extension import fix_file_extension
+from tableio_cfg_json import WizardUiBridge, WizardUiBridgeConsole, \
+    make_text_ui_bridge
+from backlogops_cli._command_io import add_force_arg, overwrite_callback
+
+CONFIG_EXTENSION = '.cfg'
+
+
+def build_wizard_parser(description: str) -> argparse.ArgumentParser:
+    """Build a wizard parser with output, no-textual and force options."""
+    parser = argparse.ArgumentParser(description=description)
+    parser.add_argument('-o', '--output', dest='output', required=True,
+                        help='Configuration file to write; the '
+                        f'{CONFIG_EXTENSION} extension is added if missing.')
+    parser.add_argument('--no-textual', dest='no_textual', action='store_true',
+                        help='Force the plain console interface instead of '
+                        'the Textual full-screen interface.')
+    add_force_arg(parser)
+    return parser
+
+
+def _check_overwrite(output: str, force: bool) -> None:
+    """Ask before overwriting an existing configuration file.
+
+    The check runs before the wizard, so the user is not asked to confirm
+    an overwrite only after entering the whole configuration.
+    """
+    if Path(output).exists():
+        overwrite_callback(force)(output)
+
+
+def _make_bridge(no_textual: bool) -> WizardUiBridge:
+    """Return the console bridge when forced, else the best text bridge.
+
+    Without ``--no-textual`` the factory returns a Textual full-screen
+    bridge in a real terminal and a console bridge otherwise, such as when
+    input is redirected or under tests.
+    """
+    if no_textual:
+        return WizardUiBridgeConsole(sys.stdout, sys.stdin, sys.stderr)
+    return make_text_ui_bridge(sys.stdout, sys.stdin, sys.stderr)
+
+
+def run_wizard_to_file(parsed: argparse.Namespace,
+                       wizard: Callable[[WizardUiBridge], Config],
+                       label: str) -> int:
+    """Run a wizard, write its configuration to the output file, report.
+
+    The output filename receives the ``.cfg`` extension when it is not
+    already present.
+
+    Args:
+        parsed: Parsed arguments holding ``output``, ``force`` and
+            ``no_textual``.
+        wizard: Wizard called with the chosen UI bridge; it returns a
+            configuration object that knows how to write itself.
+        label: Human-readable name of what was written, for the message.
+
+    Returns:
+        ``0`` on success, ``1`` when the wizard is abandoned or the
+        configuration is rejected or cannot be written.
+    """
+    output = fix_file_extension(parsed.output, CONFIG_EXTENSION)
+    try:
+        _check_overwrite(output, parsed.force)
+        config = wizard(_make_bridge(parsed.no_textual))
+        config.write(to_json_filename=output, stderr_file=sys.stderr)
+    except (ValueError, TypeError, KeyError, EOFError, OSError) as error:
+        print(f'Could not create the configuration: {error}', file=sys.stderr)
+        return 1
+    print(f'{label} written to {output}')
+    return 0

backlogops_cli/adjust_release_content.py

@@ -20,7 +20,8 @@ from datetime import timedelta
 from typing import Callable, Optional
 from backlogops import BacklogReleases
 from backlogops_cli._command_io import (
-    build_change_parser, content_report, parsed_args, run_change_command)
+    build_change_parser, content_report, overwrite_callback, parsed_args,
+    run_change_command)
 
 DESCRIPTION = 'Adjust release content to fit the planned release dates'
 
@@ -34,7 +35,7 @@ def _adjust(parsed: argparse.Namespace, data: BacklogReleases
             ) -> tuple[str, Optional[Callable[[str], None]]]:
     """Adjust the release content and return the change report."""
     changes = data.adjust_release_content(timedelta(days=parsed.buffer_days))
-    return content_report(changes)
+    return content_report(changes, overwrite_callback(parsed.force))
 
 
 def main(args: Optional[list[str]] = None) -> int:
@@ -48,7 +49,7 @@ def main(args: Optional[list[str]] = None) -> int:
         written.
     """
     parsed = parsed_args(build_parser(), args)
-    return run_change_command(parsed, lambda data: _adjust(parsed, data))
+    return run_change_command(parsed, lambda _, data: _adjust(parsed, data))
 
 
 if __name__ == '__main__':  # pragma: no cover

backlogops_cli/bloc_version_reporter.py

@@ -0,0 +1,25 @@
+#! /usr/local/bin/python3
+"""Version reporter for the backlogops_cli package."""
+
+# Copyright (c) 2026 Tom Björkholm
+# MIT License
+
+from typing import override
+from backlogops.blo_version_reporter import BloVersionReporter
+
+
+class BloCliVersionReporter(BloVersionReporter):
+    """Version reporter for the backlogops_cli package."""
+
+    @override
+    def package_names(self) -> list[str]:
+        """Return the package names that this package reports."""
+        ret = ['backlogops-cli']
+        ret += super().package_names()
+        return ret
+
+    @override
+    @classmethod
+    def get_main_package_name(cls) -> str:
+        """Return the name of the main package."""
+        return 'backlogops-cli'

backlogops_cli/config_wizard.py

@@ -0,0 +1,42 @@
+#! /usr/local/bin/python3
+"""Run the backlog-ops configuration wizard and store the result."""
+
+# PYTHON_ARGCOMPLETE_OK
+# Copyright (c) 2026, Tom Björkholm
+# MIT License
+
+import argparse
+import sys
+from typing import Optional
+from backlogops import backlog_ops_wizard
+from backlogops_cli._command_io import parsed_args
+from backlogops_cli._wizard_io import build_wizard_parser, run_wizard_to_file
+
+DESCRIPTION = 'Create a backlog-ops configuration file via a wizard'
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the command line parser for the config wizard command."""
+    return build_wizard_parser(DESCRIPTION)
+
+
+def main(args: Optional[list[str]] = None) -> int:
+    """Run the interactive wizard and write the backlog-ops configuration.
+
+    The output filename receives the ``.cfg`` extension when it is not
+    already present.
+
+    Args:
+        args: Optional replacement for ``sys.argv[1:]``, mainly for tests.
+
+    Returns:
+        ``0`` on success, ``1`` when the entered configuration is rejected
+        or cannot be written.
+    """
+    parsed = parsed_args(build_parser(), args)
+    return run_wizard_to_file(parsed, backlog_ops_wizard,
+                              'Backlog-ops configuration')
+
+
+if __name__ == '__main__':  # pragma: no cover
+    sys.exit(main())