mdify-cli 2.8.0__tar.gz → 2.9.1__tar.gz

{mdify_cli-2.8.0/mdify_cli.egg-info → mdify_cli-2.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mdify-cli
-Version: 2.8.0
+Version: 2.9.1
 Summary: Convert PDFs and document images into structured Markdown for LLM workflows
 Author: tiroq
 License-Expression: MIT
@@ -42,7 +42,10 @@ A lightweight CLI for converting documents to Markdown. The CLI is fast to insta
 ## Requirements
 
 - **Python 3.8+**
-- **Docker** or **Podman** (for document conversion)
+- **Docker**, **Podman**, or native macOS container tools (for document conversion)
+  - On macOS: Supports Apple Container (macOS 26+), OrbStack, Colima, Podman, or Docker Desktop
+  - On Linux: Docker or Podman
+  - Auto-detects available tools
 
 ## Installation
 
@@ -56,6 +59,13 @@ pipx install mdify-cli
 
 Restart your terminal after installation.
 
+For containerized document conversion, install one of these (or use Docker Desktop):
+- **Apple Container** (macOS 26+): Download from https://github.com/apple/container/releases
+- **OrbStack** (recommended): `brew install orbstack`
+- **Colima**: `brew install colima && colima start`
+- **Podman**: `brew install podman && podman machine init && podman machine start`
+- **Docker Desktop**: Available at https://www.docker.com/products/docker-desktop
+
 ### Linux
 
 ```bash
@@ -142,13 +152,50 @@ The first conversion takes longer (~30-60s) as the container loads ML models int
 | `-m, --mask` | ⚠️ **Deprecated**: PII masking not supported in current version |
 | `--gpu` | Use GPU-accelerated container (requires NVIDIA GPU and nvidia-container-toolkit) |
 | `--port PORT` | Container port (default: 5001) |
-| `--runtime RUNTIME` | Container runtime: docker or podman (auto-detected) |
+| `--runtime RUNTIME` | Container runtime: docker, podman, orbstack, colima, or container (auto-detected) |
 | `--image IMAGE` | Custom container image (default: ghcr.io/docling-project/docling-serve-cpu:main) |
 | `--pull POLICY` | Image pull policy: always, missing, never (default: missing) |
 | `--check-update` | Check for available updates and exit |
 | `--version` | Show version and exit |
 
-### Flat Mode
+### Container Runtime Selection
+
+mdify automatically detects and uses the best available container runtime. The detection order differs by platform:
+
+**macOS (recommended):**
+1. Apple Container (native, macOS 26+ required)
+2. OrbStack (lightweight, fast)
+3. Colima (open-source alternative)
+4. Podman (via Podman machine)
+5. Docker Desktop (full Docker)
+
+**Linux:**
+1. Docker
+2. Podman
+
+**Override runtime:**
+Use the `MDIFY_CONTAINER_RUNTIME` environment variable to force a specific runtime:
+
+```bash
+export MDIFY_CONTAINER_RUNTIME=orbstack
+mdify document.pdf
+```
+
+Or inline:
+```bash
+MDIFY_CONTAINER_RUNTIME=colima mdify document.pdf
+```
+
+**Supported values:** `docker`, `podman`, `orbstack`, `colima`, `container`
+
+If the selected runtime is installed but not running, mdify will display a helpful warning:
+```
+Warning: Found container runtime(s) but daemon is not running:
+  - orbstack (/opt/homebrew/bin/orbstack)
+
+Please start one of these tools before running mdify.
+macOS tip: Start OrbStack, Colima, or Podman Desktop application
+```
 
 With `--flat`, all output files are placed directly in the output directory. Directory paths are incorporated into filenames to prevent collisions:
 

{mdify_cli-2.8.0 → mdify_cli-2.9.1}/README.md

@@ -11,7 +11,10 @@ A lightweight CLI for converting documents to Markdown. The CLI is fast to insta
 ## Requirements
 
 - **Python 3.8+**
-- **Docker** or **Podman** (for document conversion)
+- **Docker**, **Podman**, or native macOS container tools (for document conversion)
+  - On macOS: Supports Apple Container (macOS 26+), OrbStack, Colima, Podman, or Docker Desktop
+  - On Linux: Docker or Podman
+  - Auto-detects available tools
 
 ## Installation
 
@@ -25,6 +28,13 @@ pipx install mdify-cli
 
 Restart your terminal after installation.
 
+For containerized document conversion, install one of these (or use Docker Desktop):
+- **Apple Container** (macOS 26+): Download from https://github.com/apple/container/releases
+- **OrbStack** (recommended): `brew install orbstack`
+- **Colima**: `brew install colima && colima start`
+- **Podman**: `brew install podman && podman machine init && podman machine start`
+- **Docker Desktop**: Available at https://www.docker.com/products/docker-desktop
+
 ### Linux
 
 ```bash
@@ -111,13 +121,50 @@ The first conversion takes longer (~30-60s) as the container loads ML models int
 | `-m, --mask` | ⚠️ **Deprecated**: PII masking not supported in current version |
 | `--gpu` | Use GPU-accelerated container (requires NVIDIA GPU and nvidia-container-toolkit) |
 | `--port PORT` | Container port (default: 5001) |
-| `--runtime RUNTIME` | Container runtime: docker or podman (auto-detected) |
+| `--runtime RUNTIME` | Container runtime: docker, podman, orbstack, colima, or container (auto-detected) |
 | `--image IMAGE` | Custom container image (default: ghcr.io/docling-project/docling-serve-cpu:main) |
 | `--pull POLICY` | Image pull policy: always, missing, never (default: missing) |
 | `--check-update` | Check for available updates and exit |
 | `--version` | Show version and exit |
 
-### Flat Mode
+### Container Runtime Selection
+
+mdify automatically detects and uses the best available container runtime. The detection order differs by platform:
+
+**macOS (recommended):**
+1. Apple Container (native, macOS 26+ required)
+2. OrbStack (lightweight, fast)
+3. Colima (open-source alternative)
+4. Podman (via Podman machine)
+5. Docker Desktop (full Docker)
+
+**Linux:**
+1. Docker
+2. Podman
+
+**Override runtime:**
+Use the `MDIFY_CONTAINER_RUNTIME` environment variable to force a specific runtime:
+
+```bash
+export MDIFY_CONTAINER_RUNTIME=orbstack
+mdify document.pdf
+```
+
+Or inline:
+```bash
+MDIFY_CONTAINER_RUNTIME=colima mdify document.pdf
+```
+
+**Supported values:** `docker`, `podman`, `orbstack`, `colima`, `container`
+
+If the selected runtime is installed but not running, mdify will display a helpful warning:
+```
+Warning: Found container runtime(s) but daemon is not running:
+  - orbstack (/opt/homebrew/bin/orbstack)
+
+Please start one of these tools before running mdify.
+macOS tip: Start OrbStack, Colima, or Podman Desktop application
+```
 
 With `--flat`, all output files are placed directly in the output directory. Directory paths are incorporated into filenames to prevent collisions:
 

{mdify_cli-2.8.0 → mdify_cli-2.9.1}/mdify/__init__.py

@@ -1,3 +1,3 @@
 """mdify - Convert documents to Markdown via Docling container."""
 
-__version__ = "2.8.0"
+__version__ = "2.9.1"

{mdify_cli-2.8.0 → mdify_cli-2.9.1}/mdify/cli.py

@@ -10,6 +10,7 @@ is lightweight and has no ML dependencies.
 import argparse
 import json
 import os
+import platform
 import shutil
 import subprocess
 import sys
@@ -33,7 +34,9 @@ CHECK_INTERVAL_SECONDS = 86400  # 24 hours
 # Container configuration
 DEFAULT_IMAGE = "ghcr.io/docling-project/docling-serve-cpu:main"
 GPU_IMAGE = "ghcr.io/docling-project/docling-serve-cu126:main"
-SUPPORTED_RUNTIMES = ("docker", "podman")
+SUPPORTED_RUNTIMES = ("docker", "podman", "orbstack", "colima", "container")
+MACOS_RUNTIMES_PRIORITY = ("container", "orbstack", "colima", "podman", "docker")
+OTHER_RUNTIMES_PRIORITY = ("docker", "podman")
 
 
 # =============================================================================
@@ -151,34 +154,117 @@ def check_for_update(force: bool = False) -> None:
 # =============================================================================
 
 
-def detect_runtime(preferred: str, explicit: bool = True) -> Optional[str]:
+def is_daemon_running(runtime: str) -> bool:
+    """
+    Check if a container runtime daemon is running.
+
+    Args:
+        runtime: Path to container runtime executable
+
+    Returns:
+        True if daemon is running and responsive, False otherwise.
+    """
+    try:
+        runtime_name = os.path.basename(runtime)
+        
+        # Apple Container uses 'container system status' to check daemon
+        if runtime_name == "container":
+            result = subprocess.run(
+                [runtime, "system", "status"],
+                capture_output=True,
+                timeout=5,
+                check=False,
+            )
+            return result.returncode == 0
+        
+        # Other runtimes use --version check
+        result = subprocess.run(
+            [runtime, "--version"],
+            capture_output=True,
+            timeout=5,
+            check=False,
+        )
+        return result.returncode == 0
+    except (OSError, subprocess.TimeoutExpired):
+        return False
+
+
+def detect_runtime(preferred: Optional[str] = None, explicit: bool = True) -> Optional[str]:
     """
     Detect available container runtime.
 
+    First checks MDIFY_CONTAINER_RUNTIME environment variable for explicit override.
+    On macOS, tries native tools first (OrbStack → Colima → Podman → Docker).
+    On other platforms, tries Docker → Podman.
+
     Args:
-        preferred: Preferred runtime ('docker' or 'podman')
-        explicit: If True, warn when falling back to alternative.
-                  If False, silently use alternative without warning.
-                  Note: This only controls warning emission; selection order
-                  is always preferred → alternative regardless of this flag.
+        preferred: Preferred runtime name override (deprecated, use MDIFY_CONTAINER_RUNTIME)
+        explicit: If True, print info about detection/fallback choices.
 
     Returns:
         Path to runtime executable, or None if not found.
     """
-    # Try preferred runtime first
-    runtime_path = shutil.which(preferred)
-    if runtime_path:
-        return runtime_path
-
-    # Try alternative
-    alternative = "podman" if preferred == "docker" else "docker"
-    runtime_path = shutil.which(alternative)
-    if runtime_path:
+    # Check for explicit environment variable override
+    env_runtime = os.environ.get("MDIFY_CONTAINER_RUNTIME", "").strip().lower()
+    if env_runtime:
+        if env_runtime not in SUPPORTED_RUNTIMES:
+            print(
+                f"Warning: MDIFY_CONTAINER_RUNTIME='{env_runtime}' is not supported. "
+                f"Supported: {', '.join(SUPPORTED_RUNTIMES)}",
+                file=sys.stderr,
+            )
+        else:
+            runtime_path = shutil.which(env_runtime)
+            if runtime_path:
+                if explicit:
+                    print(f"Using runtime from MDIFY_CONTAINER_RUNTIME: {env_runtime}")
+                return runtime_path
+            else:
+                print(
+                    f"Warning: MDIFY_CONTAINER_RUNTIME='{env_runtime}' specified but not found in PATH",
+                    file=sys.stderr,
+                )
+
+    # Determine runtime priority based on OS
+    is_macos = platform.system() == "Darwin"
+    if is_macos:
+        runtime_priority = MACOS_RUNTIMES_PRIORITY
         if explicit:
+            print(f"Detected macOS: checking for native container tools...")
+    else:
+        runtime_priority = OTHER_RUNTIMES_PRIORITY
+
+    # Try each runtime in priority order
+    found_but_not_running = []
+    for runtime_name in runtime_priority:
+        runtime_path = shutil.which(runtime_name)
+        if runtime_path:
+            # Check if daemon is running
+            if is_daemon_running(runtime_path):
+                if explicit:
+                    print(f"Using container runtime: {runtime_name}")
+                return runtime_path
+            else:
+                found_but_not_running.append((runtime_name, runtime_path))
+
+    # If we found tools but none are running, warn and ask user to start one
+    if found_but_not_running:
+        print(
+            f"\nWarning: Found container runtime(s) but daemon is not running:",
+            file=sys.stderr,
+        )
+        for runtime_name, runtime_path in found_but_not_running:
+            print(f"  - {runtime_name} ({runtime_path})", file=sys.stderr)
+        print(
+            "\nPlease start one of these tools before running mdify.",
+            file=sys.stderr,
+        )
+        if is_macos:
             print(
-                f"Warning: {preferred} not found, using {alternative}", file=sys.stderr
+                "  macOS tip: Start OrbStack, Colima, or Podman Desktop application",
+                file=sys.stderr,
             )
-        return runtime_path
+        return None
 
     return None
 
@@ -195,6 +281,27 @@ def check_image_exists(runtime: str, image: str) -> bool:
         True if image exists locally.
     """
     try:
+        runtime_name = os.path.basename(runtime)
+        
+        # Apple Container uses 'image-list' command
+        if runtime_name == "container":
+            result = subprocess.run(
+                [runtime, "image-list", "--format", "json"],
+                capture_output=True,
+                check=False,
+            )
+            if result.returncode == 0 and result.stdout:
+                try:
+                    images = json.loads(result.stdout.decode())
+                    # Check if image exists in the list
+                    for img in images:
+                        if img.get("name") == image or image in img.get("repoTags", []):
+                            return True
+                except json.JSONDecodeError:
+                    pass
+            return False
+        
+        # Docker/Podman/OrbStack/Colima use standard 'image inspect'
         result = subprocess.run(
             [runtime, "image", "inspect", image],
             capture_output=True,
@@ -221,6 +328,18 @@ def pull_image(runtime: str, image: str, quiet: bool = False) -> bool:
         print(f"Pulling image: {image}")
 
     try:
+        runtime_name = os.path.basename(runtime)
+        
+        # Apple Container uses 'image-pull' command
+        if runtime_name == "container":
+            result = subprocess.run(
+                [runtime, "image-pull", image],
+                capture_output=quiet,
+                check=False,
+            )
+            return result.returncode == 0
+        
+        # Docker/Podman/OrbStack/Colima use standard 'pull'
         result = subprocess.run(
             [runtime, "pull", image],
             capture_output=quiet,
@@ -302,7 +421,7 @@ def get_free_space(path: str) -> int:
 
 def get_storage_root(runtime: str) -> Optional[str]:
     """
-    Get the storage root directory for Docker or Podman.
+    Get the storage root directory for Docker, Podman, OrbStack, or Colima.
 
     Args:
         runtime: Path to container runtime executable
@@ -331,6 +450,18 @@ def get_storage_root(runtime: str) -> Optional[str]:
             if result.stdout:
                 info = json.loads(result.stdout.decode())
                 return info.get("store", {}).get("graphRoot")
+        elif runtime_name == "orbstack":
+            # OrbStack stores containers in ~/.orbstack
+            home = os.path.expanduser("~")
+            return os.path.join(home, ".orbstack")
+        elif runtime_name == "colima":
+            # Colima stores containers in ~/.colima
+            home = os.path.expanduser("~")
+            return os.path.join(home, ".colima")
+        elif runtime_name == "container":
+            # Apple Container stores data in Application Support
+            home = os.path.expanduser("~")
+            return os.path.join(home, "Library", "Application Support", "com.apple.container")
         return None
     except (OSError, json.JSONDecodeError):
         return None
@@ -660,15 +791,14 @@ def main() -> int:
         return 1
 
     # Detect container runtime
-    preferred = args.runtime if args.runtime else "docker"
+    # If --runtime is specified, treat as explicit user choice
     explicit = args.runtime is not None
-    runtime = detect_runtime(preferred, explicit=explicit)
+    runtime = detect_runtime(preferred=args.runtime, explicit=explicit)
     if runtime is None:
         print(
             f"Error: Container runtime not found ({', '.join(SUPPORTED_RUNTIMES)})",
             file=sys.stderr,
         )
-        print("Please install Docker or Podman to use mdify.", file=sys.stderr)
         return 2
 
     # Handle image pull policy
@@ -752,7 +882,8 @@ def main() -> int:
             return 1
     elif args.pull == "never" and not image_exists:
         print(f"Error: Image not found locally: {image}", file=sys.stderr)
-        print(f"Run with --pull=missing or pull manually: {preferred} pull {image}")
+        runtime_name = os.path.basename(runtime)
+        print(f"Run with --pull=missing or pull manually: {runtime_name} pull {image}")
         return 1
 
     # Resolve paths (use absolute() as fallback if resolve() fails due to permissions)

{mdify_cli-2.8.0 → mdify_cli-2.9.1/mdify_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mdify-cli
-Version: 2.8.0
+Version: 2.9.1
 Summary: Convert PDFs and document images into structured Markdown for LLM workflows
 Author: tiroq
 License-Expression: MIT
@@ -42,7 +42,10 @@ A lightweight CLI for converting documents to Markdown. The CLI is fast to insta
 ## Requirements
 
 - **Python 3.8+**
-- **Docker** or **Podman** (for document conversion)
+- **Docker**, **Podman**, or native macOS container tools (for document conversion)
+  - On macOS: Supports Apple Container (macOS 26+), OrbStack, Colima, Podman, or Docker Desktop
+  - On Linux: Docker or Podman
+  - Auto-detects available tools
 
 ## Installation
 
@@ -56,6 +59,13 @@ pipx install mdify-cli
 
 Restart your terminal after installation.
 
+For containerized document conversion, install one of these (or use Docker Desktop):
+- **Apple Container** (macOS 26+): Download from https://github.com/apple/container/releases
+- **OrbStack** (recommended): `brew install orbstack`
+- **Colima**: `brew install colima && colima start`
+- **Podman**: `brew install podman && podman machine init && podman machine start`
+- **Docker Desktop**: Available at https://www.docker.com/products/docker-desktop
+
 ### Linux
 
 ```bash
@@ -142,13 +152,50 @@ The first conversion takes longer (~30-60s) as the container loads ML models int
 | `-m, --mask` | ⚠️ **Deprecated**: PII masking not supported in current version |
 | `--gpu` | Use GPU-accelerated container (requires NVIDIA GPU and nvidia-container-toolkit) |
 | `--port PORT` | Container port (default: 5001) |
-| `--runtime RUNTIME` | Container runtime: docker or podman (auto-detected) |
+| `--runtime RUNTIME` | Container runtime: docker, podman, orbstack, colima, or container (auto-detected) |
 | `--image IMAGE` | Custom container image (default: ghcr.io/docling-project/docling-serve-cpu:main) |
 | `--pull POLICY` | Image pull policy: always, missing, never (default: missing) |
 | `--check-update` | Check for available updates and exit |
 | `--version` | Show version and exit |
 
-### Flat Mode
+### Container Runtime Selection
+
+mdify automatically detects and uses the best available container runtime. The detection order differs by platform:
+
+**macOS (recommended):**
+1. Apple Container (native, macOS 26+ required)
+2. OrbStack (lightweight, fast)
+3. Colima (open-source alternative)
+4. Podman (via Podman machine)
+5. Docker Desktop (full Docker)
+
+**Linux:**
+1. Docker
+2. Podman
+
+**Override runtime:**
+Use the `MDIFY_CONTAINER_RUNTIME` environment variable to force a specific runtime:
+
+```bash
+export MDIFY_CONTAINER_RUNTIME=orbstack
+mdify document.pdf
+```
+
+Or inline:
+```bash
+MDIFY_CONTAINER_RUNTIME=colima mdify document.pdf
+```
+
+**Supported values:** `docker`, `podman`, `orbstack`, `colima`, `container`
+
+If the selected runtime is installed but not running, mdify will display a helpful warning:
+```
+Warning: Found container runtime(s) but daemon is not running:
+  - orbstack (/opt/homebrew/bin/orbstack)
+
+Please start one of these tools before running mdify.
+macOS tip: Start OrbStack, Colima, or Podman Desktop application
+```
 
 With `--flat`, all output files are placed directly in the output directory. Directory paths are incorporated into filenames to prevent collisions:
 

{mdify_cli-2.8.0 → mdify_cli-2.9.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mdify-cli"
-version = "2.8.0"
+version = "2.9.1"
 description = "Convert PDFs and document images into structured Markdown for LLM workflows"
 readme = "README.md"
 requires-python = ">=3.8"

{mdify_cli-2.8.0 → mdify_cli-2.9.1}/tests/test_cli.py

@@ -1,6 +1,7 @@
 """Tests for mdify CLI runtime detection."""
 
 import json
+import subprocess
 import sys
 from pathlib import Path
 from unittest.mock import patch, Mock
@@ -9,6 +10,7 @@ from urllib.error import URLError
 
 from mdify.cli import (
     detect_runtime,
+    is_daemon_running,
     parse_args,
     format_size,
     format_duration,
@@ -45,44 +47,47 @@ class TestDetectRuntime:
 
     def test_auto_docker_exists(self):
         with patch("mdify.cli.shutil.which") as mock_which:
-            mock_which.side_effect = (
-                lambda x: "/usr/bin/docker" if x == "docker" else None
-            )
-            result = detect_runtime("docker", explicit=False)
-            assert result == "/usr/bin/docker"
+            with patch("mdify.cli.is_daemon_running", return_value=True):
+                mock_which.side_effect = (
+                    lambda x: "/usr/bin/docker" if x == "docker" else None
+                )
+                result = detect_runtime(explicit=False)
+                assert result == "/usr/bin/docker"
 
     def test_auto_only_podman_exists(self, capsys):
         with patch("mdify.cli.shutil.which") as mock_which:
-            mock_which.side_effect = (
-                lambda x: "/usr/bin/podman" if x == "podman" else None
-            )
-            result = detect_runtime("docker", explicit=False)
-            assert result == "/usr/bin/podman"
-            captured = capsys.readouterr()
-            assert captured.err == ""
+            with patch("mdify.cli.is_daemon_running", return_value=True):
+                mock_which.side_effect = (
+                    lambda x: "/usr/bin/podman" if x == "podman" else None
+                )
+                result = detect_runtime(explicit=False)
+                assert result == "/usr/bin/podman"
+                captured = capsys.readouterr()
+                assert captured.err == ""
 
     def test_auto_neither_exists(self):
         with patch("mdify.cli.shutil.which", return_value=None):
-            result = detect_runtime("docker", explicit=False)
+            result = detect_runtime(explicit=False)
             assert result is None
 
     def test_explicit_docker_exists(self):
         with patch("mdify.cli.shutil.which") as mock_which:
-            mock_which.side_effect = (
-                lambda x: "/usr/bin/docker" if x == "docker" else None
-            )
-            result = detect_runtime("docker", explicit=True)
-            assert result == "/usr/bin/docker"
+            with patch("mdify.cli.is_daemon_running", return_value=True):
+                mock_which.side_effect = (
+                    lambda x: "/usr/bin/docker" if x == "docker" else None
+                )
+                result = detect_runtime("docker", explicit=True)
+                assert result == "/usr/bin/docker"
 
     def test_explicit_docker_fallback_to_podman(self, capsys):
         with patch("mdify.cli.shutil.which") as mock_which:
-            mock_which.side_effect = (
-                lambda x: "/usr/bin/podman" if x == "podman" else None
-            )
-            result = detect_runtime("docker", explicit=True)
-            assert result == "/usr/bin/podman"
-            captured = capsys.readouterr()
-            assert "Warning: docker not found, using podman" in captured.err
+            with patch("mdify.cli.is_daemon_running", return_value=True):
+                mock_which.side_effect = (
+                    lambda x: "/usr/bin/podman" if x == "podman" else None
+                )
+                result = detect_runtime("docker", explicit=True)
+                assert result == "/usr/bin/podman"
+                # With new macOS priority-based detection, priority order is used
 
     def test_explicit_docker_neither_exists(self):
         with patch("mdify.cli.shutil.which", return_value=None):
@@ -91,27 +96,166 @@ class TestDetectRuntime:
 
     def test_explicit_podman_exists(self):
         with patch("mdify.cli.shutil.which") as mock_which:
-            mock_which.side_effect = (
-                lambda x: "/usr/bin/podman" if x == "podman" else None
-            )
-            result = detect_runtime("podman", explicit=True)
-            assert result == "/usr/bin/podman"
+            with patch("mdify.cli.is_daemon_running", return_value=True):
+                mock_which.side_effect = (
+                    lambda x: "/usr/bin/podman" if x == "podman" else None
+                )
+                result = detect_runtime("podman", explicit=True)
+                assert result == "/usr/bin/podman"
 
     def test_explicit_podman_fallback_to_docker(self, capsys):
         with patch("mdify.cli.shutil.which") as mock_which:
-            mock_which.side_effect = (
-                lambda x: "/usr/bin/docker" if x == "docker" else None
-            )
-            result = detect_runtime("podman", explicit=True)
-            assert result == "/usr/bin/docker"
-            captured = capsys.readouterr()
-            assert "Warning: podman not found, using docker" in captured.err
+            with patch("mdify.cli.is_daemon_running", return_value=True):
+                mock_which.side_effect = (
+                    lambda x: "/usr/bin/docker" if x == "docker" else None
+                )
+                result = detect_runtime("podman", explicit=True)
+                assert result == "/usr/bin/docker"
+                # With new macOS priority-based detection, priority order is used
 
     def test_explicit_podman_neither_exists(self):
         with patch("mdify.cli.shutil.which", return_value=None):
             result = detect_runtime("podman", explicit=True)
             assert result is None
 
+    # Tests for new macOS native tool support
+    def test_env_var_override_orbstack(self, monkeypatch):
+        """Test MDIFY_CONTAINER_RUNTIME env var overrides detection."""
+        monkeypatch.setenv("MDIFY_CONTAINER_RUNTIME", "orbstack")
+        with patch("mdify.cli.shutil.which") as mock_which:
+            mock_which.return_value = "/usr/local/bin/orbstack"
+            result = detect_runtime(explicit=False)
+            assert result == "/usr/local/bin/orbstack"
+
+    def test_env_var_override_colima(self, monkeypatch):
+        """Test MDIFY_CONTAINER_RUNTIME env var works for colima."""
+        monkeypatch.setenv("MDIFY_CONTAINER_RUNTIME", "colima")
+        with patch("mdify.cli.shutil.which") as mock_which:
+            mock_which.return_value = "/usr/local/bin/colima"
+            result = detect_runtime(explicit=False)
+            assert result == "/usr/local/bin/colima"
+
+    def test_env_var_not_found_in_path(self, monkeypatch, capsys):
+        """Test MDIFY_CONTAINER_RUNTIME env var when tool not in PATH."""
+        monkeypatch.setenv("MDIFY_CONTAINER_RUNTIME", "orbstack")
+        with patch("mdify.cli.shutil.which", return_value=None):
+            result = detect_runtime(explicit=False)
+            assert result is None
+            captured = capsys.readouterr()
+            assert "MDIFY_CONTAINER_RUNTIME='orbstack' specified but not found in PATH" in captured.err
+
+    def test_env_var_invalid_name(self, monkeypatch, capsys):
+        """Test MDIFY_CONTAINER_RUNTIME with invalid runtime name."""
+        monkeypatch.setenv("MDIFY_CONTAINER_RUNTIME", "invalid")
+        with patch("mdify.cli.shutil.which", return_value=None):
+            result = detect_runtime(explicit=False)
+            assert result is None
+            captured = capsys.readouterr()
+            assert "MDIFY_CONTAINER_RUNTIME='invalid' is not supported" in captured.err
+
+    def test_macos_priority_orbstack_first(self, monkeypatch):
+        """Test macOS prefers OrbStack over other tools."""
+        monkeypatch.setenv("MDIFY_CONTAINER_RUNTIME", "")  # Clear env override
+        with patch("mdify.cli.platform.system", return_value="Darwin"):
+            with patch("mdify.cli.shutil.which") as mock_which:
+                with patch("mdify.cli.is_daemon_running") as mock_running:
+                    # Setup: orbstack exists and running
+                    mock_which.side_effect = lambda x: f"/usr/local/bin/{x}" if x == "orbstack" else None
+                    mock_running.return_value = True
+                    result = detect_runtime(explicit=False)
+                    assert result == "/usr/local/bin/orbstack"
+
+    def test_macos_fallback_colima_when_orbstack_not_running(self, monkeypatch):
+        """Test macOS falls back to Colima if OrbStack not running."""
+        monkeypatch.setenv("MDIFY_CONTAINER_RUNTIME", "")
+        with patch("mdify.cli.platform.system", return_value="Darwin"):
+            with patch("mdify.cli.shutil.which") as mock_which:
+                with patch("mdify.cli.is_daemon_running") as mock_running:
+                    # Setup: orbstack exists but not running, colima exists and running
+                    def which_side_effect(x):
+                        if x in ("orbstack", "colima"):
+                            return f"/usr/local/bin/{x}"
+                        return None
+                    
+                    def running_side_effect(path):
+                        return "colima" in path
+                    
+                    mock_which.side_effect = which_side_effect
+                    mock_running.side_effect = running_side_effect
+                    result = detect_runtime(explicit=False)
+                    assert result == "/usr/local/bin/colima"
+
+    def test_non_macos_priority_docker_first(self, monkeypatch):
+        """Test non-macOS prefers Docker over other tools."""
+        monkeypatch.setenv("MDIFY_CONTAINER_RUNTIME", "")
+        with patch("mdify.cli.platform.system", return_value="Linux"):
+            with patch("mdify.cli.shutil.which") as mock_which:
+                with patch("mdify.cli.is_daemon_running") as mock_running:
+                    # Setup: docker and podman exist, docker running
+                    def which_side_effect(x):
+                        if x in ("docker", "podman"):
+                            return f"/usr/bin/{x}"
+                        return None
+                    
+                    def running_side_effect(path):
+                        return "docker" in path
+                    
+                    mock_which.side_effect = which_side_effect
+                    mock_running.side_effect = running_side_effect
+                    result = detect_runtime(explicit=False)
+                    assert result == "/usr/bin/docker"
+
+    def test_macos_priority_apple_container_first(self, monkeypatch):
+        """Test macOS prefers Apple Container over other tools."""
+        monkeypatch.setenv("MDIFY_CONTAINER_RUNTIME", "")
+        with patch("mdify.cli.platform.system", return_value="Darwin"):
+            with patch("mdify.cli.shutil.which") as mock_which:
+                with patch("mdify.cli.is_daemon_running") as mock_running:
+                    # Setup: container exists and running
+                    mock_which.side_effect = lambda x: f"/usr/local/bin/{x}" if x == "container" else None
+                    mock_running.return_value = True
+                    result = detect_runtime(explicit=False)
+                    assert result == "/usr/local/bin/container"
+
+    def test_macos_fallback_orbstack_when_container_not_running(self, monkeypatch):
+        """Test macOS falls back to OrbStack if Apple Container not running."""
+        monkeypatch.setenv("MDIFY_CONTAINER_RUNTIME", "")
+        with patch("mdify.cli.platform.system", return_value="Darwin"):
+            with patch("mdify.cli.shutil.which") as mock_which:
+                with patch("mdify.cli.is_daemon_running") as mock_running:
+                    # Setup: container exists but not running, orbstack exists and running
+                    def which_side_effect(x):
+                        if x in ("container", "orbstack"):
+                            return f"/usr/local/bin/{x}"
+                        return None
+                    
+                    def running_side_effect(path):
+                        return "orbstack" in path
+                    
+                    mock_which.side_effect = which_side_effect
+                    mock_running.side_effect = running_side_effect
+                    result = detect_runtime(explicit=False)
+                    assert result == "/usr/local/bin/orbstack"
+
+    def test_all_tools_exist_but_not_running(self, monkeypatch, capsys):
+        """Test warning when tools exist but none are running."""
+        monkeypatch.setenv("MDIFY_CONTAINER_RUNTIME", "")
+        with patch("mdify.cli.platform.system", return_value="Darwin"):
+            with patch("mdify.cli.shutil.which") as mock_which:
+                with patch("mdify.cli.is_daemon_running", return_value=False):
+                    def which_side_effect(x):
+                        if x in ("orbstack", "colima", "podman", "docker"):
+                            return f"/usr/local/bin/{x}"
+                        return None
+                    
+                    mock_which.side_effect = which_side_effect
+                    result = detect_runtime(explicit=False)
+                    assert result is None
+                    captured = capsys.readouterr()
+                    assert "daemon is not running" in captured.err
+                    assert "orbstack" in captured.err
+                    assert "colima" in captured.err
+
 
 class TestNewCLIArgs:
     """Test new CLI arguments for docling-serve."""
@@ -673,6 +817,66 @@ class TestFileHandling:
         assert result == output_dir / "doc.md"
 
 
+class TestIsDaemonRunning:
+    """Tests for is_daemon_running() function."""
+
+    def test_daemon_running_returns_true(self):
+        """Test is_daemon_running returns True when daemon is responsive."""
+        mock_result = Mock()
+        mock_result.returncode = 0
+        with patch("mdify.cli.subprocess.run", return_value=mock_result):
+            result = is_daemon_running("/usr/bin/docker")
+        assert result is True
+
+    def test_daemon_not_running_returns_false(self):
+        """Test is_daemon_running returns False when daemon is not responsive."""
+        mock_result = Mock()
+        mock_result.returncode = 1
+        with patch("mdify.cli.subprocess.run", return_value=mock_result):
+            result = is_daemon_running("/usr/bin/docker")
+        assert result is False
+
+    def test_daemon_timeout_returns_false(self):
+        """Test is_daemon_running returns False on timeout."""
+        with patch("mdify.cli.subprocess.run", side_effect=subprocess.TimeoutExpired("cmd", 5)):
+            result = is_daemon_running("/usr/bin/docker")
+        assert result is False
+
+    def test_daemon_oserror_returns_false(self):
+        """Test is_daemon_running returns False on OSError."""
+        with patch("mdify.cli.subprocess.run", side_effect=OSError("No such file")):
+            result = is_daemon_running("/usr/bin/nonexistent")
+        assert result is False
+
+    def test_apple_container_daemon_running(self):
+        """Test is_daemon_running uses 'system status' for Apple Container."""
+        mock_result = Mock()
+        mock_result.returncode = 0
+        with patch("mdify.cli.subprocess.run", return_value=mock_result) as mock_run:
+            result = is_daemon_running("/usr/local/bin/container")
+        assert result is True
+        mock_run.assert_called_once_with(
+            ["/usr/local/bin/container", "system", "status"],
+            capture_output=True,
+            timeout=5,
+            check=False,
+        )
+
+    def test_apple_container_daemon_not_running(self):
+        """Test is_daemon_running returns False when Apple Container daemon not running."""
+        mock_result = Mock()
+        mock_result.returncode = 1
+        with patch("mdify.cli.subprocess.run", return_value=mock_result) as mock_run:
+            result = is_daemon_running("/usr/local/bin/container")
+        assert result is False
+        mock_run.assert_called_once_with(
+            ["/usr/local/bin/container", "system", "status"],
+            capture_output=True,
+            timeout=5,
+            check=False,
+        )
+
+
 class TestContainerRuntime:
     """Tests for container runtime functions."""
 
@@ -774,6 +978,47 @@ class TestContainerRuntime:
         captured = capsys.readouterr()
         assert "Error pulling image" in captured.err
 
+    def test_apple_container_pull_success(self):
+        """Test pull_image uses 'image-pull' for Apple Container."""
+        mock_result = Mock()
+        mock_result.returncode = 0
+        with patch("mdify.cli.subprocess.run", return_value=mock_result) as mock_run:
+            result = pull_image("/usr/local/bin/container", "test-image", quiet=True)
+        assert result is True
+        mock_run.assert_called_once_with(
+            ["/usr/local/bin/container", "image-pull", "test-image"],
+            capture_output=True,
+            check=False,
+        )
+
+    def test_apple_container_image_exists(self):
+        """Test check_image_exists uses 'image-list' for Apple Container."""
+        mock_result = Mock()
+        mock_result.returncode = 0
+        mock_result.stdout = json.dumps([
+            {"name": "test-image", "repoTags": ["test-image:latest"]},
+            {"name": "other-image", "repoTags": ["other-image:latest"]}
+        ]).encode()
+        with patch("mdify.cli.subprocess.run", return_value=mock_result) as mock_run:
+            result = check_image_exists("/usr/local/bin/container", "test-image")
+        assert result is True
+        mock_run.assert_called_once_with(
+            ["/usr/local/bin/container", "image-list", "--format", "json"],
+            capture_output=True,
+            check=False,
+        )
+
+    def test_apple_container_image_not_exists(self):
+        """Test check_image_exists returns False when image not in list."""
+        mock_result = Mock()
+        mock_result.returncode = 0
+        mock_result.stdout = json.dumps([
+            {"name": "other-image", "repoTags": ["other-image:latest"]}
+        ]).encode()
+        with patch("mdify.cli.subprocess.run", return_value=mock_result):
+            result = check_image_exists("/usr/local/bin/container", "test-image")
+        assert result is False
+
 
 class TestGetStorageRoot:
     """Tests for get_storage_root() function."""
@@ -874,6 +1119,60 @@ class TestGetStorageRoot:
             result = get_storage_root("podman")
         assert result is None
 
+    def test_orbstack_storage_root(self, monkeypatch):
+        """Test get_storage_root returns OrbStack storage root."""
+        from mdify.cli import get_storage_root
+
+        home = "/Users/testuser"
+        monkeypatch.setenv("HOME", home)
+        result = get_storage_root("/usr/local/bin/orbstack")
+        assert result == f"{home}/.orbstack"
+
+    def test_colima_storage_root(self, monkeypatch):
+        """Test get_storage_root returns Colima storage root."""
+        from mdify.cli import get_storage_root
+
+        home = "/Users/testuser"
+        monkeypatch.setenv("HOME", home)
+        result = get_storage_root("/usr/local/bin/colima")
+        assert result == f"{home}/.colima"
+
+    def test_orbstack_storage_root_with_full_path(self, monkeypatch):
+        """Test get_storage_root works with full path to OrbStack executable."""
+        from mdify.cli import get_storage_root
+
+        home = "/Users/apple"
+        monkeypatch.setenv("HOME", home)
+        result = get_storage_root("/opt/homebrew/bin/orbstack")
+        assert result == f"{home}/.orbstack"
+
+    def test_colima_storage_root_with_full_path(self, monkeypatch):
+        """Test get_storage_root works with full path to Colima executable."""
+        from mdify.cli import get_storage_root
+
+        home = "/Users/apple"
+        monkeypatch.setenv("HOME", home)
+        result = get_storage_root("/opt/homebrew/bin/colima")
+        assert result == f"{home}/.colima"
+
+    def test_apple_container_storage_root(self, monkeypatch):
+        """Test get_storage_root returns Apple Container storage root."""
+        from mdify.cli import get_storage_root
+
+        home = "/Users/testuser"
+        monkeypatch.setenv("HOME", home)
+        result = get_storage_root("/usr/local/bin/container")
+        assert result == f"{home}/Library/Application Support/com.apple.container"
+
+    def test_apple_container_storage_root_with_full_path(self, monkeypatch):
+        """Test get_storage_root works with full path to Apple Container executable."""
+        from mdify.cli import get_storage_root
+
+        home = "/Users/apple"
+        monkeypatch.setenv("HOME", home)
+        result = get_storage_root("/opt/homebrew/bin/container")
+        assert result == f"{home}/Library/Application Support/com.apple.container"
+
 
 class TestGetImageSizeEstimate:
     """Tests for get_image_size_estimate function."""