copilot-session-tools 0.1.1__py3-none-any.whl

copilot_session_tools/cli.py

@@ -0,0 +1,993 @@
+"""Command-line interface for Copilot Session Tools.
+
+This module provides a modern CLI built with Typer for scanning, searching,
+and exporting VS Code GitHub Copilot chat history.
+"""
+
+import sys
+from concurrent.futures import ThreadPoolExecutor
+from datetime import datetime
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+from copilot_session_tools import (
+    ChatMessage,
+    ChatSession,
+    Database,
+    __version__,
+    export_session_to_file,
+    export_session_to_html_file,
+    generate_session_filename,
+    generate_session_html_filename,
+    get_vscode_storage_paths,
+    scan_chat_sessions,
+)
+from copilot_session_tools.scanner import (
+    SessionFileInfo,
+    parse_session_file,
+    scan_session_files,
+)
+
+# On Windows, reconfigure stdout/stderr to UTF-8 when piped to prevent
+# Rich from falling back to cp1252 which can't handle Unicode output
+if sys.platform == "win32":
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")  # ty: ignore[call-non-callable]
+    if hasattr(sys.stderr, "reconfigure"):
+        sys.stderr.reconfigure(encoding="utf-8", errors="replace")  # ty: ignore[call-non-callable]
+
+app = typer.Typer(
+    name="copilot-session-tools",
+    help="Create a searchable archive of VS Code GitHub Copilot chats.",
+    no_args_is_help=True,
+)
+console = Console()
+
+# Number of threads for parallel file parsing
+PARSE_WORKERS = 4
+
+
+def version_callback(value: bool):
+    """Print version and exit."""
+    if value:
+        console.print(f"copilot-session-tools version {__version__}")
+        raise typer.Exit()
+
+
+def format_timestamp(ts: str | int | None) -> str:
+    """Convert a timestamp to a human-readable date string."""
+    if ts is None:
+        return "Unknown"
+    try:
+        # Try parsing as milliseconds (JS timestamp) - int() accepts both strings and ints
+        numeric_ts = int(ts) if isinstance(ts, str) else ts
+        if numeric_ts > 1e12:  # Milliseconds
+            numeric_ts = numeric_ts / 1000
+        return datetime.fromtimestamp(numeric_ts).strftime("%Y-%m-%d %H:%M:%S")
+    except (ValueError, OSError):
+        return str(ts)
+
+
+@app.callback()
+def main(
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            "-V",
+            callback=version_callback,
+            is_eager=True,
+            help="Show version and exit.",
+        ),
+    ] = False,
+):
+    """Copilot Chat Archive - Create a searchable archive of VS Code GitHub Copilot chats."""
+    pass
+
+
+@app.command()
+def scan(
+    db: Annotated[
+        Path,
+        typer.Option(
+            "--db",
+            "-d",
+            help="Path to SQLite database file.",
+        ),
+    ] = Path("copilot_chats.db"),
+    storage_path: Annotated[
+        list[Path] | None,
+        typer.Option(
+            "--storage-path",
+            "-s",
+            help="Custom VS Code storage path(s) to scan. Can be specified multiple times.",
+            exists=True,
+            file_okay=False,
+        ),
+    ] = None,
+    edition: Annotated[
+        str,
+        typer.Option(
+            "--edition",
+            "-e",
+            help="VS Code edition to scan.",
+        ),
+    ] = "both",
+    verbose: Annotated[
+        bool,
+        typer.Option(
+            "--verbose",
+            "-v",
+            help="Show verbose output.",
+        ),
+    ] = False,
+    full: Annotated[
+        bool,
+        typer.Option(
+            "--full",
+            "-f",
+            help="Full scan: update all sessions regardless of file changes.",
+        ),
+    ] = False,
+    store_raw: Annotated[
+        bool,
+        typer.Option(
+            "--store-raw",
+            help="Store raw JSON in database (enables rebuild command, increases DB size).",
+        ),
+    ] = False,
+):
+    """Scan for and import Copilot chat sessions into the database.
+
+    By default, uses incremental refresh: only updates sessions whose source files
+    have changed (based on file mtime and size). Use --full to force a complete
+    re-import of all sessions.
+
+    Raw JSON is not stored by default to save space. Use --store-raw to enable
+    storing raw JSON, which allows using the 'rebuild' and 'raw-json' commands.
+    """
+    if edition not in ("stable", "insider", "both"):
+        console.print("[red]Error: edition must be 'stable', 'insider', or 'both'[/red]")
+        raise typer.Exit(1)
+
+    database = Database(db)
+
+    # Determine storage paths
+    if storage_path:
+        paths = [(str(p), "custom") for p in storage_path]
+    else:
+        all_paths = get_vscode_storage_paths()
+        if edition == "both":
+            paths = all_paths
+        else:
+            paths = [(p, e) for p, e in all_paths if e == edition]
+
+    console.print("Scanning for Copilot chat sessions...")
+    if full:
+        console.print("  (Full mode: will update all sessions)")
+    else:
+        console.print("  (Incremental mode: skipping unchanged sessions)")
+    if store_raw:
+        console.print("  (Storing raw JSON in database)")
+    if verbose:
+        for path, ed in paths:
+            console.print(f"  Checking: {path} ({ed})")
+
+    added = 0
+    updated = 0
+    skipped = 0
+
+    if full:
+        # Full mode: parse and update all sessions
+        for session in scan_chat_sessions(paths):
+            existing = database.get_session(session.session_id)
+            if existing:
+                database.update_session(session, store_raw=store_raw)
+                updated += 1
+                if verbose:
+                    workspace = session.workspace_name or "Unknown workspace"
+                    console.print(f"  Updated: {workspace} ({len(session.messages)} messages)")
+            else:
+                database.add_session(session, store_raw=store_raw)
+                added += 1
+                if verbose:
+                    workspace = session.workspace_name or "Unknown workspace"
+                    console.print(f"  Added: {workspace} ({len(session.messages)} messages)")
+    else:
+        # Incremental mode: load all file metadata upfront for fast comparison
+        stored_metadata = database.get_all_file_metadata()
+
+        # Collect files that need updating
+        files_to_update: list[SessionFileInfo] = []
+        for file_info in scan_session_files(paths):
+            source_file = str(file_info.file_path)
+            stored = stored_metadata.get(source_file)
+
+            needs_update = stored is None or stored[0] is None or stored[1] is None or stored[0] != file_info.mtime or stored[1] != file_info.size
+
+            if needs_update:
+                files_to_update.append(file_info)
+            else:
+                skipped += 1
+                if verbose:
+                    workspace = file_info.workspace_name or "Unknown workspace"
+                    console.print(f"  Skipped (unchanged): {workspace}")
+
+        # Parse files in parallel (I/O + CPU bound)
+        if files_to_update:
+            with ThreadPoolExecutor(max_workers=PARSE_WORKERS) as executor:
+                parse_results = list(executor.map(parse_session_file, files_to_update))
+
+            # Separate new sessions from updates
+            sessions_to_add: list[ChatSession] = []
+            sessions_to_update: list[ChatSession] = []
+
+            for sessions in parse_results:
+                for session in sessions:
+                    existing = database.get_session(session.session_id)
+                    if existing:
+                        sessions_to_update.append(session)
+                    else:
+                        sessions_to_add.append(session)
+
+            # Batch insert new sessions (single transaction)
+            if sessions_to_add:
+                batch_added, _batch_skipped = database.add_sessions_batch(sessions_to_add, store_raw=store_raw)
+                added += batch_added
+                if verbose:
+                    for session in sessions_to_add:
+                        workspace = session.workspace_name or "Unknown workspace"
+                        console.print(f"  Added: {workspace} ({len(session.messages)} messages)")
+
+            # Update existing sessions (must be individual due to delete+insert)
+            for session in sessions_to_update:
+                database.update_session(session, store_raw=store_raw)
+                updated += 1
+                if verbose:
+                    workspace = session.workspace_name or "Unknown workspace"
+                    console.print(f"  Updated: {workspace} ({len(session.messages)} messages)")
+
+    console.print("\n[green]Import complete:[/green]")
+    console.print(f"  Added: {added} sessions")
+    console.print(f"  Updated: {updated} sessions")
+    console.print(f"  Skipped (unchanged): {skipped} sessions")
+
+    stats = database.get_stats()
+    console.print("\n[cyan]Database now contains:[/cyan]")
+    console.print(f"  {stats['session_count']} sessions")
+    console.print(f"  {stats['message_count']} messages")
+    console.print(f"  {stats['workspace_count']} workspaces")
+
+
+@app.command()
+def search(
+    query: Annotated[str, typer.Argument(help="Search query.")],
+    db: Annotated[
+        Path,
+        typer.Option(
+            "--db",
+            "-d",
+            help="Path to SQLite database file.",
+            exists=True,
+        ),
+    ] = Path("copilot_chats.db"),
+    limit: Annotated[
+        int,
+        typer.Option(
+            "--limit",
+            "-l",
+            "--top",
+            help="Maximum number of results to show (top).",
+        ),
+    ] = 20,
+    skip: Annotated[
+        int,
+        typer.Option(
+            "--skip",
+            help="Number of results to skip (for pagination).",
+        ),
+    ] = 0,
+    role: Annotated[
+        str | None,
+        typer.Option(
+            "--role",
+            "-r",
+            help="Filter by message role (user or assistant).",
+        ),
+    ] = None,
+    title_filter: Annotated[
+        str | None,
+        typer.Option(
+            "--title",
+            "-t",
+            help="Filter by session title or workspace name.",
+        ),
+    ] = None,
+    repository_filter: Annotated[
+        str | None,
+        typer.Option(
+            "--repository",
+            "--repo",
+            help="Filter by repository URL (e.g., github.com/owner/repo).",
+        ),
+    ] = None,
+    no_tools: Annotated[
+        bool,
+        typer.Option(
+            "--no-tools",
+            help="Exclude tool invocations from search results.",
+        ),
+    ] = False,
+    no_files: Annotated[
+        bool,
+        typer.Option(
+            "--no-files",
+            help="Exclude file changes from search results.",
+        ),
+    ] = False,
+    tools_only: Annotated[
+        bool,
+        typer.Option(
+            "--tools-only",
+            help="Only search in tool invocations.",
+        ),
+    ] = False,
+    files_only: Annotated[
+        bool,
+        typer.Option(
+            "--files-only",
+            help="Only search in file changes.",
+        ),
+    ] = False,
+    full_content: Annotated[
+        bool,
+        typer.Option(
+            "--full",
+            "-F",
+            help="Show full content instead of truncated snippets.",
+        ),
+    ] = False,
+    sort_by: Annotated[
+        str,
+        typer.Option(
+            "--sort",
+            "-s",
+            help="Sort results by relevance (default) or date.",
+        ),
+    ] = "relevance",
+):
+    """Search chat messages in the database.
+
+    Supports advanced query syntax:
+
+    \b
+    - Multiple words: "python function" matches both words (AND logic)
+    - Exact phrases: Use quotes like "python function" for exact match
+    - Field filters in query: role:user, role:assistant, workspace:name, title:name, repository:url (or repo:url)
+    - Date filters: start_date:2024-01-01 end_date:2024-12-31 (yyyy-mm-dd format, inclusive)
+
+    Examples:
+
+    \b
+      copilot-session-tools search "python function"
+      copilot-session-tools search "role:user python"
+      copilot-session-tools search "workspace:my-project"
+      copilot-session-tools search "repo:github.com/owner/repo"
+      copilot-session-tools search "start_date:2024-01-01 end_date:2024-06-30"
+      copilot-session-tools search '"exact phrase"'
+
+    Use --role to filter by user requests or assistant responses.
+    Use --title to filter by session/workspace name.
+    Use --repository to filter by git repository URL.
+    Use --skip and --limit/--top for pagination.
+    Use --no-tools or --no-files to exclude specific content types.
+    Use --tools-only or --files-only to search only specific content types.
+    Use --full to show complete content instead of truncated snippets.
+    Use --sort to sort by relevance (default) or date.
+    """
+    if role and role not in ("user", "assistant"):
+        console.print("[red]Error: role must be 'user' or 'assistant'[/red]")
+        raise typer.Exit(1)
+
+    if sort_by not in ("relevance", "date"):
+        console.print("[red]Error: sort must be 'relevance' or 'date'[/red]")
+        raise typer.Exit(1)
+
+    # Handle search mode options
+    include_messages = True
+    include_tool_calls = not no_tools
+    include_file_changes = not no_files
+
+    if tools_only:
+        include_messages = False
+        include_file_changes = False
+        include_tool_calls = True
+    elif files_only:
+        include_messages = False
+        include_tool_calls = False
+        include_file_changes = True
+
+    database = Database(db)
+    results = database.search(
+        query,
+        limit=limit,
+        skip=skip,
+        role=role,
+        include_messages=include_messages,
+        include_tool_calls=include_tool_calls,
+        include_file_changes=include_file_changes,
+        session_title=title_filter,
+        sort_by=sort_by,
+        repository=repository_filter,
+    )
+
+    if not results:
+        console.print(f"[yellow]No results found for '{query}'[/yellow]")
+        return
+
+    # Display result count with pagination info
+    start_num = skip + 1
+    end_num = skip + len(results)
+    console.print(f"[green bold]Showing results {start_num}-{end_num} for '{query}':[/green bold]\n")
+
+    for i, result in enumerate(results, start_num):
+        console.print(f"[cyan bold]━━━ Result {i} ━━━[/cyan bold]")
+        console.print(f"[bright_blue bold]Session ID:[/bright_blue bold] {result['session_id']}")
+
+        if result.get("workspace_name"):
+            console.print(f"[bright_blue bold]Workspace:[/bright_blue bold]  [yellow]{result['workspace_name']}[/yellow]")
+
+        if result.get("custom_title"):
+            console.print(f"[bright_blue bold]Title:[/bright_blue bold]      {result['custom_title']}")
+
+        if result.get("created_at"):
+            formatted_date = format_timestamp(result["created_at"])
+            console.print(f"[bright_blue bold]Date:[/bright_blue bold]       [dim]{formatted_date}[/dim]")
+
+        role_color = "green" if result["role"] == "user" else "magenta"
+        console.print(f"[bright_blue bold]Role:[/bright_blue bold]       [{role_color}]{result['role']}[/{role_color}]")
+
+        if result.get("match_type") and result["match_type"] != "message":
+            console.print(f"[bright_blue bold]Match Type:[/bright_blue bold] [cyan]{result['match_type']}[/cyan]")
+
+        content = result["content"]
+        if not full_content and len(content) > 200:
+            content = content[:200] + "[dim]... (use --full to see more)[/dim]"
+        console.print(f"[bright_blue bold]Content:[/bright_blue bold]    {content}")
+        console.print()
+
+
+@app.command()
+def stats(
+    db: Annotated[
+        Path,
+        typer.Option(
+            "--db",
+            "-d",
+            help="Path to SQLite database file.",
+            exists=True,
+        ),
+    ] = Path("copilot_chats.db"),
+):
+    """Show database statistics."""
+    database = Database(db)
+    stats_data = database.get_stats()
+
+    console.print("[bold]Database Statistics:[/bold]")
+    console.print(f"  Sessions: {stats_data['session_count']}")
+    console.print(f"  Messages: {stats_data['message_count']}")
+    console.print(f"  Workspaces: {stats_data['workspace_count']}")
+
+    if stats_data["editions"]:
+        console.print("\n  [cyan]By VS Code Edition:[/cyan]")
+        for edition, count in stats_data["editions"].items():
+            console.print(f"    {edition}: {count}")
+
+    workspaces = database.get_workspaces()
+    if workspaces:
+        console.print("\n  [cyan]Workspaces:[/cyan]")
+        for ws in workspaces[:10]:
+            console.print(f"    {ws['workspace_name']}: {ws['session_count']} sessions")
+        if len(workspaces) > 10:
+            console.print(f"    ... and {len(workspaces) - 10} more")
+
+    repositories = database.get_repositories()
+    if repositories:
+        console.print("\n  [green]Repositories:[/green]")
+        for repo in repositories[:10]:
+            console.print(f"    {repo['repository_url']}: {repo['session_count']} sessions")
+        if len(repositories) > 10:
+            console.print(f"    ... and {len(repositories) - 10} more")
+
+
+@app.command()
+def export(
+    db: Annotated[
+        Path,
+        typer.Option(
+            "--db",
+            "-d",
+            help="Path to SQLite database file.",
+            exists=True,
+        ),
+    ] = Path("copilot_chats.db"),
+    output: Annotated[
+        str,
+        typer.Option(
+            "--output",
+            "-o",
+            help="Output file (- for stdout).",
+        ),
+    ] = "-",
+):
+    """Export the database as JSON."""
+    database = Database(db)
+    json_data = database.export_json()
+
+    if output == "-":
+        console.print(json_data)
+    else:
+        Path(output).write_text(json_data, encoding="utf-8")
+        console.print(f"[green]Exported to {output}[/green]")
+
+
+@app.command("export-markdown")
+def export_markdown(
+    db: Annotated[
+        Path,
+        typer.Option(
+            "--db",
+            "-d",
+            help="Path to SQLite database file.",
+            exists=True,
+        ),
+    ] = Path("copilot_chats.db"),
+    output_dir: Annotated[
+        Path,
+        typer.Option(
+            "--output-dir",
+            "-o",
+            help="Output directory for markdown files.",
+        ),
+    ] = Path(),
+    session_id: Annotated[
+        str | None,
+        typer.Option(
+            "--session-id",
+            "-s",
+            help="Export only a specific session by ID.",
+        ),
+    ] = None,
+    verbose: Annotated[
+        bool,
+        typer.Option(
+            "--verbose",
+            "-v",
+            help="Show verbose output.",
+        ),
+    ] = False,
+    include_diffs: Annotated[
+        bool,
+        typer.Option(
+            "--include-diffs/--no-diffs",
+            help="Include file diffs as code blocks in the markdown output.",
+        ),
+    ] = False,
+    include_tool_inputs: Annotated[
+        bool,
+        typer.Option(
+            "--include-tool-inputs/--no-tool-inputs",
+            help="Include tool inputs as code blocks in the markdown output.",
+        ),
+    ] = False,
+    include_thinking: Annotated[
+        bool,
+        typer.Option(
+            "--include-thinking/--no-thinking",
+            help="Include thinking/reasoning block content in the markdown output.",
+        ),
+    ] = False,
+):
+    """Export sessions as markdown files.
+
+    Each session is exported to a separate markdown file with:
+    - Header block with metadata (session ID, workspace, dates)
+    - Messages separated by horizontal rules
+    - Message numbers and roles as bold headers
+    - Tool call summaries in italics
+    - Thinking block notices in italics (content omitted)
+    """
+    database = Database(db)
+
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    if session_id:
+        session = database.get_session(session_id)
+        if session is None:
+            console.print(f"[red]Error: Session '{session_id}' not found.[/red]")
+            raise typer.Exit(1)
+
+        filename = generate_session_filename(session)
+        file_path = output_dir / filename
+        export_session_to_file(
+            session,
+            file_path,
+            include_diffs=include_diffs,
+            include_tool_inputs=include_tool_inputs,
+            include_thinking=include_thinking,
+        )
+        console.print(f"[green]Exported: {file_path}[/green]")
+    else:
+        sessions = database.list_sessions()
+        exported = 0
+
+        for session_info in sessions:
+            session = database.get_session(session_info["session_id"])
+            if session:
+                filename = generate_session_filename(session)
+                file_path = output_dir / filename
+                export_session_to_file(
+                    session,
+                    file_path,
+                    include_diffs=include_diffs,
+                    include_tool_inputs=include_tool_inputs,
+                    include_thinking=include_thinking,
+                )
+                exported += 1
+                if verbose:
+                    console.print(f"  Exported: {file_path}")
+
+        console.print(f"\n[green]Exported {exported} sessions to {output_dir}/[/green]")
+
+
+@app.command("export-html")
+def export_html(
+    db: Annotated[
+        Path,
+        typer.Option(
+            "--db",
+            "-d",
+            help="Path to SQLite database file.",
+            exists=True,
+        ),
+    ] = Path("copilot_chats.db"),
+    output_dir: Annotated[
+        Path,
+        typer.Option(
+            "--output-dir",
+            "-o",
+            help="Output directory for HTML files.",
+        ),
+    ] = Path(),
+    session_id: Annotated[
+        str | None,
+        typer.Option(
+            "--session-id",
+            "-s",
+            help="Export only a specific session by ID.",
+        ),
+    ] = None,
+    verbose: Annotated[
+        bool,
+        typer.Option(
+            "--verbose",
+            "-v",
+            help="Show verbose output.",
+        ),
+    ] = False,
+):
+    """Export sessions as self-contained static HTML files.
+
+    Each session is exported to a separate HTML file with the same rich
+    rendering as the web viewer, but without interactive elements (toolbar,
+    copy buttons, AJAX). The HTML is self-contained with no external
+    dependencies.
+    """
+    database = Database(db)
+
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    if session_id:
+        session = database.get_session(session_id)
+        if session is None:
+            console.print(f"[red]Error: Session '{session_id}' not found.[/red]")
+            raise typer.Exit(1)
+
+        filename = generate_session_html_filename(session)
+        file_path = output_dir / filename
+        export_session_to_html_file(session, file_path)
+        console.print(f"[green]Exported: {file_path}[/green]")
+    else:
+        sessions = database.list_sessions()
+        exported = 0
+
+        for session_info in sessions:
+            session = database.get_session(session_info["session_id"])
+            if session:
+                filename = generate_session_html_filename(session)
+                file_path = output_dir / filename
+                export_session_to_html_file(session, file_path)
+                exported += 1
+                if verbose:
+                    console.print(f"  Exported: {file_path}")
+
+        console.print(f"\n[green]Exported {exported} sessions to {output_dir}/[/green]")
+
+
+@app.command("import-json")
+def import_json(
+    json_file: Annotated[
+        Path,
+        typer.Argument(
+            help="JSON file to import.",
+            exists=True,
+        ),
+    ],
+    db: Annotated[
+        Path,
+        typer.Option(
+            "--db",
+            "-d",
+            help="Path to SQLite database file.",
+        ),
+    ] = Path("copilot_chats.db"),
+):
+    """Import sessions from a JSON file."""
+    import json
+
+    database = Database(db)
+
+    with json_file.open(encoding="utf-8") as f:
+        data = json.load(f)
+
+    if not isinstance(data, list):
+        console.print("[red]Error: JSON file must contain an array of sessions.[/red]")
+        raise typer.Exit(1)
+
+    added = 0
+    skipped = 0
+
+    for item in data:
+        if not isinstance(item, dict):
+            continue
+
+        messages = [
+            ChatMessage(
+                role=m.get("role", "unknown"),
+                content=m.get("content", ""),
+                timestamp=m.get("timestamp"),
+            )
+            for m in item.get("messages", [])
+        ]
+
+        session = ChatSession(
+            session_id=item.get("session_id", str(hash(str(item)))),
+            workspace_name=item.get("workspace_name"),
+            workspace_path=item.get("workspace_path"),
+            messages=messages,
+            created_at=item.get("created_at"),
+            updated_at=item.get("updated_at"),
+            source_file=str(json_file),
+            vscode_edition=item.get("vscode_edition", "imported"),
+        )
+
+        if database.add_session(session):
+            added += 1
+        else:
+            skipped += 1
+
+    console.print("[green]Import complete:[/green]")
+    console.print(f"  Added: {added} sessions")
+    console.print(f"  Skipped: {skipped} sessions")
+
+
+@app.command()
+def rebuild(
+    db: Annotated[
+        Path,
+        typer.Option(
+            "--db",
+            "-d",
+            help="Path to SQLite database file.",
+            exists=True,
+        ),
+    ] = Path("copilot_chats.db"),
+    verbose: Annotated[
+        bool,
+        typer.Option(
+            "--verbose",
+            "-v",
+            help="Show verbose output.",
+        ),
+    ] = False,
+):
+    """Rebuild derived tables from raw JSON data.
+
+    This command drops all derived tables (sessions, messages, tool_invocations,
+    file_changes, command_runs, content_blocks) and recreates them from the
+    compressed raw JSON stored in raw_sessions.
+
+    Use this after schema changes to regenerate all derived data without needing
+    to re-scan the original VS Code storage.
+    """
+    database = Database(db)
+
+    # Check if there are any raw sessions to rebuild from
+    raw_count = database.get_raw_session_count()
+    if raw_count == 0:
+        console.print("[yellow]Warning: No raw sessions found in database.[/yellow]")
+        console.print("Run 'copilot-session-tools scan' first to import sessions.")
+        raise typer.Exit(1)
+
+    console.print(f"Rebuilding {raw_count} sessions from raw JSON...")
+
+    def progress_callback(processed, total):
+        if verbose:
+            console.print(f"  Processed: {processed}/{total}")
+
+    result = database.rebuild_derived_tables(progress_callback=progress_callback if verbose else None)
+
+    console.print("\n[green]Rebuild complete:[/green]")
+    console.print(f"  Processed: {result['processed']} sessions")
+    if result["errors"] > 0:
+        console.print(f"  Errors: {result['errors']} sessions")
+
+    stats = database.get_stats()
+    console.print("\n[cyan]Database now contains:[/cyan]")
+    console.print(f"  {stats['session_count']} sessions")
+    console.print(f"  {stats['message_count']} messages")
+    console.print(f"  {stats['workspace_count']} workspaces")
+
+
+@app.command()
+def optimize(
+    db: Annotated[
+        Path,
+        typer.Option(
+            "--db",
+            "-d",
+            help="Path to SQLite database file.",
+            exists=True,
+        ),
+    ] = Path("copilot_chats.db"),
+):
+    """Optimize the full-text search index for better query performance.
+
+    This command merges FTS5 index segments, reducing fragmentation and
+    improving search speed. Recommended to run periodically, especially
+    after bulk imports or the rebuild command.
+
+    The optimization process:
+    1. Merges all FTS index segments into fewer, larger segments
+    2. Runs an integrity check to verify index consistency
+    """
+    database = Database(db)
+
+    console.print("Optimizing FTS5 search index...")
+
+    result = database.optimize_fts()
+
+    console.print("\n[green]Optimization complete:[/green]")
+    console.print(f"  Index segments before: {result['segments_before']}")
+    console.print(f"  Index segments after:  {result['segments_after']}")
+
+    if result["segments_before"] > result["segments_after"]:
+        reduction = result["segments_before"] - result["segments_after"]
+        console.print(f"  [cyan]Merged {reduction} segments for faster queries[/cyan]")
+    else:
+        console.print("  [dim]Index was already optimized[/dim]")
+
+
+@app.command("raw-json")
+def raw_json(
+    session_id: Annotated[
+        str,
+        typer.Argument(help="Session ID to retrieve raw JSON for."),
+    ],
+    db: Annotated[
+        Path,
+        typer.Option(
+            "--db",
+            "-d",
+            help="Path to SQLite database file.",
+            exists=True,
+        ),
+    ] = Path("copilot_chats.db"),
+    output: Annotated[
+        Path | None,
+        typer.Option(
+            "--output",
+            "-o",
+            help="Output file path. If not specified, prints to stdout.",
+        ),
+    ] = None,
+    db_only: Annotated[
+        bool,
+        typer.Option(
+            "--db-only",
+            help="Only use database copy, don't try reading from source file.",
+        ),
+    ] = False,
+):
+    """Get the raw JSON for a specific session.
+
+    By default, tries to read from the original source file first (if it exists),
+    falling back to the compressed database copy. Use --db-only to always use
+    the database copy.
+
+    This is useful for debugging, data recovery, or inspecting the original
+    session data format.
+    """
+    database = Database(db)
+
+    raw_data = database.get_raw_json(session_id, prefer_file=not db_only)
+
+    if raw_data is None:
+        console.print(f"[red]Session not found: {session_id}[/red]")
+        raise typer.Exit(1)
+
+    if output:
+        output.write_bytes(raw_data)
+        console.print(f"[green]Wrote {len(raw_data)} bytes to {output}[/green]")
+    else:
+        # Print to stdout (decode as UTF-8 for display)
+        try:
+            print(raw_data.decode("utf-8"))
+        except UnicodeDecodeError as err:
+            console.print("[red]Error: Raw data is not valid UTF-8. Use --output to save to file.[/red]")
+            raise typer.Exit(1) from err
+
+
+@app.command()
+def web(
+    db: Annotated[Path, typer.Option("--db", "-d", help="Path to SQLite database file.")] = Path("copilot_chats.db"),
+    host: Annotated[str, typer.Option("--host", "-H", help="Host to bind to.")] = "127.0.0.1",
+    port: Annotated[int, typer.Option("--port", "-p", help="Port to bind to.")] = 5000,
+    title: Annotated[str, typer.Option("--title", "-t", help="Title for the archive.")] = "Copilot Chat Archive",
+    debug: Annotated[bool, typer.Option("--debug", help="Enable debug mode.")] = False,
+):
+    """Start the web viewer for browsing chat sessions."""
+    try:
+        from copilot_session_tools.web import run_server
+    except ImportError as err:
+        console.print("[red]Web interface requires the [web] extra.[/red]")
+        console.print("Install with: pip install copilot-session-tools[web]")
+        raise typer.Exit(1) from err
+
+    if not db.exists():
+        console.print(f"[red]Database file '{db}' not found.[/red]")
+        console.print("Run 'copilot-session-tools scan' first to import chat sessions.")
+        raise typer.Exit(1)
+
+    database = Database(str(db))
+    db_stats = database.get_stats()
+
+    if db_stats["session_count"] == 0:
+        console.print("[yellow]Warning: Database is empty. Run 'copilot-session-tools scan' first.[/yellow]")
+
+    console.print("Starting web server...")
+    console.print(f"  Database: {db}")
+    console.print(f"  Sessions: {db_stats['session_count']}")
+    console.print(f"  Messages: {db_stats['message_count']}")
+    console.print(f"\nOpen http://{host}:{port}/ in a browser to view your archive.")
+    console.print("Press Ctrl+C to stop the server.\n")
+
+    run_server(
+        host=host,
+        port=port,
+        db_path=str(db),
+        title=title,
+        debug=debug,
+    )
+
+
+def run():
+    """Entry point for the CLI."""
+    app()
+
+
+if __name__ == "__main__":
+    run()