apisec-code-bolt 0.1.0__py3-none-any.whl

apisec_code_bolt/cli/main.py

@@ -0,0 +1,1069 @@
+"""
+Command-line interface for apisec-code-bolt.
+
+This module defines the CLI commands using Click.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any
+
+import click
+from rich.console import Console
+from rich.panel import Panel
+from rich.progress import Progress, SpinnerColumn, TextColumn
+from rich.table import Table
+
+from .. import __version__
+from ..core.config import DEFAULT_API_URL, CodeBoltConfig
+from ..core.log_format import analyzer_summary, log_error, log_info, log_warning
+from .exit_codes import ExitCode
+
+# Rich console for pretty output
+console = Console()
+error_console = Console(stderr=True)
+
+
+# =============================================================================
+# CLI Group
+# =============================================================================
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="apisec-code-bolt")
+@click.option(
+    "-v",
+    "--verbose",
+    is_flag=True,
+    help="Enable verbose output.",
+)
+@click.option(
+    "-q",
+    "--quiet",
+    is_flag=True,
+    help="Suppress non-essential output.",
+)
+@click.option(
+    "--debug",
+    is_flag=True,
+    help="Enable debug mode.",
+)
+@click.option(
+    "--log-format",
+    "log_format",
+    type=click.Choice(["text", "json"]),
+    default="text",
+    envvar="APISEC_LOG_FORMAT",
+    help="Log output format. 'json' emits NDJSON to stderr for pipeline use.",
+)
+@click.pass_context
+def cli(ctx: click.Context, verbose: bool, quiet: bool, debug: bool, log_format: str) -> None:
+    """
+    apisec-code-bolt — Extract architectural metadata from your codebase.
+
+    Analyze source code to extract routes, data flows, authentication patterns,
+    and more. Output is a structured manifest that can be uploaded to the
+    APIsec cloud for vulnerability analysis.
+    """
+    ctx.ensure_object(dict)
+    ctx.obj["verbose"] = verbose
+    ctx.obj["quiet"] = quiet
+    ctx.obj["debug"] = debug
+    ctx.obj["log_format"] = log_format
+
+
+# =============================================================================
+# Analyze Command
+# =============================================================================
+
+
+@cli.command()
+@click.argument(
+    "path",
+    type=click.Path(exists=True, file_okay=False, resolve_path=True, path_type=Path),
+    default=".",
+)
+@click.option(
+    "-o",
+    "--output",
+    type=click.Path(dir_okay=False, path_type=Path),
+    help="Save manifest to file instead of uploading.",
+)
+@click.option(
+    "--no-upload",
+    is_flag=True,
+    help="Skip uploading to cloud (implies --output if not set).",
+)
+@click.option(
+    "--cloud-url",
+    type=str,
+    default=None,
+    help="Reasoning engine URL (e.g., http://localhost:8100). Legacy: direct connection for local dev.",
+)
+@click.option(
+    "--api-key",
+    "api_key_override",
+    type=str,
+    help="Override stored API key.",
+)
+@click.option(
+    "--api-url",
+    "api_url_override",
+    type=str,
+    help="Override stored API URL.",
+)
+@click.option(
+    "--reasoning-url",
+    type=str,
+    help="Reasoning engine URL (if different from API URL).",
+)
+@click.option(
+    "--format",
+    "output_format",
+    type=click.Choice(["json", "yaml"]),
+    default="json",
+    help="Output format.",
+)
+@click.option(
+    "--config",
+    "config_file",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    help="Path to configuration file.",
+)
+@click.option(
+    "--frameworks",
+    type=str,
+    help="Comma-separated framework hints (e.g., fastapi,sqlalchemy).",
+)
+@click.option(
+    "--exclude",
+    multiple=True,
+    help="Glob patterns to exclude. Can be repeated.",
+)
+@click.option(
+    "--max-files",
+    type=int,
+    help="Maximum files to analyze.",
+)
+@click.option(
+    "--timeout",
+    type=int,
+    help="Analysis timeout in seconds.",
+)
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    help="Analyse project and print summary, but do not write or upload manifest.",
+)
+@click.option(
+    "--stdout",
+    "output_stdout",
+    is_flag=True,
+    help="Write manifest JSON to stdout instead of a file (for pipeline use).",
+)
+@click.pass_context
+def analyze(
+    ctx: click.Context,
+    path: Path,
+    output: Path | None,
+    no_upload: bool,
+    cloud_url: str | None,
+    api_key_override: str | None,
+    api_url_override: str | None,
+    reasoning_url: str | None,
+    output_format: str,
+    config_file: Path | None,
+    frameworks: str | None,
+    exclude: tuple[str, ...],
+    max_files: int | None,
+    timeout: int | None,
+    dry_run: bool = False,
+    output_stdout: bool = False,
+) -> None:
+    log_format: str = ctx.obj.get("log_format", "text")
+    """
+    Analyze a codebase and generate a manifest.
+
+    PATH is the root directory of the project to analyze.
+    Defaults to the current directory.
+
+    \b
+    Examples:
+        # Analyze current directory and save locally
+        apisec-code-bolt analyze . --no-upload
+
+        # Analyze and save to specific file
+        apisec-code-bolt analyze . --output manifest.json --no-upload
+
+        # Analyze and run verification against local reasoning engine
+        apisec-code-bolt analyze . --cloud-url http://localhost:8100
+
+        # Analyze with framework hints
+        apisec-code-bolt analyze . --frameworks fastapi,sqlalchemy
+    """
+    verbose = ctx.obj.get("verbose", False)
+    quiet = ctx.obj.get("quiet", False)
+
+    if api_key_override and not quiet:
+        error_console.print(
+            "[yellow]Warning: passing API keys via CLI arguments exposes them in "
+            "process listings. Prefer the CODEBOLT_API_KEY env var or the "
+            "'apisec-code-bolt auth' command.[/yellow]"
+        )
+
+    # Build configuration
+    config_overrides: dict[str, Any] = {}
+
+    if frameworks:
+        config_overrides["analysis.framework_hints"] = frameworks.split(",")
+    if exclude:
+        config_overrides["analysis.file_discovery.exclude_patterns"] = list(exclude)
+    if max_files:
+        config_overrides["analysis.file_discovery.max_files"] = max_files
+    if timeout:
+        config_overrides["analysis.timeout_seconds"] = timeout
+    if no_upload:
+        config_overrides["cloud.enabled"] = False
+    if output:
+        config_overrides["output.output_file"] = output
+    config_overrides["output.format"] = output_format
+
+    try:
+        config = CodeBoltConfig.from_cli(
+            project_root=path,
+            config_file=config_file,
+            **config_overrides,
+        )
+    except Exception as e:
+        error_console.print(f"[red]Configuration error:[/red] {e}")
+        sys.exit(ExitCode.CONFIG_ERROR)
+
+    # Registration code — required on first run, stored and never asked again.
+    # Subsequent runs use the installation ID hash only.
+    from ..core.telemetry import (
+        check_first_run_notice,
+        emit_install_event,
+        needs_registration,
+        set_registration_code,
+    )
+
+    if needs_registration():
+        import os
+
+        env_code = os.environ.get("APISEC_REGISTRATION_CODE", "").strip()
+        if env_code:
+            code = env_code
+        elif quiet or log_format == "json":
+            error_console.print(
+                "[red]Error:[/red] No registration code found. "
+                "Set APISEC_REGISTRATION_CODE or run interactively."
+            )
+            sys.exit(ExitCode.CONFIG_ERROR)
+        else:
+            console.print(
+                "\n[bold]This is an installation prompt.[/bold]\n"
+                "[dim]Your registration code was provided by APIsec during onboarding.[/dim]"
+            )
+            code = click.prompt("Please enter code (###-###)").strip()
+
+        if not code:
+            error_console.print("[red]Error:[/red] Registration code cannot be empty.")
+            sys.exit(ExitCode.CONFIG_ERROR)
+
+        set_registration_code(code)
+
+        # Fire the install event — includes code + hash, happens exactly once
+        import contextlib
+
+        with contextlib.suppress(Exception):
+            emit_install_event(probe_version=__version__)
+
+    # Opt-out notice (shown once, after registration)
+    check_first_run_notice(quiet=quiet, json_mode=(log_format == "json"))
+
+    if log_format == "json":
+        log_info("scan_start", version=__version__, project=str(path))
+    elif not quiet:
+        console.print(
+            Panel(
+                f"[bold]Analyzing:[/bold] {path}\n[dim]Version: {__version__}[/dim]",
+                title="apisec-code-bolt",
+                border_style="blue",
+            )
+        )
+
+    # Run analysis
+    from ..analysis import analyze_project
+
+    try:
+        if not quiet and log_format != "json":
+            with Progress(
+                SpinnerColumn(),
+                TextColumn("[progress.description]{task.description}"),
+                console=console,
+            ) as progress:
+                progress.add_task("Analyzing project...", total=None)
+                result = analyze_project(config)
+        else:
+            result = analyze_project(config)
+
+        # Emit telemetry (fire-and-forget, opt-in only)
+        try:
+            from ..core.telemetry import emit_analyze_event
+
+            emit_analyze_event(
+                probe_version=__version__,
+                files_analyzed=result.files_analyzed,
+                files_failed=result.files_failed,
+                files_skipped=getattr(result, "files_skipped", 0),
+                frameworks=result.manifest.project.frameworks_detected,
+                languages=result.manifest.project.languages_detected,
+                routes_found=len(result.manifest.entry_points),
+                routes_by_framework=getattr(result, "routes_by_framework", {}),
+                analysis_time_ms=result.total_time_ms,
+                parse_time_ms=result.parse_time_ms,
+                extraction_time_ms=result.extraction_time_ms,
+                stage_times_ms=getattr(result, "stage_times_ms", {}),
+                extractor_times_ms=getattr(result, "extractor_times_ms", {}),
+                has_errors=bool(result.parse_errors),
+            )
+        except Exception:
+            pass  # Telemetry must never break the CLI
+
+        # --stdout: write manifest JSON to stdout and return
+        if output_stdout:
+            sys.stdout.write(result.manifest.to_json(pretty=False))
+            sys.stdout.write("\n")
+            sys.stdout.flush()
+            if log_format == "json":
+                _emit_json_summary(path, result)
+            return
+
+        # --dry-run: print summary and return without writing
+        if dry_run:
+            if log_format == "json":
+                _emit_json_summary(path, result)
+            elif not quiet:
+                console.print()
+                console.print("[bold yellow]Dry run — manifest not written.[/bold yellow]")
+                console.print(f"  Routes: {len(result.manifest.entry_points)}")
+                console.print(f"  Files analyzed: {result.files_analyzed}")
+                console.print(
+                    f"  Frameworks: {', '.join(result.manifest.project.frameworks_detected) or 'None'}"
+                )
+            return
+
+        # Save manifest locally
+        if output:
+            output_path = output
+        else:
+            apisec_dir = path / "apisec"
+            apisec_dir.mkdir(exist_ok=True)
+            output_path = apisec_dir / "manifest.json"
+        manifest_json = result.manifest.to_json(pretty=True)
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        output_path.write_text(manifest_json)
+
+        if log_format == "json":
+            _emit_json_summary(path, result, output_path=output_path)
+        elif not quiet:
+            console.print(f"\n[green]✓ Manifest saved to {output_path}[/green]")
+
+        # Display summary (text mode only)
+        if log_format != "json" and not quiet:
+            console.print()
+
+            table = Table(title="Analysis Summary")
+            table.add_column("Metric", style="cyan")
+            table.add_column("Value", style="green")
+
+            table.add_row("Project", result.manifest.project.name or "Unknown")
+            table.add_row("Files Analyzed", str(result.files_analyzed))
+            table.add_row("Files Failed", str(result.files_failed))
+            table.add_row("Routes Found", str(len(result.manifest.entry_points)))
+            table.add_row("Functions", str(len(result.manifest.functions)))
+            table.add_row("Classes", str(len(result.manifest.classes)))
+            table.add_row(
+                "Frameworks", ", ".join(result.manifest.project.frameworks_detected) or "None"
+            )
+            table.add_row("Analysis Time", f"{result.total_time_ms}ms")
+
+            console.print(table)
+
+            if result.manifest.entry_points:
+                console.print()
+                routes_table = Table(title="Routes Detected")
+                routes_table.add_column("Method", style="yellow")
+                routes_table.add_column("Path", style="cyan")
+                routes_table.add_column("Handler", style="green")
+
+                for route in result.manifest.entry_points[:20]:
+                    routes_table.add_row(route.method, route.path, route.handler_function)
+
+                if len(result.manifest.entry_points) > 20:
+                    routes_table.add_row(
+                        "...", f"({len(result.manifest.entry_points) - 20} more)", "..."
+                    )
+
+                console.print(routes_table)
+
+            if result.parse_errors:
+                console.print()
+                console.print(
+                    f"[yellow]⚠ {len(result.parse_errors)} files failed to parse[/yellow]"
+                )
+                if verbose:
+                    for err in result.parse_errors[:10]:
+                        console.print(f"  [dim]{err}[/dim]")
+
+        # Two-phase authenticated upload (default when not --no-upload)
+        if not no_upload:
+            _run_authenticated_upload(
+                ctx,
+                path,
+                result,
+                api_key_override,
+                api_url_override,
+                reasoning_url,
+                quiet,
+            )
+        elif cloud_url:
+            # Legacy: direct connection to reasoning engine (for local dev)
+            _run_verification_loop(path, result, cloud_url, quiet)
+
+    except Exception as e:
+        if ctx.obj.get("log_format") == "json":
+            log_error("scan_failed", error=str(e))
+        else:
+            error_console.print(f"[red]Analysis failed:[/red] {e}")
+        if ctx.obj.get("debug"):
+            import traceback
+
+            error_console.print(traceback.format_exc())
+        try:
+            from ..core.telemetry import emit_error_event
+
+            emit_error_event(
+                probe_version=__version__,
+                error_type=type(e).__name__,
+            )
+        except Exception:
+            pass
+        sys.exit(ExitCode.MANIFEST_ERROR)
+
+
+def _emit_json_summary(
+    project_root: Path,
+    result: Any,
+    output_path: Path | None = None,
+) -> None:
+    """Emit the structured scan_complete record to stderr."""
+    summary = analyzer_summary(project_root, result, __version__)
+    if output_path is not None:
+        summary["manifest_path"] = str(output_path)
+    # Emit individual parse_error warning records with file:line context
+    details = getattr(result, "parse_error_details", None)
+    if details:
+        for detail in details:
+            log_warning("parse_error", **detail)
+    else:
+        for err in result.parse_errors:
+            if ": " in err:
+                file_part, _, msg = err.partition(": ")
+                log_warning("parse_error", file=file_part, error=msg)
+            else:
+                log_warning("parse_error", file="", error=err)
+    import json
+    import sys
+
+    sys.stderr.write(json.dumps(summary, default=str) + "\n")
+    sys.stderr.flush()
+
+
+def _run_authenticated_upload(
+    ctx: click.Context,
+    project_path: Path,
+    result: Any,
+    api_key_override: str | None,
+    api_url_override: str | None,
+    reasoning_url_override: str | None,
+    quiet: bool,
+) -> None:
+    """Register surface with applicationsservice (PAT), then upload manifest to the reasoning engine (same PAT + app_id)."""
+    import json
+    import os
+
+    from ..cloud.apisec_client import ApisecClient, RepoInfo
+    from ..core.credentials import load_credentials
+    from ..core.repo import detect_repo_info
+    from ..core.state import RepoState, read_state, write_state
+
+    pat = api_key_override or os.environ.get("APISEC_PAT")
+    api_url = api_url_override
+    if pat is None or api_url is None:
+        creds = load_credentials()
+        if creds:
+            pat = pat or creds.api_key
+            api_url = api_url or creds.api_url
+
+    if not pat or not api_url:
+        error_console.print(
+            "[red]No PAT or applicationsservice URL. Set APISEC_PAT (or pass --api-key), "
+            "API_APPLICATIONSSERVICE_URL (or --api-url), or run: "
+            "apisec-code-bolt auth <pat> --api-url https://...[/red]",
+        )
+        sys.exit(1)
+
+    repo_info_dict = detect_repo_info(project_path)
+    repo_info = RepoInfo(
+        repo_name=repo_info_dict["repo_name"],
+        repo_url=repo_info_dict["repo_url"],
+        branch=repo_info_dict["branch"],
+        commit_sha=repo_info_dict["commit_sha"],
+        scm_provider=repo_info_dict["scm_provider"],
+        canonical_repo_id=repo_info_dict["canonical_repo_id"],
+    )
+
+    client = ApisecClient(api_url=api_url, pat=pat)
+
+    if not quiet:
+        console.print()
+        console.print(
+            Panel(
+                f"[bold]Authenticated upload[/bold]\n"
+                f"Applicationsservice: {api_url}\n"
+                f"Repo: {repo_info.repo_name} ({repo_info.branch})\n"
+                f"Canonical id: {repo_info.canonical_repo_id}",
+                title="Cloud connection",
+                border_style="green",
+            )
+        )
+
+    try:
+        prior = read_state(project_path)
+        existing_app_id = prior.application_id if prior else None
+        registration = client.register(
+            repo_info,
+            existing_app_id=existing_app_id,
+            force_new_application=existing_app_id is None,
+        )
+
+        write_state(project_path, RepoState(application_id=registration.app_id))
+
+        manifest_data = json.loads(result.manifest.to_json())
+        upload_result = client.upload_and_verify(
+            registration,
+            manifest_data,
+            project_path,
+            reasoning_engine_url=reasoning_url_override,
+        )
+
+        if not quiet:
+            console.print()
+            vtable = Table(title="Verification Result")
+            vtable.add_column("Metric", style="cyan")
+            vtable.add_column("Value", style="green")
+            vtable.add_row("Analysis ID", upload_result.get("analysis_id") or "N/A")
+            vtable.add_row("Status", upload_result.get("status", "unknown"))
+            vtable.add_row("Rounds", str(upload_result.get("rounds", 0)))
+            vtable.add_row("Questions Answered", str(upload_result.get("questions_answered", 0)))
+            vtable.add_row("Duration", f"{upload_result.get('elapsed_seconds', 0):.1f}s")
+            if upload_result.get("error"):
+                vtable.add_row("Error", f"[red]{upload_result['error']}[/red]")
+            console.print(vtable)
+
+            console.print()
+            console.print(
+                Panel(
+                    f"http://localhost:5174/application/{registration.app_id}",
+                    title="View Results in APIsec",
+                    border_style="cyan",
+                )
+            )
+    except Exception as e:
+        error_console.print(f"[red]Upload failed:[/red] {e}")
+        if ctx and ctx.obj.get("debug"):
+            import traceback
+
+            error_console.print(traceback.format_exc())
+        sys.exit(1)
+
+
+def _run_verification_loop(
+    project_path: Path,
+    result: Any,
+    cloud_url: str,
+    quiet: bool,
+) -> None:
+    """Upload manifest and run the verification question/answer loop (PAT + app_id required)."""
+    import json
+    import os
+
+    from ..cloud.client import CloudClient
+    from ..core.credentials import load_credentials
+    from ..core.state import read_state
+    from ..query.executor import QueryExecutor
+
+    pat = os.environ.get("APISEC_PAT")
+    creds = load_credentials()
+    if not pat and creds:
+        pat = creds.api_key
+    prior = read_state(project_path)
+    app_id = os.environ.get("APISEC_APP_ID") or (prior.application_id if prior else None)
+    if not pat or not app_id:
+        error_console.print(
+            "[red]--cloud-url requires APISEC_PAT (or stored credentials) and an application id. "
+            "Set APISEC_APP_ID or run a full upload once so apisec-code-bolt/state.yaml "
+            "contains applicationId.[/red]",
+        )
+        sys.exit(1)
+
+    if not quiet:
+        console.print()
+        console.print(
+            Panel(
+                f"[bold]Verification loop[/bold]\nEngine: {cloud_url}",
+                title="Cloud connection",
+                border_style="green",
+            )
+        )
+
+    manifest_data = json.loads(result.manifest.to_json())
+
+    is_local = any(h in cloud_url for h in ("localhost", "127.0.0.1", "[::1]"))
+    if not is_local:
+        error_console.print(
+            "[yellow]Warning: --cloud-url points to a remote host. "
+            "TLS verification is only disabled for localhost. "
+            "Pass --insecure to override.[/yellow]"
+        )
+    with CloudClient(
+        api_url=cloud_url,
+        api_key=pat,
+        app_id=app_id,
+        verify_ssl=not is_local,
+        timeout_seconds=600,
+    ) as client:
+        executor = QueryExecutor(project_root=project_path, max_batches=100, max_wait=600)
+
+        if not quiet:
+            with Progress(
+                SpinnerColumn(),
+                TextColumn("[progress.description]{task.description}"),
+                console=console,
+            ) as progress:
+                progress.add_task("Running verification...", total=None)
+                exec_result = executor.run_connected(client, manifest_data)
+        else:
+            exec_result = executor.run_connected(client, manifest_data)
+
+    if not quiet:
+        console.print()
+        vtable = Table(title="Verification Result")
+        vtable.add_column("Metric", style="cyan")
+        vtable.add_column("Value", style="green")
+        vtable.add_row("Analysis ID", exec_result.analysis_id or "N/A")
+        vtable.add_row("Status", exec_result.final_status)
+        vtable.add_row("Rounds", str(exec_result.stats.rounds_completed))
+        vtable.add_row("Questions Answered", str(exec_result.stats.questions_answered))
+        vtable.add_row("Duration", f"{exec_result.stats.elapsed_seconds:.1f}s")
+        if exec_result.error:
+            vtable.add_row("Error", f"[red]{exec_result.error}[/red]")
+        console.print(vtable)
+
+
+# =============================================================================
+# Auth Command
+# =============================================================================
+
+
+@cli.command()
+@click.argument("api_key", required=False)
+@click.option(
+    "--api-url",
+    type=str,
+    default=DEFAULT_API_URL,
+    help="APIsec API URL.",
+)
+@click.option(
+    "--check",
+    is_flag=True,
+    help="Check if already authenticated.",
+)
+@click.option(
+    "--logout",
+    is_flag=True,
+    help="Remove stored credentials.",
+)
+@click.pass_context
+def auth(
+    ctx: click.Context,
+    api_key: str | None,
+    api_url: str,
+    check: bool,
+    logout: bool,
+) -> None:
+    """
+    Authenticate with the APIsec cloud.
+
+    \b
+    Examples:
+        # Interactive authentication
+        apisec-code-bolt auth
+
+        # Direct authentication
+        apisec-code-bolt auth sk_live_abc123...
+
+        # Check authentication status
+        apisec-code-bolt auth --check
+    """
+    from ..core.credentials import (
+        clear_credentials,
+        load_credentials,
+        store_credentials,
+    )
+
+    quiet = ctx.obj.get("quiet", False)
+
+    if logout:
+        clear_credentials()
+        if not quiet:
+            console.print("[green]Credentials removed.[/green]")
+        return
+
+    if check:
+        creds = load_credentials()
+        if creds and creds.api_key:
+            key = creds.api_key
+            masked = f"{key[:12]}...{key[-4:]}" if len(key) > 16 else f"{key[:4]}..."
+            if not quiet:
+                console.print(f"[green]Authenticated[/green] — API key: {masked}")
+                console.print(f"  API URL: {creds.api_url}")
+        else:
+            if not quiet:
+                console.print(
+                    "[yellow]Not authenticated. Run: apisec-code-bolt auth <api-key>[/yellow]"
+                )
+        return
+
+    if not api_key:
+        api_key = click.prompt("Enter your API key", hide_input=True)
+
+    path = store_credentials(api_key, api_url)
+    if not quiet:
+        console.print(f"[green]API key stored at {path}[/green]")
+
+
+# =============================================================================
+# Answer Command (Air-gapped mode)
+# =============================================================================
+
+
+@cli.command()
+@click.option(
+    "-q",
+    "--questions",
+    "questions_file",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    required=True,
+    help="Input questions file (JSON).",
+)
+@click.option(
+    "-o",
+    "--output",
+    type=click.Path(dir_okay=False, path_type=Path),
+    default="answers.json",
+    help="Output answers file.",
+)
+@click.option(
+    "-r",
+    "--repo",
+    type=click.Path(exists=True, file_okay=False, path_type=Path),
+    default=".",
+    help="Repository path.",
+)
+@click.option(
+    "--timeout",
+    type=int,
+    default=300,
+    help="Query timeout in seconds.",
+)
+@click.pass_context
+def answer(
+    ctx: click.Context,
+    questions_file: Path,
+    output: Path,
+    repo: Path,
+    timeout: int,
+) -> None:
+    """
+    Answer verification queries from a questions file.
+
+    This is for air-gapped environments where the manifest was uploaded
+    separately and the cloud generated questions that need answers.
+
+    \b
+    Examples:
+        # Answer questions about current repo
+        apisec-code-bolt answer --questions questions.json
+
+        # Answer questions about specific repo
+        apisec-code-bolt answer -q questions.json -r /path/to/repo -o answers.json
+    """
+    quiet = ctx.obj.get("quiet", False)
+
+    if not quiet:
+        console.print(
+            Panel(
+                f"[bold]Answering queries[/bold]\n"
+                f"Questions: {questions_file}\n"
+                f"Repository: {repo}\n"
+                f"Output: {output}",
+                title="apisec-code-bolt",
+                border_style="blue",
+            )
+        )
+
+    from ..query.executor import QueryExecutor
+
+    executor = QueryExecutor(project_root=repo)
+
+    if not quiet:
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            console=console,
+        ) as progress:
+            progress.add_task("Answering queries...", total=None)
+            exec_result = executor.run_airgapped(questions_file, output)
+    else:
+        exec_result = executor.run_airgapped(questions_file, output)
+
+    if not quiet:
+        console.print()
+        if exec_result.final_status == "complete":
+            console.print(
+                f"[green]✓ Answered {exec_result.stats.questions_answered} questions[/green]"
+            )
+            console.print(f"  Output: {output}")
+        else:
+            console.print(f"[red]✗ Failed: {exec_result.error or exec_result.final_status}[/red]")
+
+
+# =============================================================================
+# Validate Command
+# =============================================================================
+
+
+@cli.command()
+@click.argument(
+    "manifest_file",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+)
+@click.pass_context
+def validate(ctx: click.Context, manifest_file: Path) -> None:
+    """
+    Validate a manifest file against the schema.
+
+    Useful for testing and debugging manifest generation.
+    """
+    quiet = ctx.obj.get("quiet", False)
+
+    if not quiet:
+        console.print(f"[dim]Validating: {manifest_file}[/dim]")
+
+    try:
+        import json
+
+        from ..core.manifest import Manifest
+
+        content = manifest_file.read_text()
+        data = json.loads(content)
+        Manifest.model_validate(data)
+
+        if not quiet:
+            console.print("[green]✓ Manifest is valid[/green]")
+            # Show summary
+            manifest = Manifest.model_validate(data)
+            console.print(f"  Project: {manifest.project.name or 'Unknown'}")
+            console.print(f"  Routes: {len(manifest.entry_points)}")
+            console.print(f"  Functions: {len(manifest.functions)}")
+            console.print(f"  Data flows: {len(manifest.data_flows)}")
+    except json.JSONDecodeError as e:
+        error_console.print(f"[red]Invalid JSON:[/red] {e}")
+        sys.exit(1)
+    except Exception as e:
+        error_console.print(f"[red]Validation failed:[/red] {e}")
+        if ctx.obj.get("debug"):
+            import traceback
+
+            error_console.print(traceback.format_exc())
+        sys.exit(1)
+
+
+# =============================================================================
+# Telemetry Command
+# =============================================================================
+
+
+@cli.command()
+@click.argument(
+    "action",
+    type=click.Choice(["on", "off", "status"]),
+    required=True,
+)
+@click.pass_context
+def telemetry(ctx: click.Context, action: str) -> None:
+    """
+    Manage anonymous usage telemetry.
+
+    Telemetry is opt-in and disabled by default. When enabled, only
+    anonymous aggregate statistics (route counts, framework names, timing)
+    are transmitted. No code, paths, or credentials are ever included.
+
+    \b
+    Examples:
+        surface telemetry on     # Enable telemetry
+        surface telemetry off    # Disable telemetry
+        surface telemetry status # Show current status
+    """
+    from ..core.telemetry import get_telemetry_status, set_telemetry_consent
+
+    quiet = ctx.obj.get("quiet", False)
+
+    if action == "on":
+        set_telemetry_consent(True)
+        if not quiet:
+            console.print(
+                "[green]Telemetry enabled.[/green] Anonymous usage statistics will be sent."
+            )
+    elif action == "off":
+        set_telemetry_consent(False)
+        if not quiet:
+            console.print("[yellow]Telemetry disabled.[/yellow]")
+    elif action == "status":
+        status = get_telemetry_status()
+        if not quiet:
+            if status == "enabled":
+                console.print("[green]Telemetry: enabled[/green]")
+            elif status == "disabled":
+                console.print("[yellow]Telemetry: disabled[/yellow]")
+            else:
+                console.print("[dim]Telemetry: not configured (disabled by default)[/dim]")
+
+
+# =============================================================================
+# Init Command
+# =============================================================================
+
+
+@cli.command("init")
+@click.option(
+    "--output",
+    "-o",
+    type=click.Path(dir_okay=False, path_type=Path),
+    default=".surface.yaml",
+    help="Output file path (default: .surface.yaml).",
+)
+@click.option(
+    "--force",
+    is_flag=True,
+    help="Overwrite existing file.",
+)
+@click.pass_context
+def init_command(ctx: click.Context, output: Path, force: bool) -> None:
+    """
+    Scaffold a .surface.yaml configuration file.
+
+    Creates a commented template with all available configuration options.
+
+    \b
+    Examples:
+        surface init
+        surface init --output my-surface.yaml
+        surface init --force    # overwrite existing
+    """
+    quiet = ctx.obj.get("quiet", False)
+
+    if output.exists() and not force:
+        error_console.print(f"[red]File already exists:[/red] {output}\nUse --force to overwrite.")
+        sys.exit(ExitCode.CONFIG_ERROR)
+
+    template = """\
+# .surface.yaml — APIsec Surface configuration
+# Generated by: surface init
+#
+# All fields are optional — surface works with sensible defaults.
+# See: https://docs.apisec.ai/surface/config
+
+# -- Project settings --------------------------------------------------------
+
+# project_name: my-service          # Override the auto-detected project name
+# project_root: .                   # Root directory to analyze (default: .)
+
+# -- Analysis settings -------------------------------------------------------
+
+analysis:
+  # Framework hints (surface auto-detects but you can assist)
+  # framework_hints:
+  #   - fastapi
+  #   - sqlalchemy
+
+  file_discovery:
+    # Max files to analyze (default: 10000)
+    # max_files: 10000
+
+    # Additional exclusion patterns (gitignore-style)
+    # exclude_patterns:
+    #   - "vendor/**"
+    #   - "generated/**"
+
+    # Include test files in analysis (default: false)
+    # include_tests: false
+
+  data_flow:
+    # Data flow analysis depth (default: 5)
+    # max_depth: 5
+
+    # Analysis mode: 'full' or 'fast'
+    # mode: full
+
+# -- Output settings ---------------------------------------------------------
+
+output:
+  # Default output format
+  # format: json    # or: yaml
+
+  # Default output file (relative to project_root)
+  # output_file: apisec/manifest.json
+
+# -- Cloud settings ----------------------------------------------------------
+
+cloud:
+  # Set to false to skip cloud upload
+  # enabled: true
+
+  # API URL (can also use APISEC_PAT env var)
+  # api_url: https://api.apisec.ai
+"""
+
+    output.write_text(template, encoding="utf-8")
+    if not quiet:
+        console.print(f"[green]Created:[/green] {output}")
+        console.print("[dim]Edit the file to customize your surface configuration.[/dim]")
+
+
+# =============================================================================
+# Entry Point
+# =============================================================================
+
+
+def main() -> None:
+    """Main entry point."""
+    cli(obj={})
+
+
+if __name__ == "__main__":
+    main()