kerykeion-cli 6.0.0__py3-none-any.whl

kerykeion_cli/__init__.py

@@ -0,0 +1,35 @@
+# -*- coding: utf-8 -*-
+"""The ``kerykeion`` command: the console script and ``python -m kerykeion_cli`` both resolve to :func:`main`.
+
+Shipped as the ``kerykeion-cli`` distribution, which the ``kerykeion[cli]``
+extra installs — the library's own wheel carries no command. Built on the
+standard library alone (argparse), so kerykeion is the whole dependency, and
+``import kerykeion`` never imports this package.
+
+(It is not *fast*: importing a submodule imports ``kerykeion`` first — about a
+second of backend selection. Making that lazy is a change to ``kerykeion/__init__.py``.)
+"""
+
+from __future__ import annotations
+
+import sys
+
+__all__ = ["main"]
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Console-script entry point: parse, dispatch, and turn anything that escapes into a classified exit."""
+    from kerykeion_cli.app import run
+    from kerykeion_cli.errors import handle_uncaught
+
+    args = sys.argv[1:] if argv is None else list(argv)
+    try:
+        return run(args)
+    except SystemExit:
+        raise
+    except BaseException as exc:  # noqa: BLE001 — the whole point is to catch all
+        handle_uncaught(exc)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

kerykeion_cli/__main__.py

@@ -0,0 +1,6 @@
+# -*- coding: utf-8 -*-
+"""Enable ``python -m kerykeion_cli``."""
+
+from kerykeion_cli import main
+
+raise SystemExit(main())

kerykeion_cli/app.py

@@ -0,0 +1,87 @@
+# -*- coding: utf-8 -*-
+"""The command tree and its dispatch.
+
+:func:`build_parser` mounts every command and group on the root parser;
+:func:`run` parses one command line and calls the chosen command with its
+flags as keyword arguments. No kerykeion symbol is imported at module level,
+which keeps the cold-import gate green.
+"""
+
+from __future__ import annotations
+
+import argparse
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+from typing import Any, Callable
+
+from kerykeion_cli import errors, warnings
+from kerykeion_cli.parser import add_command, add_group
+
+try:
+    __version__ = _pkg_version("kerykeion-cli")
+except PackageNotFoundError:  # a source tree without installation
+    __version__ = "0.0.0"
+
+DESCRIPTION = (
+    "Astrology from the terminal. Save a subject once (kerykeion subject save ada --date 1990-07-15 "
+    "--time 10:30 --lat 41.9 --lng 12.5 --tz Europe/Rome), then pass -s ada to any command. "
+    "A terminal gets a text report, a pipe gets JSON; -f text|json|xml|svg and -o FILE choose explicitly."
+)
+
+# Namespace entries that are the parser's, not a command's.
+_INTERNAL = frozenset({"handler", "menu", "traceback", "warnings_as_errors", "envelope"})
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """The root parser with every command mounted: charts, analyses, techniques and events, subjects and setup."""
+    from kerykeion_cli.commands import analysis, call, charts, info, series, sky, status, subject, technique
+
+    root = argparse.ArgumentParser(prog="kerykeion", description=DESCRIPTION)
+    root.add_argument("-V", "--version", action="version", version=__version__, help="Print the kerykeion-cli version and exit.")
+    root.add_argument("--traceback", action="store_true", help="Show a full traceback on error (default: a one-line message).")
+    root.add_argument("--warnings-as-errors", action="store_true", help="Exit 9 when any ephemeris warning or house fallback occurs.")
+    root.set_defaults(menu=root)
+    subparsers = root.add_subparsers(metavar="<command>")
+    charts_and_analyses: list[tuple[str, Callable[..., Any]]] = [
+        ("natal", charts.natal),
+        ("now", charts.now),
+        ("synastry", charts.synastry),
+        ("transit", charts.transit),  # the single-moment dual wheel
+        ("composite", charts.composite),
+        ("return", charts.return_chart),  # `return` is a keyword, hence the callable's name
+        ("progression", charts.progression),
+        ("aspects", analysis.aspects),
+        ("dominants", analysis.dominants),
+        ("moon", analysis.moon),
+        ("relationship-score", analysis.relationship_score),
+    ]
+    for name, func in charts_and_analyses:
+        add_command(subparsers, name, func)
+    add_group(subparsers, "technique", "Analytical techniques on a stored subject.", technique.COMMANDS)
+    add_group(subparsers, "sky", "Sun, Moon and planet events, at a moment or over a range.", sky.COMMANDS)
+    series_commands: list[tuple[str, Callable[..., Any]]] = [("ephemeris", series.ephemeris), ("transits", series.transits)]
+    for name, func in series_commands:  # the time series
+        add_command(subparsers, name, func)
+    add_group(subparsers, "subject", "Save and inspect subjects; -s <name> reuses them everywhere.", subject.COMMANDS)
+    add_group(subparsers, "info", "What the flags accept: literals, point sets, fixed stars, methods.", info.COMMANDS)
+    add_command(subparsers, "status", status.status)
+    add_command(subparsers, "call", call.call)
+    return root
+
+
+def run(argv: list[str]) -> int:
+    """Parse *argv* and run the chosen command; a group or a bare ``kerykeion`` prints its help."""
+    args = build_parser().parse_args(argv)
+    errors.set_traceback_enabled(args.traceback)
+    errors.set_warnings_as_errors(args.warnings_as_errors)
+    warnings.set_envelope(bool(getattr(args, "envelope", False)))
+    handler = getattr(args, "handler", None)
+    if handler is None:
+        args.menu.print_help()
+        return 0
+    kwargs = {name: value for name, value in vars(args).items() if name not in _INTERNAL}
+    if getattr(handler, "render_flags", False):
+        from kerykeion_cli.commands._shared import _RENDER_FLAGS, _render_options
+
+        kwargs["opts"] = _render_options({flag: kwargs.pop(flag, None) for flag in _RENDER_FLAGS})
+    handler(**kwargs)
+    return 0

kerykeion_cli/commands/__init__.py

@@ -0,0 +1,2 @@
+# -*- coding: utf-8 -*-
+"""Command modules, mounted on the parser by :mod:`kerykeion_cli.app`."""

kerykeion_cli/commands/_shared.py

@@ -0,0 +1,186 @@
+# -*- coding: utf-8 -*-
+"""Helpers shared across the command modules — everything a command would otherwise repeat.
+
+A leaf module: it imports the CLI ``options``/``warnings``/``rendering`` helpers
+and the stdlib, never another command module, so importing it cannot cycle.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Callable, Optional, TypeVar
+
+from kerykeion_cli import options, warnings
+from kerykeion_cli import rendering
+
+_C = TypeVar("_C", bound=Callable[..., Any])
+
+
+def _emit(model: object, fmt: Optional[str], output: Optional[str], opts: object = None) -> None:
+    """Resolve the format and route the payload through the warnings funnel."""
+    warnings.output_with_warnings(model, rendering.resolve_format(fmt, output), output, opts=opts)
+
+
+def _given(**flags: Any) -> dict[str, Any]:
+    """The flags actually given, keyed by the library parameter they feed; ``None`` lets the library default decide."""
+    return {name: value for name, value in flags.items() if value is not None}
+
+
+def _stored_subject(spec: Optional[str], cmd: str, flag: str = "-s", **flags: Any):
+    """The stored subject a command names with ``-s`` (or ``-S``), or a usable error."""
+    if not spec:
+        raise ValueError(f"{cmd} needs {flag} <profile>")
+    from kerykeion_cli import subject_resolver
+
+    return subject_resolver.resolve_subject(subject_resolver.SubjectFlags(**flags), spec)
+
+
+def _split_csv(values: Optional[list[str]]) -> Optional[list[str]]:
+    """Flatten a repeatable option that may also carry comma-separated tokens."""
+    if values is None:
+        return None
+    out = [part.strip() for item in values for part in item.split(",") if part.strip()]
+    return out or None
+
+
+def _parse_dt(value: str) -> datetime:
+    """Parse an ISO date or datetime, with a usable error otherwise."""
+    try:
+        return datetime.fromisoformat(value)
+    except ValueError as exc:
+        raise ValueError(f"expected an ISO date or datetime (YYYY-MM-DD or YYYY-MM-DDThh:mm), got {value!r}") from exc
+
+
+def _choose(value: object, allowed: tuple[str, ...], label: str) -> object:
+    """Validate an enum-style flag case-insensitively, returning the canonical form."""
+    if value is None:
+        return None
+    canonical = {choice.lower(): choice for choice in allowed}
+    if str(value).strip().lower() not in canonical:
+        raise ValueError(f"--{label} must be {' or '.join(allowed)}, got {value!r}")
+    return canonical[str(value).strip().lower()]
+
+
+# ── --aspects: one syntax for the two shapes the library asks for ────────────
+# A plain list of names (mundane, solar arc, primary directions) or a list of
+# {name, orb} records (AspectsFactory). The optional ``:orb`` suffix is what the
+# second shape needs and the first cannot use, so _aspect_names refuses it by name.
+
+
+def _parse_aspects(values: Optional[list[str]]) -> Optional[list[tuple[str, Optional[float]]]]:
+    """``--aspects`` tokens of ``name`` or ``name:orb`` → ``[(name, orb-or-None), …]``."""
+    tokens = _split_csv(values)
+    if tokens is None:
+        return None
+    parsed: list[tuple[str, Optional[float]]] = []
+    for token in tokens:
+        name, sep, raw_orb = token.partition(":")
+        if not name.strip():
+            raise ValueError(f"--aspects: empty aspect name in {token!r}")
+        if not sep:
+            parsed.append((name.strip(), None))
+            continue
+        try:
+            parsed.append((name.strip(), float(raw_orb)))
+        except ValueError:
+            raise ValueError(
+                f"--aspects: {raw_orb.strip()!r} is not a number for the orb of {name.strip()!r} (use e.g. 'trine:6')"
+            ) from None
+    return parsed or None
+
+
+def _aspect_names(parsed: Optional[list[tuple[str, Optional[float]]]], context: str) -> Optional[list[str]]:
+    """Aspect names only, for the factories that take no per-aspect orb."""
+    if parsed is None:
+        return None
+    with_orb = [name for name, orb in parsed if orb is not None]
+    if with_orb:
+        raise ValueError(
+            f"--aspects: {context} takes aspect names without an orb; drop the ':orb' from {with_orb[0]!r}."
+        )
+    return [name for name, _ in parsed]
+
+
+def _active_aspects(parsed: Optional[list[tuple[str, Optional[float]]]]) -> Optional[list[dict[str, object]]]:
+    """``ActiveAspect`` records; an omitted orb takes the library's own default."""
+    if parsed is None:
+        return None
+    from kerykeion.settings import config_constants as cc
+
+    defaults = {str(entry["name"]): float(entry["orb"]) for entry in cc.ALL_ACTIVE_ASPECTS}
+    out: list[dict[str, object]] = []
+    for name, orb in parsed:
+        if orb is None and name not in defaults:
+            raise ValueError(
+                f"--aspects: unknown aspect {name!r}; choose from {', '.join(sorted(defaults))} "
+                "(or give an explicit orb, 'name:6')."
+            )
+        out.append({"name": name, "orb": defaults[name] if orb is None else orb})
+    return out
+
+
+# ── The shared flag sets are declared once, here ──────────────────────────────
+# A command is built from its signature, so the commands must spell the flags;
+# these keep the *set* in one place and turn a dropped flag into a loud failure
+# instead of one that quietly does nothing.
+
+_SUBJECT_FLAGS = (
+    "name", "date", "time", "seconds", "iso_utc", "lat", "lng", "tz", "city", "nation", "online", "offline",
+    "altitude", "zodiac", "sidereal_mode", "houses", "perspective", "points", "fixed_stars", "with_flags",
+    "without_flags", "set_flags",
+)  # fmt: skip
+
+
+def _subject_from(scope: dict, **overrides: object):
+    """``SubjectFlags`` from a command's ``locals()``; *overrides* replace flags the command does not expose."""
+    from kerykeion_cli import subject_resolver
+
+    missing = [name for name in _SUBJECT_FLAGS if name not in scope and name not in overrides]
+    if missing:
+        raise AssertionError(f"subject flags absent from the command signature: {', '.join(missing)}")
+    given: dict[str, Any] = {**{name: scope.get(name) for name in _SUBJECT_FLAGS}, **overrides}
+    for name in ("with_flags", "without_flags", "set_flags"):  # repeatable options arrive as None
+        given[name] = given[name] or []
+    return subject_resolver.SubjectFlags(**given)
+
+
+# CLI flag → (option alias, library parameter). Flag and parameter differ where
+# the flag reads better short and where the paired --x/--no-x form needs the
+# bare stem; ``no_aspects`` (the negative face of ``include_aspects``) is
+# translated in _render_options instead.
+_RENDER_FLAGS: dict[str, tuple[Any, Optional[str]]] = {
+    "no_aspects": (options.NoAspectsFlag, None),
+    "max_aspects": (options.MaxAspectsOpt, "max_aspects"),
+    "theme": (options.ThemeOpt, "theme"),
+    "chart_language": (options.ChartLanguageOpt, "chart_language"),
+    "style": (options.ChartStyleOpt, "style"),
+    "custom_title": (options.CustomTitleOpt, "custom_title"),
+    "padding": (options.PaddingOpt, "padding"),
+    "external_view": (options.ExternalViewFlag, "external_view"),
+    "transparent_background": (options.TransparentBackgroundFlag, "transparent_background"),
+    "cusp_position_comparison": (options.CuspComparisonFlag, "show_cusp_position_comparison"),
+    "auto_size": (options.AutoSizeFlag, "auto_size"),
+    "degree_indicators": (options.DegreeIndicatorsFlag, "show_degree_indicators"),
+    "aspect_icons": (options.AspectIconsFlag, "show_aspect_icons"),
+    "zodiac_ring": (options.ZodiacRingFlag, "show_zodiac_background_ring"),
+    "diurnality": (options.DiurnalityFlag, "show_diurnality"),
+    "house_position_comparison": (options.HousePositionComparisonFlag, "show_house_position_comparison"),
+    "aspect_grid_type": (options.AspectGridTypeOpt, "double_chart_aspect_grid_type"),
+    "svg_variant": (options.SvgVariantOpt, "svg_variant"),
+    "chart_settings": (options.ChartSettingsOpt, "chart_settings"),
+}
+
+
+def _render_options(given: dict[str, Any]) -> object:
+    """The render flags → ``RenderOptions`` (``None`` if none were given)."""
+    from kerykeion_cli import render_options
+
+    kwargs = {param: given[flag] for flag, (_, param) in _RENDER_FLAGS.items() if param}
+    kwargs["include_aspects"] = False if given["no_aspects"] else None  # not passing it stays "not given"
+    return render_options.build(**kwargs)
+
+
+def with_render_flags(command: _C) -> _C:
+    """Mark *command* as taking the shared report/chart flags: the parser declares them, the dispatcher hands them over as ``opts``."""
+    command.render_flags = True  # type: ignore[attr-defined]
+    return command

kerykeion_cli/commands/analysis.py

@@ -0,0 +1,159 @@
+# -*- coding: utf-8 -*-
+"""Analysis commands: ``aspects``, ``dominants``, ``moon``, ``relationship-score``.
+
+The four most common questions asked of a chart, reported rather than drawn.
+All of them are reachable through ``kerykeion call`` too; these give each a
+real ``--help``.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from kerykeion_cli.commands._shared import _active_aspects, _emit, _given, _parse_aspects, _split_csv, _stored_subject
+from kerykeion_cli.options import (
+    AccidentalDignitiesFlag,
+    AspectsOpt,
+    AxisOrbLimitOpt,
+    CustomWeightsOpt,
+    DeclinationOrbOpt,
+    DeclinationsFlag,
+    DistributionMethodOpt,
+    DominantMethodOpt,
+    FormatOpt,
+    LocationPrecisionOpt,
+    AllAspectsFlag,
+    OutputOpt,
+    PlanetsOpt,
+    ScoreBreakdownFlag,
+    Subject2Profile,
+    SubjectProfile,
+    UsingDefaultLocationFlag,
+)
+
+
+def aspects(
+    profile: SubjectProfile = None,
+    subject2: Subject2Profile = None,
+    declinations: DeclinationsFlag = None,
+    planets: PlanetsOpt = None,
+    aspect_list: AspectsOpt = None,
+    axis_orb_limit: AxisOrbLimitOpt = None,
+    orb: DeclinationOrbOpt = None,
+    fmt: FormatOpt = None,
+    output: OutputOpt = None,
+) -> None:
+    """Aspects within a chart, or between two (-S).
+
+    Declination aspects take a single ``--orb`` and have no per-aspect table
+    or axis rule, so ``--aspects`` and ``--axis-orb-limit`` are rejected there.
+    """
+    from kerykeion import AspectsFactory
+
+    first = _stored_subject(profile, "aspects")
+    second = _stored_subject(subject2, "aspects", "-S") if subject2 else None
+    kwargs: dict[str, Any] = _given(active_points=_split_csv(planets))
+    model: object
+    if declinations:
+        rejected = [f for f, v in (("--aspects", aspect_list), ("--axis-orb-limit", axis_orb_limit)) if v is not None]
+        if rejected:
+            raise ValueError(
+                f"{rejected[0]} does not apply to declination aspects; they use a single --orb and have no per-aspect table."
+            )
+        kwargs.update(_given(orb=orb))
+        model = (
+            AspectsFactory.dual_chart_declination_aspects(first, second, **kwargs)  # type: ignore[arg-type]
+            if second is not None
+            else AspectsFactory.single_chart_declination_aspects(first, **kwargs)  # type: ignore[arg-type]
+        )
+    else:
+        if orb is not None:
+            raise ValueError(
+                "--orb applies to --declinations; for ecliptic aspects give the orb per aspect, e.g. --aspects trine:6."
+            )
+        if axis_orb_limit is not None and axis_orb_limit <= 0:  # invalid input (4), not a library error (5)
+            raise ValueError("--axis-orb-limit must be a positive number.")
+        kwargs.update(
+            _given(active_aspects=_active_aspects(_parse_aspects(aspect_list)), axis_orb_limit=axis_orb_limit)
+        )
+        model = (
+            AspectsFactory.dual_chart_aspects(first, second, **kwargs)  # type: ignore[arg-type]
+            if second is not None
+            else AspectsFactory.single_chart_aspects(first, **kwargs)  # type: ignore[arg-type]
+        )
+    _emit(model, fmt, output)
+
+
+def dominants(
+    profile: SubjectProfile = None,
+    method: DominantMethodOpt = None,
+    planets: PlanetsOpt = None,
+    distribution_method: DistributionMethodOpt = None,
+    custom_weights: CustomWeightsOpt = None,
+    accidental_dignities: AccidentalDignitiesFlag = None,
+    score_breakdown: ScoreBreakdownFlag = None,
+    fmt: FormatOpt = None,
+    output: OutputOpt = None,
+) -> None:
+    """Dominant signs, elements, qualities and planets."""
+    from kerykeion import DominantsFactory
+
+    subject = _stored_subject(profile, "dominants")
+    kwargs: dict[str, Any] = _given(
+        active_points=_split_csv(planets),
+        distribution_method=distribution_method,
+        include_accidental_dignities=accidental_dignities,
+        include_score_breakdown=score_breakdown,
+    )
+    if method is not None:  # validated against what the library reports, so a new strategy works the day it ships
+        available = list(DominantsFactory.available_methods())
+        chosen = {name.lower(): name for name in available}.get(method.strip().lower())
+        if chosen is None:
+            raise ValueError(f"--method must be one of {', '.join(available)}, got {method!r}")
+        kwargs["strategy"] = chosen
+    if custom_weights is not None:
+        try:
+            weights = json.loads(custom_weights)
+        except json.JSONDecodeError as exc:
+            raise ValueError(
+                f"--custom-weights is not valid JSON ({exc.msg}); expected an object like '{{\"Sun\": 1.5}}'."
+            ) from None
+        if not isinstance(weights, dict):
+            raise ValueError("--custom-weights must be a JSON object, e.g. '{\"Sun\": 1.5}'.")
+        kwargs["custom_weights"] = weights
+    _emit(DominantsFactory.from_subject(subject, **kwargs), fmt, output)  # type: ignore[arg-type]
+
+
+def moon(
+    profile: SubjectProfile = None,
+    using_default_location: UsingDefaultLocationFlag = None,
+    location_precision: LocationPrecisionOpt = None,
+    fmt: FormatOpt = None,
+    output: OutputOpt = None,
+) -> None:
+    """Moon phase at the subject's moment and place."""
+    from kerykeion import MoonPhaseDetailsFactory
+
+    subject = _stored_subject(profile, "moon")
+    kwargs = _given(using_default_location=using_default_location, location_precision=location_precision)
+    _emit(MoonPhaseDetailsFactory.from_subject(subject, **kwargs), fmt, output)  # type: ignore[arg-type]
+
+
+def relationship_score(
+    profile: SubjectProfile = None,
+    subject2: Subject2Profile = None,
+    all_aspects: AllAspectsFlag = None,
+    axis_orb_limit: AxisOrbLimitOpt = None,
+    fmt: FormatOpt = None,
+    output: OutputOpt = None,
+) -> None:
+    """Discepolo relationship score of two stored subjects."""
+    from kerykeion import RelationshipScoreFactory
+
+    first = _stored_subject(profile, "relationship-score")
+    second = _stored_subject(subject2, "relationship-score", "-S")
+    kwargs = _given(
+        use_only_major_aspects=None if all_aspects is None else not all_aspects, axis_orb_limit=axis_orb_limit
+    )
+    _emit(RelationshipScoreFactory(first, second, **kwargs).get_relationship_score(), fmt, output)  # type: ignore[arg-type]

kerykeion_cli/commands/call.py

@@ -0,0 +1,88 @@
+# -*- coding: utf-8 -*-
+"""``kerykeion call`` — a guarded dispatcher over the public API.
+
+    kerykeion call ProfectionsFactory.from_subject -s ada --param target_date=2025-06-01
+    kerykeion call --list
+    kerykeion call DominantsFactory.from_subject --explain
+
+Safety is :mod:`kerykeion_cli.registry`'s job (only ``__all__`` names, no
+private members, no models/exceptions). Subject parameters are bound from
+``-s``/``-S`` profiles; everything else comes as ``--param key=value`` with
+type coercion from :mod:`kerykeion_cli.introspect`.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any, Optional
+
+from kerykeion_cli import introspect, registry, subject_resolver
+from kerykeion_cli.commands._shared import _emit
+from kerykeion_cli.options import (
+    CallSubject2Opt,
+    ExplainFlag,
+    FormatOpt,
+    ListFlag,
+    OutputOpt,
+    ParamOpt,
+    SubjectProfile,
+)
+from kerykeion_cli.parser import Arg
+
+
+def _bind_subjects(
+    target: registry.ResolvedTarget, kwargs: dict[str, Any], first: Optional[str], second: Optional[str]
+) -> None:
+    """Assign the -s/-S profiles to the target's subject parameters, in order."""
+    slots = [p.name for p in introspect.explain(target) if p.classification == introspect.SUBJECT]
+    for flag, spec, index in (("-s", first, 0), ("-S", second, 1)):
+        if spec is None:
+            continue
+        if len(slots) <= index:
+            raise ValueError(
+                f"{target.spec} has {'no' if index == 0 else 'fewer than two'} subject parameter{'' if index == 0 else 's'}; {flag} is not used here."
+            )
+        kwargs[slots[index]] = subject_resolver.resolve_subject(subject_resolver.SubjectFlags(), spec)
+
+
+def call(
+    target_arg: Annotated[Optional[str], Arg(help="Call target: Factory.method or a bare function.")] = None,
+    list_flag: ListFlag = None,
+    explain_flag: ExplainFlag = None,
+    profile: SubjectProfile = None,
+    subject2: CallSubject2Opt = None,
+    param: ParamOpt = None,
+    fmt: FormatOpt = None,
+    output: OutputOpt = None,
+) -> None:
+    """Any public factory method, for what has no command of its own."""
+    if list_flag:
+        _emit(registry.list_targets(), fmt, output)
+        return
+    if target_arg is None:
+        raise ValueError("call needs a target (Factory.method) or --list.")
+    target = registry.resolve_target(target_arg)
+    if explain_flag:
+        _emit([p.as_dict() for p in introspect.explain(target)], fmt, output)
+        return
+
+    known = {**target.init_params, **target.method_params}
+    kwargs: dict[str, Any] = {}
+    for item in param or []:
+        if "=" not in item:
+            raise ValueError(f"--param expects key=value, got {item!r}")
+        key, raw_value = item.split("=", 1)
+        key = key.strip()
+        if key not in known:  # a typo must not run the library with defaults and no error
+            raise ValueError(f"--param {key!r} is not a parameter of {target.spec} (known: {', '.join(sorted(known))})")
+        kwargs[key] = introspect.coerce_value(known[key].annotation, raw_value)
+    _bind_subjects(target, kwargs, profile, subject2)
+
+    if target.needs_instance:
+        owner = registry.public_names()[target.owner_name]
+        instance = owner(**{k: v for k, v in kwargs.items() if k in target.init_params})
+        result = getattr(instance, target.member_name)(**{k: v for k, v in kwargs.items() if k in target.method_params})  # type: ignore[arg-type]
+    elif target.member_name:  # static or classmethod: through the owner so Python binds ``cls``
+        result = getattr(registry.public_names()[target.owner_name], target.member_name)(**kwargs)
+    else:
+        result = target.callable_fn(**kwargs)
+    _emit(result, fmt, output)