feat(config): support system-installed Tailwind CSS CLI

Add TAILWIND_CLI_USE_SYSTEM_BINARY (opt-in) so users with a tailwindcss
binary already on PATH — e.g. installed via Homebrew — can skip the
automatic download entirely. The binary is resolved via shutil.which(),
which works uniformly across Intel/ARM macOS, Linuxbrew and system
package managers without hardcoding paths.

When enabled:
- The download flow is bypassed in _download_cli_with_verbose(); no
  network calls, no files under TAILWIND_CLI_PATH.
- remove_cli refuses to delete the binary, since the library did not
  install it.
- The tailwind config command reports the origin ("system binary" vs
  "managed download") and lists the new settings.
- If TAILWIND_CLI_VERSION is pinned and the installed binary reports a
  different version, a UserWarning is emitted. No warning when VERSION
  is "latest" (user has no explicit expectation) or when version
  detection fails (subprocess error, unparseable output).

Version detection runs `<binary> --help` and parses the first line of
stdout. The --version flag is deliberately not used: unknown flags are
interpreted by the CLI as a build invocation.

Optional TAILWIND_CLI_SYSTEM_BINARY_NAME lets users override the
executable name; defaults to "tailwindcss", or "tailwindcss-extra" when
DaisyUI is enabled. Mutually exclusive with TAILWIND_CLI_PATH.

Author: oliverandrich

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### 🎯 New Features
 - **Configurable minification**: New `TAILWIND_CLI_AUTOMATIC_MINIFY` setting and `--minify` / `--no-minify` flag on `tailwind build` for projects whose asset pipelines already minify CSS. Defaults preserve existing behavior.
+- **System binary support**: New `TAILWIND_CLI_USE_SYSTEM_BINARY` setting lets `django-tailwind-cli` use a Tailwind CSS CLI that is already installed on `PATH` (e.g. via Homebrew), skipping the auto-download. Pairs with optional `TAILWIND_CLI_SYSTEM_BINARY_NAME` override. Emits a warning if the installed binary's version differs from an explicitly pinned `TAILWIND_CLI_VERSION`.
 
 ### 🛠️ Developer Experience
 - **Gitignore cleanup**: Trimmed `.gitignore` to project-relevant entries only

docs/installation.md

@@ -69,6 +69,17 @@
 
 ## Optional steps
 
+### Use a system-installed Tailwind CSS CLI
+
+By default, `django-tailwind-cli` downloads the Tailwind CSS CLI binary on first use and caches it inside your project. If you already have `tailwindcss` installed through [Homebrew](https://formulae.brew.sh/formula/tailwindcss) or another package manager, you can tell the library to use that binary instead and skip the download:
+
+```python
+# settings.py
+TAILWIND_CLI_USE_SYSTEM_BINARY = True
+```
+
+See [`TAILWIND_CLI_USE_SYSTEM_BINARY`](settings.md#tailwind_cli_use_system_binary) for details.
+
 ### Install `django-browser-reload`
 
 If you enjoy automatic reloading during development. Install the [django-browser-reload](https://github.com/adamchainz/django-browser-reload) app. The following installation steps are taken from the README of the project.

docs/settings.md

@@ -42,6 +42,39 @@ In case you want to use the new behaviour, it is highly recommended to also set
 
 Enable or disable the automatic downloading of the official CLI to your machine.
 
+### TAILWIND_CLI_USE_SYSTEM_BINARY
+
+**Default**: `False`
+
+If set to `True`, the library uses a Tailwind CSS CLI that is already installed on your system's `PATH` (for example via [Homebrew](https://formulae.brew.sh/formula/tailwindcss) or a system package manager) instead of downloading its own copy. The binary is resolved with Python's `shutil.which()`, so it works on any platform as long as the executable is reachable via `PATH`.
+
+When enabled:
+
+- The automatic download is skipped entirely — no network calls, no files created under `TAILWIND_CLI_PATH`.
+- `python manage.py tailwind remove_cli` refuses to delete the binary (since the library did not install it).
+- If `TAILWIND_CLI_VERSION` is pinned to a specific version and the system binary reports a different version, a warning is emitted so you can reconcile the discrepancy. No warning is issued when `TAILWIND_CLI_VERSION = "latest"`.
+
+```python
+# settings.py
+TAILWIND_CLI_USE_SYSTEM_BINARY = True
+```
+
+:::{warning}
+`TAILWIND_CLI_USE_SYSTEM_BINARY` is **mutually exclusive** with `TAILWIND_CLI_PATH`. Use one or the other.
+:::
+
+### TAILWIND_CLI_SYSTEM_BINARY_NAME
+
+**Default**: `"tailwindcss"` (or `"tailwindcss-extra"` when `TAILWIND_CLI_USE_DAISY_UI = True`)
+
+Overrides the executable name that is looked up on `PATH` when `TAILWIND_CLI_USE_SYSTEM_BINARY = True`. You rarely need to set this — the default picks the right name automatically.
+
+```python
+# settings.py
+TAILWIND_CLI_USE_SYSTEM_BINARY = True
+TAILWIND_CLI_SYSTEM_BINARY_NAME = "my-tailwindcss"  # optional
+```
+
 ### TAILWIND_CLI_AUTOMATIC_MINIFY
 
 **Default**: `True`
@@ -285,6 +318,21 @@ In your templates, include all CSS files or filter by name:
 
 The `build` command processes all entries, and the `watch` command monitors all source files simultaneously.
 
+### Using a Homebrew-installed Tailwind CSS CLI
+
+If you have already installed `tailwindcss` through [Homebrew](https://formulae.brew.sh/formula/tailwindcss) (or any other package manager that puts it on your `PATH`), you can skip the automatic download entirely:
+
+```bash
+brew install tailwindcss
+```
+
+```python
+# settings.py
+TAILWIND_CLI_USE_SYSTEM_BINARY = True
+```
+
+That's it — the library resolves `tailwindcss` via `PATH` on every invocation and runs your builds against that binary. Pairs well with `TAILWIND_CLI_VERSION = "latest"` so you don't have to update two places when Homebrew bumps the version.
+
 ### Staging Environment
 
 Balanced between dev flexibility and prod stability:

src/django_tailwind_cli/config.py

@@ -55,6 +55,17 @@
             Default: True
             Example: TAILWIND_CLI_AUTOMATIC_DOWNLOAD = False
 
+        TAILWIND_CLI_USE_SYSTEM_BINARY (optional): Use a CLI on PATH
+            Default: False
+            Example: TAILWIND_CLI_USE_SYSTEM_BINARY = True
+            Note: Mutually exclusive with TAILWIND_CLI_PATH. When enabled,
+                  the binary is resolved via shutil.which() and the
+                  automatic download is skipped.
+
+        TAILWIND_CLI_SYSTEM_BINARY_NAME (optional): Name for PATH lookup
+            Default: "tailwindcss" (or "tailwindcss-extra" with DaisyUI)
+            Example: TAILWIND_CLI_SYSTEM_BINARY_NAME = "my-tailwindcss"
+
         TAILWIND_CLI_REQUEST_TIMEOUT (optional): Network request timeout
             Default: 10 (seconds)
             Example: TAILWIND_CLI_REQUEST_TIMEOUT = 30
@@ -87,10 +98,15 @@
     ]
 """
 
+import functools
 import os
 import platform
+import re
+import shutil
+import subprocess
 import tempfile
 import time
+import warnings
 from dataclasses import dataclass
 from pathlib import Path
 from typing import NamedTuple
@@ -121,6 +137,7 @@ class Config:
     overwrite_default_config: bool = True
     automatic_download: bool = True
     use_daisy_ui: bool = False
+    uses_system_binary: bool = False
 
     # Backward compatibility properties
     @property
@@ -222,10 +239,36 @@ def _validate_required_settings() -> None:
             "TAILWIND_CLI_SRC_REPO must not be empty. Either remove the setting or provide a valid repository URL."
         )
 
+    # Validate system-binary settings
+    _validate_system_binary_settings()
+
     # Validate mutual exclusivity of CSS settings
     _validate_css_settings()
 
 
+def _validate_system_binary_settings() -> None:
+    """Validate TAILWIND_CLI_USE_SYSTEM_BINARY and friends.
+
+    Raises:
+        ValueError: If configuration is inconsistent or invalid.
+    """
+    use_system_binary = getattr(settings, "TAILWIND_CLI_USE_SYSTEM_BINARY", False)
+    binary_name = getattr(settings, "TAILWIND_CLI_SYSTEM_BINARY_NAME", None)
+
+    if binary_name is not None and not binary_name:
+        raise ValueError(
+            "TAILWIND_CLI_SYSTEM_BINARY_NAME must not be empty. "
+            "Either remove the setting or provide a valid binary name."
+        )
+
+    if use_system_binary and getattr(settings, "TAILWIND_CLI_PATH", None):
+        raise ValueError(
+            "Cannot use TAILWIND_CLI_USE_SYSTEM_BINARY together with TAILWIND_CLI_PATH. "
+            "Choose one: either point TAILWIND_CLI_PATH at a specific binary, or set "
+            "TAILWIND_CLI_USE_SYSTEM_BINARY = True to look up the binary on PATH."
+        )
+
+
 def _validate_css_settings() -> None:
     """Validate CSS configuration settings for mutual exclusivity.
 
@@ -407,6 +450,90 @@ def get_version() -> tuple[str, Version]:
         return version_str, Version.parse(version_str)
 
 
+_VERSION_PATTERN = re.compile(r"tailwindcss v(\d+\.\d+\.\d+)")
+
+
+@functools.cache
+def detect_binary_version(cli_path: Path) -> Version | None:
+    """Detect the version of a Tailwind CSS CLI binary.
+
+    Runs ``<cli_path> --help`` and parses the version from the first line of
+    stdout. Returns None on any failure (timeout, non-zero exit, unparseable
+    output) — callers are expected to treat None as "unknown" and skip any
+    version comparisons rather than raising.
+
+    Note: ``--version`` is intentionally not used because the Tailwind CLI
+    interprets unknown flags as a build invocation, which would run a full
+    CSS build instead of reporting the version.
+
+    Args:
+        cli_path: Path to the CLI binary.
+
+    Returns:
+        Parsed Version on success, None on any failure.
+    """
+    try:
+        result = subprocess.run(
+            [str(cli_path), "--help"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+
+    if result.returncode != 0:
+        return None
+
+    match = _VERSION_PATTERN.search(result.stdout)
+    if not match:
+        return None
+
+    try:
+        return Version.parse(match.group(1))
+    except ValueError:
+        return None
+
+
+def _resolve_system_binary(binary_name: str) -> Path:
+    """Resolve a binary on the user's PATH.
+
+    Args:
+        binary_name: Name of the executable to look up (e.g. "tailwindcss").
+
+    Returns:
+        Absolute path to the binary.
+
+    Raises:
+        ValueError: If the binary cannot be found on PATH.
+    """
+    found = shutil.which(binary_name)
+    if not found:
+        raise ValueError(
+            f"TAILWIND_CLI_USE_SYSTEM_BINARY is enabled, but the binary {binary_name!r} "
+            "could not be found on PATH. Install it (e.g. 'brew install tailwindcss') "
+            "or disable TAILWIND_CLI_USE_SYSTEM_BINARY to use the automatic download instead."
+        )
+    return Path(found)
+
+
+def _get_system_binary_name(*, use_daisy_ui: bool) -> str:
+    """Return the system binary name to look up via shutil.which.
+
+    Args:
+        use_daisy_ui: Whether DaisyUI support is enabled.
+
+    Returns:
+        Binary name — honours the explicit TAILWIND_CLI_SYSTEM_BINARY_NAME
+        override if set, otherwise picks a DaisyUI-aware default.
+    """
+    override = getattr(settings, "TAILWIND_CLI_SYSTEM_BINARY_NAME", None)
+    if override:
+        return override
+    return "tailwindcss-extra" if use_daisy_ui else "tailwindcss"
+
+
 def _resolve_cli_path(platform_info: PlatformInfo, version_str: str, asset_name: str) -> Path:
     """Resolve the CLI executable path.
 
@@ -569,6 +696,7 @@ def get_config() -> Config:
     # Get basic settings
     use_daisy_ui = getattr(settings, "TAILWIND_CLI_USE_DAISY_UI", False)
     automatic_download = getattr(settings, "TAILWIND_CLI_AUTOMATIC_DOWNLOAD", True)
+    uses_system_binary = bool(getattr(settings, "TAILWIND_CLI_USE_SYSTEM_BINARY", False))
 
     # Get platform information
     platform_info = get_platform_info()
@@ -580,7 +708,15 @@ def get_config() -> Config:
     repo_url, asset_name = _get_repository_settings(use_daisy_ui=use_daisy_ui)
 
     # Resolve paths
-    cli_path = _resolve_cli_path(platform_info, version_str, asset_name)
+    if uses_system_binary:
+        binary_name = _get_system_binary_name(use_daisy_ui=use_daisy_ui)
+        cli_path = _resolve_system_binary(binary_name)
+        # System binary mode implies auto-download is off — we never downloaded it.
+        automatic_download = False
+        _maybe_warn_version_mismatch(cli_path, version_str)
+    else:
+        cli_path = _resolve_cli_path(platform_info, version_str, asset_name)
+
     css_entries, overwrite_default_config = _resolve_css_paths()
 
     # Build download URL
@@ -598,4 +734,37 @@ def get_config() -> Config:
         overwrite_default_config=overwrite_default_config,
         automatic_download=automatic_download,
         use_daisy_ui=use_daisy_ui,
+        uses_system_binary=uses_system_binary,
+    )
+
+
+def _maybe_warn_version_mismatch(cli_path: Path, configured_version: str) -> None:
+    """Warn when the system binary reports a different version than configured.
+
+    No warning is emitted when:
+    - TAILWIND_CLI_VERSION is 'latest' (user has no explicit expectation).
+    - Version detection fails (subprocess error, unparseable output).
+    - The versions match.
+
+    Args:
+        cli_path: Path to the system binary.
+        configured_version: Version string as resolved by get_version().
+    """
+    # When the user set VERSION='latest', they accepted whatever is installed.
+    if getattr(settings, "TAILWIND_CLI_VERSION", "latest") == "latest":
+        return
+
+    detected = detect_binary_version(cli_path)
+    if detected is None:
+        return
+
+    if str(detected) == configured_version:
+        return
+
+    warnings.warn(
+        f"TAILWIND_CLI_VERSION is set to {configured_version}, but the system binary at "
+        f"{cli_path} reports version {detected}. Using the system binary anyway — "
+        "update TAILWIND_CLI_VERSION or your installed binary to silence this warning.",
+        UserWarning,
+        stacklevel=2,
     )

src/django_tailwind_cli/management/commands/tailwind.py

@@ -583,7 +583,8 @@ def show_config():
     # Path information
     typer.secho("\n📁 File Paths:", fg=typer.colors.YELLOW, bold=True)
     cli_exists = "✅" if config.cli_path.exists() else "❌"
-    typer.secho(f"   CLI Binary: {config.cli_path} {cli_exists}", fg=typer.colors.GREEN)
+    origin = "system binary" if config.uses_system_binary else "managed download"
+    typer.secho(f"   CLI Binary: {config.cli_path} {cli_exists} ({origin})", fg=typer.colors.GREEN)
 
     # CSS Entries
     typer.secho(f"\n📄 CSS Entries ({len(config.css_entries)}):", fg=typer.colors.YELLOW, bold=True)
@@ -606,6 +607,12 @@ def show_config():
     if cli_path_setting:
         typer.secho(f"   TAILWIND_CLI_PATH: {cli_path_setting}", fg=typer.colors.GREEN)
 
+    if getattr(settings, "TAILWIND_CLI_USE_SYSTEM_BINARY", False):
+        typer.secho("   TAILWIND_CLI_USE_SYSTEM_BINARY: True", fg=typer.colors.GREEN)
+        system_binary_name = getattr(settings, "TAILWIND_CLI_SYSTEM_BINARY_NAME", None)
+        if system_binary_name:
+            typer.secho(f"   TAILWIND_CLI_SYSTEM_BINARY_NAME: {system_binary_name}", fg=typer.colors.GREEN)
+
     # Show CSS settings based on mode
     css_map_setting = getattr(settings, "TAILWIND_CLI_CSS_MAP", None)
     if css_map_setting:
@@ -1058,6 +1065,15 @@ def remove_cli():
     """Remove the Tailwind CSS CLI."""
     c = get_config()
 
+    if c.uses_system_binary:
+        typer.secho(
+            f"Refusing to remove system Tailwind CSS CLI at '{c.cli_path}'. "
+            "It was installed outside of django-tailwind-cli (e.g. via Homebrew) and must be "
+            "uninstalled the same way.",
+            fg=typer.colors.YELLOW,
+        )
+        return
+
     if c.cli_path.exists():
         c.cli_path.unlink()
         typer.secho(f"Removed Tailwind CSS CLI at '{c.cli_path}'.", fg=typer.colors.GREEN)
@@ -1613,6 +1629,16 @@ def _download_cli_with_verbose(*, verbose: bool = False, force_download: bool =
         typer.secho(f"   • Download URL: {c.download_url}", fg=typer.colors.BLUE)
         typer.secho(f"   • Automatic download: {c.automatic_download}", fg=typer.colors.BLUE)
 
+    # System-binary mode: the CLI lives on PATH, never download it.
+    if c.uses_system_binary:
+        if verbose:
+            typer.secho("✅ Using system Tailwind CSS CLI — download skipped", fg=typer.colors.GREEN)
+        typer.secho(
+            f"Using system Tailwind CSS CLI at '{c.cli_path}'.",
+            fg=typer.colors.GREEN,
+        )
+        return
+
     if not force_download and not c.automatic_download:
         if not _check_file_exists_cached(c.cli_path):
             if verbose: