How CLI-Anything Resolves Cross-Platform Paths Including Windows cygpath

CLI-Anything resolves cross-platform paths by detecting Windows Bash environments and enforcing cygpath availability at the shell level, while using Python's pathlib and PureWindowsPath to normalize storage references, file:// URLs, and UNC paths into native formats across Linux, macOS, and Windows.

Cross-platform path resolution is critical for the HKUDS/CLI-Anything repository, which must handle file system locations expressed as POSIX paths, Windows UNC shares, Zotero storage references, and file:// URLs across different operating systems. The codebase employs a dual-layer strategy combining shell-level environment detection with Python-level path normalization to ensure consistent behavior whether running on Linux, macOS, or Windows Git Bash.

Detecting Windows Bash and Enforcing cygpath Availability

Before any Python code executes, the setup script at cli-anything-plugin/scripts/setup-cli-anything.sh validates the execution environment. It specifically checks for Cygwin, MSYS, or MINGW shells that require the cygpath utility to translate between POSIX and Windows native path formats.

The is_windows_bash() function detects these environments by inspecting uname -s:

is_windows_bash() {
    case "$(uname -s 2>/dev/null)" in
        CYGWIN*|MINGW*|MSYS*) return 0 ;;
    esac
    return 1
}

if is_windows_bash && ! command -v cygpath >/dev/null 2>&1; then
    echo -e "${RED}✗${NC} Windows bash environment detected but 'cygpath' was not found."
    echo -e "${YELLOW}  Please install Git for Windows (Git Bash) or use WSL, then rerun this script.${NC}"
    exit 1
fi

This guard prevents obscure runtime errors by ensuring that cygpath is available before any shell operations attempt path conversion between /c/Users/... style paths and C:\Users\... style paths.

Normalizing Attachment Paths in Python

The core path resolution logic resides in zotero/agent-harness/cli_anything/zotero/utils/zotero_sqlite.py, specifically within the resolve_attachment_real_path() function. This utility safely converts Zotero attachment references—including storage prefixes, URLs, and relative paths—into concrete filesystem paths.

Handling Zotero Storage References

When an attachment uses the storage: prefix (indicating files managed within Zotero's internal storage directory), the function constructs the absolute path by combining the data directory, item key, and filename:

def resolve_attachment_real_path(item: dict[str, Any], data_dir: Path | str) -> Optional[str]:
    raw_path = str(item.get("attachmentPath"))
    data_dir = Path(data_dir)

    # Storage-based files (relative to Zotero storage folder)

    if raw_path.startswith("storage:"):
        filename = raw_path.split(":", 1)[1]
        return str((data_dir / "storage" / item["key"] / filename).resolve())

Converting file:// URLs and UNC Paths

For file:// URLs, the implementation handles three distinct cases: network shares (UNC paths), Windows drive letters encoded as POSIX paths, and standard absolute paths. The function uses urlparse to decode URL-encoded characters and PureWindowsPath to ensure proper Windows formatting:

from pathlib import Path, PureWindowsPath
from urllib.parse import urlparse, unquote
import re

def resolve_attachment_real_path(item: dict[str, Any], data_dir: Path | str) -> Optional[str]:
    raw_path = str(item.get("attachmentPath"))
    if not raw_path:
        return None
    raw_path = str(raw_path)
    data_dir = Path(data_dir)

    # file:// URLs (potentially Windows UNC)

    if raw_path.startswith("file://"):
        parsed = urlparse(raw_path)
        decoded_path = unquote(parsed.path)

        # Network share → \\servername\share\…

        if parsed.netloc and parsed.netloc.lower() != "localhost":
            unc_path = f"\\\\{parsed.netloc}{decoded_path.replace('/', '\\')}"
            return str(PureWindowsPath(unc_path))

        # Windows drive letter expressed as /C:/…

        if re.match(r"^/[A-Za-z]:", decoded_path):
            return str(PureWindowsPath(decoded_path.lstrip("/")))

        # Fallback: return POSIX path on *nix, Windows-style on Windows

        return decoded_path if os.name != "nt" else str(PureWindowsPath(decoded_path))

Key resolution strategies include:

• UNC Path Construction: When parsed.netloc contains a server name (e.g., file://fileserver/share/doc.pdf), the code builds a Windows UNC string (\\fileserver\share\doc.pdf) using PureWindowsPath.
• Drive Letter Normalization: URLs like file:///C:/path/file.pdf are converted to C:\path\file.pdf by stripping the leading slash and wrapping with PureWindowsPath.
• Platform Detection: The function checks os.name to determine whether to return POSIX-style or Windows-style paths, ensuring compatibility with the underlying operating system.

Resolving Profile Directories

Profile and executable discovery in zotero/agent-harness/cli_anything/zotero/utils/zotero_paths.py demonstrates cross-platform path expansion using Path.expanduser() and Path.resolve(). The _profile_path_from_section() function handles both relative and absolute path entries from Zotero's profiles.ini:

def _profile_path_from_section(profile_root: Path, config: configparser.ConfigParser, section: str) -> Optional[Path]:
    path_value = config.get(section, "Path", fallback="").strip()
    if not path_value:
        return None
    is_relative = config.get(section, "IsRelative", fallback="1").strip() == "1"
    return (profile_root / path_value).resolve() if is_relative else Path(path_value).expanduser()

This approach expands ~ to the user's home directory and resolves relative entries against a discovered profile_root, working uniformly across Linux, macOS, and Windows environments.

Practical Implementation Examples

Below are runnable examples demonstrating the path resolution capabilities across different scenarios.

Example 1: Resolving a UNC Path from a Zotero Attachment

from pathlib import Path
from zotero.utils.zotero_sqlite import resolve_attachment_real_path

# Simulated Zotero attachment entry with network share

attachment = {
    "attachmentPath": "file://fileserver/shared/docs/report.pdf",
    "key": "ABC123"
}
data_dir = Path("/home/user/Zotero")

real_path = resolve_attachment_real_path(attachment, data_dir)

# On Windows: '\\fileserver\shared\docs\report.pdf'

# On Linux: '/home/user/Zotero/storage/ABC123/report.pdf' (if storage-based)

print(real_path)

Example 2: Setup Script Detecting Missing cygpath

$ bash cli-anything-plugin/scripts/setup-cli-anything.sh
✗ Windows bash environment detected but 'cygpath' was not found.
  Please install Git for Windows (Git Bash) or use WSL, then rerun this script.

This early exit prevents subsequent path conversion failures.

Example 3: Cross-Platform Profile Discovery

from zotero.utils.zotero_paths import find_profile_root

# Returns appropriate path for current platform

profile_root = find_profile_root()

# Linux/macOS: PosixPath('/home/user/.zotero/zotero')

# Windows: WindowsPath('C:/Users/Alice/AppData/Roaming/Zotero/Zotero')

print(profile_root)

Summary

• Shell-level guards in setup-cli-anything.sh detect Windows Bash environments and enforce cygpath presence to prevent path conversion failures.
• Python normalization via resolve_attachment_real_path() handles storage: prefixes, file:// URLs, UNC paths, and drive-letter conversions using PureWindowsPath and pathlib.
• Profile resolution consistently expands user directories (~) and resolves relative paths across Linux, macOS, and Windows using Path.expanduser().resolve().
• Platform-aware formatting returns POSIX paths on Unix systems and Windows native paths on NT systems, ensuring compatibility with external tools and APIs.

Frequently Asked Questions

Why does CLI-Anything require cygpath on Windows?

CLI-Anything requires cygpath when running in Cygwin, MSYS, or MINGW environments because these shells express Windows paths as POSIX paths (e.g., /c/Program Files/). Without cygpath, the system cannot convert these to native Windows paths (C:\Program Files) required by external executables, leading to "file not found" errors when launching tools or accessing attachments.

How does CLI-Anything handle Windows UNC paths from URLs?

When encountering a file:// URL with a network location (e.g., file://server/share/file.pdf), the code in zotero_sqlite.py constructs a UNC string by prepending backslashes to the netloc and converting forward slashes: f"\\\\{parsed.netloc}{decoded_path.replace('/', '\\')}". This creates a valid \\server\share\file.pdf path wrapped in PureWindowsPath for Windows compatibility.

What happens if an attachment path is relative to the Zotero data directory?

If a path is neither a storage: reference, a file:// URL, nor an absolute path, the function treats it as relative to the Zotero data directory. It constructs the full path using data_dir / raw_path and calls .resolve() to normalize any .. or . segments, returning the canonical absolute path.

Does the path resolution work identically on WSL and Git Bash?

While both WSL and Git Bash run on Windows, CLI-Anything's setup script specifically targets Git Bash (Cygwin/MSYS/MINGW) for the cygpath check. WSL uses native Linux path handling and does not require cygpath conversion, as it manages its own filesystem bridge. The Python pathlib code works uniformly across both environments, but the shell-level guard in setup-cli-anything.sh is designed primarily for Git Bash installations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}