IntelPython · ndgrigorian · Jun 8, 2026 · May 28, 2026 · May 28, 2026 · May 28, 2026
@@ -7,6 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [dev] (MM/DD/YYYY)
 
 ### Added
+* Added CLI patch management for NumPy random with persistent install/status/uninstall and one-shot command patching via `python -m mkl_random --patch <command>` and `python -m mkl_random --with-numpy-patch <command>` [gh-133](https://github.com/IntelPython/mkl_random/pull/133)
 
 ### Changed
 * Removed `numpy-base` dependency and `USE_NUMPY_BASE` environment variable from conda recipe [gh-124](https://github.com/IntelPython/mkl_random/pull/124)

@@ -70,7 +70,45 @@ The list of supported by `mkl_random.RandomState` constructor `brng` keywords is
 
 # Patching Mechanisms
 
-`mkl_random` provides a convenient programmatic patch method to enable MKL-accelerated random operations in NumPy.
+`mkl_random` provides convenient patch methods to enable MKL-accelerated
+random operations in NumPy with or without modifying your code.
+
+## CLI Quickstart
+
+### Persistent patch (all Python sessions)
+
+```bash
+# Install
+python -m mkl_random --patch install
+
+# Status (exit code: 0 = installed, 1 = not installed)
+python -m mkl_random --patch status
+
+# Remove
+python -m mkl_random --patch uninstall
+```
+
+### Verify current random backend
+
+```bash
+python -c "import numpy; print(f'numpy.random.normal.__module__: {numpy.random.normal.__module__}')"
+```
+
+### One-shot patch (single command only)
+
+```bash
+# Script
+python -m mkl_random --with-numpy-patch my_script.py
+
+# Pytest
+python -m mkl_random --with-numpy-patch -m pytest tests/
+
+# One-liner
+python -m mkl_random --with-numpy-patch -c "import numpy; print(f\"numpy.random.normal.__module__: {numpy.random.normal.__module__}\")"
+
+# Non-Python command
+python -m mkl_random --with-numpy-patch -- <command> [args...]
+```
 
 ## Programmatic Quickstart
 

@@ -0,0 +1,85 @@
+# Copyright (c) 2026, Intel Corporation
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+#     * Redistributions of source code must retain the above copyright notice,
+#       this list of conditions and the following disclaimer.
+#     * Redistributions in binary form must reproduce the above copyright
+#       notice, this list of conditions and the following disclaimer in the
+#       documentation and/or other materials provided with the distribution.
+#     * Neither the name of Intel Corporation nor the names of its contributors
+#       may be used to endorse or promote products derived from this software
+#       without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+"""Command-line interface for mkl_random."""
+
+import argparse
+import sys
+
+
+def main():
+    """Entry point for the CLI."""
+    parser = argparse.ArgumentParser(
+        prog="python -m mkl_random",
+        description="MKL-accelerated random generation for NumPy",
+    )
+    parser.add_argument(
+        "-v", "--verbose", action="store_true", help="Enable verbose output"
+    )
+    parser.add_argument(
+        "--patch",
+        choices=["install", "uninstall", "status"],
+        help="Manage persistent NumPy random patching",
+    )
+    parser.add_argument(
+        "--with-numpy-patch",
+        dest="with_numpy_patch",
+        nargs=argparse.REMAINDER,
+        help="Run command with temporary NumPy random patch",
+    )
+
+    args = parser.parse_args()
+
+    if args.patch:
+        from mkl_random.patch import (
+            PatchOperationError,
+            check_status,
+            install_patch,
+            uninstall_patch,
+        )
+
+        try:
+            if args.patch == "install":
+                install_patch(verbose=args.verbose)
+            elif args.patch == "uninstall":
+                uninstall_patch(verbose=args.verbose)
+            elif args.patch == "status":
+                sys.exit(0 if check_status(verbose=args.verbose) else 1)
+        except PatchOperationError as exc:
+            print(exc, file=sys.stderr)
+            sys.exit(1)
+
+    elif args.with_numpy_patch is not None:
+        from mkl_random.with_patch import run_with_numpy_patch
+
+        run_with_numpy_patch(args.with_numpy_patch)
+
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,33 @@
+# Copyright (c) 2026, Intel Corporation
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+#     * Redistributions of source code must retain the above copyright notice,
+#       this list of conditions and the following disclaimer.
+#     * Redistributions in binary form must reproduce the above copyright
+#       notice, this list of conditions and the following disclaimer in the
+#       documentation and/or other materials provided with the distribution.
+#     * Neither the name of Intel Corporation nor the names of its contributors
+#       may be used to endorse or promote products derived from this software
+#       without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+"""Helper module for .pth-based persistent patching with error handling."""
+
+try:
+    import mkl_random
+
+    mkl_random.patch_numpy_random()
+except Exception:
+    pass
@@ -0,0 +1,143 @@
+# Copyright (c) 2026, Intel Corporation
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+#     * Redistributions of source code must retain the above copyright notice,
+#       this list of conditions and the following disclaimer.
+#     * Redistributions in binary form must reproduce the above copyright
+#       notice, this list of conditions and the following disclaimer in the
+#       documentation and/or other materials provided with the distribution.
+#     * Neither the name of Intel Corporation nor the names of its contributors
+#       may be used to endorse or promote products derived from this software
+#       without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+"""Persistent patch management for NumPy random submodule."""
+
+import site
+import sys
+import warnings
+from pathlib import Path
+
+
+class PatchOperationError(RuntimeError):
+    """Raised when a persistent patch operation cannot be completed."""
+
+
+def get_pth_path():
+    """Get the path to mkl_random_patch.pth in the appropriate site-packages."""
+    site_packages = site.getsitepackages()
+    if site_packages:
+        target_site = site_packages[0]
+    else:
+        target_site = site.getusersitepackages()
+    return Path(target_site) / "mkl_random_patch.pth"
+
+
+PTH_CONTENT = """import mkl_random._patch_startup"""
+
+
+def install_patch(verbose=False):
+    """Install persistent NumPy random patch using .pth file."""
+    pth_path = get_pth_path()
+
+    if pth_path.exists():
+        if verbose:
+            warnings.warn(
+                f"Persistent patch already installed at {pth_path}",
+                UserWarning,
+                stacklevel=2,
+            )
+        return
+
+    try:
+        pth_path.parent.mkdir(parents=True, exist_ok=True)
+        pth_path.write_text(PTH_CONTENT)
+        if verbose:
+            print(f"Persistent patch installed at {pth_path}")
+            print()
+            print(
+                "NumPy random will now use MKL-accelerated implementations in"
+            )
+            print("all Python sessions. To disable, run:")
+            print("  python -m mkl_random --patch uninstall")
+    except OSError as e:
+        raise PatchOperationError(
+            f"Error installing patch at {pth_path}: {e}\n\n"
+            "You may need to run with appropriate permissions or install to "
+            "a user site-packages directory."
+        ) from e
+
+
+def uninstall_patch(verbose=False):
+    """Uninstall persistent NumPy random patch."""
+    pth_path = get_pth_path()
+
+    if not pth_path.exists():
+        if verbose:
+            print("No persistent patch found.")
+        return
+
+    try:
+        pth_path.unlink()
+        if verbose:
+            print(f"Persistent patch removed from {pth_path}")
+            print()
+            print("NumPy random will now use the default implementations.")
+    except OSError as e:
+        raise PatchOperationError(
+            f"Error removing patch at {pth_path}: {e}"
+        ) from e
+
+
+def check_status(verbose=False):
+    """Check if persistent patch is installed."""
+    pth_path = get_pth_path()
+
+    if pth_path.exists():
+        if verbose:
+            print(f"Persistent patch is installed at {pth_path}")
+            print()
+            print(
+                "NumPy random is configured to use MKL-accelerated "
+                "implementations."
+            )
+        return True
+    else:
+        if verbose:
+            print("No persistent patch installed")
+            print()
+            print("To enable MKL-accelerated NumPy random globally, run:")
+            print("  python -m mkl_random --patch install")
+        return False
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print("Usage: python -m mkl_random.patch <install|uninstall|status>")
+        sys.exit(1)
+
+    command = sys.argv[1]
+    try:
+        if command == "install":
+            install_patch(verbose=True)
+        elif command == "uninstall":
+            uninstall_patch(verbose=True)
+        elif command == "status":
+            sys.exit(0 if check_status(verbose=True) else 1)
+        else:
+            print(f"Unknown command: {command}")
+            sys.exit(1)
+    except PatchOperationError as exc:
+        print(exc, file=sys.stderr)
+        sys.exit(1)