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

backlogops_cli/_command_io.py

@@ -20,11 +20,39 @@ from backlogops_cli._migrate_warn import (
     CliMigrateWarnHook, CliPresetMigrateWarnHook)
 from backlogops_cli.bloc_version_reporter import BloCliVersionReporter
 from backlogops import (
-    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)
+    BacklogOpsConfig, BacklogReleases, FileExistsCb, FormatRules,
+    JiraRankAnchor, 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)
+
+RANK_ANCHOR_CHOICES = {
+    'backlog-top': JiraRankAnchor.BACKLOG_TOP,
+    'backlog-bottom': JiraRankAnchor.BACKLOG_BOTTOM,
+    'first-key': JiraRankAnchor.FIRST_KEY,
+    'last-key': JiraRankAnchor.LAST_KEY}
+"""Command-line anchor names mapped to :class:`JiraRankAnchor` members."""
+
+
+def rank_anchor(value: Optional[str]) -> Optional[JiraRankAnchor]:
+    """Return the anchor for a CLI anchor name, or None for a None value."""
+    return None if value is None else RANK_ANCHOR_CHOICES[value]
+
+
+def add_rank_arg(parser: argparse.ArgumentParser) -> None:
+    """Add the optional ``--rank`` flag choosing a Jira rank anchor.
+
+    Shared by the add and update commands, where ranking is opt-in: without
+    ``--rank`` the Jira rank order is left unchanged.
+    """
+    parser.add_argument('--rank', dest='rank', default=None,
+                        choices=sorted(RANK_ANCHOR_CHOICES),
+                        help='Also set the Jira rank order to match the '
+                        'supplied backlog, placing the items at this anchor: '
+                        'backlog-top, backlog-bottom, first-key (keep the '
+                        'first item fixed) or last-key (keep the last item '
+                        'fixed). Omit to leave the Jira rank order unchanged.')
 
 
 def overwrite_callback(force: bool, in_stream: Optional[TextIO] = None,
@@ -255,11 +283,14 @@ def _write_output(parsed: argparse.Namespace,
 
 def run_write(parsed: argparse.Namespace,
               data_source: Callable[[Optional[BacklogOpsConfig]],
-                                    BacklogReleases]) -> int:
+                                    BacklogReleases],
+              require_config: bool = False) -> 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.
+    The configuration is resolved once from ``-c`` or by discovery. It
+    falls back to the built-in defaults when none is found, unless
+    ``require_config`` is True, in which case a missing configuration is
+    reported as an error.
 
     Args:
         parsed: Parsed command line arguments holding the output options
@@ -269,12 +300,15 @@ def run_write(parsed: argparse.Namespace,
             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.
+        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 the data cannot be built or written.
     """
     try:
-        config = optional_config(parsed)
+        config = (required_config(parsed) if require_config
+                  else 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)

backlogops_cli/_wizard_io.py

@@ -3,10 +3,11 @@
 
 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.
+output file, an optional input file whose contents pre-fill the wizard, a
+switch forcing the plain console interface, and a force flag), the same
+overwrite check, the same read-run-write-report flow, and the same
+crash-safe write. That shared logic lives here; the leading underscore in
+the module name keeps it out of the command listing.
 """
 # PYTHON_ARGCOMPLETE_OK
 
@@ -17,21 +18,32 @@ import argparse
 import sys
 from collections.abc import Callable
 from pathlib import Path
+from typing import Optional, TypeVar
 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 import safe_write_config
 from backlogops_cli._command_io import add_force_arg, overwrite_callback
 
 CONFIG_EXTENSION = '.cfg'
+_ConfigT = TypeVar('_ConfigT', bound=Config)
 
 
 def build_wizard_parser(description: str) -> argparse.ArgumentParser:
-    """Build a wizard parser with output, no-textual and force options."""
+    """Build a wizard parser with output, input, no-textual and force."""
     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('-i', '--input', dest='input',
+                        help='Existing configuration file whose contents '
+                        'pre-fill the wizard as the starting answers, so you '
+                        'edit them instead of starting empty. Use the same '
+                        'path as -o to edit that file in place; you are then '
+                        f'asked to confirm overwriting it. The '
+                        f'{CONFIG_EXTENSION} extension is assumed when the '
+                        'file is not found as named.')
     parser.add_argument('--no-textual', dest='no_textual', action='store_true',
                         help='Force the plain console interface instead of '
                         'the Textual full-screen interface.')
@@ -61,30 +73,52 @@ def _make_bridge(no_textual: bool) -> WizardUiBridge:
     return make_text_ui_bridge(sys.stdout, sys.stdin, sys.stderr)
 
 
+def _read_default(input_file: Optional[str],
+                  reader: Callable[[str], _ConfigT]) -> Optional[_ConfigT]:
+    """Read the pre-fill file, or return None when none is requested.
+
+    The ``.cfg`` extension is assumed when the named file is not found as
+    given, matching how the output filename is completed.
+    """
+    if input_file is None:
+        return None
+    path = fix_file_extension(input_file, CONFIG_EXTENSION, for_reading=True)
+    if not Path(path).is_file():
+        raise ValueError(f'File to read initial values from not found: {path}')
+    return reader(path)
+
+
 def run_wizard_to_file(parsed: argparse.Namespace,
-                       wizard: Callable[[WizardUiBridge], Config],
-                       label: str) -> int:
+                       wizard: Callable[..., _ConfigT],
+                       reader: Callable[[str], _ConfigT], 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.
+    When ``parsed.input`` names an existing file it is read first and used
+    to pre-fill the wizard, so the user edits those values instead of
+    starting from scratch. The output filename receives the ``.cfg``
+    extension when it is not already present, an existing output file is
+    only overwritten after confirmation (or with ``--force``), and the
+    result is written crash-safely through a ``.in_progress`` sibling file.
 
     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.
+        parsed: Parsed arguments holding ``output``, ``input``, ``force``
+            and ``no_textual``.
+        wizard: Wizard called with the chosen UI bridge and the pre-fill
+            default; it returns a configuration object that knows how to
+            write itself.
+        reader: Reads the ``input`` file into a default for the wizard.
         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.
+        configuration is rejected or cannot be read or written.
     """
     output = fix_file_extension(parsed.output, CONFIG_EXTENSION)
     try:
+        default = _read_default(parsed.input, reader)
         _check_overwrite(output, parsed.force)
-        config = wizard(_make_bridge(parsed.no_textual))
-        config.write(to_json_filename=output, stderr_file=sys.stderr)
+        config = wizard(_make_bridge(parsed.no_textual), default=default)
+        safe_write_config(config, output, sys.stderr)
     except (ValueError, TypeError, KeyError, EOFError, OSError) as error:
         print(f'Could not create the configuration: {error}', file=sys.stderr)
         return 1

backlogops_cli/add_releases_to_jira.py

@@ -0,0 +1,144 @@
+#! /usr/local/bin/python3
+"""Add releases to Jira from an input file, creating one version per name.
+
+The command reads a backlog and its releases from the input file, then
+adds the releases to Jira using a named preset of the backlog-ops
+configuration. By default it stops with an error when a release name
+already exists in Jira; ``--skip-existing`` skips those releases instead.
+
+The added releases and the releases already in Jira are printed to stdout
+as two labelled lists, unless ``-q``/``--quiet`` is given. Each list is
+also written, together with the unchanged input backlog, to a file when
+``--added-file`` or ``--existing-file`` names one; without a file name the
+list is not written. An encrypted Jira token is unlocked by a pass phrase
+asked on the terminal only when it is needed.
+"""
+
+# PYTHON_ARGCOMPLETE_OK
+# Copyright (c) 2026, Tom Björkholm
+# MIT License
+
+import argparse
+import sys
+from getpass import getpass
+from typing import Optional
+from backlogops import (
+    AddedReleasesToJira, BacklogOpsConfig, BacklogReleases, FormatRules,
+    JiraConnections, OnExistingKey, ReleaseExistsError, add_releases_to_jira,
+    format_release_result, resolve_output_config, write_backlog_releases)
+from backlogops_cli._command_io import (
+    add_config_arg, add_input_args, overwrite_callback, parsed_args,
+    read_input, required_config)
+from backlogops_cli._migrate_warn import CliPresetMigrateWarnHook
+
+DESCRIPTION = 'Add releases to Jira, creating a new version per release'
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the command line parser for the add-releases command."""
+    parser = argparse.ArgumentParser(description=DESCRIPTION)
+    add_input_args(parser)
+    add_config_arg(parser)
+    parser.add_argument('-p', '--preset', dest='preset', required=True,
+                        help='Name of the Jira preset in the configuration.')
+    parser.add_argument('--skip-existing', dest='skip_existing',
+                        action='store_true',
+                        help='Skip releases whose name already exists in Jira '
+                        '(the default stops with an error instead).')
+    parser.add_argument('--added-file', dest='added_file', metavar='FILE',
+                        help='Write the added releases, with the input '
+                        'backlog, to this file. Omit to not write it.')
+    parser.add_argument('--existing-file', dest='existing_file',
+                        metavar='FILE',
+                        help='Write the releases already in Jira, with the '
+                        'input backlog, to this file. Omit to not write it.')
+    parser.add_argument('-q', '--quiet', dest='quiet', action='store_true',
+                        help='Do not print the added and already-present '
+                        'lists to stdout.')
+    parser.add_argument('-f', '--force', dest='force', action='store_true',
+                        help='Overwrite existing output files without '
+                        'asking.')
+    return parser
+
+
+def _passphrase() -> str:
+    """Ask for the Jira token pass phrase on the terminal."""
+    return getpass('Jira API token pass phrase: ')
+
+
+def _add(parsed: argparse.Namespace, config: BacklogOpsConfig,
+         data: BacklogReleases) -> AddedReleasesToJira:
+    """Add the input releases to Jira using the named preset."""
+    print(f"Adding releases to Jira using preset '{parsed.preset}'...",
+          file=sys.stderr)
+    connections = JiraConnections(config.get_jira_config(), _passphrase)
+    mode = (OnExistingKey.SKIP if parsed.skip_existing
+            else OnExistingKey.RAISE)
+    result = add_releases_to_jira(connections, parsed.preset, data.releases,
+                                  on_existing_key=mode)
+    print(f'Added {len(result.stored)} releases to Jira; '
+          f'{len(result.already_present)} already present; '
+          f'{len(result.failed)} failed.', file=sys.stderr)
+    return result
+
+
+def _write_file(config: BacklogOpsConfig, path: str, data: BacklogReleases,
+                force: bool) -> None:
+    """Write one backlog-and-releases result to a file."""
+    out_config = resolve_output_config(None, data_file=path,
+                                       presets=config.output_configs,
+                                       auto_ch_hook=CliPresetMigrateWarnHook())
+    write_backlog_releases(data, path, out_config, FormatRules(),
+                           levels=config.get_levels(),
+                           file_exists_callback=overwrite_callback(force))
+    print(f'Wrote {path}')
+
+
+def _write_result_files(parsed: argparse.Namespace, config: BacklogOpsConfig,
+                        data: BacklogReleases,
+                        result: AddedReleasesToJira) -> None:
+    """Write the added and already-present releases to any named files."""
+    backlog = list(data.backlog)
+    if parsed.added_file is not None:
+        added = BacklogReleases(backlog=backlog, releases=result.stored)
+        _write_file(config, parsed.added_file, added, parsed.force)
+    if parsed.existing_file is not None:
+        present = BacklogReleases(backlog=backlog,
+                                  releases=result.already_present)
+        _write_file(config, parsed.existing_file, present, parsed.force)
+
+
+def _run(parsed: argparse.Namespace) -> int:
+    """Read the input, add the releases, write files and print the lists."""
+    try:
+        config = required_config(parsed)
+        data = read_input(parsed, config)
+        result = _add(parsed, config, data)
+        _write_result_files(parsed, config, data, result)
+    except ReleaseExistsError:
+        print('Nothing added to Jira.', file=sys.stderr)
+        return 1
+    except (ValueError, TypeError, KeyError, OSError) as error:
+        print(f'Could not add releases to Jira: {error}', file=sys.stderr)
+        return 1
+    if not parsed.quiet:
+        print(format_release_result(result))
+    return 0
+
+
+def main(args: Optional[list[str]] = None) -> int:
+    """Add releases to Jira and report the added and present releases.
+
+    Args:
+        args: Optional replacement for ``sys.argv[1:]``, mainly for tests.
+
+    Returns:
+        ``0`` on success, ``1`` when the releases cannot be added or a name
+        already exists in Jira without ``--skip-existing``.
+    """
+    parsed = parsed_args(build_parser(), args)
+    return _run(parsed)
+
+
+if __name__ == '__main__':  # pragma: no cover
+    sys.exit(main())

backlogops_cli/add_to_jira.py

@@ -0,0 +1,151 @@
+#! /usr/local/bin/python3
+"""Add a backlog to Jira from an input file, creating one issue per item.
+
+The command reads a backlog (or a backlog and its releases) from the input
+file, then adds the backlog items to Jira using a named preset of the
+backlog-ops configuration. By default it stops with an error when an
+item's key already exists in Jira; ``--skip-existing`` skips those items
+instead. With ``--rank`` the items are also ranked in Jira to match the
+supplied backlog order, at the chosen anchor.
+
+The added items (carrying their new Jira keys) and the items already in
+Jira are printed to stdout as two labelled lists, unless ``-q``/``--quiet``
+is given. Each list is also written to a file when ``--added-file`` or
+``--existing-file`` names one; without a file name the list is not written.
+An encrypted Jira token is unlocked by a pass phrase asked on the terminal
+only when it is needed.
+"""
+
+# PYTHON_ARGCOMPLETE_OK
+# Copyright (c) 2026, Tom Björkholm
+# MIT License
+
+import argparse
+import sys
+from getpass import getpass
+from typing import Optional
+from backlogops import (
+    AddedToJira, BacklogOpsConfig, BacklogReleases, ExistsInJiraError,
+    FormatRules, JiraConnections, OnExistingKey, add_backlog_to_jira,
+    format_add_result, resolve_output_config, write_backlog_releases)
+from backlogops_cli._command_io import (
+    add_config_arg, add_input_args, add_rank_arg, overwrite_callback,
+    parsed_args, rank_anchor, read_input, required_config)
+from backlogops_cli._migrate_warn import CliPresetMigrateWarnHook
+
+DESCRIPTION = 'Add a backlog to Jira, creating a new issue per item'
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the command line parser for the add-to-Jira command."""
+    parser = argparse.ArgumentParser(description=DESCRIPTION)
+    add_input_args(parser)
+    add_config_arg(parser)
+    parser.add_argument('-p', '--preset', dest='preset', required=True,
+                        help='Name of the Jira preset in the configuration.')
+    parser.add_argument('--skip-existing', dest='skip_existing',
+                        action='store_true',
+                        help='Skip items whose key already exists in Jira '
+                        '(the default stops with an error instead).')
+    add_rank_arg(parser)
+    parser.add_argument('--added-file', dest='added_file', metavar='FILE',
+                        help='Write the added items, with their new Jira '
+                        'keys, to this file. Omit to not write it.')
+    parser.add_argument('--existing-file', dest='existing_file',
+                        metavar='FILE',
+                        help='Write the items already in Jira to this file. '
+                        'Omit to not write it.')
+    parser.add_argument('-q', '--quiet', dest='quiet', action='store_true',
+                        help='Do not print the added and already-present '
+                        'lists to stdout.')
+    parser.add_argument('-f', '--force', dest='force', action='store_true',
+                        help='Overwrite existing output files without '
+                        'asking.')
+    return parser
+
+
+def _passphrase() -> str:
+    """Ask for the Jira token pass phrase on the terminal."""
+    return getpass('Jira API token pass phrase: ')
+
+
+def _add(parsed: argparse.Namespace, config: BacklogOpsConfig,
+         data: BacklogReleases) -> AddedToJira:
+    """Add the input backlog to Jira using the named write preset."""
+    print(f"Adding backlog to Jira using preset '{parsed.preset}'...",
+          file=sys.stderr)
+    connections = JiraConnections(config.get_jira_config(), _passphrase)
+    mode = (OnExistingKey.SKIP if parsed.skip_existing
+            else OnExistingKey.RAISE)
+    result = add_backlog_to_jira(connections, parsed.preset, data.backlog,
+                                 on_existing_key=mode,
+                                 rank_anchor=rank_anchor(parsed.rank),
+                                 levels=config.get_levels(),
+                                 status_map=config.get_status_input_map())
+    print(f'Added {len(result.stored)} items to Jira; '
+          f'{len(result.already_present)} already present; '
+          f'{len(result.failed)} failed; '
+          f'{len(result.failed_links)} links not written.', file=sys.stderr)
+    return result
+
+
+def _write_backlog_file(config: BacklogOpsConfig, path: str,
+                        data: BacklogReleases, force: bool) -> None:
+    """Write one returned backlog and the input releases to a file."""
+    out_config = resolve_output_config(None, data_file=path,
+                                       presets=config.output_configs,
+                                       auto_ch_hook=CliPresetMigrateWarnHook())
+    write_backlog_releases(data, path, out_config, FormatRules(),
+                           levels=config.get_levels(),
+                           file_exists_callback=overwrite_callback(force))
+    print(f'Wrote {path}')
+
+
+def _write_result_files(parsed: argparse.Namespace, config: BacklogOpsConfig,
+                        data: BacklogReleases, result: AddedToJira) -> None:
+    """Write the added and already-present backlogs to any named files."""
+    releases = list(data.releases)
+    if parsed.added_file is not None:
+        added = BacklogReleases(backlog=result.stored, releases=releases)
+        _write_backlog_file(config, parsed.added_file, added, parsed.force)
+    if parsed.existing_file is not None:
+        present = BacklogReleases(backlog=result.already_present,
+                                  releases=releases)
+        _write_backlog_file(config, parsed.existing_file, present,
+                            parsed.force)
+
+
+def _run(parsed: argparse.Namespace) -> int:
+    """Read the input, add it to Jira, write files and print the lists."""
+    try:
+        config = required_config(parsed)
+        data = read_input(parsed, config)
+        result = _add(parsed, config, data)
+        _write_result_files(parsed, config, data, result)
+    except ExistsInJiraError:
+        print('Nothing added to Jira.', file=sys.stderr)
+        return 1
+    except (ValueError, TypeError, KeyError, OSError) as error:
+        print(f'Could not add to Jira: {error}', file=sys.stderr)
+        return 1
+    if not parsed.quiet:
+        print(format_add_result(result))
+    return 0
+
+
+def main(args: Optional[list[str]] = None) -> int:
+    """Add a backlog to Jira and report the added and present items.
+
+    Args:
+        args: Optional replacement for ``sys.argv[1:]``, mainly for tests.
+
+    Returns:
+        ``0`` on success, ``1`` when the backlog cannot be added or a key
+        already exists in Jira without ``--skip-existing``.
+    """
+    parsed = parsed_args(build_parser(), args)
+    return _run(parsed)
+
+
+if __name__ == '__main__':  # pragma: no cover
+    sys.exit(main())

backlogops_cli/config_wizard.py

@@ -8,8 +8,10 @@
 import argparse
 import sys
 from typing import Optional
-from backlogops import backlog_ops_wizard
+from backlogops import BacklogOpsConfig, backlog_ops_wizard, \
+    read_backlog_ops_config
 from backlogops_cli._command_io import parsed_args
+from backlogops_cli._migrate_warn import CliMigrateWarnHook
 from backlogops_cli._wizard_io import build_wizard_parser, run_wizard_to_file
 
 DESCRIPTION = 'Create a backlog-ops configuration file via a wizard'
@@ -20,21 +22,30 @@ def build_parser() -> argparse.ArgumentParser:
     return build_wizard_parser(DESCRIPTION)
 
 
+def _read_config(filename: str) -> BacklogOpsConfig:
+    """Read an existing backlog-ops configuration to pre-fill the wizard."""
+    return read_backlog_ops_config(filename, sys.stderr,
+                                   auto_ch_hook=CliMigrateWarnHook())
+
+
 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.
+    With ``-i`` an existing configuration file is read first and used to
+    pre-fill the wizard, so the user edits those values; pointing ``-i`` at
+    the same file as ``-o`` edits it in place after confirming the
+    overwrite. 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.
+        or cannot be read or written.
     """
     parsed = parsed_args(build_parser(), args)
-    return run_wizard_to_file(parsed, backlog_ops_wizard,
+    return run_wizard_to_file(parsed, backlog_ops_wizard, _read_config,
                               'Backlog-ops configuration')
 
 

backlogops_cli/encrypt_token_file.py

@@ -0,0 +1,120 @@
+#!/usr/local/bin/python3
+"""Encrypt a Jira API token to a file with a pass phrase.
+
+Read a clear text API token from a file or from standard input, encrypt it
+with a pass phrase and write the encrypted token to a file. The pass phrase
+is requested on the terminal and is not echoed. The clear text token file
+is not modified, unless the the encrypted token file is the same as the
+clear text token file, in which case the clear text token file is overwritten
+with the encrypted token. The encrypted token file is written atomically,
+so that it is either the old version or the new version, and never a
+half-written file.
+"""
+
+# PYTHON_ARGCOMPLETE_OK
+# Copyright (c) 2026, Tom Björkholm
+# MIT License
+
+import argparse
+import sys
+from getpass import getpass
+from pathlib import Path
+from typing import Optional
+from backlogops import encrypt_token_to_file, encrypt_token_file
+from backlogops_cli._command_io import parsed_args
+
+
+DESCRIPTION = 'Encrypt a Jira API token file with a pass phrase.'
+
+
+def _ok_to_overwrite(filename: Path) -> bool:
+    """Return True if the file can be overwritten, False otherwise."""
+    txt = f'The output file {filename} already exists. Overwrite? [y/n] '
+    while True:
+        answer = input(txt)
+        if answer.lower().strip() in ('y', 'ye', 'yes'):
+            return True
+        if answer.lower().strip() in ('n', 'no'):
+            return False
+        print('Please answer yes or no.')
+    return False  # pragma: no cover
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the command line parser for the encrypt-token-file command."""
+    descr = DESCRIPTION + '. The pass phrase is requested on the terminal.'
+    descr += ' The clear text token file is not modified, unless the output'
+    descr += ' file is the same as the input file, in which case the clear'
+    descr += ' text token file is overwritten with the encrypted token.'
+    parser = argparse.ArgumentParser(description=descr)
+    inhelp = 'The clear text token file to read from. Omit to read from stdin.'
+    parser.add_argument('-i', '--infile', required=False, help=inhelp)
+    parser.add_argument('-o', '--outfile', required=True,
+                        help='The encrypted token file to write to.')
+    return parser
+
+
+EXCEPTIONS = (FileNotFoundError, ValueError, FileExistsError,
+              NotADirectoryError, OSError)
+
+
+def _run(parsed: argparse.Namespace) -> int:
+    """Run the encrypt-token-file command with the given parsed arguments.
+
+    Args:
+        parsed: The parsed command line arguments.
+    Returns:
+        0 if the command was successful, 1 if there was an error
+    """
+    outfile = Path(parsed.outfile)
+    token: Optional[str] = None
+    pphrase1 = 'a'
+    phrase2 = 'b'
+    while pphrase1 != phrase2 or not pphrase1:
+        pphrase1 = getpass('Enter the pass phrase to encrypt the token with: ')
+        if not pphrase1:
+            print('No pass phrase entered. Exiting.')
+            return 1
+        phrase2 = getpass('Re-enter the pass phrase to confirm: ')
+        if pphrase1 != phrase2:
+            print('Pass phrases do not match. Please try again.')
+    if not parsed.infile:
+        print('Enter the clear text token on a single line, then press Enter.')
+        token = input().strip()
+        if not token:
+            print('No token entered. Exiting.')
+            return 1
+        try:
+            encrypt_token_to_file(token, passphrase=pphrase1, filename=outfile,
+                                  ok_to_overwrite=_ok_to_overwrite)
+            return 0
+        except EXCEPTIONS as e:
+            print(f'Error encrypting token: {e}')
+            return 1
+    infile = Path(parsed.infile)
+    try:
+        encrypt_token_file(clear_file=infile, encrypted_file=outfile,
+                           passphrase=pphrase1,
+                           ok_to_overwrite=_ok_to_overwrite)
+        return 0
+    except EXCEPTIONS as e:
+        print(f'Error encrypting token file: {e}')
+        return 1
+    return 2  # pragma: no cover  # this should never be reached
+
+
+def main(arguments: Optional[list[str]] = None) -> int:
+    """Encrypt a Jira API token file with a pass phrase.
+
+    Args:
+        arguments: The command line arguments to parse. If None, the arguments
+            are taken from sys.argv.
+    Returns:
+        0 if the command was successful, 1 if there was an error.
+    """
+    parsed = parsed_args(build_parser(), arguments)
+    return _run(parsed)
+
+
+if __name__ == '__main__':  # pragma: no cover
+    sys.exit(main())