cloudcost-cli 0.1.0__py3-none-any.whl

backend/app/cli.py

@@ -0,0 +1,726 @@
+import argparse
+import asyncio
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import webbrowser
+from dataclasses import dataclass
+from decimal import Decimal
+from pathlib import Path
+from typing import Any
+
+from backend.app.comments import format_money, to_decimal
+from backend.app.config import Settings
+from backend.app.infracost import InfracostClient, InfracostEstimate
+
+
+VERSION = "0.1.0"
+DEFAULT_CONFIG_PATH = Path.home() / ".cloudcost" / "config.json"
+DEFAULT_BACKEND_URL = "https://cloudcost.live"
+DEFAULT_PLAN_NAMES = ("tfplan.json", "plan.json", "terraform-plan.json", "infracost-plan.json")
+SKIPPED_DISCOVERY_DIRS = {
+    ".cloudcost",
+    ".git",
+    ".terraform",
+    ".venv",
+    "__pycache__",
+    "dist",
+    "node_modules",
+}
+
+
+@dataclass(frozen=True)
+class ResourceCost:
+    name: str
+    resource_type: str
+    monthly_cost: Any
+
+
+def config_path() -> Path:
+    raw_path = os.environ.get("CLOUDCOST_CONFIG")
+    return Path(raw_path).expanduser() if raw_path else DEFAULT_CONFIG_PATH
+
+
+def read_config() -> dict[str, Any]:
+    path = config_path()
+    if not path.exists():
+        return {}
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+    return payload if isinstance(payload, dict) else {}
+
+
+def write_config(payload: dict[str, Any]) -> Path:
+    path = config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+    return path
+
+
+def normalize_backend_url(value: str) -> str:
+    value = value.strip()
+    if not value:
+        return DEFAULT_BACKEND_URL
+    if not value.startswith(("http://", "https://")):
+        value = "https://" + value
+    return value.rstrip("/")
+
+
+def backend_url_from_args(args: argparse.Namespace) -> str:
+    config = read_config()
+    raw_url = (
+        getattr(args, "backend_url", None)
+        or config.get("backend_url")
+        or os.environ.get("CLOUDCOST_BACKEND_URL")
+        or os.environ.get("PUBLIC_BASE_URL")
+        or DEFAULT_BACKEND_URL
+    )
+    return normalize_backend_url(str(raw_url))
+
+
+def github_install_url(args: argparse.Namespace) -> str:
+    return f"{backend_url_from_args(args)}/install/github"
+
+
+def settings_from_args(args: argparse.Namespace) -> Settings:
+    config = read_config()
+    base = Settings()
+    updates: dict[str, Any] = {}
+
+    infracost_mode = getattr(args, "infracost_mode", None) or config.get("infracost_mode")
+    infracost_cli_path = getattr(args, "infracost_cli_path", None) or config.get("infracost_cli_path")
+    pricing_api_endpoint = getattr(args, "pricing_api_endpoint", None) or config.get("pricing_api_endpoint")
+    infracost_api_key = getattr(args, "infracost_api_key", None) or config.get("infracost_api_key")
+
+    if infracost_mode:
+        updates["infracost_mode"] = infracost_mode
+    if infracost_cli_path:
+        updates["infracost_cli_path"] = infracost_cli_path
+    if pricing_api_endpoint:
+        updates["infracost_pricing_api_endpoint"] = pricing_api_endpoint
+    if infracost_api_key:
+        updates["infracost_api_key"] = infracost_api_key
+
+    return base.model_copy(update=updates)
+
+
+def ordered_plan_names(settings: Settings) -> list[str]:
+    names: list[str] = []
+    for name in (*DEFAULT_PLAN_NAMES, *sorted(settings.plan_names)):
+        normalized = name.strip().lower()
+        if normalized and normalized not in names:
+            names.append(normalized)
+    return names
+
+
+def is_plan_json(path: Path, settings: Settings) -> bool:
+    name = path.name.lower()
+    return name in ordered_plan_names(settings) or name.endswith(settings.plan_suffixes)
+
+
+def discover_plan_path(root: Path, settings: Settings, *, recursive: bool = False) -> Path | None:
+    root = root.expanduser().resolve()
+    if not root.exists() or not root.is_dir():
+        return None
+
+    for name in ordered_plan_names(settings):
+        candidate = root / name
+        if candidate.is_file():
+            return candidate
+
+    direct_matches = sorted(
+        path for path in root.iterdir() if path.is_file() and is_plan_json(path, settings)
+    )
+    if direct_matches:
+        return direct_matches[0]
+
+    if not recursive:
+        return None
+
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [
+            dirname
+            for dirname in dirnames
+            if dirname not in SKIPPED_DISCOVERY_DIRS and not dirname.startswith(".terraform")
+        ]
+        current = Path(dirpath)
+        for filename in sorted(filenames):
+            candidate = current / filename
+            if is_plan_json(candidate, settings):
+                return candidate
+    return None
+
+
+def run_process(command: list[str], *, cwd: Path, timeout: int) -> subprocess.CompletedProcess[bytes]:
+    try:
+        return subprocess.run(
+            command,
+            cwd=str(cwd),
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            timeout=timeout,
+            check=False,
+        )
+    except FileNotFoundError as exc:
+        raise RuntimeError(f"Command not found: {command[0]}") from exc
+    except subprocess.TimeoutExpired as exc:
+        raise RuntimeError(f"Command timed out after {timeout} seconds: {' '.join(command)}") from exc
+
+
+def parse_github_remote_url(remote_url: str) -> str | None:
+    remote_url = remote_url.strip()
+    patterns = [
+        r"^git@github\.com:(?P<owner>[^/]+)/(?P<repo>[^/]+?)(?:\.git)?$",
+        r"^https?://github\.com/(?P<owner>[^/]+)/(?P<repo>[^/]+?)(?:\.git)?/?$",
+        r"^ssh://git@github\.com/(?P<owner>[^/]+)/(?P<repo>[^/]+?)(?:\.git)?/?$",
+    ]
+    for pattern in patterns:
+        match = re.match(pattern, remote_url)
+        if match:
+            return f"{match.group('owner')}/{match.group('repo')}"
+    return None
+
+
+def detect_github_repo(root: Path) -> str | None:
+    try:
+        process = run_process(
+            ["git", "remote", "get-url", "origin"],
+            cwd=root.expanduser().resolve(),
+            timeout=10,
+        )
+    except RuntimeError:
+        return None
+    if process.returncode != 0:
+        return None
+    remote_url = process.stdout.decode("utf-8", errors="replace").strip()
+    return parse_github_remote_url(remote_url)
+
+
+def raise_for_process(process: subprocess.CompletedProcess[bytes], label: str) -> None:
+    if process.returncode == 0:
+        return
+    stderr = process.stderr.decode("utf-8", errors="replace").strip()
+    stdout = process.stdout.decode("utf-8", errors="replace").strip()
+    detail = stderr or stdout or f"exit code {process.returncode}"
+    raise RuntimeError(f"{label} failed: {detail[:2000]}")
+
+
+def generate_terraform_plan_json(args: argparse.Namespace, root: Path) -> Path | None:
+    terraform_bin = getattr(args, "terraform_bin", None) or "terraform"
+    terraform_path = Path(terraform_bin)
+    if not terraform_path.exists() and shutil.which(terraform_bin) is None:
+        return None
+
+    root = root.expanduser().resolve()
+    output_dir = root / ".cloudcost"
+    output_dir.mkdir(parents=True, exist_ok=True)
+    binary_path = output_dir / "tfplan.binary"
+    json_path = output_dir / "tfplan.json"
+    timeout = int(getattr(args, "terraform_timeout", 600) or 600)
+
+    if not getattr(args, "skip_terraform_init", False) and not (root / ".terraform").exists():
+        print("No .terraform directory found. Running terraform init...", file=sys.stderr)
+        init_process = run_process(
+            [terraform_bin, "init", "-input=false"],
+            cwd=root,
+            timeout=timeout,
+        )
+        raise_for_process(init_process, "terraform init")
+
+    print("Generating Terraform plan JSON...", file=sys.stderr)
+    plan_process = run_process(
+        [terraform_bin, "plan", "-input=false", "-out", str(binary_path)],
+        cwd=root,
+        timeout=timeout,
+    )
+    raise_for_process(plan_process, "terraform plan")
+
+    show_process = run_process(
+        [terraform_bin, "show", "-json", str(binary_path)],
+        cwd=root,
+        timeout=timeout,
+    )
+    raise_for_process(show_process, "terraform show")
+    json_path.write_bytes(show_process.stdout)
+    return json_path
+
+
+def extract_resource_costs(payload: dict[str, Any]) -> list[ResourceCost]:
+    resources: list[ResourceCost] = []
+    projects = payload.get("projects")
+    if not isinstance(projects, list):
+        projects = [payload]
+
+    for project in projects:
+        if not isinstance(project, dict):
+            continue
+        breakdown = project.get("breakdown")
+        candidates = []
+        if isinstance(breakdown, dict):
+            candidates.extend(breakdown.get("resources") or [])
+        candidates.extend(project.get("resources") or [])
+
+        for resource in candidates:
+            if not isinstance(resource, dict):
+                continue
+            name = str(
+                resource.get("name")
+                or resource.get("resourceName")
+                or resource.get("address")
+                or resource.get("resourceType")
+                or "unknown"
+            )
+            resource_type = str(resource.get("resourceType") or resource.get("type") or "")
+            monthly_cost = (
+                resource.get("monthlyCost")
+                or resource.get("totalMonthlyCost")
+                or resource.get("cost")
+                or resource.get("monthly_cost")
+            )
+            resources.append(
+                ResourceCost(
+                    name=name,
+                    resource_type=resource_type,
+                    monthly_cost=monthly_cost,
+                )
+            )
+
+    return resources
+
+
+def sort_resources(resources: list[ResourceCost]) -> list[ResourceCost]:
+    return sorted(
+        resources,
+        key=lambda item: abs(to_decimal(item.monthly_cost) or Decimal("0")),
+        reverse=True,
+    )
+
+
+def estimate_summary(estimate: InfracostEstimate, plan_path: Path) -> dict[str, Any]:
+    resources = extract_resource_costs(estimate.raw)
+    return {
+        "plan": str(plan_path),
+        "previous_monthly_cost": estimate.past_total_monthly_cost,
+        "proposed_monthly_cost": estimate.total_monthly_cost,
+        "diff_total_monthly_cost": estimate.diff_total_monthly_cost,
+        "resources": [
+            {
+                "name": item.name,
+                "resource_type": item.resource_type,
+                "monthly_cost": item.monthly_cost,
+            }
+            for item in sort_resources(resources)
+        ],
+    }
+
+
+def terminal_report(summary: dict[str, Any], limit: int = 12) -> str:
+    rows = summary["resources"][:limit]
+    lines = [
+        "CloudCost AI analyze",
+        "",
+        f"Plan: {summary['plan']}",
+        "",
+        "Monthly estimate",
+        "----------------",
+        f"Previous: {format_money(summary['previous_monthly_cost'])}",
+        f"Proposed: {format_money(summary['proposed_monthly_cost'])}",
+        f"Delta:    {format_money(summary['diff_total_monthly_cost'], signed=True)}",
+    ]
+
+    if rows:
+        lines.extend(["", "Largest resources", "-----------------"])
+        width = min(max(len(item["name"]) for item in rows), 56)
+        for item in rows:
+            name = item["name"]
+            if len(name) > width:
+                name = name[: width - 1] + "."
+            lines.append(f"{name:<{width}}  {format_money(item['monthly_cost'])}")
+    else:
+        lines.extend(["", "No resource-level costs were returned."])
+
+    lines.extend(
+        [
+            "",
+            "Next steps",
+            "----------",
+            "Use this in CI, or run `cloudcost connect-github` so CloudCost comments on pull requests automatically.",
+        ]
+    )
+    return "\n".join(lines)
+
+
+def markdown_report(summary: dict[str, Any], limit: int = 12) -> str:
+    lines = [
+        "## CloudCost AI estimate",
+        "",
+        "| Metric | Estimate |",
+        "| --- | ---: |",
+        f"| Previous monthly cost | {format_money(summary['previous_monthly_cost'])} |",
+        f"| Proposed monthly cost | {format_money(summary['proposed_monthly_cost'])} |",
+        f"| Diff total monthly cost | {format_money(summary['diff_total_monthly_cost'], signed=True)} |",
+        "",
+    ]
+    rows = summary["resources"][:limit]
+    if rows:
+        lines.extend(["| Resource | Monthly |", "| --- | ---: |"])
+        for item in rows:
+            lines.append(f"| `{item['name']}` | {format_money(item['monthly_cost'])} |")
+        lines.append("")
+    lines.append(f"Terraform plan JSON: `{summary['plan']}`")
+    return "\n".join(lines)
+
+
+async def run_analyze(args: argparse.Namespace) -> int:
+    settings = settings_from_args(args)
+    plan_value = getattr(args, "plan", None)
+    if plan_value:
+        plan_path = Path(plan_value).expanduser()
+    else:
+        plan_path = discover_plan_path(
+            Path(getattr(args, "path", ".")).expanduser(),
+            settings,
+            recursive=bool(getattr(args, "recursive", False)),
+        )
+        if plan_path is None:
+            print(
+                "No Terraform plan JSON found. Pass --plan, or run `cloudcost` to generate one automatically.",
+                file=sys.stderr,
+            )
+            return 1
+
+    if not plan_path.exists():
+        print(f"Plan file not found: {plan_path}", file=sys.stderr)
+        return 1
+
+    try:
+        estimate = await InfracostClient(settings).estimate_plan_json(
+            plan_path.read_bytes(),
+            filename=plan_path.name,
+        )
+    except Exception as exc:
+        print(f"CloudCost could not estimate the plan: {exc}", file=sys.stderr)
+        return 1
+
+    summary = estimate_summary(estimate, plan_path)
+
+    if args.format == "json":
+        output = json.dumps(summary, indent=2)
+    elif args.format == "markdown":
+        output = markdown_report(summary, limit=args.limit)
+    else:
+        output = terminal_report(summary, limit=args.limit)
+
+    if args.out:
+        Path(args.out).expanduser().write_text(output + "\n", encoding="utf-8")
+    else:
+        print(output)
+
+    if args.fail_on_increase is not None:
+        diff = to_decimal(summary["diff_total_monthly_cost"]) or Decimal("0")
+        threshold = Decimal(str(args.fail_on_increase))
+        if diff > threshold:
+            print(
+                f"Cost increase {format_money(diff, signed=True)} exceeds threshold {format_money(threshold)}.",
+                file=sys.stderr,
+            )
+            return 2
+    return 0
+
+
+async def run_one_command(args: argparse.Namespace) -> int:
+    settings = settings_from_args(args)
+    root = Path(getattr(args, "path", ".")).expanduser()
+    plan_value = getattr(args, "plan", None)
+    plan_path = Path(plan_value).expanduser() if plan_value else None
+
+    if plan_path is None:
+        plan_path = discover_plan_path(
+            root,
+            settings,
+            recursive=bool(getattr(args, "recursive", False)),
+        )
+        if plan_path:
+            print(f"Using Terraform plan JSON: {plan_path}", file=sys.stderr)
+
+    if plan_path is None and not getattr(args, "no_terraform", False):
+        try:
+            plan_path = generate_terraform_plan_json(args, root)
+            if plan_path:
+                print(f"Generated Terraform plan JSON: {plan_path}", file=sys.stderr)
+        except Exception as exc:
+            print(f"CloudCost could not generate a Terraform plan: {exc}", file=sys.stderr)
+            return 1
+
+    if plan_path is None:
+        print(
+            "No Terraform plan JSON found and Terraform could not be auto-run.",
+            file=sys.stderr,
+        )
+        print(
+            "From a Terraform project, run `cloudcost`, or pass an existing file with `cloudcost --plan tfplan.json`.",
+            file=sys.stderr,
+        )
+        return 1
+
+    args.plan = str(plan_path)
+    return await run_analyze(args)
+
+
+def run_connect_github(args: argparse.Namespace) -> int:
+    install_url = github_install_url(args)
+    repo = getattr(args, "repo", None) or detect_github_repo(Path(getattr(args, "path", ".")))
+
+    print("CloudCost GitHub automation")
+    print("")
+    print(f"Install URL: {install_url}")
+    if repo:
+        print(f"Detected repository: {repo}")
+        print("When GitHub opens, choose that repository for installation.")
+    else:
+        print("When GitHub opens, choose the repository that should receive CloudCost PR comments.")
+    print("")
+    print("Permissions GitHub will ask for:")
+    print("  contents: read")
+    print("  metadata: read")
+    print("  issues: write")
+    print("  pull_requests: write")
+    print("  events: pull_request")
+
+    if getattr(args, "no_open", False):
+        return 0
+
+    if webbrowser.open(install_url):
+        print("")
+        print("Opened the GitHub App install flow in your browser.")
+        return 0
+
+    print("")
+    print("Could not open a browser automatically. Open the Install URL above.")
+    return 0
+
+
+async def run_go(args: argparse.Namespace) -> int:
+    print("CloudCost go")
+    print("")
+    estimate_code = 0
+    if not getattr(args, "skip_estimate", False):
+        estimate_code = await run_one_command(args)
+        print("")
+        if estimate_code != 0:
+            print("Local estimate did not complete. You can still connect GitHub automation.")
+            if getattr(args, "require_estimate", False):
+                return estimate_code
+
+    return run_connect_github(args)
+
+
+def run_setup(args: argparse.Namespace) -> int:
+    payload = read_config()
+    if args.backend_url:
+        payload["backend_url"] = args.backend_url.rstrip("/")
+    if args.pricing_api_endpoint:
+        payload["pricing_api_endpoint"] = args.pricing_api_endpoint.rstrip("/")
+    if args.infracost_cli_path:
+        payload["infracost_cli_path"] = args.infracost_cli_path
+    if args.infracost_mode:
+        payload["infracost_mode"] = args.infracost_mode
+
+    path = write_config(payload)
+    print(f"CloudCost config written to {path}")
+    print("")
+    print("Try your first estimate:")
+    print("  cd path/to/terraform-project")
+    print("  cloudcost")
+    return 0
+
+
+def run_doctor(args: argparse.Namespace) -> int:
+    settings = settings_from_args(args)
+    config = read_config()
+    cli_path = Path(settings.infracost_cli_path)
+    cli_found = cli_path.exists() or shutil.which(settings.infracost_cli_path) is not None
+
+    checks = [
+        ("config", "found" if config else "missing", str(config_path())),
+        ("infracost_cli", "ready" if cli_found else "missing", settings.infracost_cli_path),
+        (
+            "pricing_api",
+            "configured" if settings.infracost_pricing_api_endpoint else "missing",
+            settings.infracost_pricing_api_endpoint or "set INFRACOST_PRICING_API_ENDPOINT",
+        ),
+        ("mode", settings.infracost_mode, "cli is recommended for local plan JSON"),
+    ]
+
+    print("CloudCost doctor")
+    print("")
+    for label, state, detail in checks:
+        print(f"{label:<14} {state:<12} {detail}")
+    return 0 if cli_found else 1
+
+
+def add_estimate_options(parser: argparse.ArgumentParser, *, plan_required: bool) -> None:
+    parser.add_argument("--plan", required=plan_required, help="Path to Terraform plan JSON.")
+    parser.add_argument("--format", choices=["terminal", "json", "markdown"], default="terminal")
+    parser.add_argument("--out", help="Write output to a file instead of stdout.")
+    parser.add_argument("--limit", type=int, default=12, help="Number of resources to show.")
+    parser.add_argument(
+        "--fail-on-increase",
+        type=Decimal,
+        help="Exit 2 if monthly increase is above this amount.",
+    )
+    parser.add_argument("--infracost-cli-path", help="Path to the infracost binary.")
+    parser.add_argument("--pricing-api-endpoint", help="Infracost pricing API endpoint.")
+    parser.add_argument("--infracost-mode", choices=["cli", "api"])
+    parser.add_argument("--infracost-api-key", help="Infracost or CloudCost pricing API key.")
+
+
+def add_one_command_options(parser: argparse.ArgumentParser) -> None:
+    add_estimate_options(parser, plan_required=False)
+    parser.add_argument(
+        "--path",
+        default=".",
+        help="Terraform project directory to scan or run from. Defaults to the current directory.",
+    )
+    parser.add_argument(
+        "--recursive",
+        action="store_true",
+        help="Search child directories for an existing Terraform plan JSON.",
+    )
+    parser.add_argument(
+        "--no-terraform",
+        action="store_true",
+        help="Do not auto-run terraform when no plan JSON is found.",
+    )
+    parser.add_argument("--terraform-bin", default="terraform", help="Terraform executable path.")
+    parser.add_argument(
+        "--skip-terraform-init",
+        action="store_true",
+        help="Skip automatic terraform init when .terraform is missing.",
+    )
+    parser.add_argument(
+        "--terraform-timeout",
+        type=int,
+        default=600,
+        help="Seconds to allow each terraform command.",
+    )
+
+
+def add_github_connect_options(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--backend-url",
+        help=(
+            "CloudCost backend URL that hosts /install/github. Defaults to saved config, "
+            "CLOUDCOST_BACKEND_URL, PUBLIC_BASE_URL, or https://cloudcost.live."
+        ),
+    )
+    parser.add_argument(
+        "--path",
+        default=".",
+        help="Repository directory used to detect the GitHub remote. Defaults to the current directory.",
+    )
+    parser.add_argument("--repo", help="Repository hint to show after opening GitHub, for example acme/infra.")
+    parser.add_argument("--no-open", action="store_true", help="Print the install URL without opening a browser.")
+
+
+def add_go_options(parser: argparse.ArgumentParser) -> None:
+    add_one_command_options(parser)
+    parser.add_argument(
+        "--backend-url",
+        help=(
+            "CloudCost backend URL that hosts /install/github. Defaults to saved config, "
+            "CLOUDCOST_BACKEND_URL, PUBLIC_BASE_URL, or https://cloudcost.live."
+        ),
+    )
+    parser.add_argument("--repo", help="Repository hint to show after opening GitHub, for example acme/infra.")
+    parser.add_argument("--no-open", action="store_true", help="Print the install URL without opening a browser.")
+    parser.add_argument(
+        "--skip-estimate",
+        action="store_true",
+        help="Skip the local estimate and only open the GitHub App install flow.",
+    )
+    parser.add_argument(
+        "--require-estimate",
+        action="store_true",
+        help="Stop before GitHub install if the local estimate fails.",
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="cloudcost",
+        description=(
+            "CloudCost AI CLI. Run `cloudcost` in a Terraform project for the one-command "
+            "cost estimate path."
+        ),
+    )
+    parser.add_argument("--version", action="version", version=f"cloudcost {VERSION}")
+    add_one_command_options(parser)
+    parser.set_defaults(func=lambda parsed: asyncio.run(run_one_command(parsed)))
+    subparsers = parser.add_subparsers(dest="command")
+
+    run_parser = subparsers.add_parser(
+        "run",
+        help="One-command path: find or generate Terraform plan JSON, then estimate it.",
+    )
+    add_one_command_options(run_parser)
+    run_parser.set_defaults(func=lambda parsed: asyncio.run(run_one_command(parsed)))
+
+    go_parser = subparsers.add_parser(
+        "go",
+        help="Run the local estimate, then open the GitHub App install flow.",
+    )
+    add_go_options(go_parser)
+    go_parser.set_defaults(func=lambda parsed: asyncio.run(run_go(parsed)))
+
+    connect_parser = subparsers.add_parser(
+        "connect-github",
+        help="Open the GitHub App manifest install flow for this CloudCost backend.",
+    )
+    add_github_connect_options(connect_parser)
+    connect_parser.set_defaults(func=run_connect_github)
+
+    setup_parser = subparsers.add_parser("setup", help="Write local CloudCost CLI configuration.")
+    setup_parser.add_argument("--backend-url", help="CloudCost backend URL, for example https://cloudcost.live.")
+    setup_parser.add_argument("--pricing-api-endpoint", help="Infracost pricing API endpoint.")
+    setup_parser.add_argument("--infracost-cli-path", help="Path to the infracost binary.")
+    setup_parser.add_argument("--infracost-mode", choices=["cli", "api"], default="cli")
+    setup_parser.set_defaults(func=run_setup)
+
+    doctor_parser = subparsers.add_parser("doctor", help="Check local CLI prerequisites.")
+    doctor_parser.add_argument("--infracost-cli-path", help="Path to the infracost binary.")
+    doctor_parser.add_argument("--pricing-api-endpoint", help="Infracost pricing API endpoint.")
+    doctor_parser.add_argument("--infracost-mode", choices=["cli", "api"])
+    doctor_parser.add_argument("--infracost-api-key", help="Infracost or CloudCost pricing API key.")
+    doctor_parser.set_defaults(func=run_doctor)
+
+    analyze_parser = subparsers.add_parser("analyze", help="Estimate a Terraform plan JSON file.")
+    add_estimate_options(analyze_parser, plan_required=False)
+    analyze_parser.add_argument(
+        "--path",
+        default=".",
+        help="Directory to scan when --plan is omitted. Defaults to the current directory.",
+    )
+    analyze_parser.add_argument(
+        "--recursive",
+        action="store_true",
+        help="Search child directories when --plan is omitted.",
+    )
+    analyze_parser.set_defaults(func=lambda parsed: asyncio.run(run_analyze(parsed)))
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())