katalyst-taxonomy-cli 2.0.1a2__tar.gz → 2.0.1a3__tar.gz

{katalyst_taxonomy_cli-2.0.1a2 → katalyst_taxonomy_cli-2.0.1a3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: katalyst-taxonomy-cli
-Version: 2.0.1a2
+Version: 2.0.1a3
 Summary: CLI for katalyst-taxonomy — the kata command
 Author: eSimplicity
 License: Proprietary
@@ -8,5 +8,12 @@ Requires-Python: >=3.12
 Requires-Dist: click>=8.1
 Requires-Dist: katalyst-core<1,>=0.1
 Requires-Dist: katalyst-engine<6,>=5
+Requires-Dist: katalyst-plugin-context<1,>=0.2
+Requires-Dist: katalyst-plugin-harness<1,>=0.1
+Requires-Dist: katalyst-plugin-scaffolding<2,>=1
 Requires-Dist: katalyst-taxonomy-mcp<5,>=4
 Requires-Dist: katalyst-taxonomy<6,>=5
+Provides-Extra: bard
+Requires-Dist: katalyst-plugin-bard<1,>=0.1; extra == 'bard'
+Provides-Extra: tui
+Requires-Dist: katalyst-taxonomy-tui<3,>=2; extra == 'tui'

{katalyst_taxonomy_cli-2.0.1a2 → katalyst_taxonomy_cli-2.0.1a3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "katalyst-taxonomy-cli"
-version = "2.0.1a2"
+version = "2.0.1a3"
 description = "CLI for katalyst-taxonomy — the kata command"
 license = { text = "Proprietary" }
 requires-python = ">=3.12"
@@ -15,8 +15,20 @@ dependencies = [
     "katalyst-engine>=5,<6",
     "click>=8.1",
     "katalyst-core>=0.1,<1",
+    # The plugins that ship with kata: `kata tax context|harness|add`. Bounded to the
+    # config-rooted runtime, like the plugins' own floors on this package (a cycle pip
+    # and uv both resolve: a plugin's command imports this package's context and options).
+    "katalyst-plugin-context>=0.2,<1",
+    "katalyst-plugin-harness>=0.1,<1",
+    "katalyst-plugin-scaffolding>=1,<2",
 ]
 
+[project.optional-dependencies]
+# `kata tax bard`: the web UI plugin.
+bard = ["katalyst-plugin-bard>=0.1,<1"]
+# `kata tui`: the terminal UI.
+tui = ["katalyst-taxonomy-tui>=2,<3"]
+
 [project.scripts]
 kata = "katalyst_taxonomy_cli.__main__:main"
 

{katalyst_taxonomy_cli-2.0.1a2 → katalyst_taxonomy_cli-2.0.1a3}/src/katalyst_taxonomy_cli/_wiring.py

@@ -123,7 +123,9 @@ def _named(registry: BackendRegistry, target: str | None, address: str) -> tuple
     A prefix and ``--backend`` that disagree is an error rather than one silently
     winning: the command was told two different stores.
     """
-    if address:
+    from katalyst_taxonomy.config.routing import split_backend_prefix
+
+    if address and (target is None or split_backend_prefix(address)[0] is not None):
         parsed = registry.address(address)
         if target and target != parsed.backend:
             raise click.ClickException(
@@ -135,7 +137,7 @@ def _named(registry: BackendRegistry, target: str | None, address: str) -> tuple
             from katalyst_taxonomy.config.routing import UnknownBackendError
 
             raise UnknownBackendError(target, registry.profile_backends())
-        return target, ""
+        return target, address
     return None, ""
 
 

{katalyst_taxonomy_cli-2.0.1a2 → katalyst_taxonomy_cli-2.0.1a3}/src/katalyst_taxonomy_cli/app.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import importlib.util
 import subprocess
 import sys
 from pathlib import Path
@@ -77,6 +78,42 @@ class KataGroup(click.Group):
             raise click.ClickException(str(exc)) from exc
 
 
+def _missing_extra(name: str) -> str | None:
+    """The extra of this package named *name* whose requirements are not installed.
+
+    A command group a plugin contributes is offered as an extra of the same name
+    (``katalyst-taxonomy-cli[<name>]``). Read from this distribution's own metadata, so
+    the CLI names no plugin: ``None`` when there is no such extra, or it is installed.
+    """
+    import importlib.metadata as metadata
+    import re
+
+    try:
+        requirements = metadata.requires("katalyst-taxonomy-cli") or []
+    except metadata.PackageNotFoundError:
+        return None
+    marker = re.compile(rf"""extra\s*==\s*['"]{re.escape(name)}['"]""")
+    wanted = [r for r in requirements if marker.search(r)]
+    if not wanted:
+        return None
+    for requirement in wanted:
+        distribution = re.split(r"[\s;<>=!~\[(]", requirement, maxsplit=1)[0]
+        try:
+            metadata.distribution(distribution)
+        except metadata.PackageNotFoundError:
+            return name
+    return None
+
+
+def _not_installed_message(extra: str, label: str) -> str:
+    return (
+        f"{label} is not installed. Install it with:\n"
+        f"    pip install 'katalyst-taxonomy-cli[{extra}]'\n"
+        f"or, for a uv tool install:\n"
+        f"    uv tool install 'katalyst-taxonomy-cli[{extra}]'"
+    )
+
+
 class TaxGroup(click.Group):
     """The ``tax`` group, which resolves plugin-contributed commands **lazily**.
 
@@ -114,6 +151,16 @@ class TaxGroup(click.Group):
         self._ensure_plugin_commands(ctx)
         return super().get_command(ctx, cmd_name)
 
+    def resolve_command(
+        self, ctx: click.Context, args: list[str]
+    ) -> tuple[str | None, click.Command | None, list[str]]:
+        name = args[0] if args else None
+        if name and self.get_command(ctx, name) is None:
+            extra = _missing_extra(name)
+            if extra is not None:
+                raise click.ClickException(_not_installed_message(extra, f"`kata tax {name}`"))
+        return super().resolve_command(ctx, args)
+
     def _ensure_plugin_commands(self, ctx: click.Context) -> None:
         if self._plugin_commands_resolved:
             return
@@ -295,7 +342,12 @@ def _configure_logging() -> None:
 
 @cli.command("tui")
 def tui_cmd() -> None:
-    """Launch the interactive terminal UI."""
+    """Launch the interactive terminal UI.
+
+    The UI is an extra: ``pip install 'katalyst-taxonomy-cli[tui]'``.
+    """
+    if importlib.util.find_spec("katalyst_taxonomy_tui") is None:
+        raise click.ClickException(_not_installed_message("tui", "the terminal UI"))
     try:
         subprocess.run(
             [sys.executable, "-m", "katalyst_taxonomy_tui"],
@@ -466,6 +518,7 @@ def _register_core_commands() -> None:
         kinds,
         lifecycle,
         lint,
+        migrate,
         plugin,
         promote,
         query,
@@ -505,6 +558,7 @@ def _register_core_commands() -> None:
     tax.add_command(show.show)
     tax.add_command(kinds.kinds)
     tax.add_command(lint.lint)
+    tax.add_command(migrate.migrate)
     tax.add_command(deps.deps)
     tax.add_command(status.status)
     tax.add_command(rollback.rollback)

{katalyst_taxonomy_cli-2.0.1a2 → katalyst_taxonomy_cli-2.0.1a3}/src/katalyst_taxonomy_cli/commands/create.py

@@ -98,13 +98,13 @@ def create(
 
     Examples:
 
-        kata tax create stage verify --set halt_on_failure=false --set concern_order=maintainability
+        kata tax create layer api --under shop.backend --set audited=false --set tier=gold
 
-        kata tax create operation probe --set order=10 --set scope.regions=eu-west
+        kata tax create layer worker --under shop.backend --set priority=10 --set limits.region=eu-west
 
-        kata tax create venue ci --set 'triggers=[{"on":"push","environments":["dev"]}]'
+        kata tax create capability checkout --under shop --set 'hooks=[{"on":"push","branches":["main"]}]'
 
-        kata tax create environment qa --set template_replacements.log_level=debug
+        kata tax create stack web --under shop --set limits.log_level=debug
     """
     from katalyst_taxonomy.adapters.orchestration import run_create
     from katalyst_taxonomy.config.routing import split_backend_prefix

{katalyst_taxonomy_cli-2.0.1a2 → katalyst_taxonomy_cli-2.0.1a3}/src/katalyst_taxonomy_cli/commands/init.py

@@ -66,7 +66,7 @@ def init(
 
     Writes the taxonomy root (.global/taxonomy/) and version.yaml — together the
     "initialized" marker — and registers the repository as a filesystem backend of a
-    profile in the user config file (<user config home>/config.yaml): the --profile
+    profile in the active home's config (`kata config path` prints it): the --profile
     profile (created when it is not declared), else the active one; a file with no
     profiles gets a new `local`, made active. The backend is named --backend, else for
     the directory; a name the profile already declares for another directory is refused

{katalyst_taxonomy_cli-2.0.1a2 → katalyst_taxonomy_cli-2.0.1a3}/src/katalyst_taxonomy_cli/commands/lint.py

@@ -16,21 +16,39 @@ from katalyst_taxonomy_cli.context import CliContext
     is_flag=True,
     help=(
         "Treat advisory findings (governance id collisions, duplicate names, undeclared "
-        "spec keys, misplaced documents) as errors."
+        "spec keys, misplaced documents, shape findings and shape warnings) as errors."
+    ),
+)
+@click.option(
+    "--backend",
+    default=None,
+    help=(
+        "Report only this backend's findings. Its documents are still checked against "
+        "the graph of every backend the profile reads."
     ),
 )
 @click.pass_obj
-def lint(ctx: CliContext, verbose: bool, strict: bool) -> None:
+def lint(ctx: CliContext, verbose: bool, strict: bool, backend: str | None) -> None:
     """Validate taxonomy against schema — everything the active profile reads.
 
-    Document checks run over every backend the profile reads. Repository-local checks
-    (plugin rules, plugin-document schemas, version constraints) run once per
-    filesystem backend, and each finding is labelled [backend].
+    Every check runs over one graph: the documents of every backend the profile reads,
+    so a reference into another backend (other:shop.storefront.checkout) is checked
+    against the node it names. Each finding is labelled [backend] when the profile
+    reads more than one. Repository-local checks (plugin rules, plugin-document schemas,
+    version constraints) run once per filesystem backend. A backend that cannot be read
+    is an error naming it.
     """
     from katalyst_taxonomy.adapters.orchestration import run_lint
+    from katalyst_taxonomy.config.routing import BackendUnavailableError
 
     try:
-        result = run_lint(profile=ctx.profile)
+        result = run_lint(profile=ctx.profile, backend=backend)
+    except BackendUnavailableError as exc:
+        raise click.ClickException(
+            f"{exc}\nLint checks the graph of every backend the profile reads, so each "
+            "must be readable: make it reachable, or lint with a profile that does not "
+            "read it."
+        ) from exc
     except ValueError as exc:
         # A `filters` block that cannot be honoured — `include: []`, a clause
         # declaring `match.backend` — is a user error (#217), and lint does not go
@@ -39,6 +57,17 @@ def lint(ctx: CliContext, verbose: bool, strict: bool) -> None:
         # it still reaches the root group and still exits 7.
         raise click.ClickException(str(exc)) from exc
 
+    labelled = len(result.graph_backends) > 1
+
+    def _where(path: object) -> str:
+        """``[backend] path: `` for a finding about a file, as much as is known."""
+        label = ""
+        if labelled and isinstance(path, Path):
+            owner = result.backend_of(path)
+            label = f"[{owner}] " if owner else ""
+        shown = f"{path}: " if path is not None and str(path) not in ("", ".") else ""
+        return f"{label}{shown}"
+
     # Version constraint warnings are advisory (they do not make the taxonomy
     # invalid) but must still be surfaced — previously they were unreachable
     # when the taxonomy was otherwise valid, and only shown under --verbose.
@@ -99,21 +128,15 @@ def lint(ctx: CliContext, verbose: bool, strict: bool) -> None:
             ("Misplaced documents", result.misplaced_documents),
             ("Relationships no kind carries", result.uncarried_relationships),
             ("Shape findings", result.shape_findings),
+            ("Shape warnings", result.shape_warnings),
         ):
             if not found:
                 continue
             ctx.output.echo(f"\n{title} ({len(found)}):")
             for violation in found:
-                where = f"{violation.path}: " if str(violation.path) not in ("", ".") else ""
-                ctx.output.echo(f"  {severity}: {where}{violation.message}")
+                ctx.output.echo(f"  {severity}: {_where(violation.path)}{violation.message}")
             if not strict:
                 ctx.output.echo("  Re-run with --strict to fail on these.")
-        # A shape's warnings (e.g. coverage) are a report, strict or not.
-        if result.shape_warnings:
-            ctx.output.echo(f"\nShape warnings ({len(result.shape_warnings)}):")
-            for violation in result.shape_warnings:
-                where = f"{violation.path}: " if str(violation.path) not in ("", ".") else ""
-                ctx.output.echo(f"  WARNING: {where}{violation.message}")
 
     def _print_history_notes() -> None:
         found = result.removed_history_targets
@@ -121,8 +144,7 @@ def lint(ctx: CliContext, verbose: bool, strict: bool) -> None:
             return
         ctx.output.echo(f"\nHistory references to removed nodes ({len(found)}):")
         for violation in found:
-            where = f"{violation.path}: " if str(violation.path) not in ("", ".") else ""
-            ctx.output.echo(f"  INFO: {where}{violation.message}")
+            ctx.output.echo(f"  INFO: {_where(violation.path)}{violation.message}")
 
     strict_findings = (
         len(result.governance_id_collisions)
@@ -131,6 +153,7 @@ def lint(ctx: CliContext, verbose: bool, strict: bool) -> None:
         + len(result.misplaced_documents)
         + len(result.uncarried_relationships)
         + len(result.shape_findings)
+        + len(result.shape_warnings)
     )
     strict_failure = strict and strict_findings > 0
 
@@ -142,6 +165,10 @@ def lint(ctx: CliContext, verbose: bool, strict: bool) -> None:
             for repo in result.repositories
         )
         ctx.output.echo(f"  Repositories checked: {repositories or '(none)'}")
+        if result.focus is not None:
+            ctx.output.echo(
+                f"  Findings for: {result.focus}; graph: {', '.join(result.graph_backends)}"
+            )
         # Show the receipts: a gate that verified nothing must not look identical
         # to one that verified everything.
         ctx.output.echo(
@@ -179,14 +206,14 @@ def lint(ctx: CliContext, verbose: bool, strict: bool) -> None:
     if result.document_errors:
         ctx.output.echo(f"\nDocument errors ({len(result.document_errors)}):")
         for err in result.document_errors:
-            ctx.output.echo(f"  {err.path}: {err.message}")
+            ctx.output.echo(f"  {_where(err.path)}{err.message}")
 
     # Positioned between document and plugin-schema errors so block order is
     # fixed across runs and corpora.
     if result.reference_errors:
         ctx.output.echo(f"\nReference errors ({len(result.reference_errors)}):")
         for ref_err in result.reference_errors:
-            ctx.output.echo(f"  {ref_err.path}: {ref_err.message}")
+            ctx.output.echo(f"  {_where(ref_err.path)}{ref_err.message}")
 
     if result.plugin_schema_errors:
         ctx.output.echo(f"\nSchema errors ({len(result.plugin_schema_errors)}):")

katalyst_taxonomy_cli-2.0.1a3/src/katalyst_taxonomy_cli/commands/migrate.py

@@ -0,0 +1,210 @@
+"""kata tax migrate — move a repository's documents to the loaded schema versions."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import click
+
+from katalyst_taxonomy_cli.context import CliContext
+
+if TYPE_CHECKING:
+    from katalyst_taxonomy.services.schema_migration import MigrationReport
+
+
+@click.command("migrate")
+@click.option(
+    "--backend",
+    "backend",
+    default=None,
+    help=(
+        "The repository (a filesystem backend of the active profile) to migrate. "
+        "Default: every repository the profile reads."
+    ),
+)
+@click.option("--dry-run", is_flag=True, help="Show what would change, as a diff; write nothing.")
+@click.option(
+    "--from",
+    "starts",
+    multiple=True,
+    metavar="SCHEMA=VERSION",
+    help=(
+        "The version a schema's documents are at, instead of what the repository "
+        "records (or, when it records nothing, the schema's first release). Repeatable."
+    ),
+)
+@click.option(
+    "--allow-dirty",
+    is_flag=True,
+    help="Migrate even when files the migration writes have uncommitted changes.",
+)
+@click.option(
+    "--allow-lint-errors",
+    is_flag=True,
+    help="Write even when the migrated documents do not lint clean (strict).",
+)
+@click.option("--json", "as_json", is_flag=True, help="Print the report as JSON.")
+@click.pass_obj
+def migrate(
+    ctx: CliContext,
+    backend: str | None,
+    dry_run: bool,
+    starts: tuple[str, ...],
+    allow_dirty: bool,
+    allow_lint_errors: bool,
+    as_json: bool,
+) -> None:
+    """Move a repository's documents to the schema versions this kata loads.
+
+    A repository records the version of each schema its documents were written for
+    (.global/taxonomy/schema.lock). When a schema's major is behind the loaded one, the
+    repository is read-only until it is migrated: this runs the schema's migrations,
+    each major in turn, then lints the result strictly and records the new versions.
+
+    Nothing is committed: review the change with `git diff`, then commit it. A
+    repository already at the loaded majors is not changed (its lock is written when it
+    has none, or records an older minor), so running it twice is safe.
+    """
+    from katalyst_engine.evolution.chain import MigrationChainError
+    from katalyst_engine.evolution.lock import SchemaLockError
+    from katalyst_engine.evolution.migration import MigrationFileError, MigrationStepError
+    from katalyst_taxonomy.adapters.filesystem.schema_migration import MigrationWriteError
+    from katalyst_taxonomy.adapters.permission_gate import unwrap_backend
+    from katalyst_taxonomy.adapters.schema_migrate import MigrationRefused, migrate_repository
+    from katalyst_taxonomy.services.schema_migration import parse_starts
+
+    from katalyst_taxonomy_cli._wiring import load_registry
+
+    try:
+        start_versions = parse_starts(starts)
+    except ValueError as exc:
+        raise click.BadParameter(str(exc), param_hint="--from") from exc
+
+    registry = load_registry(ctx)
+    if backend is not None:
+        names = [backend]
+        if backend not in registry.profile_backends():
+            reads = ", ".join(registry.profile_backends()) or "none"
+            raise click.ClickException(
+                f"backend {backend!r} is not one the active profile reads ({reads})"
+            )
+    else:
+        names = list(registry.profile_backends())
+    repositories: list[tuple[str, Any]] = []
+    for name in names:
+        inner = unwrap_backend(registry.get(name))
+        if getattr(inner, "repository_root", None) is None or not callable(
+            getattr(inner, "read_schema_lock", None)
+        ):
+            if backend is not None:
+                raise click.ClickException(
+                    f"backend {name!r} is not a repository; `kata tax migrate` moves "
+                    "repositories (filesystem backends) forward"
+                )
+            continue
+        repositories.append((name, inner))
+    if not repositories:
+        raise click.ClickException("the active profile reads no repository to migrate")
+
+    payloads: list[dict[str, object]] = []
+    failed = False
+    for name, inner in repositories:
+        root = inner.repository_root
+        try:
+            report = migrate_repository(
+                name,
+                root,
+                dry_run=dry_run,
+                allow_dirty=allow_dirty,
+                allow_lint_errors=allow_lint_errors,
+                starts=start_versions,
+                excluded_subtrees=tuple(getattr(inner, "excluded_subtrees", ())),
+            )
+        except (
+            MigrationRefused,
+            MigrationChainError,
+            MigrationFileError,
+            MigrationStepError,
+            MigrationWriteError,
+            SchemaLockError,
+            ValueError,
+        ) as exc:
+            message = str(exc) if str(exc).startswith(f"{name}:") else f"{name}: {exc}"
+            payloads.append({"backend": name, "error": message})
+            if not as_json:
+                ctx.output.error(message)
+            failed = True
+            continue
+        payloads.append(report.to_dict())
+        if not as_json:
+            _print(ctx, report, dry_run=dry_run)
+    if as_json:
+        ctx.output.json_out(payloads[0] if len(payloads) == 1 else payloads)
+    if failed:
+        raise SystemExit(1)
+
+
+def _versions(report: MigrationReport) -> str:
+    moving = report.moving
+    if moving:
+        return ", ".join(f"{c.name} {c.start} → {c.target}" for c in moving)
+    return ", ".join(f"{c.name} {c.target}" for c in report.chains)
+
+
+def _print(ctx: CliContext, report: MigrationReport, *, dry_run: bool) -> None:
+    out = ctx.output
+    if report.rolled_back:
+        out.echo(
+            f"{report.backend}: an interrupted migration was rolled back "
+            f"({len(report.rolled_back)} file(s) put back)."
+        )
+    if report.nothing_to_do:
+        out.echo(f"{report.backend}: current ({_versions(report)}). Nothing to migrate.")
+        return
+    count = sum(len(c.migrations) for c in report.moving)
+    if report.moving:
+        taken = (
+            "" if report.status.recorded else " (no schema.lock: taken to be at the first release)"
+        )
+        out.echo(f"{report.backend}: {_versions(report)} ({count} migration(s)){taken}")
+    else:
+        out.echo(f"{report.backend}: current; recording its schema versions")
+    for chain in report.moving:
+        for migration in chain.migrations:
+            out.echo(f"  {chain.name} {migration.from_}-to-{migration.to}")
+            for outcome in report.outcomes:
+                if outcome.migration is migration:
+                    counts = f"{outcome.written} document(s)"
+                    if outcome.removed:
+                        counts += f", {outcome.removed} removed"
+                    out.echo(f"    {outcome.label:<52} {counts}")
+    actions: dict[str, int] = {}
+    for planned in report.files:
+        actions[planned.action] = actions.get(planned.action, 0) + 1
+    summary = ", ".join(f"{n} {a}" for a, n in sorted(actions.items()))
+    out.echo(f"Files ({len(report.files)}): {summary}")
+    for planned in report.files:
+        where = f"{planned.moved_from} → {planned.path}" if planned.moved_from else planned.path
+        out.echo(f"  {planned.action:<7} {where}")
+    after = ", ".join(f"{k} {v}" for k, v in report.lock_after.as_strings().items())
+    out.echo(f"schema.lock: {after}")
+    if report.lint_clean:
+        out.echo(f"lint after: clean (strict, {report.lint_documents} document(s))")
+    else:
+        out.echo(f"lint after: {len(report.lint_problems)} problem(s) (strict) in files it writes")
+        for problem in report.lint_problems[:20]:
+            out.echo(f"  {problem}")
+    if report.lint_other:
+        out.echo(
+            f"lint after, elsewhere: {len(report.lint_other)} problem(s) the migration "
+            "does not touch (not stopping it)"
+        )
+        for problem in report.lint_other[:20]:
+            out.echo(f"  {problem}")
+    if report.dirty:
+        out.echo(f"uncommitted changes to: {', '.join(report.dirty)}")
+    if dry_run:
+        out.echo("Nothing written (dry run). The changes, as a diff:")
+        out.echo(report.diff.rstrip("\n"))
+    elif report.applied:
+        out.echo("Written. Review the change with `git diff`, then commit it.")

{katalyst_taxonomy_cli-2.0.1a2 → katalyst_taxonomy_cli-2.0.1a3}/src/katalyst_taxonomy_cli/commands/relate.py

@@ -6,14 +6,31 @@ import click
 
 from katalyst_taxonomy_cli.context import CliContext
 
+_BACKEND = click.option(
+    "--backend",
+    "backend_target",
+    default=None,
+    help="The source's backend, when SOURCE_FQTN has no prefix.",
+)
 
-def _endpoints(ctx: CliContext, source_address: str, target_address: str):  # noqa: ANN202
+
+def _endpoints(  # noqa: ANN202
+    ctx: CliContext, source_address: str, target_address: str, backend_target: str | None = None
+):
     """The source and target ends; an unprefixed target is in the source's backend."""
-    from katalyst_taxonomy.config.routing import BackendAddressError
+    from katalyst_taxonomy.config.routing import BackendAddressError, split_backend_prefix
     from katalyst_taxonomy.services.relationships import endpoints
 
     from .._wiring import load_registry
 
+    prefix, bare = split_backend_prefix(source_address)
+    if backend_target is not None:
+        if prefix is not None and prefix != backend_target:
+            raise click.ClickException(
+                f"{source_address!r} names backend {prefix!r} but --backend is {backend_target!r}."
+            )
+        if prefix is None:
+            source_address = f"{backend_target}:{bare}"
     try:
         return endpoints(load_registry(ctx), source_address, target_address)
     except BackendAddressError as exc:
@@ -51,6 +68,7 @@ def _service():  # noqa: ANN202
     "--before", default=None, metavar="TARGET", help="In an ordered field, before TARGET."
 )
 @click.option("--after", default=None, metavar="TARGET", help="In an ordered field, after TARGET.")
+@_BACKEND
 @click.pass_obj
 def relate(
     ctx: CliContext,
@@ -61,6 +79,7 @@ def relate(
     index: int | None,
     before: str | None,
     after: str | None,
+    backend_target: str | None,
 ) -> None:
     """Relate two nodes, in the source's backend.
 
@@ -102,7 +121,7 @@ def relate(
         position = Position(index=index, before=before, after=after)
     except ValueError as exc:
         raise click.ClickException("give one of --index, --before and --after") from exc
-    source, target = _endpoints(ctx, source_fqtn, target_fqtn)
+    source, target = _endpoints(ctx, source_fqtn, target_fqtn, backend_target)
     outcome = _service().relate(source, rel_type, target, properties=props, position=position)
     if not outcome.success or outcome.relationship is None:
         ctx.output.echo(f"Error: {outcome.error}")
@@ -118,15 +137,22 @@ def relate(
 @click.argument("source_fqtn")
 @click.argument("rel_type")
 @click.argument("target_fqtn")
+@_BACKEND
 @click.pass_obj
-def unrelate(ctx: CliContext, source_fqtn: str, rel_type: str, target_fqtn: str) -> None:
+def unrelate(
+    ctx: CliContext,
+    source_fqtn: str,
+    rel_type: str,
+    target_fqtn: str,
+    backend_target: str | None,
+) -> None:
     """Remove a relationship ``kata tax relate`` made, from the source's backend.
 
     Examples:
 
         kata tax unrelate local:payments.checkout DEPENDS_ON payments.billing
     """
-    source, target = _endpoints(ctx, source_fqtn, target_fqtn)
+    source, target = _endpoints(ctx, source_fqtn, target_fqtn, backend_target)
     outcome = _service().unrelate(source, rel_type, target)
     if not outcome.success or outcome.relationship is None:
         ctx.output.echo(f"Error: {outcome.error}")