hud-python 0.4.1__py3-none-any.whl → 0.4.3__py3-none-any.whl

hud/cli/__init__.py

@@ -1,617 +1,617 @@
-"""HUD CLI - Command-line interface for MCP environment analysis and debugging."""
-
-from __future__ import annotations
-
-import asyncio
-import json
-import os
-import sys
-from pathlib import Path  # noqa: TC003
-
-import typer
-from rich.console import Console
-from rich.panel import Panel
-from rich.table import Table
-
-from .analyze import (
-    analyze_environment,
-    analyze_environment_from_config,
-    analyze_environment_from_mcp_config,
-)
-from .build import build_command
-from .clone import clone_repository, get_clone_message, print_error, print_tutorial
-from .cursor import get_cursor_config_path, list_cursor_servers, parse_cursor_config
-from .debug import debug_mcp_stdio
-from .init import create_environment
-from .mcp_server import run_mcp_dev_server
-from .pull import pull_command
-from .push import push_command
-from .utils import CaptureLogger
-
-# Create the main Typer app
-app = typer.Typer(
-    name="hud",
-    help="🚀 HUD CLI for MCP environment analysis and debugging",
-    add_completion=False,
-    rich_markup_mode="rich",
-)
-
-console = Console()
-
-
-# Capture IMAGE and any following Docker args as a single variadic argument list.
-@app.command(context_settings={"allow_extra_args": True, "ignore_unknown_options": True})
-def analyze(
-    params: list[str] = typer.Argument(  # type: ignore[arg-type]  # noqa: B008
-        None,  # Optional positional arguments
-        help="Docker image followed by optional Docker run arguments (e.g., 'hud-image:latest -e KEY=value')",  # noqa: E501
-    ),
-    config: Path = typer.Option(  # noqa: B008
-        None,
-        "--config",
-        "-c",
-        help="JSON config file with MCP configuration",
-        exists=True,
-        file_okay=True,
-        dir_okay=False,
-    ),
-    cursor: str | None = typer.Option(
-        None,
-        "--cursor",
-        help="Analyze a server from Cursor config",
-    ),
-    output_format: str = typer.Option(
-        "interactive",
-        "--format",
-        "-f",
-        help="Output format: interactive, json, markdown",
-    ),
-    verbose: bool = typer.Option(
-        False,
-        "--verbose",
-        "-v",
-        help="Enable verbose output (shows tool schemas)",
-    ),
-    live: bool = typer.Option(
-        False,
-        "--live",
-        help="Run container for live analysis (slower but more accurate)",
-    ),
-) -> None:
-    """🔍 Analyze MCP environment - discover tools, resources, and capabilities.
-
-    By default, uses cached metadata for instant results.
-    Use --live to run the container for real-time analysis.
-
-    Examples:
-        hud analyze hudpython/test_init      # Fast metadata inspection
-        hud analyze my-env --live            # Full container analysis
-        hud analyze --config mcp-config.json # From MCP config
-        hud analyze --cursor text-2048-dev   # From Cursor config
-    """
-    if config:
-        # Load config from JSON file (always live for configs)
-        asyncio.run(analyze_environment_from_config(config, output_format, verbose))
-    elif cursor:
-        # Parse cursor config (always live for cursor)
-        command, error = parse_cursor_config(cursor)
-        if error or command is None:
-            console.print(f"[red]❌ {error or 'Failed to parse cursor config'}[/red]")
-            raise typer.Exit(1)
-        # Convert to MCP config
-        mcp_config = {
-            "local": {"command": command[0], "args": command[1:] if len(command) > 1 else []}
-        }
-        asyncio.run(analyze_environment_from_mcp_config(mcp_config, output_format, verbose))
-    elif params:
-        image, *docker_args = params
-        if live or docker_args:  # If docker args provided, assume live mode
-            # Build Docker command from image and args
-            docker_cmd = ["docker", "run", "--rm", "-i", *docker_args, image]
-            asyncio.run(analyze_environment(docker_cmd, output_format, verbose))
-        else:
-            # Fast mode - analyze from metadata
-            from .analyze_metadata import analyze_from_metadata
-
-            asyncio.run(analyze_from_metadata(image, output_format, verbose))
-    else:
-        console.print("[red]Error: Must specify either a Docker image, --config, or --cursor[/red]")
-        console.print("\nExamples:")
-        console.print("  hud analyze hudpython/test_init       # Fast metadata analysis")
-        console.print("  hud analyze my-env --live             # Live container analysis")
-        console.print("  hud analyze --config mcp-config.json  # From config file")
-        console.print("  hud analyze --cursor my-server        # From Cursor")
-        raise typer.Exit(1)
-
-
-# Same variadic approach for debug.
-@app.command(context_settings={"allow_extra_args": True, "ignore_unknown_options": True})
-def debug(
-    params: list[str] = typer.Argument(  # type: ignore[arg-type]  # noqa: B008
-        None,
-        help="Docker image followed by optional Docker run arguments (e.g., 'hud-image:latest -e KEY=value')",  # noqa: E501
-    ),
-    config: Path = typer.Option(  # noqa: B008
-        None,
-        "--config",
-        "-c",
-        help="JSON config file with MCP configuration",
-        exists=True,
-        file_okay=True,
-        dir_okay=False,
-    ),
-    cursor: str | None = typer.Option(
-        None,
-        "--cursor",
-        help="Debug a server from Cursor config",
-    ),
-    max_phase: int = typer.Option(
-        5,
-        "--max-phase",
-        "-p",
-        min=1,
-        max=5,
-        help="Maximum debug phase (1-5)",
-    ),
-) -> None:
-    """🐛 Debug MCP environment - test initialization, tools, and readiness.
-
-    Examples:
-        hud debug hud-text-2048:latest
-        hud debug my-mcp-server:v1 -e API_KEY=xxx -p 8080:8080
-        hud debug --config mcp-config.json
-        hud debug --cursor text-2048-dev
-        hud debug hud-browser:dev --max-phase 3
-    """
-
-    # Determine the command to run
-    command = None
-
-    if config:
-        # Load config from JSON file
-        with open(config) as f:
-            mcp_config = json.load(f)
-
-        # Extract command from first server in config
-        server_name = next(iter(mcp_config.keys()))
-        server_config = mcp_config[server_name]
-        command = [server_config["command"], *server_config.get("args", [])]
-    elif cursor:
-        # Parse cursor config
-        command, error = parse_cursor_config(cursor)
-        if error or command is None:
-            console.print(f"[red]❌ {error or 'Failed to parse cursor config'}[/red]")
-            raise typer.Exit(1)
-    elif params:
-        image, *docker_args = params
-        # Build Docker command
-        command = ["docker", "run", "--rm", "-i", *docker_args, image]
-    else:
-        console.print("[red]Error: Must specify either a Docker image, --config, or --cursor[/red]")
-        console.print("\nExamples:")
-        console.print("  hud debug hud-text-2048:latest")
-        console.print("  hud debug --config mcp-config.json")
-        console.print("  hud debug --cursor my-server")
-        raise typer.Exit(1)
-
-    # Create logger and run debug
-    logger = CaptureLogger(print_output=True)
-    phases_completed = asyncio.run(debug_mcp_stdio(command, logger, max_phase=max_phase))
-
-    # Show summary using design system
-    from hud.utils.design import HUDDesign
-
-    design = HUDDesign()
-
-    design.info("")  # Empty line
-    design.section_title("Debug Summary")
-
-    if phases_completed == max_phase:
-        design.success(f"All {max_phase} phases completed successfully!")
-        if max_phase == 5:
-            design.info("Your MCP server is fully functional and ready for production use.")
-    else:
-        design.warning(f"Completed {phases_completed} out of {max_phase} phases")
-        design.info("Check the errors above for troubleshooting.")
-
-    # Exit with appropriate code
-    if phases_completed < max_phase:
-        raise typer.Exit(1)
-
-
-@app.command()
-def cursor_list() -> None:
-    """📋 List all MCP servers configured in Cursor."""
-    console.print(Panel.fit("📋 [bold cyan]Cursor MCP Servers[/bold cyan]", border_style="cyan"))
-
-    servers, error = list_cursor_servers()
-
-    if error:
-        console.print(f"[red]❌ {error}[/red]")
-        raise typer.Exit(1)
-
-    if not servers:
-        console.print("[yellow]No servers found in Cursor config[/yellow]")
-        return
-
-    # Display servers in a table
-    table = Table(title="Available Servers")
-    table.add_column("Server Name", style="cyan")
-    table.add_column("Command Preview", style="dim")
-
-    config_path = get_cursor_config_path()
-    if config_path.exists():
-        with open(config_path) as f:
-            config = json.load(f)
-            mcp_servers = config.get("mcpServers", {})
-
-            for server_name in servers:
-                server_config = mcp_servers.get(server_name, {})
-                command = server_config.get("command", "")
-                args = server_config.get("args", [])
-
-                # Create command preview
-                if args:
-                    preview = f"{command} {' '.join(args[:2])}"
-                    if len(args) > 2:
-                        preview += " ..."
-                else:
-                    preview = command
-
-                table.add_row(server_name, preview)
-
-    console.print(table)
-    console.print(f"\n[dim]Config location: {config_path}[/dim]")
-    console.print(
-        "\n[green]Tip:[/green] Use [cyan]hud debug --cursor <server-name>[/cyan] to debug a server"
-    )
-
-
-@app.command()
-def version() -> None:
-    """Show HUD CLI version."""
-    try:
-        from hud import __version__
-
-        console.print(f"HUD CLI version: [cyan]{__version__}[/cyan]")
-    except ImportError:
-        console.print("HUD CLI version: [cyan]unknown[/cyan]")
-
-
-@app.command(context_settings={"allow_extra_args": True, "ignore_unknown_options": True})
-def dev(
-    params: list[str] = typer.Argument(  # type: ignore[arg-type]  # noqa: B008
-        None,
-        help="Environment directory followed by optional Docker arguments (e.g., '. -e KEY=value')",
-    ),
-    image: str | None = typer.Option(
-        None, "--image", "-i", help="Docker image name (overrides auto-detection)"
-    ),
-    build: bool = typer.Option(False, "--build", "-b", help="Build image before starting"),
-    no_cache: bool = typer.Option(False, "--no-cache", help="Force rebuild without cache"),
-    transport: str = typer.Option(
-        "http", "--transport", "-t", help="Transport protocol: http (default) or stdio"
-    ),
-    port: int = typer.Option(8765, "--port", "-p", help="HTTP server port (ignored for stdio)"),
-    no_reload: bool = typer.Option(False, "--no-reload", help="Disable hot-reload"),
-    verbose: bool = typer.Option(False, "--verbose", "-v", help="Show server logs"),
-    inspector: bool = typer.Option(
-        False, "--inspector", help="Launch MCP Inspector (HTTP mode only)"
-    ),
-    no_logs: bool = typer.Option(False, "--no-logs", help="Disable streaming Docker logs"),
-    interactive: bool = typer.Option(
-        False, "--interactive", help="Launch interactive testing mode (HTTP mode only)"
-    ),
-) -> None:
-    """🔥 Development mode with hot-reload.
-
-    Runs your MCP environment in Docker with automatic restart on file changes.
-
-    The container's last command (typically the MCP server) will be wrapped
-    with watchfiles for hot-reload functionality.
-
-    Examples:
-        hud dev                      # Auto-detect in current directory
-        hud dev environments/browser # Specific directory
-        hud dev . --build            # Build image first
-        hud dev . --image custom:tag # Use specific image
-        hud dev . --no-cache         # Force clean rebuild
-        hud dev . --verbose          # Show detailed logs
-        hud dev . --transport stdio  # Use stdio proxy for multiple connections
-        hud dev . --inspector        # Launch MCP Inspector (HTTP mode only)
-        hud dev . --interactive      # Launch interactive testing mode (HTTP mode only)
-        hud dev . --no-logs          # Disable Docker log streaming
-
-        # With Docker arguments (after all options):
-        hud dev . -e BROWSER_PROVIDER=anchorbrowser -e ANCHOR_API_KEY=xxx
-        hud dev . -e API_KEY=secret -v /tmp/data:/data --network host
-        hud dev . --build -e DEBUG=true --memory 2g
-    """
-    # Parse directory and Docker arguments
-    if params:
-        directory = params[0]
-        docker_args = params[1:] if len(params) > 1 else []
-    else:
-        directory = "."
-        docker_args = []
-
-    run_mcp_dev_server(
-        directory,
-        image,
-        build,
-        no_cache,
-        transport,
-        port,
-        no_reload,
-        verbose,
-        inspector,
-        no_logs,
-        interactive,
-        docker_args,
-    )
-
-
-@app.command(context_settings={"allow_extra_args": True, "ignore_unknown_options": True})
-def run(
-    params: list[str] = typer.Argument(  # type: ignore[arg-type]  # noqa: B008
-        None,
-        help="Docker image followed by optional arguments (e.g., 'hud-image:latest -e KEY=value')",
-    ),
-    local: bool = typer.Option(
-        False,
-        "--local",
-        help="Run locally with Docker (default: remote via mcp.hud.so)",
-    ),
-    remote: bool = typer.Option(
-        False,
-        "--remote",
-        help="Run remotely via mcp.hud.so (default)",
-    ),
-    transport: str = typer.Option(
-        "stdio",
-        "--transport",
-        "-t",
-        help="Transport protocol: stdio (default) or http",
-    ),
-    port: int = typer.Option(
-        8765,
-        "--port",
-        "-p",
-        help="Port for HTTP transport (ignored for stdio)",
-    ),
-    url: str = typer.Option(
-        None,
-        "--url",
-        help="Remote MCP server URL (default: HUD_MCP_URL or mcp.hud.so)",
-    ),
-    api_key: str | None = typer.Option(
-        None,
-        "--api-key",
-        help="API key for remote server (default: HUD_API_KEY env var)",
-    ),
-    run_id: str | None = typer.Option(
-        None,
-        "--run-id",
-        help="Run ID for tracking (remote only)",
-    ),
-    verbose: bool = typer.Option(
-        False,
-        "--verbose",
-        "-v",
-        help="Show detailed output",
-    ),
-) -> None:
-    """🚀 Run MCP server locally or remotely.
-
-    By default, runs remotely via mcp.hud.so. Use --local for Docker.
-
-    Remote Examples:
-        hud run hud-text-2048:latest
-        hud run my-server:v1 -e API_KEY=xxx -h Run-Id:abc123
-        hud run my-server:v1 --transport http --port 9000
-
-    Local Examples:
-        hud run --local hud-text-2048:latest
-        hud run --local my-server:v1 -e API_KEY=xxx
-        hud run --local my-server:v1 --transport http
-    """
-    if not params:
-        typer.echo("❌ Docker image is required")
-        raise typer.Exit(1)
-
-    # Parse image and args
-    image = params[0]
-    docker_args = params[1:] if len(params) > 1 else []
-
-    # Handle conflicting flags
-    if local and remote:
-        typer.echo("❌ Cannot use both --local and --remote")
-        raise typer.Exit(1)
-
-    # Default to remote if not explicitly local
-    is_local = local and not remote
-
-    if is_local:
-        # Local Docker execution
-        from .runner import run_mcp_server
-
-        run_mcp_server(image, docker_args, transport, port, verbose)
-    else:
-        # Remote execution via proxy
-        from .remote_runner import run_remote_server
-
-        # Get URL from options or environment
-        if not url:
-            url = os.getenv("HUD_MCP_URL", "https://mcp.hud.so/v3/mcp")
-
-        run_remote_server(image, docker_args, transport, port, url, api_key, run_id, verbose)
-
-
-@app.command()
-def clone(
-    url: str = typer.Argument(
-        ...,
-        help="Git repository URL to clone",
-    ),
-) -> None:
-    """🚀 Clone a git repository quietly with a pretty output.
-
-    This command wraps 'git clone' with the --quiet flag and displays
-    a rich formatted success message. If the repository contains a clone
-    message in pyproject.toml, it will be displayed as a tutorial.
-
-    Configure clone messages in your repository's pyproject.toml:
-
-    [tool.hud.clone]
-    title = "🚀 My Project"
-    message = "Thanks for cloning! Run 'pip install -e .' to get started."
-
-    # Or use markdown format:
-    # markdown = "## Welcome!\\n\\nHere's how to get started..."
-    # style = "cyan"
-
-    Examples:
-        hud clone https://github.com/user/repo.git
-    """
-    # Run the clone
-    success, result = clone_repository(url)
-
-    if success:
-        # Look for clone message configuration
-        clone_config = get_clone_message(result)
-        print_tutorial(clone_config)
-    else:
-        print_error(result)
-        raise typer.Exit(1)
-
-
-@app.command()
-def build(
-    directory: str = typer.Argument(".", help="Environment directory to build"),
-    tag: str | None = typer.Option(
-        None, "--tag", "-t", help="Docker image tag (default: from pyproject.toml)"
-    ),
-    no_cache: bool = typer.Option(False, "--no-cache", help="Build without Docker cache"),
-    verbose: bool = typer.Option(False, "--verbose", "-v", help="Show detailed output"),
-) -> None:
-    """🏗️ Build a HUD environment and generate lock file.
-
-    This command:
-    - Builds a Docker image from your environment
-    - Analyzes the MCP server to extract metadata
-    - Generates a hud.lock.yaml file for reproducibility
-
-    Examples:
-        hud build                    # Build current directory
-        hud build environments/text_2048
-        hud build . --tag my-env:v1.0
-        hud build . --no-cache       # Force rebuild
-    """
-    build_command(directory, tag, no_cache, verbose)
-
-
-@app.command()
-def push(
-    directory: str = typer.Argument(".", help="Environment directory containing hud.lock.yaml"),
-    image: str | None = typer.Option(None, "--image", "-i", help="Override registry image name"),
-    tag: str | None = typer.Option(
-        None, "--tag", "-t", help="Override tag (e.g., 'v1.0', 'latest')"
-    ),
-    sign: bool = typer.Option(
-        False, "--sign", help="Sign the image with cosign (not yet implemented)"
-    ),
-    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompts"),
-    verbose: bool = typer.Option(False, "--verbose", "-v", help="Show detailed output"),
-) -> None:
-    """📤 Push HUD environment to registry.
-
-    Reads hud.lock.yaml from the directory and pushes to registry.
-    Auto-detects your Docker username if --image not specified.
-
-    Examples:
-        hud push                     # Push with auto-detected name
-        hud push --tag v1.0          # Push with specific tag
-        hud push . --image myuser/myenv:v1.0
-        hud push --yes               # Skip confirmation
-    """
-    push_command(directory, image, tag, sign, yes, verbose)
-
-
-@app.command()
-def pull(
-    target: str = typer.Argument(..., help="Image reference or lock file to pull"),
-    lock_file: str | None = typer.Option(
-        None, "--lock", "-l", help="Path to lock file (if target is image ref)"
-    ),
-    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt"),
-    verify_only: bool = typer.Option(
-        False, "--verify-only", help="Only verify metadata without pulling"
-    ),
-    verbose: bool = typer.Option(False, "--verbose", "-v", help="Show detailed output"),
-) -> None:
-    """📥 Pull HUD environment from registry with metadata preview.
-
-    Shows environment details before downloading.
-
-    Examples:
-        hud pull hud.lock.yaml               # Pull from lock file
-        hud pull myuser/myenv:latest        # Pull by image reference
-        hud pull myuser/myenv --verify-only # Check metadata only
-    """
-    pull_command(target, lock_file, yes, verify_only, verbose)
-
-
-@app.command()
-def init(
-    name: str = typer.Argument(None, help="Environment name (default: current directory name)"),
-    directory: str = typer.Option(".", "--dir", "-d", help="Target directory"),
-    force: bool = typer.Option(False, "--force", "-f", help="Overwrite existing files"),
-) -> None:
-    """🚀 Initialize a new HUD environment with minimal boilerplate.
-
-    Creates a working MCP environment with:
-    - Dockerfile for containerization
-    - pyproject.toml for dependencies
-    - Minimal MCP server with context
-    - Required setup/evaluate tools
-
-    Examples:
-        hud init                    # Use current directory name
-        hud init my-env             # Create in ./my-env/
-        hud init my-env --dir /tmp  # Create in /tmp/my-env/
-    """
-    create_environment(name, directory, force)
-
-
-@app.command()
-def quickstart() -> None:
-    """
-    Quickstart with evaluating an agent!
-    """
-    # Just call the clone command with the quickstart URL
-    clone("https://github.com/hud-evals/quickstart.git")
-
-
-def main() -> None:
-    """Main entry point for the CLI."""
-    # Show header for main help
-    if len(sys.argv) == 1 or (len(sys.argv) == 2 and sys.argv[1] in ["--help", "-h"]):
-        console.print(
-            Panel.fit(
-                "[bold cyan]🚀 HUD CLI[/bold cyan]\nMCP Environment Analysis & Debugging",
-                border_style="cyan",
-            )
-        )
-        console.print("\n[yellow]Quick Start:[/yellow]")
-        console.print("  1. Create a new environment: [cyan]hud init my-env && cd my-env[/cyan]")
-        console.print("  2. Develop with hot-reload: [cyan]hud dev --interactive[/cyan]")
-        console.print("  3. Build for production: [cyan]hud build[/cyan]")
-        console.print("  4. Share your environment: [cyan]hud push[/cyan]")
-        console.print("  5. Get shared environments: [cyan]hud pull <org/name:tag>[/cyan]")
-        console.print("  6. Run and test: [cyan]hud run <image>[/cyan]\n")
-
-    app()
-
-
-if __name__ == "__main__":
-    main()
+"""HUD CLI - Command-line interface for MCP environment analysis and debugging."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import sys
+from pathlib import Path  # noqa: TC003
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from .analyze import (
+    analyze_environment,
+    analyze_environment_from_config,
+    analyze_environment_from_mcp_config,
+)
+from .build import build_command
+from .clone import clone_repository, get_clone_message, print_error, print_tutorial
+from .cursor import get_cursor_config_path, list_cursor_servers, parse_cursor_config
+from .debug import debug_mcp_stdio
+from .init import create_environment
+from .mcp_server import run_mcp_dev_server
+from .pull import pull_command
+from .push import push_command
+from .utils import CaptureLogger
+
+# Create the main Typer app
+app = typer.Typer(
+    name="hud",
+    help="🚀 HUD CLI for MCP environment analysis and debugging",
+    add_completion=False,
+    rich_markup_mode="rich",
+)
+
+console = Console()
+
+
+# Capture IMAGE and any following Docker args as a single variadic argument list.
+@app.command(context_settings={"allow_extra_args": True, "ignore_unknown_options": True})
+def analyze(
+    params: list[str] = typer.Argument(  # type: ignore[arg-type]  # noqa: B008
+        None,  # Optional positional arguments
+        help="Docker image followed by optional Docker run arguments (e.g., 'hud-image:latest -e KEY=value')",  # noqa: E501
+    ),
+    config: Path = typer.Option(  # noqa: B008
+        None,
+        "--config",
+        "-c",
+        help="JSON config file with MCP configuration",
+        exists=True,
+        file_okay=True,
+        dir_okay=False,
+    ),
+    cursor: str | None = typer.Option(
+        None,
+        "--cursor",
+        help="Analyze a server from Cursor config",
+    ),
+    output_format: str = typer.Option(
+        "interactive",
+        "--format",
+        "-f",
+        help="Output format: interactive, json, markdown",
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        "-v",
+        help="Enable verbose output (shows tool schemas)",
+    ),
+    live: bool = typer.Option(
+        False,
+        "--live",
+        help="Run container for live analysis (slower but more accurate)",
+    ),
+) -> None:
+    """🔍 Analyze MCP environment - discover tools, resources, and capabilities.
+
+    By default, uses cached metadata for instant results.
+    Use --live to run the container for real-time analysis.
+
+    Examples:
+        hud analyze hudpython/test_init      # Fast metadata inspection
+        hud analyze my-env --live            # Full container analysis
+        hud analyze --config mcp-config.json # From MCP config
+        hud analyze --cursor text-2048-dev   # From Cursor config
+    """
+    if config:
+        # Load config from JSON file (always live for configs)
+        asyncio.run(analyze_environment_from_config(config, output_format, verbose))
+    elif cursor:
+        # Parse cursor config (always live for cursor)
+        command, error = parse_cursor_config(cursor)
+        if error or command is None:
+            console.print(f"[red]❌ {error or 'Failed to parse cursor config'}[/red]")
+            raise typer.Exit(1)
+        # Convert to MCP config
+        mcp_config = {
+            "local": {"command": command[0], "args": command[1:] if len(command) > 1 else []}
+        }
+        asyncio.run(analyze_environment_from_mcp_config(mcp_config, output_format, verbose))
+    elif params:
+        image, *docker_args = params
+        if live or docker_args:  # If docker args provided, assume live mode
+            # Build Docker command from image and args
+            docker_cmd = ["docker", "run", "--rm", "-i", *docker_args, image]
+            asyncio.run(analyze_environment(docker_cmd, output_format, verbose))
+        else:
+            # Fast mode - analyze from metadata
+            from .analyze_metadata import analyze_from_metadata
+
+            asyncio.run(analyze_from_metadata(image, output_format, verbose))
+    else:
+        console.print("[red]Error: Must specify either a Docker image, --config, or --cursor[/red]")
+        console.print("\nExamples:")
+        console.print("  hud analyze hudpython/test_init       # Fast metadata analysis")
+        console.print("  hud analyze my-env --live             # Live container analysis")
+        console.print("  hud analyze --config mcp-config.json  # From config file")
+        console.print("  hud analyze --cursor my-server        # From Cursor")
+        raise typer.Exit(1)
+
+
+# Same variadic approach for debug.
+@app.command(context_settings={"allow_extra_args": True, "ignore_unknown_options": True})
+def debug(
+    params: list[str] = typer.Argument(  # type: ignore[arg-type]  # noqa: B008
+        None,
+        help="Docker image followed by optional Docker run arguments (e.g., 'hud-image:latest -e KEY=value')",  # noqa: E501
+    ),
+    config: Path = typer.Option(  # noqa: B008
+        None,
+        "--config",
+        "-c",
+        help="JSON config file with MCP configuration",
+        exists=True,
+        file_okay=True,
+        dir_okay=False,
+    ),
+    cursor: str | None = typer.Option(
+        None,
+        "--cursor",
+        help="Debug a server from Cursor config",
+    ),
+    max_phase: int = typer.Option(
+        5,
+        "--max-phase",
+        "-p",
+        min=1,
+        max=5,
+        help="Maximum debug phase (1-5)",
+    ),
+) -> None:
+    """🐛 Debug MCP environment - test initialization, tools, and readiness.
+
+    Examples:
+        hud debug hud-text-2048:latest
+        hud debug my-mcp-server:v1 -e API_KEY=xxx -p 8080:8080
+        hud debug --config mcp-config.json
+        hud debug --cursor text-2048-dev
+        hud debug hud-browser:dev --max-phase 3
+    """
+
+    # Determine the command to run
+    command = None
+
+    if config:
+        # Load config from JSON file
+        with open(config) as f:
+            mcp_config = json.load(f)
+
+        # Extract command from first server in config
+        server_name = next(iter(mcp_config.keys()))
+        server_config = mcp_config[server_name]
+        command = [server_config["command"], *server_config.get("args", [])]
+    elif cursor:
+        # Parse cursor config
+        command, error = parse_cursor_config(cursor)
+        if error or command is None:
+            console.print(f"[red]❌ {error or 'Failed to parse cursor config'}[/red]")
+            raise typer.Exit(1)
+    elif params:
+        image, *docker_args = params
+        # Build Docker command
+        command = ["docker", "run", "--rm", "-i", *docker_args, image]
+    else:
+        console.print("[red]Error: Must specify either a Docker image, --config, or --cursor[/red]")
+        console.print("\nExamples:")
+        console.print("  hud debug hud-text-2048:latest")
+        console.print("  hud debug --config mcp-config.json")
+        console.print("  hud debug --cursor my-server")
+        raise typer.Exit(1)
+
+    # Create logger and run debug
+    logger = CaptureLogger(print_output=True)
+    phases_completed = asyncio.run(debug_mcp_stdio(command, logger, max_phase=max_phase))
+
+    # Show summary using design system
+    from hud.utils.design import HUDDesign
+
+    design = HUDDesign()
+
+    design.info("")  # Empty line
+    design.section_title("Debug Summary")
+
+    if phases_completed == max_phase:
+        design.success(f"All {max_phase} phases completed successfully!")
+        if max_phase == 5:
+            design.info("Your MCP server is fully functional and ready for production use.")
+    else:
+        design.warning(f"Completed {phases_completed} out of {max_phase} phases")
+        design.info("Check the errors above for troubleshooting.")
+
+    # Exit with appropriate code
+    if phases_completed < max_phase:
+        raise typer.Exit(1)
+
+
+@app.command()
+def cursor_list() -> None:
+    """📋 List all MCP servers configured in Cursor."""
+    console.print(Panel.fit("📋 [bold cyan]Cursor MCP Servers[/bold cyan]", border_style="cyan"))
+
+    servers, error = list_cursor_servers()
+
+    if error:
+        console.print(f"[red]❌ {error}[/red]")
+        raise typer.Exit(1)
+
+    if not servers:
+        console.print("[yellow]No servers found in Cursor config[/yellow]")
+        return
+
+    # Display servers in a table
+    table = Table(title="Available Servers")
+    table.add_column("Server Name", style="cyan")
+    table.add_column("Command Preview", style="dim")
+
+    config_path = get_cursor_config_path()
+    if config_path.exists():
+        with open(config_path) as f:
+            config = json.load(f)
+            mcp_servers = config.get("mcpServers", {})
+
+            for server_name in servers:
+                server_config = mcp_servers.get(server_name, {})
+                command = server_config.get("command", "")
+                args = server_config.get("args", [])
+
+                # Create command preview
+                if args:
+                    preview = f"{command} {' '.join(args[:2])}"
+                    if len(args) > 2:
+                        preview += " ..."
+                else:
+                    preview = command
+
+                table.add_row(server_name, preview)
+
+    console.print(table)
+    console.print(f"\n[dim]Config location: {config_path}[/dim]")
+    console.print(
+        "\n[green]Tip:[/green] Use [cyan]hud debug --cursor <server-name>[/cyan] to debug a server"
+    )
+
+
+@app.command()
+def version() -> None:
+    """Show HUD CLI version."""
+    try:
+        from hud import __version__
+
+        console.print(f"HUD CLI version: [cyan]{__version__}[/cyan]")
+    except ImportError:
+        console.print("HUD CLI version: [cyan]unknown[/cyan]")
+
+
+@app.command(context_settings={"allow_extra_args": True, "ignore_unknown_options": True})
+def dev(
+    params: list[str] = typer.Argument(  # type: ignore[arg-type]  # noqa: B008
+        None,
+        help="Environment directory followed by optional Docker arguments (e.g., '. -e KEY=value')",
+    ),
+    image: str | None = typer.Option(
+        None, "--image", "-i", help="Docker image name (overrides auto-detection)"
+    ),
+    build: bool = typer.Option(False, "--build", "-b", help="Build image before starting"),
+    no_cache: bool = typer.Option(False, "--no-cache", help="Force rebuild without cache"),
+    transport: str = typer.Option(
+        "http", "--transport", "-t", help="Transport protocol: http (default) or stdio"
+    ),
+    port: int = typer.Option(8765, "--port", "-p", help="HTTP server port (ignored for stdio)"),
+    no_reload: bool = typer.Option(False, "--no-reload", help="Disable hot-reload"),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Show server logs"),
+    inspector: bool = typer.Option(
+        False, "--inspector", help="Launch MCP Inspector (HTTP mode only)"
+    ),
+    no_logs: bool = typer.Option(False, "--no-logs", help="Disable streaming Docker logs"),
+    interactive: bool = typer.Option(
+        False, "--interactive", help="Launch interactive testing mode (HTTP mode only)"
+    ),
+) -> None:
+    """🔥 Development mode with hot-reload.
+
+    Runs your MCP environment in Docker with automatic restart on file changes.
+
+    The container's last command (typically the MCP server) will be wrapped
+    with watchfiles for hot-reload functionality.
+
+    Examples:
+        hud dev                      # Auto-detect in current directory
+        hud dev environments/browser # Specific directory
+        hud dev . --build            # Build image first
+        hud dev . --image custom:tag # Use specific image
+        hud dev . --no-cache         # Force clean rebuild
+        hud dev . --verbose          # Show detailed logs
+        hud dev . --transport stdio  # Use stdio proxy for multiple connections
+        hud dev . --inspector        # Launch MCP Inspector (HTTP mode only)
+        hud dev . --interactive      # Launch interactive testing mode (HTTP mode only)
+        hud dev . --no-logs          # Disable Docker log streaming
+
+        # With Docker arguments (after all options):
+        hud dev . -e BROWSER_PROVIDER=anchorbrowser -e ANCHOR_API_KEY=xxx
+        hud dev . -e API_KEY=secret -v /tmp/data:/data --network host
+        hud dev . --build -e DEBUG=true --memory 2g
+    """
+    # Parse directory and Docker arguments
+    if params:
+        directory = params[0]
+        docker_args = params[1:] if len(params) > 1 else []
+    else:
+        directory = "."
+        docker_args = []
+
+    run_mcp_dev_server(
+        directory,
+        image,
+        build,
+        no_cache,
+        transport,
+        port,
+        no_reload,
+        verbose,
+        inspector,
+        no_logs,
+        interactive,
+        docker_args,
+    )
+
+
+@app.command(context_settings={"allow_extra_args": True, "ignore_unknown_options": True})
+def run(
+    params: list[str] = typer.Argument(  # type: ignore[arg-type]  # noqa: B008
+        None,
+        help="Docker image followed by optional arguments (e.g., 'hud-image:latest -e KEY=value')",
+    ),
+    local: bool = typer.Option(
+        False,
+        "--local",
+        help="Run locally with Docker (default: remote via mcp.hud.so)",
+    ),
+    remote: bool = typer.Option(
+        False,
+        "--remote",
+        help="Run remotely via mcp.hud.so (default)",
+    ),
+    transport: str = typer.Option(
+        "stdio",
+        "--transport",
+        "-t",
+        help="Transport protocol: stdio (default) or http",
+    ),
+    port: int = typer.Option(
+        8765,
+        "--port",
+        "-p",
+        help="Port for HTTP transport (ignored for stdio)",
+    ),
+    url: str = typer.Option(
+        None,
+        "--url",
+        help="Remote MCP server URL (default: HUD_MCP_URL or mcp.hud.so)",
+    ),
+    api_key: str | None = typer.Option(
+        None,
+        "--api-key",
+        help="API key for remote server (default: HUD_API_KEY env var)",
+    ),
+    run_id: str | None = typer.Option(
+        None,
+        "--run-id",
+        help="Run ID for tracking (remote only)",
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        "-v",
+        help="Show detailed output",
+    ),
+) -> None:
+    """🚀 Run MCP server locally or remotely.
+
+    By default, runs remotely via mcp.hud.so. Use --local for Docker.
+
+    Remote Examples:
+        hud run hud-text-2048:latest
+        hud run my-server:v1 -e API_KEY=xxx -h Run-Id:abc123
+        hud run my-server:v1 --transport http --port 9000
+
+    Local Examples:
+        hud run --local hud-text-2048:latest
+        hud run --local my-server:v1 -e API_KEY=xxx
+        hud run --local my-server:v1 --transport http
+    """
+    if not params:
+        typer.echo("❌ Docker image is required")
+        raise typer.Exit(1)
+
+    # Parse image and args
+    image = params[0]
+    docker_args = params[1:] if len(params) > 1 else []
+
+    # Handle conflicting flags
+    if local and remote:
+        typer.echo("❌ Cannot use both --local and --remote")
+        raise typer.Exit(1)
+
+    # Default to remote if not explicitly local
+    is_local = local and not remote
+
+    if is_local:
+        # Local Docker execution
+        from .runner import run_mcp_server
+
+        run_mcp_server(image, docker_args, transport, port, verbose)
+    else:
+        # Remote execution via proxy
+        from .remote_runner import run_remote_server
+
+        # Get URL from options or environment
+        if not url:
+            url = os.getenv("HUD_MCP_URL", "https://mcp.hud.so/v3/mcp")
+
+        run_remote_server(image, docker_args, transport, port, url, api_key, run_id, verbose)
+
+
+@app.command()
+def clone(
+    url: str = typer.Argument(
+        ...,
+        help="Git repository URL to clone",
+    ),
+) -> None:
+    """🚀 Clone a git repository quietly with a pretty output.
+
+    This command wraps 'git clone' with the --quiet flag and displays
+    a rich formatted success message. If the repository contains a clone
+    message in pyproject.toml, it will be displayed as a tutorial.
+
+    Configure clone messages in your repository's pyproject.toml:
+
+    [tool.hud.clone]
+    title = "🚀 My Project"
+    message = "Thanks for cloning! Run 'pip install -e .' to get started."
+
+    # Or use markdown format:
+    # markdown = "## Welcome!\\n\\nHere's how to get started..."
+    # style = "cyan"
+
+    Examples:
+        hud clone https://github.com/user/repo.git
+    """
+    # Run the clone
+    success, result = clone_repository(url)
+
+    if success:
+        # Look for clone message configuration
+        clone_config = get_clone_message(result)
+        print_tutorial(clone_config)
+    else:
+        print_error(result)
+        raise typer.Exit(1)
+
+
+@app.command()
+def build(
+    directory: str = typer.Argument(".", help="Environment directory to build"),
+    tag: str | None = typer.Option(
+        None, "--tag", "-t", help="Docker image tag (default: from pyproject.toml)"
+    ),
+    no_cache: bool = typer.Option(False, "--no-cache", help="Build without Docker cache"),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Show detailed output"),
+) -> None:
+    """🏗️ Build a HUD environment and generate lock file.
+
+    This command:
+    - Builds a Docker image from your environment
+    - Analyzes the MCP server to extract metadata
+    - Generates a hud.lock.yaml file for reproducibility
+
+    Examples:
+        hud build                    # Build current directory
+        hud build environments/text_2048
+        hud build . --tag my-env:v1.0
+        hud build . --no-cache       # Force rebuild
+    """
+    build_command(directory, tag, no_cache, verbose)
+
+
+@app.command()
+def push(
+    directory: str = typer.Argument(".", help="Environment directory containing hud.lock.yaml"),
+    image: str | None = typer.Option(None, "--image", "-i", help="Override registry image name"),
+    tag: str | None = typer.Option(
+        None, "--tag", "-t", help="Override tag (e.g., 'v1.0', 'latest')"
+    ),
+    sign: bool = typer.Option(
+        False, "--sign", help="Sign the image with cosign (not yet implemented)"
+    ),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompts"),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Show detailed output"),
+) -> None:
+    """📤 Push HUD environment to registry.
+
+    Reads hud.lock.yaml from the directory and pushes to registry.
+    Auto-detects your Docker username if --image not specified.
+
+    Examples:
+        hud push                     # Push with auto-detected name
+        hud push --tag v1.0          # Push with specific tag
+        hud push . --image myuser/myenv:v1.0
+        hud push --yes               # Skip confirmation
+    """
+    push_command(directory, image, tag, sign, yes, verbose)
+
+
+@app.command()
+def pull(
+    target: str = typer.Argument(..., help="Image reference or lock file to pull"),
+    lock_file: str | None = typer.Option(
+        None, "--lock", "-l", help="Path to lock file (if target is image ref)"
+    ),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt"),
+    verify_only: bool = typer.Option(
+        False, "--verify-only", help="Only verify metadata without pulling"
+    ),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Show detailed output"),
+) -> None:
+    """📥 Pull HUD environment from registry with metadata preview.
+
+    Shows environment details before downloading.
+
+    Examples:
+        hud pull hud.lock.yaml               # Pull from lock file
+        hud pull myuser/myenv:latest        # Pull by image reference
+        hud pull myuser/myenv --verify-only # Check metadata only
+    """
+    pull_command(target, lock_file, yes, verify_only, verbose)
+
+
+@app.command()
+def init(
+    name: str = typer.Argument(None, help="Environment name (default: current directory name)"),
+    directory: str = typer.Option(".", "--dir", "-d", help="Target directory"),
+    force: bool = typer.Option(False, "--force", "-f", help="Overwrite existing files"),
+) -> None:
+    """🚀 Initialize a new HUD environment with minimal boilerplate.
+
+    Creates a working MCP environment with:
+    - Dockerfile for containerization
+    - pyproject.toml for dependencies
+    - Minimal MCP server with context
+    - Required setup/evaluate tools
+
+    Examples:
+        hud init                    # Use current directory name
+        hud init my-env             # Create in ./my-env/
+        hud init my-env --dir /tmp  # Create in /tmp/my-env/
+    """
+    create_environment(name, directory, force)
+
+
+@app.command()
+def quickstart() -> None:
+    """
+    Quickstart with evaluating an agent!
+    """
+    # Just call the clone command with the quickstart URL
+    clone("https://github.com/hud-evals/quickstart.git")
+
+
+def main() -> None:
+    """Main entry point for the CLI."""
+    # Show header for main help
+    if len(sys.argv) == 1 or (len(sys.argv) == 2 and sys.argv[1] in ["--help", "-h"]):
+        console.print(
+            Panel.fit(
+                "[bold cyan]🚀 HUD CLI[/bold cyan]\nMCP Environment Analysis & Debugging",
+                border_style="cyan",
+            )
+        )
+        console.print("\n[yellow]Quick Start:[/yellow]")
+        console.print("  1. Create a new environment: [cyan]hud init my-env && cd my-env[/cyan]")
+        console.print("  2. Develop with hot-reload: [cyan]hud dev --interactive[/cyan]")
+        console.print("  3. Build for production: [cyan]hud build[/cyan]")
+        console.print("  4. Share your environment: [cyan]hud push[/cyan]")
+        console.print("  5. Get shared environments: [cyan]hud pull <org/name:tag>[/cyan]")
+        console.print("  6. Run and test: [cyan]hud run <image>[/cyan]\n")
+
+    app()
+
+
+if __name__ == "__main__":
+    main()