recce-cloud 1.32.0__py3-none-any.whl → 1.33.1__py3-none-any.whl

recce_cloud/cli.py

@@ -7,6 +7,7 @@ import logging
 import os
 import subprocess
 import sys
+from typing import Optional
 
 import click
 from rich.console import Console
@@ -15,6 +16,7 @@ from rich.logging import RichHandler
 from recce_cloud import __version__
 from recce_cloud.artifact import get_adapter_type, verify_artifacts_path
 from recce_cloud.ci_providers import CIDetector
+from recce_cloud.commands.diagnostics import doctor
 from recce_cloud.delete import (
     delete_existing_session,
     delete_with_platform_apis,
@@ -49,12 +51,403 @@ def cloud_cli():
     pass
 
 
+# Register commands from command modules
+cloud_cli.add_command(doctor)
+
+
 @cloud_cli.command()
 def version():
     """Show the version of recce-cloud."""
     click.echo(__version__)
 
 
+@cloud_cli.command()
+@click.option(
+    "--token",
+    default=None,
+    help="API token for authentication (for headless/CI environments)",
+)
+@click.option(
+    "--status",
+    is_flag=True,
+    help="Check current login status without modifying credentials",
+)
+def login(token, status):
+    """
+    Authenticate with Recce Cloud.
+
+    By default, opens a browser for OAuth authentication. The browser flow
+    securely exchanges credentials using RSA encryption.
+
+    \b
+    Examples:
+      # Browser-based OAuth login (recommended)
+      recce-cloud login
+
+      # Check if already logged in
+      recce-cloud login --status
+
+      # Direct token authentication (for headless/CI environments)
+      recce-cloud login --token <your-api-token>
+    """
+    from recce_cloud.auth.login import (
+        check_login_status,
+        get_api_token,
+        login_with_browser,
+        login_with_token,
+    )
+
+    console = Console()
+
+    # Status check mode
+    if status:
+        is_logged_in, email = check_login_status()
+        if is_logged_in:
+            console.print(f"[green]✓[/green] Logged in as [cyan]{email or 'Unknown'}[/cyan]")
+            token_value = get_api_token()
+            if token_value:
+                masked = f"{token_value[:8]}...{token_value[-4:]}" if len(token_value) > 12 else "***"
+                console.print(f"  Token: {masked} (valid)")
+        else:
+            console.print("[yellow]Not logged in[/yellow]")
+            console.print("Run 'recce-cloud login' to authenticate")
+        sys.exit(0 if is_logged_in else 1)
+
+    # Check if already logged in
+    is_logged_in, email = check_login_status()
+    if is_logged_in:
+        console.print(f"[green]✓[/green] Already logged in as [cyan]{email or 'Unknown'}[/cyan]")
+        if not click.confirm("Do you want to re-authenticate?", default=False):
+            sys.exit(0)
+
+    # Direct token authentication mode
+    if token:
+        if login_with_token(token):
+            sys.exit(0)
+        else:
+            sys.exit(1)
+
+    # Browser OAuth flow
+    if login_with_browser():
+        sys.exit(0)
+    else:
+        console.print()
+        console.print("[yellow]Tip:[/yellow] For headless environments, use 'recce-cloud login --token <token>'")
+        sys.exit(1)
+
+
+@cloud_cli.command()
+def logout():
+    """
+    Remove stored Recce Cloud credentials.
+
+    Clears the API token from ~/.recce/profile.yml.
+    """
+    from recce_cloud.auth.login import logout as do_logout
+    from recce_cloud.auth.profile import get_profile_path
+
+    console = Console()
+
+    do_logout()
+    console.print("[green]✓[/green] Logged out successfully")
+    console.print(f"  Credentials removed from {get_profile_path()}")
+
+
+@cloud_cli.command()
+@click.option(
+    "--org",
+    help="Organization name or slug to bind to",
+)
+@click.option(
+    "--project",
+    help="Project name or slug to bind to",
+)
+@click.option(
+    "--status",
+    is_flag=True,
+    help="Show current project binding without modifying",
+)
+@click.option(
+    "--clear",
+    is_flag=True,
+    help="Remove current project binding",
+)
+def init(org, project, status, clear):
+    """
+    Bind current directory to a Recce Cloud project.
+
+    Creates a .recce/config file that stores the org/project binding.
+    Subsequent commands will auto-detect this binding.
+
+    \b
+    Examples:
+      # Interactive mode: Select org and project
+      recce-cloud init
+
+      # Explicit mode: Direct binding (for scripts/CI)
+      recce-cloud init --org myorg --project my-dbt-project
+
+      # Check current binding
+      recce-cloud init --status
+
+      # Remove binding
+      recce-cloud init --clear
+    """
+    from recce_cloud.api.client import RecceCloudClient
+    from recce_cloud.api.exceptions import RecceCloudException
+    from recce_cloud.auth.login import get_user_info
+    from recce_cloud.auth.profile import get_api_token
+    from recce_cloud.config.project_config import (
+        add_to_gitignore,
+        clear_project_binding,
+        get_config_path,
+        get_project_binding,
+        save_project_binding,
+    )
+
+    console = Console()
+
+    # Check authentication first
+    token = get_api_token()
+    if not token:
+        console.print("[red]Error:[/red] Not logged in")
+        console.print("Run 'recce-cloud login' first")
+        sys.exit(1)
+
+    # Status check mode
+    if status:
+        binding = get_project_binding()
+        if binding:
+            console.print(f"[green]✓[/green] Bound to [cyan]{binding['org']}/{binding['project']}[/cyan]")
+            if binding.get("bound_at"):
+                console.print(f"  Bound at: {binding['bound_at']}")
+            if binding.get("bound_by"):
+                console.print(f"  Bound by: {binding['bound_by']}")
+            console.print(f"  Config file: {get_config_path()}")
+        else:
+            console.print("[yellow]Not bound to any project[/yellow]")
+            console.print("Run 'recce-cloud init' to bind this directory")
+        sys.exit(0 if binding else 1)
+
+    # Clear mode
+    if clear:
+        if clear_project_binding():
+            console.print("[green]✓[/green] Project binding removed")
+        else:
+            console.print("[yellow]No project binding to remove[/yellow]")
+        sys.exit(0)
+
+    # Validate flag combinations
+    if (org and not project) or (project and not org):
+        console.print("[red]Error:[/red] Both --org and --project must be provided together")
+        sys.exit(1)
+
+    # Get user email for binding metadata
+    user_info = get_user_info(token)
+    user_email = user_info.get("email") if user_info else None
+
+    # Explicit mode: Direct binding
+    if org and project:
+        # Validate org/project exist
+        try:
+            api = RecceCloudClient(token)
+            org_obj = api.get_organization(org)
+            if not org_obj:
+                console.print(f"[red]Error:[/red] Organization '{org}' not found")
+                sys.exit(1)
+
+            # Use org ID for project lookup (API requires ID)
+            project_obj = api.get_project(org_obj.get("id"), project)
+            if not project_obj:
+                console.print(f"[red]Error:[/red] Project '{project}' not found in organization '{org}'")
+                sys.exit(1)
+
+            # Use slug for storage (more stable than name)
+            org_slug = org_obj.get("slug", org)
+            project_slug = project_obj.get("slug", project)
+
+            save_project_binding(org_slug, project_slug, user_email)
+            console.print(f"[green]✓[/green] Bound to [cyan]{org_slug}/{project_slug}[/cyan]")
+            console.print(f"  Config saved to {get_config_path()}")
+
+            # Offer to add to .gitignore
+            if click.confirm("Add .recce/ to .gitignore?", default=True):
+                if add_to_gitignore():
+                    console.print("[green]✓[/green] Added .recce/ to .gitignore")
+                else:
+                    console.print("  .recce/ already in .gitignore")
+
+            sys.exit(0)
+
+        except RecceCloudException as e:
+            console.print(f"[red]Error:[/red] {e}")
+            sys.exit(1)
+
+    # Interactive mode: Select org → project
+    try:
+        api = RecceCloudClient(token)
+
+        # List organizations
+        console.print("Fetching organizations...")
+        orgs = api.list_organizations()
+
+        if not orgs:
+            console.print("[yellow]No organizations found[/yellow]")
+            console.print("Please create an organization at https://cloud.datarecce.io first")
+            sys.exit(1)
+
+        # Build org choices: (id for API, name for config, display_name for UI)
+        org_choices = []
+        for o in orgs:
+            org_id = o.get("id")
+            org_name = o.get("name") or o.get("slug") or str(org_id)
+            display_name = o.get("display_name") or org_name
+            org_choices.append((org_id, org_name, display_name))
+
+        # Select organization
+        console.print()
+        console.print("[cyan]Select organization:[/cyan]")
+        for i, (_, _, display_name) in enumerate(org_choices, 1):
+            console.print(f"  {i}. {display_name}")
+
+        org_idx = click.prompt("Enter number", type=click.IntRange(1, len(org_choices)))
+        selected_org_id, selected_org_name, selected_org_display = org_choices[org_idx - 1]
+
+        # List projects (use org_id for API call)
+        console.print()
+        console.print(f"Fetching projects for {selected_org_display}...")
+        projects = api.list_projects(selected_org_id)
+
+        if not projects:
+            console.print(f"[yellow]No projects found in {selected_org_display}[/yellow]")
+            console.print("Please create a project at https://cloud.datarecce.io first")
+            sys.exit(1)
+
+        # Build project choices: (name for config, display_name for UI)
+        # Filter out archived projects
+        project_choices = []
+        for p in projects:
+            # Skip archived projects (check status field and archived flags)
+            if p.get("status") == "archived" or p.get("archived") or p.get("is_archived"):
+                continue
+            project_name = p.get("name") or p.get("slug") or str(p.get("id"))
+            display_name = p.get("display_name") or project_name
+            project_choices.append((project_name, display_name))
+
+        if not project_choices:
+            console.print(f"[yellow]No active projects found in {selected_org_display}[/yellow]")
+            console.print("Please create a project at https://cloud.datarecce.io first")
+            sys.exit(1)
+
+        # Select project
+        console.print()
+        console.print("[cyan]Select project:[/cyan]")
+        for i, (_, display_name) in enumerate(project_choices, 1):
+            console.print(f"  {i}. {display_name}")
+
+        project_idx = click.prompt("Enter number", type=click.IntRange(1, len(project_choices)))
+        selected_project_name, selected_project_display = project_choices[project_idx - 1]
+
+        # Save binding (use names for config, not IDs)
+        save_project_binding(selected_org_name, selected_project_name, user_email)
+        console.print()
+        console.print(f"[green]✓[/green] Bound to [cyan]{selected_org_name}/{selected_project_name}[/cyan]")
+        console.print(f"  Config saved to {get_config_path()}")
+
+        # Offer to add to .gitignore
+        if click.confirm("Add .recce/ to .gitignore?", default=True):
+            if add_to_gitignore():
+                console.print("[green]✓[/green] Added .recce/ to .gitignore")
+            else:
+                console.print("  .recce/ already in .gitignore")
+
+    except RecceCloudException as e:
+        console.print(f"[red]Error:[/red] Failed to fetch data from Recce Cloud: {e}")
+        sys.exit(1)
+    except Exception as e:
+        logger.debug("Unexpected error during init: %s", e, exc_info=True)
+        console.print(f"[red]Error:[/red] An unexpected error occurred: {e}")
+        console.print("  Try running 'recce-cloud login' again or check your network connection.")
+        sys.exit(1)
+
+
+def _get_production_session_id(console: Console, token: str) -> Optional[str]:
+    """
+    Fetch the production session ID from Recce Cloud.
+
+    Returns the session ID if found, None otherwise (with error message printed).
+    """
+    from recce_cloud.api.client import RecceCloudClient
+    from recce_cloud.api.exceptions import RecceCloudException
+    from recce_cloud.config.project_config import get_project_binding
+
+    # Get project binding
+    binding = get_project_binding()
+    if not binding:
+        # Check environment variables as fallback
+        env_org = os.environ.get("RECCE_ORG")
+        env_project = os.environ.get("RECCE_PROJECT")
+        if env_org and env_project:
+            binding = {"org": env_org, "project": env_project}
+        else:
+            console.print("[red]Error:[/red] No project binding found")
+            console.print("Run 'recce-cloud init' to bind this directory to a project")
+            return None
+
+    org_slug = binding.get("org")
+    project_slug = binding.get("project")
+
+    try:
+        client = RecceCloudClient(token)
+
+        # Get org and project IDs
+        org_info = client.get_organization(org_slug)
+        if not org_info:
+            console.print(f"[red]Error:[/red] Organization '{org_slug}' not found")
+            return None
+        org_id = org_info.get("id")
+        if not org_id:
+            console.print(f"[red]Error:[/red] Organization '{org_slug}' response missing ID")
+            return None
+
+        project_info = client.get_project(org_id, project_slug)
+        if not project_info:
+            console.print(f"[red]Error:[/red] Project '{project_slug}' not found")
+            return None
+        project_id = project_info.get("id")
+        if not project_id:
+            console.print(f"[red]Error:[/red] Project '{project_slug}' response missing ID")
+            return None
+
+        # List sessions and find production session
+        sessions = client.list_sessions(org_id, project_id)
+        for session in sessions:
+            if session.get("is_base"):
+                session_id = session.get("id")
+                if not session_id:
+                    console.print("[red]Error:[/red] Production session found but has no ID")
+                    return None
+                session_name = session.get("name") or "(unnamed)"
+                session_id_display = session_id[:8] if len(session_id) >= 8 else session_id
+                console.print(
+                    f"[cyan]Info:[/cyan] Found production session '{session_name}' (ID: {session_id_display}...)"
+                )
+                return session_id
+
+        console.print("[red]Error:[/red] No production session found")
+        console.print("Create a production session first using 'recce-cloud upload --type prod' or via CI pipeline")
+        return None
+
+    except RecceCloudException as e:
+        console.print(f"[red]Error:[/red] Failed to fetch sessions: {e}")
+        return None
+    except Exception as e:
+        logger.debug("Unexpected error in _get_production_session_id: %s", e, exc_info=True)
+        console.print(f"[red]Error:[/red] Unexpected error: {e}")
+        console.print("  Check your network connection and try again.")
+        return None
+
+
 @cloud_cli.command()
 @click.option(
     "--target-path",
@@ -68,6 +461,18 @@ def version():
     help="Recce Cloud session ID to upload artifacts to (or use RECCE_SESSION_ID env var). "
     "If not provided, session will be created automatically using platform-specific APIs (GitHub/GitLab).",
 )
+@click.option(
+    "--session-name",
+    help="Session name to look up or create. If a session with this name exists, "
+    "uploads to it; otherwise prompts to create a new session (use --yes to skip prompt).",
+)
+@click.option(
+    "--yes",
+    "-y",
+    "skip_confirmation",
+    is_flag=True,
+    help="Skip confirmation prompts (auto-create session if not found).",
+)
 @click.option(
     "--cr",
     type=int,
@@ -84,13 +489,13 @@ def version():
     is_flag=True,
     help="Show what would be uploaded without actually uploading",
 )
-def upload(target_path, session_id, cr, session_type, dry_run):
+def upload(target_path, session_id, session_name, skip_confirmation, cr, session_type, dry_run):
     """
     Upload dbt artifacts (manifest.json, catalog.json) to Recce Cloud.
 
     \b
     Authentication (auto-detected):
-    - RECCE_API_TOKEN (for --session-id workflow)
+    - RECCE_API_TOKEN env var or 'recce-cloud login' profile (for --session-id/--session-name workflow)
     - GITHUB_TOKEN (GitHub Actions)
     - CI_JOB_TOKEN (GitLab CI)
 
@@ -102,9 +507,15 @@ def upload(target_path, session_id, cr, session_type, dry_run):
       # Upload production metadata from main branch
       recce-cloud upload --type prod
 
-      # Upload to specific session
+      # Upload to specific session by ID
       recce-cloud upload --session-id abc123
 
+      # Upload by session name (creates if not exists)
+      recce-cloud upload --session-name "my-evaluation-session"
+
+      # Auto-create session without confirmation
+      recce-cloud upload --session-name "new-session" --yes
+
       # Custom target path
       recce-cloud upload --target-path custom-target
     """
@@ -204,8 +615,15 @@ def upload(target_path, session_id, cr, session_type, dry_run):
         # Display upload summary
         console.print("[cyan]Upload Workflow:[/cyan]")
         if session_id:
-            console.print("  • Upload to existing session")
+            console.print("  • Upload to existing session by ID")
             console.print(f"  • Session ID: {session_id}")
+        elif session_name:
+            console.print("  • Upload by session name (lookup or create)")
+            console.print(f"  • Session Name: {session_name}")
+            if skip_confirmation:
+                console.print("  • Auto-create if not exists (--yes flag)")
+            else:
+                console.print("  • Will prompt before creating if not exists")
         else:
             console.print("  • Auto-create session and upload")
             if ci_info and ci_info.platform in ["github-actions", "gitlab-ci"]:
@@ -223,32 +641,236 @@ def upload(target_path, session_id, cr, session_type, dry_run):
         console.print("[green]✓[/green] Dry run completed successfully")
         sys.exit(0)
 
-    # 5. Choose upload workflow based on whether session_id is provided
+    # 5. Choose upload workflow based on provided options
+    # Priority: --session-id > --session-name > platform-specific auto-detection
     if session_id:
         # Generic workflow: Upload to existing session using session ID
-        # This workflow requires RECCE_API_TOKEN
-        token = os.getenv("RECCE_API_TOKEN")
+        # This workflow requires RECCE_API_TOKEN or logged-in profile
+        from recce_cloud.auth.profile import get_api_token
+
+        token = os.getenv("RECCE_API_TOKEN") or get_api_token()
         if not token:
-            console.print("[red]Error:[/red] No RECCE_API_TOKEN provided")
-            console.print("Set RECCE_API_TOKEN environment variable for session-based upload")
+            console.print("[red]Error:[/red] No RECCE_API_TOKEN provided and not logged in")
+            console.print("Either set RECCE_API_TOKEN environment variable or run 'recce-cloud login' first")
             sys.exit(2)
 
         upload_to_existing_session(console, token, session_id, manifest_path, catalog_path, adapter_type, target_path)
+    elif session_name:
+        # Session name workflow: Look up session by name, create if not exists
+        # This workflow requires RECCE_API_TOKEN or logged-in profile, plus org/project config
+        from recce_cloud.auth.profile import get_api_token
+        from recce_cloud.upload import upload_with_session_name
+
+        token = os.getenv("RECCE_API_TOKEN") or get_api_token()
+        if not token:
+            console.print("[red]Error:[/red] No RECCE_API_TOKEN provided and not logged in")
+            console.print("Either set RECCE_API_TOKEN environment variable or run 'recce-cloud login' first")
+            sys.exit(2)
+
+        upload_with_session_name(
+            console,
+            token,
+            session_name,
+            manifest_path,
+            catalog_path,
+            adapter_type,
+            target_path,
+            skip_confirmation=skip_confirmation,
+        )
     else:
-        # Platform-specific workflow: Use platform APIs to create session and upload
+        # GitHub Action or GitLab CI/CD workflow: Use platform APIs to create session and upload
         # This workflow MUST use CI job tokens (CI_JOB_TOKEN or GITHUB_TOKEN)
         if not ci_info or not ci_info.access_token:
-            console.print("[red]Error:[/red] Platform-specific upload requires CI environment")
-            console.print("Either run in GitHub Actions/GitLab CI or provide --session-id for generic upload")
+            # If --type prod is specified outside CI, fetch the production session and upload to it
+            if session_type == "prod":
+                from recce_cloud.auth.profile import get_api_token
+
+                token = os.getenv("RECCE_API_TOKEN") or get_api_token()
+                if not token:
+                    console.print("[red]Error:[/red] No RECCE_API_TOKEN provided and not logged in")
+                    console.print("Either set RECCE_API_TOKEN environment variable or run 'recce-cloud login' first")
+                    sys.exit(2)
+
+                # Fetch the production session ID
+                prod_session_id = _get_production_session_id(console, token)
+                if not prod_session_id:
+                    sys.exit(2)
+
+                upload_to_existing_session(
+                    console, token, prod_session_id, manifest_path, catalog_path, adapter_type, target_path
+                )
+            else:
+                console.print("[red]Error:[/red] Platform-specific upload requires CI environment")
+                console.print(
+                    "Either run in GitHub Actions/GitLab CI or provide --session-id/--session-name for generic upload"
+                )
+                sys.exit(2)
+        else:
+            token = ci_info.access_token
+            if ci_info.platform == "github-actions":
+                console.print("[cyan]Info:[/cyan] Using GITHUB_TOKEN for platform-specific authentication")
+            elif ci_info.platform == "gitlab-ci":
+                console.print("[cyan]Info:[/cyan] Using CI_JOB_TOKEN for platform-specific authentication")
+
+            upload_with_platform_apis(console, token, ci_info, manifest_path, catalog_path, adapter_type, target_path)
+
+
+@cloud_cli.command(name="list")
+@click.option(
+    "--type",
+    "session_type",
+    type=click.Choice(["cr", "prod", "dev"]),
+    help="Filter by session type (prod=base, cr=has PR link, dev=other)",
+)
+@click.option(
+    "--json",
+    "output_json",
+    is_flag=True,
+    help="Output in JSON format",
+)
+def list_sessions_cmd(session_type, output_json):
+    """
+    List sessions in the configured Recce Cloud project.
+
+    \b
+    Requires:
+    - RECCE_API_TOKEN env var or 'recce-cloud login'
+    - Project binding via 'recce-cloud init' or RECCE_ORG/RECCE_PROJECT env vars
+
+    \b
+    Examples:
+      # List all sessions
+      recce-cloud list
+
+      # List only production sessions
+      recce-cloud list --type prod
+
+      # Output as JSON
+      recce-cloud list --json
+    """
+    import json
+
+    from rich.table import Table
+
+    from recce_cloud.api.client import RecceCloudClient
+    from recce_cloud.auth.profile import get_api_token
+    from recce_cloud.config.resolver import ConfigurationError, resolve_config
+
+    console = Console()
+
+    # 1. Get API token
+    token = os.getenv("RECCE_API_TOKEN") or get_api_token()
+    if not token:
+        console.print("[red]Error:[/red] No RECCE_API_TOKEN provided and not logged in")
+        console.print("Either set RECCE_API_TOKEN environment variable or run 'recce-cloud login' first")
+        sys.exit(2)
+
+    # 2. Resolve org/project configuration
+    try:
+        config = resolve_config()
+        org = config.org
+        project = config.project
+    except ConfigurationError as e:
+        console.print("[red]Error:[/red] Could not resolve org/project configuration")
+        console.print(f"Reason: {e}")
+        console.print()
+        console.print("Run 'recce-cloud init' to bind this directory to a project,")
+        console.print("or set RECCE_ORG and RECCE_PROJECT environment variables")
+        sys.exit(2)
+
+    # 3. Initialize client and resolve IDs
+    try:
+        client = RecceCloudClient(token)
+
+        org_info = client.get_organization(org)
+        if not org_info:
+            console.print(f"[red]Error:[/red] Organization '{org}' not found or you don't have access")
+            sys.exit(2)
+        org_id = org_info.get("id")
+        if not org_id:
+            console.print(f"[red]Error:[/red] Organization '{org}' response missing ID")
             sys.exit(2)
 
-        token = ci_info.access_token
-        if ci_info.platform == "github-actions":
-            console.print("[cyan]Info:[/cyan] Using GITHUB_TOKEN for platform-specific authentication")
-        elif ci_info.platform == "gitlab-ci":
-            console.print("[cyan]Info:[/cyan] Using CI_JOB_TOKEN for platform-specific authentication")
+        project_info = client.get_project(org_id, project)
+        if not project_info:
+            console.print(f"[red]Error:[/red] Project '{project}' not found in organization '{org}'")
+            sys.exit(2)
+        project_id = project_info.get("id")
+        if not project_id:
+            console.print(f"[red]Error:[/red] Project '{project}' response missing ID")
+            sys.exit(2)
+
+    except Exception as e:
+        logger.debug("Failed to initialize client for list_sessions: %s", e, exc_info=True)
+        console.print(f"[red]Error:[/red] Failed to initialize: {e}")
+        console.print("  Check your authentication and network connection.")
+        sys.exit(2)
+
+    # Helper to derive session type from fields:
+    # - prod: is_base = True
+    # - cr: pr_link is not null
+    # - dev: everything else
+    def get_session_type(s):
+        if s.get("is_base"):
+            return "prod"
+        elif s.get("pr_link"):
+            return "cr"
+        else:
+            return "dev"
 
-        upload_with_platform_apis(console, token, ci_info, manifest_path, catalog_path, adapter_type, target_path)
+    # 4. List sessions
+    try:
+        sessions = client.list_sessions(org_id, project_id)
+
+        if session_type:
+            sessions = [s for s in sessions if get_session_type(s) == session_type]
+    except Exception as e:
+        console.print(f"[red]Error:[/red] Failed to list sessions: {e}")
+        sys.exit(2)
+
+    # 5. Output results
+    if output_json:
+        console.print(json.dumps(sessions, indent=2, default=str))
+        sys.exit(0)
+
+    if not sessions:
+        console.print("[yellow]No sessions found[/yellow]")
+        if session_type:
+            console.print(f"(filtered by type: {session_type})")
+        sys.exit(0)
+
+    # Display as table
+    console.print(f"[cyan]Organization:[/cyan] {org}")
+    console.print(f"[cyan]Project:[/cyan] {project}")
+    console.print()
+
+    table = Table(title=f"Sessions ({len(sessions)} total)")
+    table.add_column("Name", style="cyan", no_wrap=True)
+    table.add_column("ID", style="dim")
+    table.add_column("Type", style="green")
+    table.add_column("Created At")
+    table.add_column("Adapter")
+
+    for session in sessions:
+        name = session.get("name", "-")
+        session_id = session.get("id", "-")
+        s_type = get_session_type(session)
+        created_at = session.get("created_at", "-")
+        if created_at and created_at != "-":
+            # Format datetime if present
+            try:
+                from datetime import datetime
+
+                dt = datetime.fromisoformat(created_at.replace("Z", "+00:00"))
+                created_at = dt.strftime("%Y-%m-%d %H:%M")
+            except (ValueError, AttributeError):
+                pass
+        adapter = session.get("adapter_type", "-")
+
+        table.add_row(name or "(unnamed)", session_id, s_type, created_at, adapter or "-")
+
+    console.print(table)
+    sys.exit(0)
 
 
 @cloud_cli.command()
@@ -286,7 +908,7 @@ def download(target_path, session_id, prod, dry_run, force):
 
     \b
     Authentication (auto-detected):
-    - RECCE_API_TOKEN (for --session-id workflow)
+    - RECCE_API_TOKEN env var or 'recce-cloud login' profile (for --session-id workflow)
     - GITHUB_TOKEN (GitHub Actions)
     - CI_JOB_TOKEN (GitLab CI)
 
@@ -411,11 +1033,13 @@ def download(target_path, session_id, prod, dry_run, force):
     # 3. Choose download workflow based on whether session_id is provided
     if session_id:
         # Generic workflow: Download from existing session using session ID
-        # This workflow requires RECCE_API_TOKEN
-        token = os.getenv("RECCE_API_TOKEN")
+        # This workflow requires RECCE_API_TOKEN or logged-in profile
+        from recce_cloud.auth.profile import get_api_token
+
+        token = os.getenv("RECCE_API_TOKEN") or get_api_token()
         if not token:
-            console.print("[red]Error:[/red] No RECCE_API_TOKEN provided")
-            console.print("Set RECCE_API_TOKEN environment variable for session-based download")
+            console.print("[red]Error:[/red] No RECCE_API_TOKEN provided and not logged in")
+            console.print("Either set RECCE_API_TOKEN environment variable or run 'recce-cloud login' first")
             sys.exit(2)
 
         download_from_existing_session(console, token, session_id, target_path, force)
@@ -463,7 +1087,7 @@ def delete(session_id, dry_run, force):
 
     \b
     Authentication (auto-detected):
-    - RECCE_API_TOKEN (for --session-id workflow)
+    - RECCE_API_TOKEN env var or 'recce-cloud login' profile (for --session-id workflow)
     - GITHUB_TOKEN (GitHub Actions)
     - CI_JOB_TOKEN (GitLab CI)
 
@@ -576,11 +1200,13 @@ def delete(session_id, dry_run, force):
     # 4. Choose delete workflow based on whether session_id is provided
     if session_id:
         # Generic workflow: Delete from existing session using session ID
-        # This workflow requires RECCE_API_TOKEN
-        token = os.getenv("RECCE_API_TOKEN")
+        # This workflow requires RECCE_API_TOKEN or logged-in profile
+        from recce_cloud.auth.profile import get_api_token
+
+        token = os.getenv("RECCE_API_TOKEN") or get_api_token()
         if not token:
-            console.print("[red]Error:[/red] No RECCE_API_TOKEN provided")
-            console.print("Set RECCE_API_TOKEN environment variable for session-based delete")
+            console.print("[red]Error:[/red] No RECCE_API_TOKEN provided and not logged in")
+            console.print("Either set RECCE_API_TOKEN environment variable or run 'recce-cloud login' first")
             sys.exit(2)
 
         delete_existing_session(console, token, session_id)
@@ -648,7 +1274,7 @@ def report(repo, since, until, base_branch, merged_only, output):
 
     \b
     Authentication:
-    - Requires RECCE_API_TOKEN environment variable
+    - Requires RECCE_API_TOKEN env var or 'recce-cloud login' profile
 
     \b
     Examples:
@@ -669,11 +1295,13 @@ def report(repo, since, until, base_branch, merged_only, output):
     """
     console = Console()
 
-    # Check for API token
-    token = os.getenv("RECCE_API_TOKEN")
+    # Check for API token (env var or logged-in profile)
+    from recce_cloud.auth.profile import get_api_token
+
+    token = os.getenv("RECCE_API_TOKEN") or get_api_token()
     if not token:
-        console.print("[red]Error:[/red] RECCE_API_TOKEN environment variable is required")
-        console.print("Set RECCE_API_TOKEN to your Recce Cloud API token")
+        console.print("[red]Error:[/red] No RECCE_API_TOKEN provided and not logged in")
+        console.print("Either set RECCE_API_TOKEN environment variable or run 'recce-cloud login' first")
         sys.exit(2)
 
     # Auto-detect repo from git remote if not provided