ixt-cli 0.9.1__tar.gz → 0.10.0__tar.gz

{ixt_cli-0.9.1 → ixt_cli-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ixt-cli
-Version: 0.9.1
+Version: 0.10.0
 Summary: Universal CLI tool isolator - manage Python, Node, and binary tools with per-tool isolation
 Project-URL: Homepage, https://gitlab.com/pytgaen-group/ixt
 Project-URL: Repository, https://gitlab.com/pytgaen-group/ixt.git
@@ -223,7 +223,7 @@ resolve upstream again and refresh the lock.
 | `ixt tool apply --locked --strict`             | Sync using exact versions and assets from ixt.lock                    |
 | `ixt tool export`                              | Export installed tools as ixt.toml (stdout), preserves install intent |
 | `ixt lock write`                               | Resolve ixt.toml and write ixt.lock                                   |
-| `ixt lock check`                               | Validate ixt.lock against ixt.toml locally                             |
+| `ixt lock check`                               | Validate ixt.lock against ixt.toml locally                            |
 | `ixt lock diff`                                | Show semantic differences between ixt.toml and ixt.lock               |
 | `ixt asset-index export`                       | Export portable binary-resolution metadata as JSON                    |
 | `ixt tool config <pkg> expose <rules...>`      | Change exposed binaries                                               |
@@ -232,6 +232,7 @@ resolve upstream again and refresh the lock.
 | `ixt tool config __all__ expose <rules...>`    | Re-expose every installed tool                                        |
 | `ixt tool shell <pkg>`                         | Open a subshell in tool's env                                         |
 | `ixt tool where <pkg>`                         | Print the tool env path                                               |
+| `ixt exec [--sudo] <tool> -- <args...>`        | Run an exposed tool by name, without relying on PATH                  |
 | `ixt environment [--sizes]`                    | Show ixt configuration, paths, and optional storage sizes             |
 | `ixt doctor`                                   | Check ixt health (runtimes, PATH, caches)                             |
 | `ixt cache info`                               | Show cache paths and sizes                                            |

{ixt_cli-0.9.1 → ixt_cli-0.10.0}/README.md

@@ -194,7 +194,7 @@ resolve upstream again and refresh the lock.
 | `ixt tool apply --locked --strict`             | Sync using exact versions and assets from ixt.lock                    |
 | `ixt tool export`                              | Export installed tools as ixt.toml (stdout), preserves install intent |
 | `ixt lock write`                               | Resolve ixt.toml and write ixt.lock                                   |
-| `ixt lock check`                               | Validate ixt.lock against ixt.toml locally                             |
+| `ixt lock check`                               | Validate ixt.lock against ixt.toml locally                            |
 | `ixt lock diff`                                | Show semantic differences between ixt.toml and ixt.lock               |
 | `ixt asset-index export`                       | Export portable binary-resolution metadata as JSON                    |
 | `ixt tool config <pkg> expose <rules...>`      | Change exposed binaries                                               |
@@ -203,6 +203,7 @@ resolve upstream again and refresh the lock.
 | `ixt tool config __all__ expose <rules...>`    | Re-expose every installed tool                                        |
 | `ixt tool shell <pkg>`                         | Open a subshell in tool's env                                         |
 | `ixt tool where <pkg>`                         | Print the tool env path                                               |
+| `ixt exec [--sudo] <tool> -- <args...>`        | Run an exposed tool by name, without relying on PATH                  |
 | `ixt environment [--sizes]`                    | Show ixt configuration, paths, and optional storage sizes             |
 | `ixt doctor`                                   | Check ixt health (runtimes, PATH, caches)                             |
 | `ixt cache info`                               | Show cache paths and sizes                                            |

{ixt_cli-0.9.1 → ixt_cli-0.10.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ixt-cli"
-version = "0.9.1" # to bump
+version = "0.10.0" # to bump
 description = "Universal CLI tool isolator - manage Python, Node, and binary tools with per-tool isolation"
 readme = "README.md"
 requires-python = ">=3.10"

{ixt_cli-0.9.1 → ixt_cli-0.10.0}/src/ixt/backends/binary.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import hashlib
 import json
+import os
 import re
 from dataclasses import dataclass, field
 from pathlib import Path
@@ -31,8 +32,10 @@ from ixt.config.settings import Settings, get_settings
 from ixt.core.backend import BackendType
 from ixt.core.discover import find_executables
 from ixt.core.extract import extract, is_archive
+from ixt.libs.elf import PREFIX_SIZE as ELF_PREFIX_SIZE
+from ixt.libs.elf import parse_elf, read_elf
 from ixt.libs.logger import get_logger, get_verbosity
-from ixt.net.http import MAX_DOWNLOAD_SIZE, DownloadTooLargeError
+from ixt.net.http import MAX_DOWNLOAD_SIZE, DownloadTooLargeError, get_range
 from ixt.net.source import Asset, Release, ReleaseSource, RepoSpec, parse_spec
 from ixt.platform import get_arch, get_os
 
@@ -88,14 +91,27 @@ class SetupMetadata(_SetupMetadataRequired, total=False):
 class AssetSelectionError(RuntimeError):
     """Raised when no suitable asset could be selected for the current platform."""
 
-    def __init__(self, spec: str, release_tag: str, asset_names: list[str]):
+    def __init__(
+        self,
+        spec: str,
+        release_tag: str,
+        asset_names: list[str],
+        unusable: list[tuple[str, str]] | None = None,
+    ):
         self.spec = spec
         self.release_tag = release_tag
         self.asset_names = asset_names
+        self.unusable = unusable or []
         names = ", ".join(asset_names[:10]) or "<none>"
-        super().__init__(
+        message = (
             f"No suitable asset found for '{spec}' (release {release_tag}). Available: {names}"
         )
+        if self.unusable:
+            skipped = ", ".join(
+                f"{name} (needs missing loader {loader})" for name, loader in self.unusable
+            )
+            message += f". Skipped as unrunnable here: {skipped}"
+        super().__init__(message)
 
 
 class BinaryPlatformError(RuntimeError):
@@ -580,7 +596,22 @@ class BinaryBackend:
             log.debug(f"user-forced asset_pattern: {asset_pattern!r}")
         selection_pattern = _selection_pattern(effective_pattern, release.tag)
         if locked_binary is None:
-            asset = self._select_asset(release, selection_pattern, tool_name, spec)
+            try:
+                asset = self._select_asset(
+                    release, selection_pattern, tool_name, spec, repo_spec=repo_spec
+                )
+            except AssetSelectionError:
+                # A synthesized release carries only the asset its pattern named.
+                # If that asset cannot run here, the pattern is wrong for this
+                # host, not merely stale — relearn it against the full release.
+                relearned = self._relearn_release(source, repo_spec, release)
+                if relearned is None:
+                    raise
+                release = relearned
+                selection_pattern = _selection_pattern(effective_pattern, release.tag)
+                asset = self._select_asset(
+                    release, selection_pattern, tool_name, spec, repo_spec=repo_spec
+                )
         else:
             asset = release.assets[0]
             if not is_asset_arch_compatible(
@@ -733,23 +764,110 @@ class BinaryBackend:
         asset_pattern: str | None,
         tool_name: str,
         main_spec: str,
+        *,
+        repo_spec: RepoSpec | None = None,
     ) -> Asset:
+        log = get_logger("binary")
         heuristics = load_heuristics()
-        asset = select_asset(
-            release.assets,
-            tool_name,
-            _strip_v_prefix(release.tag),
-            heuristics=heuristics,
-            asset_pattern=asset_pattern,
-            verbose=get_verbosity(),
-        )
-        if asset is None:
-            raise AssetSelectionError(
-                main_spec,
-                release.tag,
-                [a.name for a in release.assets],
+        candidates = list(release.assets)
+        unusable: list[tuple[str, str]] = []
+
+        while candidates:
+            asset = select_asset(
+                candidates,
+                tool_name,
+                _strip_v_prefix(release.tag),
+                heuristics=heuristics,
+                asset_pattern=asset_pattern,
+                verbose=get_verbosity(),
             )
-        return asset
+            if asset is None:
+                break
+
+            loader = self._unrunnable_loader(asset, repo_spec=repo_spec, tag=release.tag)
+            if loader is None:
+                return asset
+
+            log.debug(f"asset skip: {asset.name} needs missing loader {loader}")
+            unusable.append((asset.name, loader))
+            candidates = [a for a in candidates if a.name != asset.name]
+
+        raise AssetSelectionError(
+            main_spec,
+            release.tag,
+            [a.name for a in release.assets],
+            unusable,
+        )
+
+    def _relearn_release(
+        self,
+        source: ReleaseSource,
+        repo_spec: RepoSpec,
+        release: Release,
+    ) -> Release | None:
+        """Re-fetch *release* from the API after its learned pattern proved wrong.
+
+        The fast path synthesizes a release holding only the asset its pattern
+        names, so a pattern pointing at an unrunnable build leaves selection
+        with nothing to fall back on. The pattern is dropped and the real asset
+        list fetched, which lets scoring reach the runnable siblings.
+
+        Returns None when the release already came from the API: there is then
+        no wider list to fall back to, and the caller should surface the
+        original selection error instead.
+        """
+        if (release.resolution_source or "").endswith("-api"):
+            return None
+
+        log = get_logger("binary")
+        log.debug(
+            f"asset pattern for {repo_spec.owner}/{repo_spec.repo} names an unrunnable "
+            "asset — invalidating and refetching from the release API"
+        )
+        from ixt.config import asset_pattern_cache
+
+        asset_pattern_cache.invalidate(repo_spec.owner, repo_spec.repo)
+        self._require_github_api(repo_spec)
+        refetched = source.get_release_by_tag(repo_spec.owner, repo_spec.repo, release.tag)
+        refetched.resolution_source = f"{repo_spec.platform}-api"
+        log.debug(f"release (relearn): {refetched.tag} ({len(refetched.assets)} assets)")
+        return refetched
+
+    def _unrunnable_loader(
+        self,
+        asset: Asset,
+        *,
+        repo_spec: RepoSpec | None,
+        tag: str,
+    ) -> str | None:
+        """Return the loader *asset* needs but this host lacks, else None.
+
+        A cached asset is read from disk; otherwise only the head of the asset
+        is fetched over HTTP Range, which keeps a doomed candidate from costing
+        a full download. Only bare binaries can be checked this way — an
+        archive reveals nothing at offset zero, so those are validated after
+        extraction by ``find_executables`` instead.
+
+        Any doubt resolves to None: a server without Range support, a network
+        hiccup, or a truncated prefix all fall through to the normal path.
+        """
+        if os.name == "nt" or is_archive(asset.name):
+            return None
+        if repo_spec is not None:
+            cache_path = _asset_cache_path(self.settings.downloads_dir, repo_spec, asset, tag=tag)
+            cached = _cached_asset(cache_path, asset.size)
+            if cached is not None:
+                # Already on disk: judge the real file, no request needed.
+                info = read_elf(cached)
+                return info.interpreter if info is not None and info.loader_missing() else None
+
+        head = get_range(asset.url, ELF_PREFIX_SIZE)
+        if head is None:
+            return None
+        info = parse_elf(head)
+        if info is None or not info.loader_missing():
+            return None
+        return info.interpreter
 
     def uninstall_package(self, env_dir: Path, package: str) -> None:
         """No-op — binary tools are atomic (uninstall removes the whole env)."""

{ixt_cli-0.9.1 → ixt_cli-0.10.0}/src/ixt/backends/node.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 import json
 import os
 import re
+import shlex
 import shutil
 from dataclasses import dataclass, field
 from pathlib import Path
@@ -27,6 +28,29 @@ from ixt.platform import is_windows
 #   #!/usr/bin/env nodemon          → no match
 _NODE_SHEBANG_RE = re.compile(rb"^#!.*\bnode\b")
 
+
+def _resolve_bun_path(bun_path: str) -> str:
+    """Return an absolute path without resolving a stable bun symlink."""
+    candidate = Path(bun_path).expanduser()
+    if not candidate.is_absolute():
+        resolved = shutil.which(bun_path)
+        if resolved is None:
+            raise FileNotFoundError(f"Cannot resolve bun executable: {bun_path}")
+        candidate = Path(resolved)
+    return str(candidate.absolute())
+
+
+def _bun_shebang(bun_path: str) -> bytes:
+    """Build a portable launcher header for an absolute bun path."""
+    if "\n" in bun_path or "\r" in bun_path:
+        raise ValueError("bun executable path cannot contain a line break")
+    if any(char.isspace() for char in bun_path):
+        # macOS splits shebang arguments before ``env -S`` can parse quotes.
+        # This second line is a shell exec and a JavaScript no-op/comment.
+        return (f'#!/bin/sh\n\':\' //; exec {shlex.quote(bun_path)} "$0" "$@"').encode()
+    return f"#!{bun_path}".encode()
+
+
 # ---------------------------------------------------------------------------
 # npm spec helpers
 # ---------------------------------------------------------------------------
@@ -190,9 +214,11 @@ def _shim_node_shebangs(env_dir: Path, bun_path: str) -> list[str]:
     Returns the list of ``.bin/`` entry names whose real script was
     rewritten (for a user-facing warning).
     """
-    if shutil.which("node"):
+    if is_windows() or shutil.which("node"):
         return []
 
+    bun_path = _resolve_bun_path(bun_path)
+
     rewritten: list[str] = []
     bin_dir = _dot_bin_dir(env_dir)
     if not bin_dir.exists():
@@ -226,7 +252,7 @@ def _shim_node_shebangs(env_dir: Path, bun_path: str) -> list[str]:
 
         # Break potential hardlink to bun's global cache, then rewrite.
         mode = target.stat().st_mode
-        new_content = f"#!{bun_path}".encode() + content[nl:]
+        new_content = _bun_shebang(bun_path) + content[nl:]
         target.unlink()
         target.write_bytes(new_content)
         target.chmod(mode)
@@ -321,10 +347,19 @@ class NodeBackend:
         main_spec = specs[0]
         pkg_name, _version = parse_npm_spec(main_spec)
 
-        used_npm = self._run_install_command(env_dir, specs, runtime=runtime, upgrade=upgrade)
+        used_npm, bun_path = self._run_install_command(
+            env_dir, specs, runtime=runtime, upgrade=upgrade
+        )
         pkg_data, used_npm = self._verify_and_retry_with_npm(env_dir, pkg_name, specs, used_npm)
+        if used_npm:
+            bun_path = None
 
-        self._maybe_shim_node_shebangs(env_dir, used_npm=used_npm, node_shim=node_shim)
+        self._maybe_shim_node_shebangs(
+            env_dir,
+            used_npm=used_npm,
+            node_shim=node_shim,
+            bun_path=bun_path,
+        )
 
         binaries = {p.stem: str(p) for p in _list_dot_bin(env_dir)}
 
@@ -345,10 +380,10 @@ class NodeBackend:
         *,
         runtime: str | None,
         upgrade: bool,
-    ) -> bool:
+    ) -> tuple[bool, str | None]:
         """Run the install via bun (default) or npm (explicit --runtime=node).
 
-        Returns True when npm was used (directly or as a bun-failure fallback).
+        Return whether npm was used and the exact bun path used otherwise.
         """
         log = get_logger("node")
 
@@ -361,14 +396,14 @@ class NodeBackend:
             log.debug(f"npm install (--runtime=node): {' '.join(specs)}")
             cmd = ["npm", "install", "--no-fund", "--no-audit", *specs]
             shell_run(cmd, cwd=env_dir, capture_output=True, check=True)
-            return True
+            return True, None
 
         try:
-            bun = self._bun()
+            bun = _resolve_bun_path(self._bun())
             cmd = [bun, "add", *(["--force"] if upgrade else []), *specs]
             log.debug(f"bun add: {' '.join(specs)}")
             shell_run(cmd, cwd=env_dir, capture_output=True, check=True)
-            return False
+            return False, bun
         except (ShellError, Exception) as exc:
             if not self._npm_available():
                 raise RuntimeError(
@@ -379,7 +414,7 @@ class NodeBackend:
             log.debug(f"bun failed, falling back to npm: {exc}")
             cmd = ["npm", "install", "--no-fund", "--no-audit", *specs]
             shell_run(cmd, cwd=env_dir, capture_output=True, check=True)
-            return True
+            return True, None
 
     def _verify_and_retry_with_npm(
         self,
@@ -403,18 +438,18 @@ class NodeBackend:
         *,
         used_npm: bool,
         node_shim: bool | None,
+        bun_path: str | None,
     ) -> None:
         """Rewrite #!node shebangs to bun when bun installed and host has no node.
 
         Keeps the tool self-contained without requiring node on the host.
         """
-        if used_npm or node_shim is False:
+        if used_npm or node_shim is False or bun_path is None:
             return
         log = get_logger("node")
         try:
-            bun_for_shim = self._bun()
-            rewritten = _shim_node_shebangs(env_dir, bun_for_shim)
-        except (OSError, ShellError) as exc:
+            rewritten = _shim_node_shebangs(env_dir, bun_path)
+        except (OSError, ShellError, ValueError) as exc:
             log.debug(f"node shebang shim skipped: {exc}")
             return
         if rewritten:

{ixt_cli-0.9.1 → ixt_cli-0.10.0}/src/ixt/cli/__init__.py

@@ -7,9 +7,18 @@ __all__ = ["main"]
 
 def main() -> int:
     """Entry point for ixt CLI."""
+    import sys
+
     from ixt.cli.commands import COMMANDS
     from ixt.cli.parser import build_parser, normalize_verbosity
 
+    # 'exec' forwards every argument after the tool name to that tool, including
+    # '--help' and '--'. argparse cannot express that, so it never sees them.
+    if sys.argv[1:2] == ["exec"]:
+        from ixt.cli.cmd_exec import run_exec_argv
+
+        return run_exec_argv(sys.argv[2:])
+
     parser = build_parser()
     args = parser.parse_args()
 

ixt_cli-0.10.0/src/ixt/cli/cmd_exec.py

@@ -0,0 +1,71 @@
+"""``ixt exec`` — run a managed tool by its exposed name."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import TYPE_CHECKING
+
+from ixt.libs.logger import get_logger
+from ixt.libs.style import dim
+
+if TYPE_CHECKING:
+    from ixt.core.exec_tool import ExecError, ExecRequest
+
+
+def _report(exc: ExecError) -> int:
+    logger = get_logger("exec")
+    logger.error(str(exc))
+    if exc.hint:
+        logger.error(f"  {dim('Hint: ' + exc.hint)}")
+    return 1
+
+
+def _run(request: ExecRequest) -> int:
+    from ixt.config.settings import get_settings
+    from ixt.core.exec_tool import ExecError, build_exec_plan, run_exec_plan
+
+    try:
+        plan = build_exec_plan(request, get_settings().bin_dir)
+        if request.dry_run:
+            sys.stdout.write(f"{plan.render()}\n")
+            return 0
+        return run_exec_plan(plan)
+    except ExecError as exc:
+        return _report(exc)
+
+
+def run_exec_argv(argv: list[str]) -> int:
+    """Entry point for the short-circuited ``ixt exec`` path.
+
+    Called from ``cli.main`` before argparse runs, so that options meant for
+    the tool — ``--help`` in particular — are never claimed by ixt.
+    """
+    from ixt.core.exec_tool import ExecError, ExecHelpRequested, parse_exec_argv
+
+    try:
+        request = parse_exec_argv(argv)
+    except ExecHelpRequested:
+        from ixt.cli.parser import build_parser
+
+        # argparse prints the subparser help and exits, as for any other command.
+        build_parser().parse_args(["exec", "--help"])
+        return 0
+    except ExecError as exc:
+        return _report(exc)
+
+    return _run(request)
+
+
+def cmd_exec(args: argparse.Namespace) -> int:
+    """Dispatch entry point, kept so the declared subparser stays reachable."""
+    from ixt.core.exec_tool import ExecRequest
+
+    return _run(
+        ExecRequest(
+            tool=args.tool,
+            tool_args=tuple(getattr(args, "args", ())),
+            sudo=getattr(args, "sudo", False),
+            dry_run=getattr(args, "dry_run", False),
+        )
+    )

{ixt_cli-0.9.1 → ixt_cli-0.10.0}/src/ixt/cli/cmd_info.py

@@ -9,9 +9,10 @@ from ixt.cli.render import format_exposed_bin
 from ixt.config.models import ToolRecord
 from ixt.config.settings import get_settings
 from ixt.core.install import display_tool_name, resolve_tool_arg
+from ixt.libs.elf import missing_loader
 from ixt.libs.logger import get_logger
 from ixt.libs.output import data
-from ixt.libs.style import bold, cyan, dim
+from ixt.libs.style import bold, cyan, dim, yellow
 
 
 def _load_binary_metadata(env_dir: Path) -> dict | None:
@@ -110,6 +111,9 @@ def cmd_info(args: argparse.Namespace) -> int:
         data("  Exposed:")
         for name, source in sorted(record.exposed_bins.items()):
             data(f"    {cyan(name)} {dim('->')} {dim(source)}")
+            loader = missing_loader(Path(source))
+            if loader:
+                data(f"      {yellow(f'! not runnable: missing loader {loader}')}")
     else:
         data(f"  Exposed:  {dim('none')}")
 

{ixt_cli-0.9.1 → ixt_cli-0.10.0}/src/ixt/cli/cmd_misc.py

@@ -163,9 +163,32 @@ def cmd_doctor(args: argparse.Namespace) -> int:
     logger.info("")
     if report.ok:
         logger.info(f"  {green('All checks passed')}")
-    else:
+        return 0
+
+    fixable = report.fixable
+    if not getattr(args, "fix", False):
         n = len(report.warnings)
         logger.info(f"  {yellow(f'{n} warning(s)')}")
+        if fixable:
+            logger.info(f"  {dim(f'{len(fixable)} can be repaired with: ixt doctor --fix')}")
+        return 0
+
+    if not fixable:
+        n = len(report.warnings)
+        logger.info(f"  {yellow(f'{n} warning(s)')} {dim('— none of them have an automatic fix')}")
+        return 0
+
+    for check in fixable:
+        assert check.fix is not None
+        try:
+            logger.info(f"  {green('fixed')}  {check.name:15s} {check.fix()}")
+        except Exception as exc:
+            logger.info(f"  {yellow('!!')}  {check.name:15s} fix failed: {exc}")
+
+    remaining = len(report.warnings) - len(fixable)
+    if remaining > 0:
+        logger.info("")
+        logger.info(f"  {yellow(f'{remaining} warning(s) left')} {dim('— no automatic fix')}")
 
     return 0
 

{ixt_cli-0.9.1 → ixt_cli-0.10.0}/src/ixt/cli/commands.py

@@ -13,6 +13,7 @@ from collections.abc import Callable
 from ixt.cli.cmd_apply import cmd_apply, cmd_export
 from ixt.cli.cmd_cache import cmd_cache
 from ixt.cli.cmd_config import cmd_config
+from ixt.cli.cmd_exec import cmd_exec
 from ixt.cli.cmd_info import cmd_info, cmd_list
 from ixt.cli.cmd_install import _log_not_found_hint, cmd_add, cmd_install, cmd_uninstall
 from ixt.cli.cmd_lock import cmd_lock
@@ -36,6 +37,7 @@ __all__ = [
     "cmd_config",
     "cmd_doctor",
     "cmd_environment",
+    "cmd_exec",
     "cmd_export",
     "cmd_info",
     "cmd_install",
@@ -58,6 +60,7 @@ COMMANDS: dict[str, Callable] = {
     "upgrade": cmd_upgrade,
     "list": cmd_list,
     "info": cmd_info,
+    "exec": cmd_exec,
     "config": cmd_config,
     "shell": cmd_shell,
     "where": cmd_where,

{ixt_cli-0.9.1 → ixt_cli-0.10.0}/src/ixt/cli/parser.py

@@ -529,6 +529,11 @@ def build_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="Skip GitHub, PyPI, npm, and latest-version network probes",
     )
+    p_doctor.add_argument(
+        "--fix",
+        action="store_true",
+        help="Repair the findings that have an unambiguous remedy",
+    )
 
     # -- environment -----------------------------------------------------------
     p_environment = sub.add_parser("environment", help="Show ixt configuration and paths")
@@ -549,6 +554,38 @@ def build_parser() -> argparse.ArgumentParser:
     p_where.set_defaults(command="where")
     p_where.add_argument("tool", help="Tool spec or @id:<installed-id>")
 
+    # -- exec ------------------------------------------------------------------
+    # Declared for --help and shell completions only. The real parsing is
+    # short-circuited in cli.main, because everything after the tool name must
+    # reach the tool untouched, '--help' and '--' included.
+    p_exec = sub.add_parser(
+        "exec",
+        help="Run an exposed tool by name, without relying on PATH",
+        description=(
+            "Run an ixt-exposed tool by name. Useful under sudo, which replaces "
+            "PATH with secure_path and cannot see the ixt bin directory. "
+            "Every argument after the tool name is forwarded untouched."
+        ),
+        epilog="Example: ixt exec --sudo rg -- PermitRootLogin /etc/ssh",
+    )
+    p_exec.set_defaults(command="exec")
+    p_exec.add_argument(
+        "--sudo",
+        action="store_true",
+        help="Run the tool through sudo (Unix only)",
+    )
+    p_exec.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print the resolved command without running it",
+    )
+    p_exec.add_argument("tool", help="Exposed tool name")
+    p_exec.add_argument(
+        "args",
+        nargs=argparse.REMAINDER,
+        help="Arguments forwarded to the tool ('--' recommended before them)",
+    )
+
     # -- setup -----------------------------------------------------------------
     p_setup = sub.add_parser("setup", help="Configure shell integration (PATH, ...)")
     p_setup.set_defaults(command="setup")