hpcflow-new2 0.2.0a188__py3-none-any.whl → 0.2.0a190__py3-none-any.whl

hpcflow/sdk/cli.py

@@ -2,12 +2,13 @@
 Command line interface implementation.
 """
 
+from __future__ import annotations
 import json
 import os
-from typing import Dict, List
 import click
 from colorama import init as colorama_init
-from termcolor import colored
+from termcolor import colored  # type: ignore
+from typing import TYPE_CHECKING
 from rich.pretty import pprint
 
 from hpcflow import __version__, _app_name
@@ -46,7 +47,16 @@ from hpcflow.sdk.cli_common import (
 )
 from hpcflow.sdk.helper.cli import get_helper_CLI
 from hpcflow.sdk.log import TimeIt
+from hpcflow.sdk.core.workflow import Workflow
 from hpcflow.sdk.submission.shells import ALL_SHELLS
+from hpcflow.sdk.submission.jobscript import Jobscript
+from hpcflow.sdk.submission.submission import Submission
+from hpcflow.sdk.submission.schedulers.sge import SGEPosix
+
+if TYPE_CHECKING:
+    from pathlib import Path
+    from typing import Literal
+    from .app import BaseApp
 
 #: Standard option
 string_option = click.option(
@@ -59,16 +69,22 @@ string_option = click.option(
 workflow_ref_type_opt = click.option(
     "--ref-type",
     "-r",
-    type=click.Choice(["assume-id", "id", "path"]),
+    type=click.Choice(("assume-id", "id", "path")),
     default="assume-id",
     help="How to interpret a reference, as an ID, a path, or to guess.",
 )
 
+#: Get the current workflow from the context.
+_pass_workflow = click.make_pass_decorator(Workflow)
+#: Get the current submission from the context.
+_pass_submission = click.make_pass_decorator(Submission)
+#: Get the current jobscript from the context.
+_pass_js = click.make_pass_decorator(Jobscript)
 
 _add_doc_from_help(string_option, workflow_ref_type_opt)
 
 
-def parse_jobscript_wait_spec(jobscripts: str) -> Dict[int, List[int]]:
+def parse_jobscript_wait_spec(jobscripts: str) -> dict[int, list[int]]:
     """
     Parse a jobscript wait specification.
     """
@@ -79,7 +95,15 @@ def parse_jobscript_wait_spec(jobscripts: str) -> Dict[int, List[int]]:
     return sub_js_idx_dct
 
 
-def _make_API_CLI(app):
+def _set_help_name(cmd: click.Group | click.Command, app: BaseApp):
+    """
+    Update the help string of the command to contain the name of the application.
+    """
+    if cmd.help:
+        cmd.help = cmd.help.format(app_name=app.name)
+
+
+def _make_API_CLI(app: BaseApp):
     """Generate the CLI for the main functionality."""
 
     @click.command(name="make")
@@ -95,17 +119,17 @@ def _make_API_CLI(app):
     @variables_option
     @make_status_opt
     def make_workflow(
-        template_file_or_str,
-        string,
-        format,
-        path,
-        name,
-        overwrite,
-        store,
-        ts_fmt=None,
-        ts_name_fmt=None,
-        variables=None,
-        status=True,
+        template_file_or_str: str,
+        string: bool,
+        format: Literal["json", "yaml"] | None,
+        path: Path | None,
+        name: str | None,
+        overwrite: bool,
+        store: str,
+        ts_fmt: str | None = None,
+        ts_name_fmt: str | None = None,
+        variables: list[tuple[str, str]] | None = None,
+        status: bool = True,
     ):
         """Generate a new {app_name} workflow.
 
@@ -123,7 +147,7 @@ def _make_API_CLI(app):
             store=store,
             ts_fmt=ts_fmt,
             ts_name_fmt=ts_name_fmt,
-            variables=dict(variables),
+            variables=dict(variables) if variables is not None else None,
             status=status,
         )
         click.echo(wk.path)
@@ -147,23 +171,23 @@ def _make_API_CLI(app):
     @cancel_opt
     @submit_status_opt
     def make_and_submit_workflow(
-        template_file_or_str,
-        string,
-        format,
-        path,
-        name,
-        overwrite,
-        store,
-        ts_fmt=None,
-        ts_name_fmt=None,
-        variables=None,
-        js_parallelism=None,
-        wait=False,
-        add_to_known=True,
-        print_idx=False,
-        tasks=None,
-        cancel=False,
-        status=True,
+        template_file_or_str: str,
+        string: bool,
+        format: Literal["json", "yaml"] | None,
+        path: Path | None,
+        name: str | None,
+        overwrite: bool,
+        store: str,
+        ts_fmt: str | None = None,
+        ts_name_fmt: str | None = None,
+        variables: list[tuple[str, str]] | None = None,
+        js_parallelism: bool | None = None,
+        wait: bool = False,
+        add_to_known: bool = True,
+        print_idx: bool = False,
+        tasks: list[int] | None = None,
+        cancel: bool = False,
+        status: bool = True,
     ):
         """Generate and submit a new {app_name} workflow.
 
@@ -182,7 +206,7 @@ def _make_API_CLI(app):
             store=store,
             ts_fmt=ts_fmt,
             ts_name_fmt=ts_name_fmt,
-            variables=dict(variables),
+            variables=dict(variables) if variables is not None else None,
             JS_parallelism=js_parallelism,
             wait=wait,
             add_to_known=add_to_known,
@@ -192,12 +216,13 @@ def _make_API_CLI(app):
             status=status,
         )
         if print_idx:
+            assert isinstance(out, tuple)
             click.echo(out[1])
 
     @click.command(context_settings={"ignore_unknown_options": True})
     @click.argument("py_test_args", nargs=-1, type=click.UNPROCESSED)
     @click.pass_context
-    def test(ctx, py_test_args):
+    def test(ctx: click.Context, py_test_args: list[str]):
         """Run {app_name} test suite.
 
         PY_TEST_ARGS are arguments passed on to Pytest.
@@ -208,7 +233,7 @@ def _make_API_CLI(app):
     @click.command(context_settings={"ignore_unknown_options": True})
     @click.argument("py_test_args", nargs=-1, type=click.UNPROCESSED)
     @click.pass_context
-    def test_hpcflow(ctx, py_test_args):
+    def test_hpcflow(ctx: click.Context, py_test_args: list[str]):
         """Run hpcFlow test suite.
 
         PY_TEST_ARGS are arguments passed on to Pytest.
@@ -222,8 +247,7 @@ def _make_API_CLI(app):
         test,
     ]
     for cmd in commands:
-        if cmd.help:
-            cmd.help = cmd.help.format(app_name=app.name)
+        _set_help_name(cmd, app)
 
     if app.name != "hpcFlow":
         # `test_hpcflow` is the same as `test` for the hpcflow app no need to add both:
@@ -232,118 +256,116 @@ def _make_API_CLI(app):
     return commands
 
 
-def _make_workflow_submission_jobscript_CLI(app):
+def _make_workflow_submission_jobscript_CLI(app: BaseApp):
     """Generate the CLI for interacting with existing workflow submission
     jobscripts."""
 
     @click.group(name="js")
+    @_pass_submission
     @click.pass_context
     @click.argument("js_idx", type=click.INT)
-    def jobscript(ctx, js_idx):
+    def jobscript(ctx: click.Context, sb: Submission, js_idx: int):
         """Interact with existing {app_name} workflow submission jobscripts.
 
         JS_IDX is the jobscript index within the submission object.
 
         """
-        ctx.obj["jobscript"] = ctx.obj["submission"].jobscripts[js_idx]
+        ctx.obj = sb.jobscripts[js_idx]
 
     @jobscript.command(name="res")
-    @click.pass_context
-    def resources(ctx):
+    @_pass_js
+    def resources(job: Jobscript):
         """Get resources associated with this jobscript."""
-        click.echo(ctx.obj["jobscript"].resources.__dict__)
+        click.echo(job.resources.__dict__)
 
     @jobscript.command(name="deps")
-    @click.pass_context
-    def dependencies(ctx):
+    @_pass_js
+    def dependencies(job: Jobscript):
         """Get jobscript dependencies."""
-        click.echo(ctx.obj["jobscript"].dependencies)
+        click.echo(job.dependencies)
 
     @jobscript.command()
-    @click.pass_context
-    def path(ctx):
+    @_pass_js
+    def path(job: Jobscript):
         """Get the file path to the jobscript."""
-        click.echo(ctx.obj["jobscript"].jobscript_path)
+        click.echo(job.jobscript_path)
 
     @jobscript.command()
-    @click.pass_context
-    def show(ctx):
+    @_pass_js
+    def show(job: Jobscript):
         """Show the jobscript file."""
-        with ctx.obj["jobscript"].jobscript_path.open("rt") as fp:
+        with job.jobscript_path.open("rt") as fp:
             click.echo(fp.read())
 
-    jobscript.help = jobscript.help.format(app_name=app.name)
-
+    _set_help_name(jobscript, app)
     return jobscript
 
 
-def _make_workflow_submission_CLI(app):
+def _make_workflow_submission_CLI(app: BaseApp):
     """Generate the CLI for interacting with existing workflow submissions."""
 
     @click.group(name="sub")
+    @_pass_workflow
     @click.pass_context
     @click.argument("sub_idx", type=click.INT)
-    def submission(ctx, sub_idx):
+    def submission(ctx: click.Context, wf: Workflow, sub_idx: int):
         """Interact with existing {app_name} workflow submissions.
 
         SUB_IDX is the submission index.
 
         """
-        ctx.obj["submission"] = ctx.obj["workflow"].submissions[sub_idx]
+        ctx.obj = wf.submissions[sub_idx]
 
     @submission.command("status")
-    @click.pass_context
-    def status(ctx):
+    @_pass_submission
+    def status(sb: Submission):
         """Get the submission status."""
-        click.echo(ctx.obj["submission"].status.name.lower())
+        click.echo(sb.status.name.lower())
 
     @submission.command("submitted-js")
-    @click.pass_context
-    def submitted_JS(ctx):
+    @_pass_submission
+    def submitted_JS(sb: Submission):
         """Get a list of jobscript indices that have been submitted."""
-        click.echo(ctx.obj["submission"].submitted_jobscripts)
+        click.echo(sb.submitted_jobscripts)
 
     @submission.command("outstanding-js")
-    @click.pass_context
-    def outstanding_JS(ctx):
+    @_pass_submission
+    def outstanding_JS(sb: Submission):
         """Get a list of jobscript indices that have not yet been submitted."""
-        click.echo(ctx.obj["submission"].outstanding_jobscripts)
+        click.echo(sb.outstanding_jobscripts)
 
     @submission.command("needs-submit")
-    @click.pass_context
-    def needs_submit(ctx):
+    @_pass_submission
+    def needs_submit(sb: Submission):
         """Check if this submission needs submitting."""
-        click.echo(ctx.obj["submission"].needs_submit)
+        click.echo(sb.needs_submit)
 
     @submission.command("get-active-jobscripts")
-    @click.pass_context
-    def get_active_jobscripts(ctx):
+    @_pass_submission
+    def get_active_jobscripts(sb: Submission):
         """Show active jobscripts and their jobscript-element states."""
-        pprint(ctx.obj["submission"].get_active_jobscripts(as_json=True))
+        pprint(sb.get_active_jobscripts(as_json=True))
 
-    submission.help = submission.help.format(app_name=app.name)
+    _set_help_name(submission, app)
     submission.add_command(_make_workflow_submission_jobscript_CLI(app))
-
     return submission
 
 
-def _make_workflow_CLI(app):
+def _make_workflow_CLI(app: BaseApp):
     """Generate the CLI for interacting with existing workflows."""
 
     @click.group()
     @click.argument("workflow_ref")
     @workflow_ref_type_opt
     @click.pass_context
-    def workflow(ctx, workflow_ref, ref_type):
+    def workflow(ctx: click.Context, workflow_ref: str, ref_type: str | None):
         """Interact with existing {app_name} workflows.
 
         WORKFLOW_REF is the path to, or local ID of, an existing workflow.
 
         """
         workflow_path = app._resolve_workflow_reference(workflow_ref, ref_type)
-        wk = app.Workflow(workflow_path)
-        ctx.ensure_object(dict)
-        ctx.obj["workflow"] = wk
+        ctx.obj = app.Workflow(workflow_path)
 
     @workflow.command(name="submit")
     @js_parallelism_option
@@ -353,23 +375,23 @@ def _make_workflow_CLI(app):
     @tasks_opt
     @cancel_opt
     @submit_status_opt
-    @click.pass_context
+    @_pass_workflow
     def submit_workflow(
-        ctx,
-        js_parallelism=None,
-        wait=False,
-        add_to_known=True,
-        print_idx=False,
-        tasks=None,
-        cancel=False,
-        status=True,
+        wf: Workflow,
+        js_parallelism: bool | None = None,
+        wait: bool = False,
+        add_to_known: bool = True,
+        print_idx: bool = False,
+        tasks: list[int] | None = None,
+        cancel: bool = False,
+        status: bool = True,
     ):
         """Submit the workflow."""
-        out = ctx.obj["workflow"].submit(
+        out = wf.submit(
             JS_parallelism=js_parallelism,
             wait=wait,
             add_to_known=add_to_known,
-            return_idx=print_idx,
+            return_idx=True,
             tasks=tasks,
             cancel=cancel,
             status=status,
@@ -389,19 +411,19 @@ def _make_workflow_CLI(app):
             "separate patterns like these."
         ),
     )
-    @click.pass_context
-    def wait(ctx, jobscripts):
+    @_pass_workflow
+    def wait(wf: Workflow, jobscripts: str | None):
         js_spec = parse_jobscript_wait_spec(jobscripts) if jobscripts else None
-        ctx.obj["workflow"].wait(sub_js=js_spec)
+        wf.wait(sub_js=js_spec)
 
     @workflow.command(name="abort-run")
     @click.option("--submission", type=click.INT, default=-1)
     @click.option("--task", type=click.INT)
     @click.option("--element", type=click.INT)
-    @click.pass_context
-    def abort_run(ctx, submission, task, element):
+    @_pass_workflow
+    def abort_run(wf: Workflow, submission: int, task: int, element: int):
         """Abort the specified run."""
-        ctx.obj["workflow"].abort_run(
+        wf.abort_run(
             submission_idx=submission,
             task_idx=task,
             element_idx=element,
@@ -409,36 +431,36 @@ def _make_workflow_CLI(app):
 
     @workflow.command(name="get-param")
     @click.argument("index", type=click.INT)
-    @click.pass_context
-    def get_parameter(ctx, index):
+    @_pass_workflow
+    def get_parameter(wf: Workflow, index: int):
         """Get a parameter value by data index."""
-        click.echo(ctx.obj["workflow"].get_parameter_data(index))
+        click.echo(wf.get_parameter_data(index))
 
     @workflow.command(name="get-param-source")
     @click.argument("index", type=click.INT)
-    @click.pass_context
-    def get_parameter_source(ctx, index):
+    @_pass_workflow
+    def get_parameter_source(wf: Workflow, index: int):
         """Get a parameter source by data index."""
-        click.echo(ctx.obj["workflow"].get_parameter_source(index))
+        click.echo(wf.get_parameter_source(index))
 
     @workflow.command(name="get-all-params")
-    @click.pass_context
-    def get_all_parameters(ctx):
+    @_pass_workflow
+    def get_all_parameters(wf: Workflow):
         """Get all parameter values."""
-        click.echo(ctx.obj["workflow"].get_all_parameter_data())
+        click.echo(wf.get_all_parameter_data())
 
     @workflow.command(name="is-param-set")
     @click.argument("index", type=click.INT)
-    @click.pass_context
-    def is_parameter_set(ctx, index):
+    @_pass_workflow
+    def is_parameter_set(wf: Workflow, index: int):
         """Check if a parameter specified by data index is set."""
-        click.echo(ctx.obj["workflow"].is_parameter_set(index))
+        click.echo(wf.is_parameter_set(index))
 
     @workflow.command(name="show-all-status")
-    @click.pass_context
-    def show_all_EAR_statuses(ctx):
+    @_pass_workflow
+    def show_all_EAR_statuses(wf: Workflow):
         """Show the submission status of all workflow EARs."""
-        ctx.obj["workflow"].show_all_EAR_statuses()
+        wf.show_all_EAR_statuses()
 
     @workflow.command(name="zip")
     @zip_path_opt
@@ -446,19 +468,19 @@ def _make_workflow_CLI(app):
     @zip_log_opt
     @zip_include_execute_opt
     @zip_include_rechunk_backups_opt
-    @click.pass_context
+    @_pass_workflow
     def zip_workflow(
-        ctx,
-        path,
-        overwrite,
-        log,
-        include_execute,
-        include_rechunk_backups,
+        wf: Workflow,
+        path: str,
+        overwrite: bool,
+        log: str | None,
+        include_execute: bool,
+        include_rechunk_backups: bool,
     ):
         """Generate a copy of the workflow in the zip file format in the current working
         directory."""
         click.echo(
-            ctx.obj["workflow"].zip(
+            wf.zip(
                 path=path,
                 overwrite=overwrite,
                 log=log,
@@ -470,54 +492,48 @@ def _make_workflow_CLI(app):
     @workflow.command(name="unzip")
     @unzip_path_opt
     @unzip_log_opt
-    @click.pass_context
-    def unzip_workflow(ctx, path, log):
+    @_pass_workflow
+    def unzip_workflow(wf: Workflow, path: str, log: str | None):
         """Generate a copy of the zipped workflow in the submittable Zarr format in the
         current working directory."""
-        click.echo(ctx.obj["workflow"].unzip(path=path, log=log))
+        click.echo(wf.unzip(path=path, log=log))
 
     @workflow.command(name="rechunk")
     @rechunk_backup_opt
     @rechunk_chunk_size_opt
     @rechunk_status_opt
-    @click.pass_context
-    def rechunk(ctx, backup, chunk_size, status):
+    @_pass_workflow
+    def rechunk(wf: Workflow, backup: bool, chunk_size: int, status: bool):
         """Rechunk metadata/runs and parameters/base arrays."""
-        ctx.obj["workflow"].rechunk(backup=backup, chunk_size=chunk_size, status=status)
+        wf.rechunk(backup=backup, chunk_size=chunk_size, status=status)
 
     @workflow.command(name="rechunk-runs")
     @rechunk_backup_opt
     @rechunk_chunk_size_opt
     @rechunk_status_opt
-    @click.pass_context
-    def rechunk_runs(ctx, backup, chunk_size, status):
+    @_pass_workflow
+    def rechunk_runs(wf: Workflow, backup: bool, chunk_size: int, status: bool):
         """Rechunk the metadata/runs array."""
-        ctx.obj["workflow"].rechunk_runs(
-            backup=backup, chunk_size=chunk_size, status=status
-        )
+        wf.rechunk_runs(backup=backup, chunk_size=chunk_size, status=status)
 
     @workflow.command(name="rechunk-parameter-base")
     @rechunk_backup_opt
     @rechunk_chunk_size_opt
     @rechunk_status_opt
-    @click.pass_context
-    def rechunk_parameter_base(ctx, backup, chunk_size, status):
+    @_pass_workflow
+    def rechunk_parameter_base(wf: Workflow, backup: bool, chunk_size: int, status: bool):
         """Rechunk the parameters/base array."""
-        ctx.obj["workflow"].rechunk_parameter_base(
-            backup=backup, chunk_size=chunk_size, status=status
-        )
-
-    workflow.help = workflow.help.format(app_name=app.name)
+        wf.rechunk_parameter_base(backup=backup, chunk_size=chunk_size, status=status)
 
+    _set_help_name(workflow, app)
     workflow.add_command(_make_workflow_submission_CLI(app))
-
     return workflow
 
 
-def _make_submission_CLI(app):
+def _make_submission_CLI(app: BaseApp):
     """Generate the CLI for submission related queries."""
 
-    def OS_info_callback(ctx, param, value):
+    def OS_info_callback(ctx: click.Context, param, value: bool):
         if not value or ctx.resilient_parsing:
             return
         pprint(app.get_OS_info())
@@ -532,16 +548,15 @@ def _make_submission_CLI(app):
         expose_value=False,
         callback=OS_info_callback,
     )
-    @click.pass_context
-    def submission(ctx):
+    def submission():
         """Submission-related queries."""
-        ctx.ensure_object(dict)
+        pass
 
     @submission.command("shell-info")
-    @click.argument("shell_name", type=click.Choice(ALL_SHELLS))
+    @click.argument("shell_name", type=click.Choice(list(ALL_SHELLS)))
     @click.option("--exclude-os", is_flag=True, default=False)
     @click.pass_context
-    def shell_info(ctx, shell_name, exclude_os):
+    def shell_info(ctx: click.Context, shell_name: str, exclude_os: bool):
         """Show information about the specified shell, such as the version."""
         pprint(app.get_shell_info(shell_name, exclude_os))
         ctx.exit()
@@ -549,13 +564,14 @@ def _make_submission_CLI(app):
     @submission.group("scheduler")
     @click.argument("scheduler_name")
     @click.pass_context
-    def scheduler(ctx, scheduler_name):
-        ctx.obj["scheduler_obj"] = app.get_scheduler(scheduler_name, os.name)
+    def scheduler(ctx: click.Context, scheduler_name: str):
+        ctx.obj = app.get_scheduler(scheduler_name, os.name)
+
+    pass_scheduler = click.make_pass_decorator(SGEPosix)
 
     @scheduler.command()
-    @click.pass_context
-    def get_login_nodes(ctx):
-        scheduler = ctx.obj["scheduler_obj"]
+    @pass_scheduler
+    def get_login_nodes(scheduler: SGEPosix):
         pprint(scheduler.get_login_nodes())
 
     @submission.command()
@@ -566,8 +582,7 @@ def _make_submission_CLI(app):
         default=False,
         help="Do not format and only show JSON-compatible information.",
     )
-    @click.pass_context
-    def get_known(ctx, as_json=False):
+    def get_known(as_json: bool = False):
         """Print known-submissions information as a formatted Python object."""
         out = app.get_known_submissions(as_json=as_json)
         if as_json:
@@ -578,11 +593,11 @@ def _make_submission_CLI(app):
     return submission
 
 
-def _make_internal_CLI(app):
+def _make_internal_CLI(app: BaseApp):
     """Generate the CLI for internal use."""
 
     @click.group()
-    def internal(help=True):  # TEMP
+    def internal(help: bool = True):  # TEMP
         """Internal CLI to be invoked by scripts generated by the app."""
         pass
 
@@ -594,36 +609,36 @@ def _make_internal_CLI(app):
     @internal.group()
     @click.argument("path", type=click.Path(exists=True))
     @click.pass_context
-    def workflow(ctx, path):
+    def workflow(ctx: click.Context, path: Path):
         """"""
-        wk = app.Workflow(path)
-        ctx.ensure_object(dict)
-        ctx.obj["workflow"] = wk
+        ctx.obj = app.Workflow(path)
 
     @workflow.command()
+    @_pass_workflow
     @click.pass_context
     @click.argument("submission_idx", type=click.INT)
     @click.argument("jobscript_idx", type=click.INT)
     @click.argument("js_action_idx", type=click.INT)
     @click.argument("ear_id", type=click.INT)
     def write_commands(
-        ctx,
+        ctx: click.Context,
+        wf: Workflow,
         submission_idx: int,
         jobscript_idx: int,
         js_action_idx: int,
         ear_id: int,
     ):
         app.CLI_logger.info(f"write commands for EAR ID {ear_id!r}.")
-        ctx.exit(
-            ctx.obj["workflow"].write_commands(
-                submission_idx,
-                jobscript_idx,
-                js_action_idx,
-                ear_id,
-            )
+        wf.write_commands(
+            submission_idx,
+            jobscript_idx,
+            js_action_idx,
+            ear_id,
         )
+        ctx.exit()
 
     @workflow.command()
+    @_pass_workflow
     @click.pass_context
     @click.argument("name")
     @click.argument("value")
@@ -631,7 +646,8 @@ def _make_internal_CLI(app):
     @click.argument("cmd_idx", type=click.INT)
     @click.option("--stderr", is_flag=True, default=False)
     def save_parameter(
-        ctx,
+        ctx: click.Context,
+        wf: Workflow,
         name: str,
         value: str,
         ear_id: int,
@@ -643,9 +659,8 @@ def _make_internal_CLI(app):
             f"{cmd_idx!r} (stderr={stderr!r})"
         )
         app.CLI_logger.debug(f"save parameter value is: {value!r}")
-        wk = ctx.obj["workflow"]
-        with wk._store.cached_load():
-            value = wk.process_shell_parameter_output(
+        with wf._store.cached_load():
+            value = wf.process_shell_parameter_output(
                 name=name,
                 value=value,
                 EAR_ID=ear_id,
@@ -653,23 +668,27 @@ def _make_internal_CLI(app):
                 stderr=stderr,
             )
             app.CLI_logger.debug(f"save parameter processed value is: {value!r}")
-            ctx.exit(wk.save_parameter(name=name, value=value, EAR_ID=ear_id))
+            ctx.exit(wf.save_parameter(name=name, value=value, EAR_ID=ear_id))
 
     @workflow.command()
+    @_pass_workflow
     @click.pass_context
     @click.argument("ear_id", type=click.INT)
-    def set_EAR_start(ctx, ear_id: int):
+    def set_EAR_start(ctx: click.Context, wf: Workflow, ear_id: int):
         app.CLI_logger.info(f"set EAR start for EAR ID {ear_id!r}.")
-        ctx.exit(ctx.obj["workflow"].set_EAR_start(ear_id))
+        wf.set_EAR_start(ear_id)
+        ctx.exit()
 
     @workflow.command()
+    @_pass_workflow
     @click.pass_context
     @click.argument("js_idx", type=click.INT)
     @click.argument("js_act_idx", type=click.INT)
     @click.argument("ear_id", type=click.INT)
     @click.argument("exit_code", type=click.INT)
     def set_EAR_end(
-        ctx,
+        ctx: click.Context,
+        wf: Workflow,
         js_idx: int,
         js_act_idx: int,
         ear_id: int,
@@ -678,38 +697,42 @@ def _make_internal_CLI(app):
         app.CLI_logger.info(
             f"set EAR end for EAR ID {ear_id!r} with exit code {exit_code!r}."
         )
-        ctx.exit(
-            ctx.obj["workflow"].set_EAR_end(
-                js_idx=js_idx,
-                js_act_idx=js_act_idx,
-                EAR_ID=ear_id,
-                exit_code=exit_code,
-            )
+        wf.set_EAR_end(
+            js_idx=js_idx,
+            js_act_idx=js_act_idx,
+            EAR_ID=ear_id,
+            exit_code=exit_code,
         )
+        ctx.exit()
 
     @workflow.command()
+    @_pass_workflow
     @click.pass_context
     @click.argument("ear_id", type=click.INT)
-    def set_EAR_skip(ctx, ear_id: int):
+    def set_EAR_skip(ctx: click.Context, wf: Workflow, ear_id: int):
         app.CLI_logger.info(f"set EAR skip for EAR ID {ear_id!r}.")
-        ctx.exit(ctx.obj["workflow"].set_EAR_skip(ear_id))
+        wf.set_EAR_skip(ear_id)
+        ctx.exit()
 
     @workflow.command()
+    @_pass_workflow
     @click.pass_context
     @click.argument("ear_id", type=click.INT)
-    def get_EAR_skipped(ctx, ear_id: int):
+    def get_EAR_skipped(ctx: click.Context, wf: Workflow, ear_id: int):
         """Return 1 if the given EAR is to be skipped, else return 0."""
         app.CLI_logger.info(f"get EAR skip for EAR ID {ear_id!r}.")
-        click.echo(int(ctx.obj["workflow"].get_EAR_skipped(ear_id)))
+        click.echo(int(wf.get_EAR_skipped(ear_id)))
 
     @workflow.command()
+    @_pass_workflow
     @click.pass_context
     @click.argument("loop_name", type=click.STRING)
     @click.argument("ear_id", type=click.INT)
-    def check_loop(ctx, loop_name: str, ear_id: int):
+    def check_loop(ctx: click.Context, wf: Workflow, loop_name: str, ear_id: int):
         """Check if an iteration has met its loop's termination condition."""
         app.CLI_logger.info(f"check_loop for loop {loop_name!r} and EAR ID {ear_id!r}.")
-        ctx.exit(ctx.obj["workflow"].check_loop_termination(loop_name, ear_id))
+        wf.check_loop_termination(loop_name, ear_id)
+        ctx.exit()
 
     # TODO: in general, maybe the workflow command group can expose the simple Workflow
     # properties; maybe use a decorator on the Workflow property object to signify
@@ -718,17 +741,17 @@ def _make_internal_CLI(app):
     return internal
 
 
-def _make_template_components_CLI(app):
+def _make_template_components_CLI(app: BaseApp):
     @click.command()
-    def tc(help=True):
+    def tc(help: bool = True):
         """For showing template component data."""
         pprint(app.template_components)
 
     return tc
 
 
-def _make_show_CLI(app):
-    def show_legend_callback(ctx, param, value):
+def _make_show_CLI(app: BaseApp):
+    def show_legend_callback(ctx: click.Context, param, value: bool):
         if not value or ctx.resilient_parsing:
             return
         app.show_legend()
@@ -765,14 +788,14 @@ def _make_show_CLI(app):
         expose_value=False,
         callback=show_legend_callback,
     )
-    def show(max_recent, full, no_update):
+    def show(max_recent: int, full: bool, no_update: bool):
         """Show information about running and recently active workflows."""
         app.show(max_recent=max_recent, full=full, no_update=no_update)
 
     return show
 
 
-def _make_zip_CLI(app):
+def _make_zip_CLI(app: BaseApp):
     @click.command(name="zip")
     @click.argument("workflow_ref")
     @zip_path_opt
@@ -782,13 +805,13 @@ def _make_zip_CLI(app):
     @zip_include_rechunk_backups_opt
     @workflow_ref_type_opt
     def zip_workflow(
-        workflow_ref,
-        path,
-        overwrite,
-        log,
-        include_execute,
-        include_rechunk_backups,
-        ref_type,
+        workflow_ref: str,
+        path: str,
+        overwrite: bool,
+        log: str | None,
+        include_execute: bool,
+        include_rechunk_backups: bool,
+        ref_type: str | None,
     ):
         """Generate a copy of the specified workflow in the zip file format in the
         current working directory.
@@ -811,12 +834,12 @@ def _make_zip_CLI(app):
     return zip_workflow
 
 
-def _make_unzip_CLI(app):
+def _make_unzip_CLI(app: BaseApp):
     @click.command(name="unzip")
     @click.argument("workflow_path")
     @unzip_path_opt
     @unzip_log_opt
-    def unzip_workflow(workflow_path, path, log):
+    def unzip_workflow(workflow_path: str, path: str, log: str | None):
         """Generate a copy of the specified zipped workflow in the submittable Zarr
         format in the current working directory.
 
@@ -829,11 +852,11 @@ def _make_unzip_CLI(app):
     return unzip_workflow
 
 
-def _make_cancel_CLI(app):
+def _make_cancel_CLI(app: BaseApp):
     @click.command()
     @click.argument("workflow_ref")
     @workflow_ref_type_opt
-    def cancel(workflow_ref, ref_type):
+    def cancel(workflow_ref: str, ref_type: str | None):
         """Stop all running jobscripts of the specified workflow.
 
         WORKFLOW_REF is the local ID (that provided by the `show` command}) or the
@@ -845,14 +868,20 @@ def _make_cancel_CLI(app):
     return cancel
 
 
-def _make_rechunk_CLI(app):
+def _make_rechunk_CLI(app: BaseApp):
     @click.command(name="rechunk")
     @click.argument("workflow_ref")
     @workflow_ref_type_opt
     @rechunk_backup_opt
     @rechunk_chunk_size_opt
     @rechunk_status_opt
-    def rechunk(workflow_ref, ref_type, backup, chunk_size, status):
+    def rechunk(
+        workflow_ref: str,
+        ref_type: str | None,
+        backup: bool,
+        chunk_size: int,
+        status: bool,
+    ):
         """Rechunk metadata/runs and parameters/base arrays.
 
         WORKFLOW_REF is the local ID (that provided by the `show` command}) or the
@@ -866,7 +895,7 @@ def _make_rechunk_CLI(app):
     return rechunk
 
 
-def _make_open_CLI(app):
+def _make_open_CLI(app: BaseApp):
     @click.group(name="open")
     def open_file():
         """Open a file (for example {app_name}'s log file) using the default
@@ -874,9 +903,9 @@ def _make_open_CLI(app):
 
     @open_file.command()
     @click.option("--path", is_flag=True, default=False)
-    def log(path=False):
+    def log(path: bool = False):
         """Open the {app_name} log file."""
-        file_path = app.config.get("log_file_path")
+        file_path = app.config.log_file_path
         if path:
             click.echo(file_path)
         else:
@@ -884,9 +913,9 @@ def _make_open_CLI(app):
 
     @open_file.command()
     @click.option("--path", is_flag=True, default=False)
-    def config(path=False):
+    def config(path: bool = False):
         """Open the {app_name} config file, or retrieve it's path."""
-        file_path = app.config.get("config_file_path")
+        file_path = app.config.config_file_path
         if path:
             click.echo(file_path)
         else:
@@ -895,34 +924,30 @@ def _make_open_CLI(app):
     @open_file.command()
     @click.option("--name")
     @click.option("--path", is_flag=True, default=False)
-    def env_source(name=None, path=False):
+    def env_source(name: str | None = None, path: bool = False):
         """Open a named environment sources file, or the first one."""
-        sources = app.config.get("environment_sources")
-        if not sources:
+        if not (sources := app.config.environment_sources):
             raise ValueError("No environment sources specified in the config file.")
-        file_paths = []
         if not name:
             file_paths = [sources[0]]
         else:
-            for i in sources:
-                if i.name == name:
-                    file_paths.append(i)
+            file_paths = [pth for pth in sources if pth.name == name]
         if not file_paths:
             raise ValueError(
                 f"No environment source named {name!r} could be found; available "
-                f"environment source files have names: {[i.name for i in sources]!r}"
+                f"environment source files have names: {[pth.name for pth in sources]!r}"
             )
 
         assert len(file_paths) < 5  # don't open a stupid number of files
-        for i in file_paths:
+        for pth in file_paths:
             if path:
-                click.echo(i)
+                click.echo(pth)
             else:
-                utils.open_file(i)
+                utils.open_file(pth)
 
     @open_file.command()
     @click.option("--path", is_flag=True, default=False)
-    def known_subs(path=False):
+    def known_subs(path: bool = False):
         """Open the known-submissions text file."""
         file_path = app.known_subs_file_path
         if path:
@@ -934,7 +959,7 @@ def _make_open_CLI(app):
     @click.argument("workflow_ref")
     @click.option("--path", is_flag=True, default=False)
     @workflow_ref_type_opt
-    def workflow(workflow_ref, ref_type, path=False):
+    def workflow(workflow_ref: str, ref_type: str | None, path: bool = False):
         """Open a workflow directory using, for example, File Explorer on Windows."""
         workflow_path = app._resolve_workflow_reference(workflow_ref, ref_type)
         if path:
@@ -944,7 +969,7 @@ def _make_open_CLI(app):
 
     @open_file.command()
     @click.option("--path", is_flag=True, default=False)
-    def user_data_dir(path=False):
+    def user_data_dir(path: bool = False):
         dir_path = app._ensure_user_data_dir()
         if path:
             click.echo(dir_path)
@@ -953,7 +978,7 @@ def _make_open_CLI(app):
 
     @open_file.command()
     @click.option("--path", is_flag=True, default=False)
-    def user_cache_dir(path=False):
+    def user_cache_dir(path: bool = False):
         dir_path = app._ensure_user_cache_dir()
         if path:
             click.echo(dir_path)
@@ -962,7 +987,7 @@ def _make_open_CLI(app):
 
     @open_file.command()
     @click.option("--path", is_flag=True, default=False)
-    def user_runtime_dir(path=False):
+    def user_runtime_dir(path: bool = False):
         dir_path = app._ensure_user_runtime_dir()
         if path:
             click.echo(dir_path)
@@ -971,7 +996,7 @@ def _make_open_CLI(app):
 
     @open_file.command()
     @click.option("--path", is_flag=True, default=False)
-    def user_data_hostname_dir(path=False):
+    def user_data_hostname_dir(path: bool = False):
         dir_path = app._ensure_user_data_hostname_dir()
         if path:
             click.echo(dir_path)
@@ -980,7 +1005,7 @@ def _make_open_CLI(app):
 
     @open_file.command()
     @click.option("--path", is_flag=True, default=False)
-    def user_cache_hostname_dir(path=False):
+    def user_cache_hostname_dir(path: bool = False):
         dir_path = app._ensure_user_cache_hostname_dir()
         if path:
             click.echo(dir_path)
@@ -989,32 +1014,31 @@ def _make_open_CLI(app):
 
     @open_file.command()
     @click.option("--path", is_flag=True, default=False)
-    def demo_data_cache_dir(path=False):
+    def demo_data_cache_dir(path: bool = False):
         dir_path = app._ensure_demo_data_cache_dir()
         if path:
             click.echo(dir_path)
         else:
             utils.open_file(dir_path)
 
-    open_file.help = open_file.help.format(app_name=app.name)
-    log.help = log.help.format(app_name=app.name)
-    config.help = config.help.format(app_name=app.name)
-
+    _set_help_name(open_file, app)
+    _set_help_name(log, app)
+    _set_help_name(config, app)
     return open_file
 
 
-def _make_demo_data_CLI(app):
+def _make_demo_data_CLI(app: BaseApp):
     """Generate the CLI for interacting with example data files that are used in demo
     workflows."""
 
-    def list_callback(ctx, param, value):
+    def list_callback(ctx: click.Context, param, value: bool):
         if not value or ctx.resilient_parsing:
             return
         # TODO: format with Rich with a one-line description
         click.echo("\n".join(app.list_demo_data_files()))
         ctx.exit()
 
-    def cache_all_callback(ctx, param, value):
+    def cache_all_callback(ctx: click.Context, param, value: bool):
         if not value or ctx.resilient_parsing:
             return
         app.cache_all_demo_data_files()
@@ -1036,7 +1060,7 @@ def _make_demo_data_CLI(app):
     @demo_data.command("copy")
     @click.argument("file_name")
     @click.argument("destination")
-    def copy_demo_data(file_name, destination):
+    def copy_demo_data(file_name: str, destination: str):
         """Copy a demo data file to the specified location."""
         app.copy_demo_data(file_name=file_name, dst=destination)
 
@@ -1050,14 +1074,14 @@ def _make_demo_data_CLI(app):
         callback=cache_all_callback,
     )
     @click.argument("file_name")
-    def cache_demo_data(file_name):
+    def cache_demo_data(file_name: str):
         """Ensure a demo data file is in the demo data cache."""
         app.cache_demo_data_file(file_name)
 
     return demo_data
 
 
-def _make_manage_CLI(app):
+def _make_manage_CLI(app: BaseApp):
     """Generate the CLI for infrequent app management tasks."""
 
     @click.group()
@@ -1074,7 +1098,7 @@ def _make_manage_CLI(app):
         "--config-dir",
         help="The directory containing the config file to be reset.",
     )
-    def reset_config(config_dir):
+    def reset_config(config_dir: str):
         """Reset the configuration file to defaults.
 
         This can be used if the current configuration file is invalid."""
@@ -1085,7 +1109,7 @@ def _make_manage_CLI(app):
         "--config-dir",
         help="The directory containing the config file whose path is to be returned.",
     )
-    def get_config_path(config_dir):
+    def get_config_path(config_dir: str):
         """Print the config file path without loading the config.
 
         This can be used instead of `{app_name} open config --path` if the config file
@@ -1106,7 +1130,7 @@ def _make_manage_CLI(app):
 
     @manage.command("clear-cache")
     @click.option("--hostname", is_flag=True, default=False)
-    def clear_cache(hostname):
+    def clear_cache(hostname: bool):
         """Delete the app cache directory."""
         if hostname:
             app.clear_user_cache_hostname_dir()
@@ -1121,12 +1145,12 @@ def _make_manage_CLI(app):
     return manage
 
 
-def make_cli(app):
+def make_cli(app: BaseApp):
     """Generate the root CLI for the app."""
 
     colorama_init(autoreset=True)
 
-    def run_time_info_callback(ctx, param, value):
+    def run_time_info_callback(ctx: click.Context, param, value: bool):
         app.run_time_info.from_CLI = True
         if not value or ctx.resilient_parsing:
             return
@@ -1181,7 +1205,9 @@ def make_cli(app):
         ),
     )
     @click.pass_context
-    def new_CLI(ctx, config_dir, config_key, with_config, timeit, timeit_file):
+    def new_CLI(
+        ctx: click.Context, config_dir, config_key, with_config, timeit, timeit_file
+    ):
         app.run_time_info.from_CLI = True
         TimeIt.active = timeit or timeit_file
         TimeIt.file_path = timeit_file
@@ -1208,7 +1234,12 @@ def make_cli(app):
     @click.option("--use-current-env", is_flag=True, default=False)
     @click.option("--setup", type=click.STRING)
     @click.option("--env-source-file", type=click.STRING)
-    def configure_env(name, use_current_env, setup=None, env_source_file=None):
+    def configure_env(
+        name: str,
+        use_current_env: bool,
+        setup: list[str] | None = None,
+        env_source_file: str | None = None,
+    ):
         """Configure an app environment, using, for example, the currently activated
         Python environment."""
         app.configure_env(
@@ -1216,7 +1247,7 @@ def make_cli(app):
             setup=setup,
             executables=None,
             use_current_env=use_current_env,
-            env_source_file=env_source_file,
+            env_source_file=None if env_source_file is None else Path(env_source_file),
         )
 
     new_CLI.__doc__ = app.description