pipu-cli 0.1.dev7__py3-none-any.whl → 0.2.0__py3-none-any.whl

pipu_cli/cli.py

@@ -1,905 +1,955 @@
+"""CLI interface for pipu using rich_click."""
+
+import json
+import logging
 import sys
-from typing import List
+import time
+from typing import Optional
+
 import rich_click as click
-from .internals import list_outdated
-from .package_constraints import (
-    read_constraints,
-    read_ignores,
-    read_invalidation_triggers,
-    _get_constraint_invalid_when,
-    _set_constraint_invalid_when
+from rich.console import Console
+from rich.logging import RichHandler
+from rich.progress import Progress, SpinnerColumn, TextColumn, BarColumn, TaskProgressColumn
+from rich.table import Table
+
+from pipu_cli.package_management import (
+    inspect_installed_packages,
+    get_latest_versions,
+    get_latest_versions_parallel,
+    resolve_upgradable_packages,
+    resolve_upgradable_packages_with_reasons,
+    install_packages,
+)
+from pipu_cli.pretty import (
+    print_upgradable_packages_table,
+    print_upgrade_results,
+    print_blocked_packages_table,
+    ConsoleStream,
+    select_packages_interactively,
+)
+from pipu_cli.output import JsonOutputFormatter
+from pipu_cli.config_file import load_config, get_config_value
+from pipu_cli.config import DEFAULT_CACHE_TTL
+from pipu_cli.cache import (
+    is_cache_fresh,
+    load_cache,
+    save_cache,
+    build_cache_from_results,
+    get_cache_info,
+    format_cache_age,
+    get_cache_age_seconds,
+    clear_cache,
+    clear_all_caches,
 )
-from .common import console
-from pip._internal.commands.install import InstallCommand
 
 
-def _install_packages(package_names: List[str], packages_being_updated: List[str] | None = None) -> int:
-    """
-    Install packages using pip API with filtered constraints.
+# Configure rich_click
+click.rich_click.USE_RICH_MARKUP = True
+click.rich_click.SHOW_ARGUMENTS = True
+click.rich_click.GROUP_ARGUMENTS_OPTIONS = True
 
-    :param package_names: List of package names to install
-    :param packages_being_updated: List of package names being updated (to exclude from constraints)
-    :returns: Exit code (0 for success, non-zero for failure)
-    """
-    import tempfile
-    import os
-    from packaging.utils import canonicalize_name
-
-    # If packages_being_updated not provided, use package_names
-    if packages_being_updated is None:
-        packages_being_updated = package_names
-
-    # Get all current constraints and filter out packages being updated
-    from .package_constraints import read_constraints
-    all_constraints = read_constraints()
-
-    # Get canonical names of packages being updated
-    packages_being_updated_canonical = {canonicalize_name(pkg) for pkg in packages_being_updated}
-
-    # Filter out constraints for packages being updated to avoid conflicts
-    filtered_constraints = {
-        pkg: constraint
-        for pkg, constraint in all_constraints.items()
-        if pkg not in packages_being_updated_canonical
-    }
-
-    # Create a temporary constraints file if there are any constraints to apply
-    constraint_file_path = None
-    try:
-        if filtered_constraints:
-            with tempfile.NamedTemporaryFile(mode='w', suffix='.txt', delete=False) as f:
-                constraint_file_path = f.name
-                for pkg, constraint in filtered_constraints.items():
-                    f.write(f"{pkg}{constraint}\n")
-
-            # Set environment variable for pip to use the filtered constraints
-            os.environ['PIP_CONSTRAINT'] = constraint_file_path
-            console.print(f"[dim]Using filtered constraints (excluding {len(packages_being_updated_canonical)} package(s) being updated)[/dim]")
-
-        install_cmd = InstallCommand("install", "Install packages")
-        install_args = ["--upgrade"] + package_names
-        return install_cmd.main(install_args)
-
-    finally:
-        # Clean up: remove the constraint file and unset environment variable
-        if constraint_file_path:
-            if 'PIP_CONSTRAINT' in os.environ:
-                del os.environ['PIP_CONSTRAINT']
-            if os.path.exists(constraint_file_path):
-                try:
-                    os.unlink(constraint_file_path)
-                except Exception:
-                    pass  # Best effort cleanup
-
-
-def launch_tui() -> None:
-    """
-    Launch the main TUI interface.
-    """
-    try:
-        # Check for invalid constraints and triggers from removed/renamed packages
-        from .package_constraints import cleanup_invalid_constraints_and_triggers
-        _, _, cleanup_summary = cleanup_invalid_constraints_and_triggers()
-        if cleanup_summary:
-            console.print(f"[yellow]🧹 {cleanup_summary}[/yellow]")
-            console.print("[dim]Press any key to continue...[/dim]")
-            input()  # Wait for user acknowledgment before launching TUI
-
-        from .ui import main_tui_app
-        main_tui_app()
-    except Exception as e:
-        console.print(f"[red]Error launching TUI: {e}[/red]")
-        sys.exit(1)
 
+def parse_package_spec(spec: str) -> tuple[str, Optional[str]]:
+    """Parse a package specification like 'requests==2.31.0' or 'requests>=2.30'.
+
+    :param spec: Package specification string
+    :returns: Tuple of (package_name, version_constraint or None)
+    """
+    # Common specifier patterns (check longest operators first to avoid partial matches)
+    for op in ['==', '>=', '<=', '~=', '!=', '>', '<']:
+        if op in spec:
+            parts = spec.split(op, 1)
+            return (parts[0].strip(), op + parts[1].strip())
 
+    return (spec.strip(), None)
 
 
 @click.group(invoke_without_command=True)
 @click.pass_context
-def cli(ctx):
+def cli(ctx: click.Context) -> None:
     """
-    pipu - Python package updater with constraint management
+    [bold cyan]pipu[/bold cyan] - A cute Python package updater
 
-    If no command is specified, launches the interactive TUI.
-    """
-    if ctx.invoked_subcommand is None:
-        # No subcommand was invoked, launch the TUI
-        launch_tui()
+    Automatically checks for package updates and upgrades them with proper
+    constraint resolution.
 
+    [bold]Commands:[/bold]
+      pipu update      Refresh package version cache
+      pipu upgrade     Upgrade packages (default command)
+      pipu rollback    Restore packages to a previous state
 
-@cli.command(name='list')
-@click.option('--pre', is_flag=True, help='Include pre-release versions (alpha, beta, rc, dev)')
-@click.option('--debug', is_flag=True, help='Print debug information as packages are checked')
-def list_packages(pre, debug):
-    """
-    List outdated packages
-
-    Displays a formatted table of installed packages that have newer versions
-    available on the configured package indexes. By default, pre-release versions
-    are excluded unless --pre is specified.
+    Run [cyan]pipu <command> --help[/cyan] for command-specific help.
     """
-    try:
-        # Check for invalid constraints and triggers from removed/renamed packages
-        from .package_constraints import cleanup_invalid_constraints_and_triggers
-        _, _, cleanup_summary = cleanup_invalid_constraints_and_triggers()
-        if cleanup_summary:
-            console.print(f"[yellow]🧹 {cleanup_summary}[/yellow]")
-
-        # Read constraints, ignores, and invalidation triggers from configuration
-        constraints = read_constraints()
-        ignores = read_ignores()
-        invalidation_triggers = read_invalidation_triggers()
-
-        # Set up debug callbacks if debug mode is enabled
-        progress_callback = None
-        result_callback = None
-        if debug:
-            def debug_progress(package_name):
-                console.print(f"[dim]DEBUG: Checking {package_name}...[/dim]")
-
-            def debug_callback(package_result):
-                pkg_name = package_result.get('name', 'unknown')
-                current_ver = package_result.get('version', 'unknown')
-                latest_ver = package_result.get('latest_version', 'unknown')
-                if current_ver != latest_ver:
-                    console.print(f"[dim]DEBUG: {pkg_name}: {current_ver} -> {latest_ver}[/dim]")
-                else:
-                    console.print(f"[dim]DEBUG: {pkg_name}: {current_ver} (up-to-date)[/dim]")
-
-            progress_callback = debug_progress
-            result_callback = debug_callback
-
-        # Use the internals function to get outdated packages and print the table
-        outdated_packages = list_outdated(
-            console=console,
-            print_table=True,
-            constraints=constraints,
-            ignores=ignores,
-            pre=pre,
-            progress_callback=progress_callback,
-            result_callback=result_callback,
-            invalidation_triggers=invalidation_triggers
-        )
-
-        # The function already prints the table, so we just return the data
-        return outdated_packages
-
-    except Exception as e:
-        console.print(f"[red]Unexpected error: {e}[/red]")
-        sys.exit(1)
+    # If no subcommand provided, default to upgrade
+    if ctx.invoked_subcommand is None:
+        ctx.invoke(upgrade)
 
 
 @cli.command()
-@click.option('--pre', is_flag=True, help='Include pre-release versions (alpha, beta, rc, dev)')
-@click.option('-y', '--yes', is_flag=True, help='Skip confirmation prompt and install all updates')
-def update(pre, yes):
+@click.option(
+    "--timeout",
+    type=int,
+    default=10,
+    help="Network timeout in seconds for package queries"
+)
+@click.option(
+    "--pre",
+    is_flag=True,
+    help="Include pre-release versions"
+)
+@click.option(
+    "--parallel",
+    type=int,
+    default=1,
+    help="Number of parallel requests for version checking (default: 1)"
+)
+@click.option(
+    "--debug",
+    is_flag=True,
+    help="Enable debug logging"
+)
+@click.option(
+    "--output",
+    type=click.Choice(["human", "json"]),
+    default="human",
+    help="Output format (human-readable or json)"
+)
+def update(timeout: int, pre: bool, parallel: int, debug: bool, output: str) -> None:
     """
-    Update outdated packages
+    Refresh the package version cache.
 
-    Lists all outdated packages and prompts for confirmation before installing
-    updates. Respects version constraints from configuration files.
+    Fetches the latest version information from PyPI for all installed
+    packages and stores it locally. This speeds up subsequent upgrade
+    commands by avoiding repeated network requests.
 
-    For interactive package selection, run 'pipu' with no arguments to launch the TUI.
+    [bold]Examples:[/bold]
+      pipu update              Update cache with defaults
+      pipu update --parallel 4 Update with parallel requests
+      pipu update --pre        Include pre-release versions
     """
-    try:
-        # Check for invalid constraints and triggers from removed/renamed packages
-        from .package_constraints import cleanup_invalid_constraints_and_triggers
-        _, _, cleanup_summary = cleanup_invalid_constraints_and_triggers()
-        if cleanup_summary:
-            console.print(f"[yellow]🧹 {cleanup_summary}[/yellow]")
-
-        # Read constraints, ignores, and invalidation triggers from configuration
-        constraints = read_constraints()
-        ignores = read_ignores()
-        invalidation_triggers = read_invalidation_triggers()
-
-        # Get outdated packages
-        outdated_packages = list_outdated(
-            console=console, print_table=True, constraints=constraints, ignores=ignores, pre=pre, invalidation_triggers=invalidation_triggers
+    console = Console()
+
+    # Load configuration file
+    config = load_config()
+    if timeout == 10:
+        timeout = get_config_value(config, 'timeout', 10)
+    if not pre:
+        pre = get_config_value(config, 'pre', False)
+    if not debug:
+        debug = get_config_value(config, 'debug', False)
+    if parallel == 1:
+        parallel = get_config_value(config, 'parallel', 1)
+
+    # Configure logging
+    if debug and output != "json":
+        logging.basicConfig(
+            level=logging.DEBUG,
+            format='%(message)s',
+            handlers=[RichHandler(console=console, show_time=False, show_path=False, markup=True)]
         )
+        logging.getLogger('pip._internal').setLevel(logging.WARNING)
+        logging.getLogger('pip._vendor').setLevel(logging.WARNING)
+        console.print("[dim]Debug mode enabled[/dim]\n")
 
-        if not outdated_packages:
-            console.print("[green]All packages are already up to date![/green]")
-            return
-
-        # Determine which packages to update
-        packages_to_update = outdated_packages
-
-        if not yes:
-            # Standard confirmation mode
-            console.print()
-            response = click.confirm("Do you want to update these packages?", default=False)
-            if not response:
-                console.print("[yellow]Update cancelled.[/yellow]")
-                return
-
-        # Validate constraint compatibility before installation
-        console.print()
-        console.print("[bold blue]Validating constraint compatibility...[/bold blue]")
-
-        from .package_constraints import validate_package_installation, get_constraint_violation_summary
-
-        # Extract package names for validation
-        package_names_to_install = [pkg['name'] for pkg in packages_to_update]
-
-        # Check for constraint violations
-        safe_packages, invalidated_constraints = validate_package_installation(package_names_to_install)
-
-        if invalidated_constraints:
-            # Show constraint violations
-            console.print("[bold red]⚠ Constraint Violations Detected![/bold red]")
-            console.print(get_constraint_violation_summary(invalidated_constraints))
-
-            # Filter out packages that would violate constraints
-            violating_package_names = set()
-            for violators in invalidated_constraints.values():
-                violating_package_names.update(pkg.lower() for pkg in violators)
-
-            # Keep only safe packages
-            original_count = len(packages_to_update)
-            packages_to_update = [
-                pkg for pkg in packages_to_update
-                if pkg['name'].lower() not in violating_package_names
-            ]
-
-            blocked_count = original_count - len(packages_to_update)
-
-            if packages_to_update:
-                console.print(f"\n[yellow]Proceeding with {len(packages_to_update)} packages that don't violate constraints.")
-                console.print(f"Blocked {blocked_count} packages due to constraint violations.[/yellow]")
+    try:
+        # Step 1: Inspect installed packages
+        if output != "json":
+            console.print("[bold]Step 1/3:[/bold] Inspecting installed packages...")
+
+        step1_start = time.time()
+        if output != "json":
+            with Progress(
+                SpinnerColumn(),
+                TextColumn("[progress.description]{task.description}"),
+                console=console,
+                transient=True
+            ) as progress:
+                task = progress.add_task("Loading packages...", total=None)
+                installed_packages = inspect_installed_packages(timeout=timeout)
+                progress.update(task, completed=True)
+        else:
+            installed_packages = inspect_installed_packages(timeout=timeout)
+        step1_time = time.time() - step1_start
+
+        num_installed = len(installed_packages)
+        if output != "json":
+            console.print(f"  Found {num_installed} installed packages")
+            if debug:
+                console.print(f"  [dim]Time: {step1_time:.2f}s[/dim]")
+
+        if not installed_packages:
+            if output == "json":
+                print('{"error": "No packages found"}')
             else:
-                console.print(f"\n[red]All {blocked_count} packages would violate constraints. No packages will be installed.[/red]")
-                return
-
-        # Install updates
-        console.print()
-        console.print("[bold green]Installing updates...[/bold green]")
-
-        # Create list of package names to install
-        # Use --upgrade without version pinning to allow pip's dependency resolver
-        # to handle interdependent packages (e.g., pydantic and pydantic-core)
-        package_names = [package['name'] for package in packages_to_update]
-
-        # Install packages using pip API with filtered constraints
-        exit_code = _install_packages(package_names, packages_being_updated=package_names)
+                console.print("[yellow]No packages found.[/yellow]")
+            sys.exit(0)
+
+        # Step 2: Check for updates
+        if output != "json":
+            console.print("\n[bold]Step 2/3:[/bold] Fetching latest versions...")
+
+        step2_start = time.time()
+        if output != "json":
+            with Progress(
+                TextColumn("[progress.description]{task.description}"),
+                BarColumn(),
+                TaskProgressColumn(),
+                console=console,
+                transient=True
+            ) as progress:
+                task = progress.add_task("Checking packages...", total=len(installed_packages))
+
+                def update_progress(current, total):
+                    progress.update(task, completed=current)
+
+                if parallel > 1:
+                    latest_versions = get_latest_versions_parallel(
+                        installed_packages, timeout=timeout, include_prereleases=pre,
+                        max_workers=parallel, progress_callback=update_progress
+                    )
+                else:
+                    latest_versions = get_latest_versions(
+                        installed_packages, timeout=timeout, include_prereleases=pre,
+                        progress_callback=update_progress
+                    )
+        else:
+            if parallel > 1:
+                latest_versions = get_latest_versions_parallel(
+                    installed_packages, timeout=timeout, include_prereleases=pre, max_workers=parallel
+                )
+            else:
+                latest_versions = get_latest_versions(
+                    installed_packages, timeout=timeout, include_prereleases=pre
+                )
+        step2_time = time.time() - step2_start
+
+        num_updates = len(latest_versions)
+        if output != "json":
+            console.print(f"  Found {num_updates} packages with newer versions available")
+            if debug:
+                console.print(f"  [dim]Time: {step2_time:.2f}s[/dim]")
+
+        # Step 3: Resolve and cache
+        if output != "json":
+            console.print("\n[bold]Step 3/3:[/bold] Resolving constraints and saving cache...")
+
+        step3_start = time.time()
+        all_upgradable = resolve_upgradable_packages(latest_versions, installed_packages)
+        upgradable_packages = [pkg for pkg in all_upgradable if pkg.upgradable]
+        step3_time = time.time() - step3_start
+
+        # Build and save cache
+        cache_data = build_cache_from_results(installed_packages, latest_versions, upgradable_packages)
+        cache_path = save_cache(cache_data)
+
+        num_upgradable = len(upgradable_packages)
+
+        if output == "json":
+            result = {
+                "status": "success",
+                "packages_checked": num_installed,
+                "packages_with_updates": num_updates,
+                "packages_upgradable": num_upgradable,
+                "cache_path": str(cache_path)
+            }
+            print(json.dumps(result, indent=2))
+        else:
+            console.print(f"  {num_upgradable} packages can be safely upgraded")
+            if debug:
+                console.print(f"  [dim]Time: {step3_time:.2f}s[/dim]")
+                console.print(f"  [dim]Cache saved to: {cache_path}[/dim]")
 
-        if exit_code == 0:
-            console.print("[bold green]✓ All packages updated successfully![/bold green]")
+            console.print("\n[bold green]Package list updated![/bold green] Run [cyan]pipu upgrade[/cyan] to upgrade your packages.")
 
-            # Clean up constraints whose invalidation triggers have been satisfied
-            from .package_constraints import post_install_cleanup
-            post_install_cleanup(console)
+            total_time = step1_time + step2_time + step3_time
+            if debug:
+                console.print(f"[dim]Total time: {total_time:.2f}s[/dim]")
 
-        else:
-            console.print("[bold red]✗ Some packages failed to update.[/bold red]")
-            sys.exit(exit_code)
+        sys.exit(0)
 
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Interrupted by user.[/yellow]")
+        sys.exit(130)
     except Exception as e:
-        console.print(f"[red]Unexpected error: {e}[/red]")
+        if output == "json":
+            print(json.dumps({"error": str(e)}))
+        else:
+            console.print(f"\n[bold red]Error:[/bold red] {e}")
         sys.exit(1)
 
 
 @cli.command()
-@click.argument('constraint_specs', nargs=-1, required=False)
-@click.option('--env', help='Target environment section (defaults to current environment or global)')
-@click.option('--list', 'list_constraints', is_flag=True, help='List existing constraints for specified environment (or all environments if no --env specified)')
-@click.option('--remove', 'remove_constraints', is_flag=True, help='Remove constraints for specified packages')
-@click.option('--remove-all', 'remove_all_constraints', is_flag=True, help='Remove all constraints from specified environment (or all environments if no --env specified)')
-@click.option('--yes', '-y', 'skip_confirmation', is_flag=True, help='Skip confirmation prompt')
-@click.option('--invalidates-when', 'invalidation_triggers', multiple=True, help='Specify trigger conditions that invalidate this constraint (format: "package>=version" or "package>version"). Only ">=" and ">" operators allowed.')
-def constrain(constraint_specs, env, list_constraints, remove_constraints, remove_all_constraints, skip_confirmation, invalidation_triggers):
-    """
-    Add or update package constraints in pip configuration
-
-    Sets version constraints for packages in the pip configuration file.
-    Constraints prevent packages from being updated beyond specified versions.
-
-    Note: Automatic constraints from installed packages are now discovered
-    on every pipu execution and do not need to be manually added. The constraints
-    you add here will override any automatic constraints.
-
-    \b
-    Examples:
-        pipu constrain "requests==2.31.0"
-        pipu constrain "numpy>=1.20.0" "pandas<2.0.0"
-        pipu constrain "django~=4.1.0" --env production
-        pipu constrain "flask<2" --invalidates-when "other_package>=1" --invalidates-when "another_package>1.5"
-        pipu constrain --list
-        pipu constrain --list --env production
-        pipu constrain --remove requests numpy
-        pipu constrain --remove django --env production
-        pipu constrain --remove-all --env production
-        pipu constrain --remove-all --yes
-
-    \f
-    :param constraint_specs: One or more constraint specifications or package names (for --remove)
-    :param env: Target environment section name
-    :param list_constraints: List existing constraints instead of adding new ones
-    :param remove_constraints: Remove constraints for specified packages
-    :param remove_all_constraints: Remove all constraints from environment(s)
-    :param skip_confirmation: Skip confirmation prompt for --remove-all
-    :raises SystemExit: Exits with code 1 if an error occurs
+@click.argument('packages', nargs=-1)
+@click.option(
+    "--timeout",
+    type=int,
+    default=10,
+    help="Network timeout in seconds for package queries"
+)
+@click.option(
+    "--pre",
+    is_flag=True,
+    help="Include pre-release versions"
+)
+@click.option(
+    "--yes", "-y",
+    is_flag=True,
+    help="Automatically confirm upgrade without prompting"
+)
+@click.option(
+    "--debug",
+    is_flag=True,
+    help="Enable debug logging and show performance timing"
+)
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    help="Show what would be upgraded without actually upgrading"
+)
+@click.option(
+    "--exclude",
+    type=str,
+    default="",
+    help="Comma-separated list of packages to exclude from upgrade"
+)
+@click.option(
+    "--show-blocked",
+    is_flag=True,
+    help="Show packages that cannot be upgraded and why"
+)
+@click.option(
+    "--output",
+    type=click.Choice(["human", "json"]),
+    default="human",
+    help="Output format (human-readable or json)"
+)
+@click.option(
+    "--update-requirements",
+    type=click.Path(exists=True),
+    default=None,
+    help="Update the specified requirements.txt file with new versions"
+)
+@click.option(
+    "--parallel",
+    type=int,
+    default=1,
+    help="Number of parallel requests for version checking (default: 1)"
+)
+@click.option(
+    "--interactive", "-i",
+    is_flag=True,
+    help="Interactively select packages to upgrade"
+)
+@click.option(
+    "--no-cache",
+    is_flag=True,
+    help="Skip cache and fetch fresh version data"
+)
+@click.option(
+    "--cache-ttl",
+    type=int,
+    default=None,
+    help=f"Cache freshness threshold in seconds (default: {DEFAULT_CACHE_TTL})"
+)
+def upgrade(packages: tuple[str, ...], timeout: int, pre: bool, yes: bool, debug: bool, dry_run: bool,
+            exclude: str, show_blocked: bool, output: str, update_requirements: Optional[str],
+            parallel: int, interactive: bool, no_cache: bool, cache_ttl: Optional[int]) -> None:
     """
-    try:
-        # Validate mutually exclusive options
-        # Note: constraint_specs with --remove are package names, not constraint specs
-        has_constraint_specs_for_adding = bool(constraint_specs) and not (remove_constraints or remove_all_constraints)
-        active_options = [list_constraints, remove_constraints, remove_all_constraints, has_constraint_specs_for_adding]
-        if sum(active_options) > 1:
-            console.print("[red]Error: Cannot use --list, --remove, --remove-all, and constraint specs together. Use only one at a time.[/red]")
-            sys.exit(1)
+    Upgrade installed packages.
 
-        # Validate --invalidates-when can only be used when adding constraints
-        if invalidation_triggers and (list_constraints or remove_constraints or remove_all_constraints):
-            console.print("[red]Error: --invalidates-when cannot be used with --list, --remove, or --remove-all.[/red]")
-            sys.exit(1)
+    By default, upgrades all packages that have newer versions available.
+    Optionally specify PACKAGES to upgrade only those packages.
 
-        if invalidation_triggers and not has_constraint_specs_for_adding:
-            console.print("[red]Error: --invalidates-when can only be used when adding constraint specifications.[/red]")
-            sys.exit(1)
+    Uses cached version data if available and fresh. Run [cyan]pipu update[/cyan]
+    to refresh the cache manually.
 
-        # Handle --list option
-        if list_constraints:
-            from .package_constraints import list_all_constraints
-
-            console.print("[bold blue]Listing constraints from pip configuration...[/bold blue]")
+    [bold]Examples:[/bold]
+      pipu upgrade                    Upgrade all packages
+      pipu upgrade requests numpy     Upgrade specific packages
+      pipu upgrade --dry-run          Preview without installing
+      pipu upgrade -i                 Interactive package selection
+      pipu upgrade --no-cache         Force fresh version check
+    """
+    console = Console()
+
+    # Load configuration file
+    config = load_config()
+
+    # Apply config file values for options at defaults
+    if timeout == 10:
+        timeout = get_config_value(config, 'timeout', 10)
+    if not exclude:
+        exclude_list = get_config_value(config, 'exclude', [])
+        if exclude_list:
+            exclude = ','.join(exclude_list)
+    if not pre:
+        pre = get_config_value(config, 'pre', False)
+    if not yes:
+        yes = get_config_value(config, 'yes', False)
+    if not debug:
+        debug = get_config_value(config, 'debug', False)
+    if not dry_run:
+        dry_run = get_config_value(config, 'dry_run', False)
+    if not show_blocked:
+        show_blocked = get_config_value(config, 'show_blocked', False)
+    if output == "human":
+        output = get_config_value(config, 'output', 'human')
+    if cache_ttl is None:
+        cache_ttl = get_config_value(config, 'cache_ttl', DEFAULT_CACHE_TTL)
+
+    # Check if caching is enabled
+    cache_enabled = get_config_value(config, 'cache_enabled', True) and not no_cache
+
+    # Initialize JSON formatter if needed
+    json_formatter = JsonOutputFormatter() if output == "json" else None
+
+    # Interactive mode only works in human output mode
+    if interactive and output == "json":
+        console.print("[yellow]Warning: --interactive is not compatible with --output json. Ignoring --interactive.[/yellow]")
+        interactive = False
+
+    # Configure logging
+    if debug and output != "json":
+        logging.basicConfig(
+            level=logging.DEBUG,
+            format='%(message)s',
+            handlers=[RichHandler(console=console, show_time=False, show_path=False, markup=True)]
+        )
+        logging.getLogger('pip._internal').setLevel(logging.WARNING)
+        logging.getLogger('pip._vendor').setLevel(logging.WARNING)
+        console.print("[dim]Debug mode enabled[/dim]\n")
 
-            all_constraints = list_all_constraints(env)
+    try:
+        # Check cache freshness
+        effective_cache_ttl = DEFAULT_CACHE_TTL if cache_ttl is None else cache_ttl
+        use_cache = cache_enabled and is_cache_fresh(effective_cache_ttl)
+
+        if use_cache and output != "json":
+            cache_age = get_cache_age_seconds()
+            console.print(f"[dim]Using cached data ({format_cache_age(cache_age)})[/dim]\n")
+
+        # Step 1: Inspect installed packages
+        if output != "json":
+            console.print("[bold]Step 1/5:[/bold] Inspecting installed packages...")
+
+        step1_start = time.time()
+        if output != "json":
+            with Progress(
+                SpinnerColumn(),
+                TextColumn("[progress.description]{task.description}"),
+                console=console,
+                transient=True
+            ) as progress:
+                task = progress.add_task("Loading packages...", total=None)
+                installed_packages = inspect_installed_packages(timeout=timeout)
+                progress.update(task, completed=True)
+        else:
+            installed_packages = inspect_installed_packages(timeout=timeout)
+        step1_time = time.time() - step1_start
+
+        num_installed = len(installed_packages)
+        if output != "json":
+            console.print(f"  Found {num_installed} installed packages")
+            if debug:
+                console.print(f"  [dim]Time: {step1_time:.2f}s[/dim]")
+
+        if not installed_packages:
+            if output == "json":
+                print('{"error": "No packages found"}')
+            else:
+                console.print("[yellow]No packages found.[/yellow]")
+            sys.exit(0)
 
-            if not all_constraints:
-                if env:
-                    console.print(f"[yellow]No constraints found for environment '[bold]{env}[/bold]'.[/yellow]")
+        # Step 2: Check for updates (from cache or network)
+        if output != "json":
+            if use_cache:
+                console.print("\n[bold]Step 2/5:[/bold] Loading cached version data...")
+            else:
+                console.print("\n[bold]Step 2/5:[/bold] Checking for updates...")
+
+        step2_start = time.time()
+        latest_versions: dict = {}
+
+        if use_cache:
+            # Load from cache
+            cache_data = load_cache()
+            if cache_data and cache_data.packages:
+                # Reconstruct latest_versions from cache
+                # We need to fetch fresh for accurate constraint resolution
+                # Cache is mainly to avoid the slow PyPI queries
+                if output != "json":
+                    with Progress(
+                        TextColumn("[progress.description]{task.description}"),
+                        BarColumn(),
+                        TaskProgressColumn(),
+                        console=console,
+                        transient=True
+                    ) as progress:
+                        task = progress.add_task("Checking packages...", total=len(installed_packages))
+
+                        def update_progress(current, total):
+                            progress.update(task, completed=current)
+
+                        if parallel > 1:
+                            latest_versions = get_latest_versions_parallel(
+                                installed_packages, timeout=timeout, include_prereleases=pre,
+                                max_workers=parallel, progress_callback=update_progress
+                            )
+                        else:
+                            latest_versions = get_latest_versions(
+                                installed_packages, timeout=timeout, include_prereleases=pre,
+                                progress_callback=update_progress
+                            )
                 else:
-                    console.print("[yellow]No constraints found in any environment.[/yellow]")
-                return
-
-            # Display constraints
-            for env_name, constraints in all_constraints.items():
-                console.print(f"\n[bold cyan]Environment: {env_name}[/bold cyan]")
-                if constraints:
-                    for package, constraint_spec in sorted(constraints.items()):
-                        console.print(f"  {package}{constraint_spec}")
+                    if parallel > 1:
+                        latest_versions = get_latest_versions_parallel(
+                            installed_packages, timeout=timeout, include_prereleases=pre, max_workers=parallel
+                        )
+                    else:
+                        latest_versions = get_latest_versions(
+                            installed_packages, timeout=timeout, include_prereleases=pre
+                        )
+            else:
+                use_cache = False
+
+        if not use_cache:
+            # Fetch from network
+            if output != "json":
+                with Progress(
+                    TextColumn("[progress.description]{task.description}"),
+                    BarColumn(),
+                    TaskProgressColumn(),
+                    console=console,
+                    transient=True
+                ) as progress:
+                    task = progress.add_task("Checking packages...", total=len(installed_packages))
+
+                    def update_progress(current, total):
+                        progress.update(task, completed=current)
+
+                    if parallel > 1:
+                        latest_versions = get_latest_versions_parallel(
+                            installed_packages, timeout=timeout, include_prereleases=pre,
+                            max_workers=parallel, progress_callback=update_progress
+                        )
+                    else:
+                        latest_versions = get_latest_versions(
+                            installed_packages, timeout=timeout, include_prereleases=pre,
+                            progress_callback=update_progress
+                        )
+            else:
+                if parallel > 1:
+                    latest_versions = get_latest_versions_parallel(
+                        installed_packages, timeout=timeout, include_prereleases=pre, max_workers=parallel
+                    )
                 else:
-                    console.print("  [dim]No constraints[/dim]")
-
-            return
-
-        # Handle --remove option
-        if remove_constraints:
-            if not constraint_specs:
-                console.print("[red]Error: At least one package name must be specified for removal.[/red]")
-                sys.exit(1)
-
-            from .package_constraints import remove_constraints_from_config, parse_invalidation_triggers_storage, get_current_environment_name, parse_inline_constraints
-
-            package_names = list(constraint_specs)
-            console.print(f"[bold blue]Removing constraints for {len(package_names)} package(s)...[/bold blue]")
+                    latest_versions = get_latest_versions(
+                        installed_packages, timeout=timeout, include_prereleases=pre
+                    )
 
-            try:
-                config_path, removed_constraints, removed_triggers = remove_constraints_from_config(package_names, env)
+        step2_time = time.time() - step2_start
 
-                if not removed_constraints:
-                    console.print("[yellow]No constraints were removed (packages not found in constraints).[/yellow]")
-                    return
+        num_updates = len(latest_versions)
+        if output != "json":
+            console.print(f"  Found {num_updates} packages with newer versions available")
+            if debug:
+                console.print(f"  [dim]Time: {step2_time:.2f}s[/dim]")
 
-                # Triggers are already cleaned up by remove_constraints_from_config
-
-                # Display summary
-                console.print("\n[bold green]✓ Constraints removed successfully![/bold green]")
-                console.print(f"[bold]File:[/bold] {config_path}")
-
-                # Show removed constraints
-                console.print("\n[bold]Constraints removed:[/bold]")
-                for package, constraint_spec in removed_constraints.items():
-                    console.print(f"  [red]Removed[/red]: {package}{constraint_spec}")
+        if not latest_versions:
+            if output == "json":
+                print('{"upgradable": [], "upgradable_count": 0, "message": "All packages are up to date"}')
+            else:
+                console.print("\n[bold green]All packages are up to date![/bold green]")
+            sys.exit(0)
+
+        # Step 3: Resolve upgradable packages
+        if output != "json":
+            console.print("\n[bold]Step 3/5:[/bold] Resolving dependency constraints...")
+        step3_start = time.time()
+
+        if show_blocked:
+            upgradable_packages, blocked_packages = resolve_upgradable_packages_with_reasons(
+                latest_versions, installed_packages
+            )
+        else:
+            all_upgradable = resolve_upgradable_packages(latest_versions, installed_packages)
+            upgradable_packages = [pkg for pkg in all_upgradable if pkg.upgradable]
+            blocked_packages = []
+
+        step3_time = time.time() - step3_start
+
+        # Update cache with fresh data (if we fetched from network)
+        if not use_cache and cache_enabled:
+            cache_data = build_cache_from_results(installed_packages, latest_versions, upgradable_packages)
+            save_cache(cache_data)
+
+        # Apply exclusions
+        excluded_names = set()
+        if exclude:
+            excluded_names = {name.strip().lower() for name in exclude.split(',')}
+            if debug and excluded_names:
+                console.print(f"  [dim]Excluding: {', '.join(sorted(excluded_names))}[/dim]")
+
+        # Filter to only upgradable packages (excluding excluded ones)
+        can_upgrade = [pkg for pkg in upgradable_packages if pkg.name.lower() not in excluded_names]
+
+        # Parse package specifications and filter to specific packages if provided
+        package_constraints = {}
+        if packages:
+            requested_packages = set()
+            for spec in packages:
+                name, constraint = parse_package_spec(spec)
+                requested_packages.add(name.lower())
+                if constraint:
+                    package_constraints[name.lower()] = constraint
+
+            can_upgrade = [pkg for pkg in can_upgrade if pkg.name.lower() in requested_packages]
+
+            if debug:
+                console.print(f"  [dim]Filtering to: {', '.join(packages)}[/dim]")
+                if package_constraints:
+                    console.print(f"  [dim]Version constraints: {package_constraints}[/dim]")
+
+        if not can_upgrade:
+            if output == "json":
+                assert json_formatter is not None
+                json_data = json_formatter.format_all(
+                    upgradable=[],
+                    blocked=blocked_packages if show_blocked else None
+                )
+                print(json_data)
+            else:
+                console.print("\n[yellow]No packages can be upgraded (all blocked by constraints).[/yellow]")
+                if show_blocked and blocked_packages:
+                    console.print()
+                    print_blocked_packages_table(blocked_packages, console=console)
+            sys.exit(0)
+
+        num_upgradable = len(can_upgrade)
+        if output != "json":
+            console.print(f"  {num_upgradable} packages can be safely upgraded")
+            if debug:
+                console.print(f"  [dim]Time: {step3_time:.2f}s[/dim]")
+
+        # Step 4: Display table and ask for confirmation
+        if output == "json":
+            assert json_formatter is not None
+            if dry_run:
+                json_data = json_formatter.format_all(
+                    upgradable=can_upgrade,
+                    blocked=blocked_packages if show_blocked else None
+                )
+                print(json_data)
+                sys.exit(0)
+        else:
+            console.print("\n[bold]Step 4/5:[/bold] Packages ready for upgrade:\n")
+            print_upgradable_packages_table(can_upgrade, console=console)
 
-                # Show removed invalidation triggers if any
-                if removed_triggers:
-                    console.print("\n[bold]Invalidation triggers removed:[/bold]")
-                    for package, triggers in removed_triggers.items():
-                        for trigger in triggers:
-                            console.print(f"  [red]Removed trigger[/red]: {trigger}")
+            if show_blocked and blocked_packages:
+                console.print()
+                print_blocked_packages_table(blocked_packages, console=console)
 
-                # Show which environment was updated
-                if env:
-                    console.print(f"\n[bold cyan]Environment updated:[/bold cyan] {env}")
-                else:
-                    from .package_constraints import get_current_environment_name
-                    current_env = get_current_environment_name()
-                    if current_env and current_env != "global":
-                        console.print(f"\n[bold cyan]Environment updated:[/bold cyan] {current_env}")
-                    else:
-                        console.print("\n[bold cyan]Environment updated:[/bold cyan] global")
-
-                return
-
-            except ValueError as e:
-                console.print(f"[red]Error: {e}[/red]")
-                sys.exit(1)
-            except IOError as e:
-                console.print(f"[red]Error writing configuration: {e}[/red]")
-                sys.exit(1)
-
-        # Handle --remove-all option
-        if remove_all_constraints:
-            from .package_constraints import remove_all_constraints_from_config, list_all_constraints, parse_invalidation_triggers_storage
-
-            # Get confirmation if not using --yes and removing from all environments
-            if not env and not skip_confirmation:
-                # Show what will be removed
-                try:
-                    all_constraints = list_all_constraints()
-                    if not all_constraints:
-                        console.print("[yellow]No constraints found in any environment.[/yellow]")
-                        return
-
-                    console.print("[bold red]WARNING: This will remove ALL constraints from ALL environments![/bold red]")
-                    console.print("\n[bold]Constraints that will be removed:[/bold]")
-
-                    total_constraints = 0
-                    for env_name, constraints in all_constraints.items():
-                        console.print(f"\n[bold cyan]{env_name}:[/bold cyan]")
-                        for package, constraint_spec in sorted(constraints.items()):
-                            console.print(f"  {package}{constraint_spec}")
-                            total_constraints += 1
-
-                    console.print(f"\n[bold]Total: {total_constraints} constraint(s) in {len(all_constraints)} environment(s)[/bold]")
-
-                    if not click.confirm("\nAre you sure you want to remove all constraints?"):
-                        console.print("[yellow]Operation cancelled.[/yellow]")
-                        return
-
-                except Exception:
-                    # If we can't list constraints, ask for generic confirmation
-                    if not click.confirm("Are you sure you want to remove all constraints from all environments?"):
-                        console.print("[yellow]Operation cancelled.[/yellow]")
-                        return
-
-            console.print(f"[bold blue]Removing all constraints from {'all environments' if not env else env}...[/bold blue]")
-
-            try:
-                config_path, removed_constraints, removed_triggers_by_env = remove_all_constraints_from_config(env)
-
-                if not removed_constraints:
-                    if env:
-                        console.print(f"[yellow]No constraints found in environment '{env}'.[/yellow]")
-                    else:
-                        console.print("[yellow]No constraints found in any environment.[/yellow]")
-                    return
-
-                # Triggers are already cleaned up by remove_all_constraints_from_config
-
-                # Display summary
-                console.print("\n[bold green]✓ All constraints removed successfully![/bold green]")
-                console.print(f"[bold]File:[/bold] {config_path}")
-
-                # Show removed constraints
-                console.print("\n[bold]Constraints removed:[/bold]")
-                total_removed = 0
-                for env_name, constraints in removed_constraints.items():
-                    console.print(f"\n[bold cyan]{env_name}:[/bold cyan]")
-                    for package, constraint_spec in sorted(constraints.items()):
-                        console.print(f"  [red]Removed[/red]: {package}{constraint_spec}")
-                        total_removed += 1
-
-                console.print(f"\n[bold]Total removed: {total_removed} constraint(s) from {len(removed_constraints)} environment(s)[/bold]")
-
-                # Show removed invalidation triggers if any
-                if removed_triggers_by_env:
-                    console.print("\n[bold]Invalidation triggers removed:[/bold]")
-                    total_triggers_removed = 0
-                    for env_name, env_triggers in removed_triggers_by_env.items():
-                        console.print(f"\n[bold cyan]{env_name}:[/bold cyan]")
-                        for package, triggers in env_triggers.items():
-                            for trigger in triggers:
-                                console.print(f"  [red]Removed trigger[/red]: {trigger}")
-                                total_triggers_removed += 1
-                    console.print(f"\n[bold]Total triggers removed: {total_triggers_removed}[/bold]")
-
-                # Show which environment(s) were updated
-                if env:
-                    console.print(f"\n[bold cyan]Environment updated:[/bold cyan] {env}")
-                else:
-                    environments_updated = list(removed_constraints.keys())
-                    console.print(f"\n[bold cyan]Environments updated:[/bold cyan] {', '.join(sorted(environments_updated))}")
+            if interactive:
+                can_upgrade = select_packages_interactively(can_upgrade, console)
+                if not can_upgrade:
+                    console.print("[yellow]No packages selected for upgrade.[/yellow]")
+                    sys.exit(0)
 
-                return
+            if dry_run:
+                console.print("\n[bold cyan]Dry run complete.[/bold cyan] No packages were modified.")
+                sys.exit(0)
 
-            except ValueError as e:
-                console.print(f"[red]Error: {e}[/red]")
-                sys.exit(1)
-            except IOError as e:
-                console.print(f"[red]Error writing configuration: {e}[/red]")
-                sys.exit(1)
+        # Skip confirmation if interactive mode (already confirmed) or --yes flag
+        if not yes and not interactive and output != "json":
+            console.print()
+            confirm = click.confirm("Do you want to proceed with the upgrade?", default=True)
+            if not confirm:
+                console.print("[yellow]Upgrade cancelled.[/yellow]")
+                sys.exit(0)
+
+        # Step 5: Install packages
+        if output != "json":
+            console.print("\n[bold]Step 5/5:[/bold] Upgrading packages...\n")
+        step5_start = time.time()
+
+        # Save state for potential rollback
+        from pipu_cli.rollback import save_state
+        pre_upgrade_packages = [
+            {"name": pkg.name, "version": str(pkg.version)}
+            for pkg in can_upgrade
+        ]
+        save_state(pre_upgrade_packages, "Pre-upgrade state")
+
+        stream = ConsoleStream(console) if output != "json" else None
+        results = install_packages(
+            can_upgrade,
+            output_stream=stream,
+            timeout=300,
+            version_constraints=package_constraints if package_constraints else None
+        )
+        step5_time = time.time() - step5_start
+
+        # Update requirements file if requested
+        if update_requirements:
+            from pathlib import Path
+            from pipu_cli.requirements import update_requirements_file
+            req_path = Path(update_requirements)
+            updated = update_requirements_file(req_path, results)
+            if updated and output != "json":
+                console.print(f"\n[bold green]Updated {updated} package(s) in {update_requirements}[/bold green]")
+
+        # Print results summary
+        if output == "json":
+            assert json_formatter is not None
+            json_data = json_formatter.format_all(
+                upgradable=can_upgrade,
+                blocked=blocked_packages if show_blocked else None,
+                results=results
+            )
+            print(json_data)
+        else:
+            print_upgrade_results(results, console=console)
 
-        constraint_list = list(constraint_specs)
+            if debug:
+                console.print(f"\n[dim]Step 5 time: {step5_time:.2f}s[/dim]")
+                total_time = step1_time + step2_time + step3_time + step5_time
+                console.print(f"[dim]Total time: {total_time:.2f}s[/dim]")
 
-        if not constraint_list:
-            console.print("[red]Error: At least one constraint must be specified.[/red]")
+        # Exit with appropriate code
+        failed = [pkg for pkg in results if not pkg.upgraded]
+        if failed:
             sys.exit(1)
-
-        console.print("[bold blue]Adding constraints to pip configuration...[/bold blue]")
-
-        # Use backend function for constraint addition
-        from .package_constraints import (
-            add_constraints_to_config,
-            validate_invalidation_triggers,
-            get_recommended_pip_config_path,
-            get_current_environment_name,
-            parse_invalidation_triggers_storage,
-            merge_invalidation_triggers,
-            format_invalidation_triggers,
-            parse_inline_constraints,
-            parse_requirement_line
-        )
-        import configparser
-
-        # Get the recommended config file path early for error handling
-        config_path = get_recommended_pip_config_path()
-
-        try:
-            # Validate invalidation triggers if provided
-            validated_triggers = []
-            if invalidation_triggers:
-                validated_triggers = validate_invalidation_triggers(list(invalidation_triggers))
-
-            # Add constraints using the backend function
-            config_path, changes = add_constraints_to_config(constraint_list, env)
-
-            # Handle invalidation triggers if provided
-            if validated_triggers:
-                # Load the config and add triggers for the constrained packages
-                config = configparser.ConfigParser()
-                config.read(config_path)
-
-                # Determine target environment section
-                if env is None:
-                    env = get_current_environment_name()
-                section_name = env if env else 'global'
-
-                # Get existing invalidation triggers
-                existing_triggers_storage = {}
-                existing_value = _get_constraint_invalid_when(config, section_name)
-                if existing_value:
-                    existing_triggers_storage = parse_invalidation_triggers_storage(existing_value)
-
-                # Get current constraints to find the packages that were added/updated
-                current_constraints = {}
-                if config.has_option(section_name, 'constraints'):
-                    constraints_value = config.get(section_name, 'constraints')
-                    if any(op in constraints_value for op in ['>=', '<=', '==', '!=', '~=', '>', '<']):
-                        current_constraints = parse_inline_constraints(constraints_value)
-
-                # Process triggers for each package that was specified (whether changed or not)
-                updated_triggers_storage = existing_triggers_storage.copy()
-
-                # Get all package names from the constraint list
-                all_package_names = set()
-                for spec in constraint_list:
-                    parsed = parse_requirement_line(spec)
-                    if parsed:
-                        all_package_names.add(parsed['name'].lower())
-
-                for package_name in all_package_names:
-                    # Get existing triggers for this package
-                    existing_package_triggers = existing_triggers_storage.get(package_name, [])
-
-                    # Merge with new triggers
-                    merged_triggers = merge_invalidation_triggers(existing_package_triggers, validated_triggers)
-
-                    if merged_triggers:
-                        updated_triggers_storage[package_name] = merged_triggers
-
-                # Format and store the triggers
-                if updated_triggers_storage:
-                    trigger_entries = []
-                    for package_name, triggers in updated_triggers_storage.items():
-                        # Get the constraint for this package to format properly
-                        if package_name in current_constraints:
-                            package_constraint = current_constraints[package_name]
-                            formatted_entry = format_invalidation_triggers(f"{package_name}{package_constraint}", triggers)
-                            if formatted_entry:
-                                trigger_entries.append(formatted_entry)
-
-                    triggers_value = ','.join(trigger_entries) if trigger_entries else ''
-                    _set_constraint_invalid_when(config, section_name, triggers_value)
-
-                # Write the updated config file
-                with open(config_path, 'w', encoding='utf-8') as f:
-                    config.write(f)
-
-        except Exception as e:
-            if isinstance(e, ValueError):
-                raise e
-            else:
-                raise IOError(f"Failed to write pip config file '{config_path}': {e}")
-
-        if not changes and not validated_triggers:
-            console.print("[yellow]No changes made - all constraints already exist with the same values.[/yellow]")
-            return
-
-        # Display summary
-        console.print("\n[bold green]✓ Configuration updated successfully![/bold green]")
-        console.print(f"[bold]File:[/bold] {config_path}")
-
-        # Show changes
-        if changes:
-            console.print("\n[bold]Constraints modified:[/bold]")
-            for package, (action, constraint) in changes.items():
-                action_color = "green" if action == "added" else "yellow"
-                console.print(f"  [{action_color}]{action.title()}[/{action_color}]: {package}{constraint}")
-
-        # Show invalidation triggers if added
-        if validated_triggers:
-            console.print("\n[bold]Invalidation triggers added:[/bold]")
-            for trigger in validated_triggers:
-                console.print(f"  [cyan]Trigger[/cyan]: {trigger}")
-
-        # Show which environment was updated
-        if env:
-            console.print(f"\n[bold cyan]Environment updated:[/bold cyan] {env}")
         else:
-            current_env = get_current_environment_name()
-            if current_env and current_env != "global":
-                console.print(f"\n[bold cyan]Environment updated:[/bold cyan] {current_env}")
-            else:
-                console.print("\n[bold cyan]Environment updated:[/bold cyan] global")
-
-    except ValueError as e:
-        console.print(f"[red]Error: {e}[/red]")
-        sys.exit(1)
-    except IOError as e:
-        console.print(f"[red]Error writing configuration: {e}[/red]")
-        sys.exit(1)
+            sys.exit(0)
+
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Interrupted by user.[/yellow]")
+        sys.exit(130)
+    except click.Abort:
+        console.print("\n[yellow]Update cancelled by user[/yellow]")
+        sys.exit(130)
     except Exception as e:
-        console.print(f"[red]Unexpected error: {e}[/red]")
+        console.print(f"\n[bold red]Error:[/bold red] {e}")
         sys.exit(1)
 
 
 @cli.command()
-@click.argument('package_names', nargs=-1, required=False)
-@click.option('--env', help='Target environment section (defaults to current environment or global)')
-@click.option('--list', 'list_ignores', is_flag=True, help='List existing ignores for specified environment (or all environments if no --env specified)')
-@click.option('--remove', 'remove_ignores', is_flag=True, help='Remove ignores for specified packages')
-@click.option('--remove-all', 'remove_all_ignores', is_flag=True, help='Remove all ignores from specified environment (or all environments if no --env specified)')
-@click.option('--yes', '-y', 'skip_confirmation', is_flag=True, help='Skip confirmation prompt')
-def ignore(package_names, env, list_ignores, remove_ignores, remove_all_ignores, skip_confirmation):
+@click.option(
+    "--list", "-l",
+    "list_states_flag",
+    is_flag=True,
+    help="List all saved rollback states"
+)
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    help="Show what would be restored without actually restoring"
+)
+@click.option(
+    "--yes", "-y",
+    is_flag=True,
+    help="Automatically confirm rollback without prompting"
+)
+@click.option(
+    "--state",
+    type=str,
+    default=None,
+    help="Specific state file to rollback to (use --list to see available states)"
+)
+def rollback(list_states_flag: bool, dry_run: bool, yes: bool, state: Optional[str]) -> None:
     """
-    Add or remove package ignores in pip configuration
-
-    Manages packages that should be ignored during update operations.
-    Ignored packages will be skipped when checking for outdated packages.
-
-    \b
-    Examples:
-        pipu ignore requests numpy
-        pipu ignore flask --env production
-        pipu ignore --list
-        pipu ignore --list --env production
-        pipu ignore --remove requests numpy
-        pipu ignore --remove flask --env production
-        pipu ignore --remove-all --env production
-        pipu ignore --remove-all --yes
-
-    \f
-    :param package_names: One or more package names to ignore or remove
-    :param env: Target environment section name
-    :param list_ignores: List existing ignores instead of adding new ones
-    :param remove_ignores: Remove ignores for specified packages
-    :param remove_all_ignores: Remove all ignores from environment(s)
-    :param skip_confirmation: Skip confirmation prompt for --remove-all
-    :raises SystemExit: Exits with code 1 if an error occurs
+    Restore packages to a previous state.
+
+    Before each upgrade, pipu saves the current package versions. Use this
+    command to restore packages to their pre-upgrade state.
+
+    [bold]Examples:[/bold]
+      pipu rollback --list       List all saved states
+      pipu rollback --dry-run    Preview what would be restored
+      pipu rollback --yes        Rollback without confirmation
+      pipu rollback --state FILE Rollback to a specific state
     """
-    try:
-        # Validate mutually exclusive options
-        active_options = [list_ignores, remove_ignores, remove_all_ignores, bool(package_names and not (list_ignores or remove_ignores or remove_all_ignores))]
-        if sum(active_options) > 1:
-            console.print("[red]Error: Cannot use --list, --remove, --remove-all, and package names together. Use only one at a time.[/red]")
+    from pipu_cli.rollback import get_latest_state, rollback_to_state, list_states as get_states, ROLLBACK_DIR
+
+    console = Console()
+
+    # List saved states if requested
+    if list_states_flag:
+        states = get_states()
+        if not states:
+            console.print("[yellow]No saved states found.[/yellow]")
+            console.print(f"[dim]States are saved in: {ROLLBACK_DIR}[/dim]")
+            sys.exit(0)
+
+        table = Table(title="[bold]Saved Rollback States[/bold]")
+        table.add_column("#", style="dim", width=3)
+        table.add_column("State File", style="cyan")
+        table.add_column("Timestamp", style="green")
+        table.add_column("Packages", style="magenta", justify="right")
+        table.add_column("Description", style="dim")
+
+        for idx, s in enumerate(states, 1):
+            ts = s["timestamp"]
+            if len(ts) == 15 and ts[8] == "_":
+                formatted_ts = f"{ts[:4]}-{ts[4:6]}-{ts[6:8]} {ts[9:11]}:{ts[11:13]}:{ts[13:15]}"
+            else:
+                formatted_ts = ts
+
+            table.add_row(
+                str(idx),
+                s["file"],
+                formatted_ts,
+                str(s["package_count"]),
+                s["description"] or "-"
+            )
+
+        console.print(table)
+        console.print(f"\n[dim]States saved in: {ROLLBACK_DIR}[/dim]")
+        console.print("[dim]Use --state <filename> to rollback to a specific state[/dim]")
+        sys.exit(0)
+
+    # Get the state to rollback to
+    if state:
+        state_path = ROLLBACK_DIR / state
+        if not state_path.exists():
+            console.print(f"[red]State file not found:[/red] {state}")
+            console.print("[dim]Use 'pipu rollback --list' to see available states[/dim]")
             sys.exit(1)
 
-        # Handle --list option
-        if list_ignores:
-            from .package_constraints import list_all_ignores
+        with open(state_path, 'r') as f:
+            state_data = json.load(f)
+    else:
+        state_data = get_latest_state()
 
-            console.print("[bold blue]Listing ignores from pip configuration...[/bold blue]")
+    if state_data is None:
+        console.print("[yellow]No saved state found.[/yellow]")
+        console.print("[dim]A state is automatically saved before each upgrade.[/dim]")
+        sys.exit(0)
 
-            all_ignores = list_all_ignores(env)
+    # Show what will be rolled back
+    packages = state_data.get("packages", [])
+    timestamp = state_data.get("timestamp", "unknown")
+    description = state_data.get("description", "")
 
-            if not all_ignores:
-                if env:
-                    console.print(f"[yellow]No ignores found for environment '[bold]{env}[/bold]'.[/yellow]")
-                else:
-                    console.print("[yellow]No ignores found in any environment.[/yellow]")
-                return
-
-            # Display ignores
-            for env_name, ignores in all_ignores.items():
-                console.print(f"\n[bold cyan]Environment: {env_name}[/bold cyan]")
-                if ignores:
-                    for package in sorted(ignores):
-                        console.print(f"  {package}")
-                else:
-                    console.print("  [dim]No ignores[/dim]")
+    if len(timestamp) == 15 and timestamp[8] == "_":
+        formatted_ts = f"{timestamp[:4]}-{timestamp[4:6]}-{timestamp[6:8]} {timestamp[9:11]}:{timestamp[11:13]}:{timestamp[13:15]}"
+    else:
+        formatted_ts = timestamp
 
-            return
+    console.print(f"\n[bold]Rollback State:[/bold] {formatted_ts}")
+    if description:
+        console.print(f"[dim]{description}[/dim]")
+    console.print()
 
-        # Handle --remove option
-        if remove_ignores:
-            if not package_names:
-                console.print("[red]Error: At least one package name must be specified for removal.[/red]")
-                sys.exit(1)
+    table = Table(title=f"[bold]{len(packages)} Package(s) to Restore[/bold]")
+    table.add_column("Package", style="cyan")
+    table.add_column("Version", style="green")
 
-            from .package_constraints import remove_ignores_from_config
+    for pkg in packages:
+        table.add_row(pkg["name"], pkg["version"])
 
-            packages_list = list(package_names)
-            console.print(f"[bold blue]Removing ignores for {len(packages_list)} package(s)...[/bold blue]")
+    console.print(table)
 
-            try:
-                config_path, removed_packages = remove_ignores_from_config(packages_list, env)
+    if dry_run:
+        console.print("\n[bold cyan]Dry run complete.[/bold cyan] No packages were modified.")
+        sys.exit(0)
 
-                if not removed_packages:
-                    console.print("[yellow]No ignores were removed (packages not found in ignores).[/yellow]")
-                    return
+    if not yes:
+        console.print()
+        confirm = click.confirm("Do you want to proceed with the rollback?", default=True)
+        if not confirm:
+            console.print("[yellow]Rollback cancelled.[/yellow]")
+            sys.exit(0)
 
-                # Display summary
-                console.print("\n[bold green]✓ Ignores removed successfully![/bold green]")
-                console.print(f"[bold]File:[/bold] {config_path}")
+    console.print("\n[bold]Rolling back packages...[/bold]\n")
 
-                # Show removed ignores
-                console.print("\n[bold]Ignores removed:[/bold]")
-                for package in removed_packages:
-                    console.print(f"  [red]Removed[/red]: {package}")
+    rolled_back = rollback_to_state(state_data, dry_run=False)
 
-                # Show which environment was updated
-                if env:
-                    console.print(f"\n[bold cyan]Environment updated:[/bold cyan] {env}")
-                else:
-                    from .package_constraints import get_current_environment_name
-                    current_env = get_current_environment_name()
-                    if current_env and current_env != "global":
-                        console.print(f"\n[bold cyan]Environment updated:[/bold cyan] {current_env}")
-                    else:
-                        console.print("\n[bold cyan]Environment updated:[/bold cyan] global")
-
-                return
-
-            except ValueError as e:
-                console.print(f"[red]Error: {e}[/red]")
-                sys.exit(1)
-            except IOError as e:
-                console.print(f"[red]Error writing configuration: {e}[/red]")
-                sys.exit(1)
-
-        # Handle --remove-all option
-        if remove_all_ignores:
-            from .package_constraints import remove_all_ignores_from_config, list_all_ignores
-
-            # Get confirmation if not using --yes and removing from all environments
-            if not env and not skip_confirmation:
-                # Show what will be removed
-                try:
-                    all_ignores = list_all_ignores()
-                    if not all_ignores:
-                        console.print("[yellow]No ignores found in any environment.[/yellow]")
-                        return
-
-                    console.print("[bold red]WARNING: This will remove ALL ignores from ALL environments![/bold red]")
-                    console.print("\n[bold]Ignores that will be removed:[/bold]")
-
-                    total_ignores = 0
-                    for env_name, ignores in all_ignores.items():
-                        console.print(f"\n[bold cyan]{env_name}:[/bold cyan]")
-                        for package in sorted(ignores):
-                            console.print(f"  {package}")
-                            total_ignores += 1
-
-                    console.print(f"\n[bold]Total: {total_ignores} ignore(s) in {len(all_ignores)} environment(s)[/bold]")
-
-                    if not click.confirm("\nAre you sure you want to remove all ignores?"):
-                        console.print("[yellow]Operation cancelled.[/yellow]")
-                        return
-
-                except Exception:
-                    # If we can't list ignores, ask for generic confirmation
-                    if not click.confirm("Are you sure you want to remove all ignores from all environments?"):
-                        console.print("[yellow]Operation cancelled.[/yellow]")
-                        return
-
-            console.print(f"[bold blue]Removing all ignores from {'all environments' if not env else env}...[/bold blue]")
-
-            try:
-                config_path, removed_ignores = remove_all_ignores_from_config(env)
-
-                if not removed_ignores:
-                    if env:
-                        console.print(f"[yellow]No ignores found in environment '{env}'.[/yellow]")
-                    else:
-                        console.print("[yellow]No ignores found in any environment.[/yellow]")
-                    return
-
-                # Display summary
-                console.print("\n[bold green]✓ All ignores removed successfully![/bold green]")
-                console.print(f"[bold]File:[/bold] {config_path}")
-
-                # Show removed ignores
-                console.print("\n[bold]Ignores removed:[/bold]")
-                total_removed = 0
-                for env_name, ignores in removed_ignores.items():
-                    console.print(f"\n[bold cyan]{env_name}:[/bold cyan]")
-                    for package in sorted(ignores):
-                        console.print(f"  [red]Removed[/red]: {package}")
-                        total_removed += 1
-
-                console.print(f"\n[bold]Total removed: {total_removed} ignore(s) from {len(removed_ignores)} environment(s)[/bold]")
-
-                # Show which environment(s) were updated
-                if env:
-                    console.print(f"\n[bold cyan]Environment updated:[/bold cyan] {env}")
-                else:
-                    environments_updated = list(removed_ignores.keys())
-                    console.print(f"\n[bold cyan]Environments updated:[/bold cyan] {', '.join(sorted(environments_updated))}")
+    if rolled_back:
+        console.print(f"\n[bold green]Successfully rolled back {len(rolled_back)} package(s):[/bold green]")
+        for pkg in rolled_back:
+            console.print(f"  - {pkg}")
+    else:
+        console.print("[yellow]No packages were rolled back.[/yellow]")
 
-                return
+    sys.exit(0)
 
-            except ValueError as e:
-                console.print(f"[red]Error: {e}[/red]")
-                sys.exit(1)
-            except IOError as e:
-                console.print(f"[red]Error writing configuration: {e}[/red]")
-                sys.exit(1)
 
-        # Handle adding ignores (default behavior)
-        if not package_names:
-            console.print("[red]Error: At least one package name must be specified.[/red]")
-            sys.exit(1)
+@cli.command()
+def cache() -> None:
+    """
+    Show cache information.
 
-        from .package_constraints import add_ignores_to_config, get_current_environment_name
+    Displays details about the package version cache for the current
+    Python environment, including age and freshness status.
 
-        packages_list = list(package_names)
-        console.print("[bold blue]Adding ignores to pip configuration...[/bold blue]")
+    [bold]Examples:[/bold]
+      pipu cache           Show cache status
+      pipu clean           Clear current environment cache
+      pipu clean --all     Clear all environment caches
+    """
+    console = Console()
 
-        # Get the recommended config file path early for error handling
-        from .package_constraints import get_recommended_pip_config_path
-        config_path = get_recommended_pip_config_path()
+    # Show cache info
+    info = get_cache_info()
 
-        try:
-            config_path, changes = add_ignores_to_config(packages_list, env)
+    console.print("[bold]Cache Information[/bold]\n")
+    console.print(f"  Environment ID: [cyan]{info['environment_id']}[/cyan]")
+    console.print(f"  Python: [dim]{info['python_executable']}[/dim]")
+    console.print(f"  Cache path: [dim]{info['path']}[/dim]")
 
-            if not any(action == 'added' for action in changes.values()):
-                console.print("[yellow]No changes made - all packages are already ignored.[/yellow]")
-                return
+    if info['exists']:
+        console.print("\n  [green]Cache exists[/green]")
+        console.print(f"  Updated: {info.get('age_human', 'unknown')}")
+        console.print(f"  Packages cached: {info.get('package_count', 0)}")
 
-            # Display summary
-            console.print("\n[bold green]✓ Configuration updated successfully![/bold green]")
-            console.print(f"[bold]File:[/bold] {config_path}")
+        # Check if fresh
+        if is_cache_fresh():
+            console.print("  Status: [green]Fresh[/green] (within TTL)")
+        else:
+            console.print("  Status: [yellow]Stale[/yellow] (will refresh on next upgrade)")
+    else:
+        console.print("\n  [yellow]No cache[/yellow]")
+        console.print("  Run [cyan]pipu update[/cyan] to create cache")
 
-            # Show changes
-            console.print("\n[bold]Ignores modified:[/bold]")
-            for package, action in changes.items():
-                if action == 'added':
-                    console.print(f"  [green]Added[/green]: {package}")
-                elif action == 'already_exists':
-                    console.print(f"  [yellow]Already ignored[/yellow]: {package}")
+    sys.exit(0)
 
-            # Show which environment was updated
-            if env:
-                console.print(f"\n[bold cyan]Environment updated:[/bold cyan] {env}")
-            else:
-                current_env = get_current_environment_name()
-                if current_env and current_env != "global":
-                    console.print(f"\n[bold cyan]Environment updated:[/bold cyan] {current_env}")
-                else:
-                    console.print("\n[bold cyan]Environment updated:[/bold cyan] global")
 
-        except IOError as e:
-            console.print(f"[red]Error writing configuration: {e}[/red]")
-            sys.exit(1)
+@cli.command()
+@click.option(
+    "--all", "-a",
+    "clean_all",
+    is_flag=True,
+    help="Clean up files for all environments"
+)
+def clean(clean_all: bool) -> None:
+    """
+    Clean up pipu caches and temporary files.
 
-    except Exception as e:
-        console.print(f"[red]Unexpected error: {e}[/red]")
-        sys.exit(1)
+    Removes cached package version data and other temporary files
+    created by pipu. By default, cleans up files for the current
+    Python environment only.
+
+    [bold]Examples:[/bold]
+      pipu clean           Clean current environment
+      pipu clean --all     Clean all environments
+    """
+    console = Console()
+
+    if clean_all:
+        count = clear_all_caches()
+        if count > 0:
+            console.print(f"[bold green]Cleared {count} cache(s).[/bold green]")
+        else:
+            console.print("[yellow]No caches to clear.[/yellow]")
+    else:
+        if clear_cache():
+            console.print("[bold green]Cache cleared for current environment.[/bold green]")
+        else:
+            console.print("[yellow]No cache to clear for current environment.[/yellow]")
+
+    sys.exit(0)
 
 
-# This allows the module to be run with: python -m pipu_cli.cli
-if __name__ == '__main__':
+if __name__ == "__main__":
     cli()