feat: add find command for catalog search

.changes/unreleased/added-20260209-171617.yaml

@@ -0,0 +1,6 @@
+kind: added
+body: Add new 'fab find' command for searching the Fabric catalog across workspaces
+time: 2026-02-09T17:16:17.2056327+02:00
+custom:
+    Author: nschachter
+    AuthorLink: https://github.com/nschachter

src/fabric_cli/client/fab_api_catalog.py

@@ -0,0 +1,47 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+"""Catalog API client for searching Fabric items across workspaces.
+
+API Reference: POST https://api.fabric.microsoft.com/v1/catalog/search
+Required Scope: Catalog.Read.All
+"""
+
+from argparse import Namespace
+
+from fabric_cli.client import fab_api_client as fabric_api
+from fabric_cli.client.fab_api_types import ApiResponse
+
+
+def catalog_search(args: Namespace, payload: dict) -> ApiResponse:
+    """Search the Fabric catalog for items.
+
+    https://learn.microsoft.com/en-us/rest/api/fabric/core/catalog/search
+
+    Args:
+        args: Namespace with request configuration
+        payload: Dict with search request body:
+            - search (required): Text to search across displayName, description, workspaceName
+            - pageSize: Number of results per page
+            - continuationToken: Token for pagination
+            - filter: OData filter string, e.g., "Type eq 'Report' or Type eq 'Lakehouse'"
+
+    Returns:
+        ApiResponse with search results containing:
+            - value: List of ItemCatalogEntry objects
+            - continuationToken: Token for next page (if more results exist)
+
+    Note:
+        The following item types are NOT searchable via this API:
+        Dashboard
+
+        Note: Dataflow Gen1 and Gen2 are currently not searchable; only Dataflow Gen2
+        CI/CD items are returned (as type 'Dataflow').
+        Scorecards are returned as type 'Report'.
+    """
+    args.uri = "catalog/search"
+    args.method = "post"
+    # Use raw_response to avoid auto-pagination (we handle pagination in display)
+    args.raw_response = True
+    return fabric_api.do_request(args, json=payload)
+

src/fabric_cli/commands/find/__init__.py

@@ -0,0 +1,2 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.

src/fabric_cli/commands/find/fab_find.py

@@ -0,0 +1,228 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+"""Find command for searching the Fabric catalog."""
+
+import json
+from argparse import Namespace
+from typing import Any
+
+from fabric_cli.client import fab_api_catalog as catalog_api
+from fabric_cli.core import fab_constant
+from fabric_cli.core.fab_decorators import handle_exceptions, set_command_context
+from fabric_cli.core.fab_exceptions import FabricCLIError
+from fabric_cli.utils import fab_ui as utils_ui
+
+
+# All Fabric item types (from API spec, alphabetically sorted)
+ALL_ITEM_TYPES = [
+    "AnomalyDetector",
+    "ApacheAirflowJob",
+    "CopyJob",
+    "CosmosDBDatabase",
+    "Dashboard",
+    "Dataflow",
+    "Datamart",
+    "DataPipeline",
+    "DigitalTwinBuilder",
+    "DigitalTwinBuilderFlow",
+    "Environment",
+    "Eventhouse",
+    "EventSchemaSet",
+    "Eventstream",
+    "GraphModel",
+    "GraphQLApi",
+    "GraphQuerySet",
+    "KQLDashboard",
+    "KQLDatabase",
+    "KQLQueryset",
+    "Lakehouse",
+    "Map",
+    "MirroredAzureDatabricksCatalog",
+    "MirroredDatabase",
+    "MirroredWarehouse",
+    "MLExperiment",
+    "MLModel",
+    "MountedDataFactory",
+    "Notebook",
+    "Ontology",
+    "OperationsAgent",
+    "PaginatedReport",
+    "Reflex",
+    "Report",
+    "SemanticModel",
+    "SnowflakeDatabase",
+    "SparkJobDefinition",
+    "SQLDatabase",
+    "SQLEndpoint",
+    "UserDataFunction",
+    "VariableLibrary",
+    "Warehouse",
+    "WarehouseSnapshot",
+]
+
+# Types that exist in Fabric but are NOT searchable via the Catalog Search API
+UNSUPPORTED_ITEM_TYPES = [
+    "Dashboard",
+]
+
+# Types that ARE searchable (for validation)
+SEARCHABLE_ITEM_TYPES = [t for t in ALL_ITEM_TYPES if t not in UNSUPPORTED_ITEM_TYPES]
+
+
+def complete_item_types(prefix: str, **kwargs) -> list[str]:
+    """Completer for --type flag. Returns matching searchable item types."""
+    prefix_lower = prefix.lower()
+    # Only complete searchable types to avoid user frustration
+    return [t for t in SEARCHABLE_ITEM_TYPES if t.lower().startswith(prefix_lower)]
+
+
+@handle_exceptions()
+@set_command_context()
+def find_command(args: Namespace) -> None:
+    """Search the Fabric catalog for items."""
+    # Validate: either query or --next-token must be provided
+    has_query = hasattr(args, "query") and args.query
+    has_continue = hasattr(args, "continue_token") and args.continue_token
+
+    if not has_query and not has_continue:
+        raise FabricCLIError(
+            "Either a search query or --next-token is required.",
+            fab_constant.ERROR_INVALID_INPUT,
+        )
+
+    payload = _build_search_payload(args)
+
+    if has_continue:
+        utils_ui.print_grey("Fetching next page of results...")
+    else:
+        utils_ui.print_grey(f"Searching catalog for '{args.query}'...")
+
+    response = catalog_api.catalog_search(args, payload)
+
+    _handle_response(args, response)
+
+
+def _build_search_payload(args: Namespace) -> dict[str, Any]:
+    """Build the search request payload from command arguments."""
+    request: dict[str, Any] = {}
+
+    # If continuation token is provided, only send that (search/filter are encoded in token)
+    if hasattr(args, "continue_token") and args.continue_token:
+        request["continuationToken"] = args.continue_token
+        # Add page size if specified (allowed with continuation token)
+        if hasattr(args, "limit") and args.limit:
+            request["pageSize"] = args.limit
+        return request
+
+    # Normal search request
+    request["search"] = args.query
+
+    # Add page size if specified
+    if hasattr(args, "limit") and args.limit:
+        request["pageSize"] = args.limit
+
+    # Build type filter if specified
+    if hasattr(args, "type") and args.type:
+        types = args.type  # Already a list from argparse nargs="+"
+        # Validate types
+        for t in types:
+            if t in UNSUPPORTED_ITEM_TYPES:
+                raise FabricCLIError(
+                    f"Item type '{t}' is not searchable via catalog search API. "
+                    f"Unsupported types: {', '.join(UNSUPPORTED_ITEM_TYPES)}",
+                    fab_constant.ERROR_UNSUPPORTED_ITEM_TYPE,
+                )
+            if t not in SEARCHABLE_ITEM_TYPES:
+                raise FabricCLIError(
+                    f"Unknown item type: '{t}'. Use tab completion to see valid types.",
+                    fab_constant.ERROR_INVALID_ITEM_TYPE,
+                )
+
+        filter_parts = [f"Type eq '{t}'" for t in types]
+        request["filter"] = " or ".join(filter_parts)
+
+    return request
+
+
+def _handle_response(args: Namespace, response) -> None:
+    """Handle the API response, including error cases."""
+    # Check for error responses
+    if response.status_code != 200:
+        try:
+            error_data = json.loads(response.text)
+            error_code = error_data.get("errorCode", "UnknownError")
+            error_message = error_data.get("message", response.text)
+        except json.JSONDecodeError:
+            error_code = "UnknownError"
+            error_message = response.text
+
+        raise FabricCLIError(
+            f"Catalog search failed: {error_message}",
+            error_code,
+        )
+
+    _display_results(args, response)
+
+
+def _display_results(args: Namespace, response) -> None:
+    """Format and display search results."""
+    results = json.loads(response.text)
+    items = results.get("value", [])
+    continuation_token = results.get("continuationToken")
+
+    if not items:
+        utils_ui.print_grey("No items found.")
+        return
+
+    # Add result count info
+    count = len(items)
+    has_more = continuation_token is not None
+    count_msg = f"{count} item(s) found" + (" (more available)" if has_more else "")
+    utils_ui.print_grey("")  # Blank line after "Searching..."
+    utils_ui.print_grey(count_msg)
+    utils_ui.print_grey("")  # Blank line separator
+
+    # Check if detailed output is requested
+    detailed = getattr(args, "long", False)
+
+    if detailed:
+        # Detailed output: vertical key-value list with all fields
+        # Use snake_case keys for proper Title Case formatting by fab_ui
+        # Only include keys with non-empty values
+        display_items = []
+        for item in items:
+            entry = {
+                "name": item.get("displayName") or item.get("name"),
+                "id": item.get("id"),
+                "type": item.get("type"),
+                "workspace": item.get("workspaceName"),
+                "workspace_id": item.get("workspaceId"),
+            }
+            # Only add description if it has a value
+            if item.get("description"):
+                entry["description"] = item.get("description")
+            display_items.append(entry)
+        utils_ui.print_output_format(args, data=display_items, show_key_value_list=True)
+    else:
+        # Default output: compact table view
+        # Check if any items have descriptions
+        has_descriptions = any(item.get("description") for item in items)
+
+        display_items = []
+        for item in items:
+            entry = {
+                "name": item.get("displayName") or item.get("name"),
+                "type": item.get("type"),
+                "workspace": item.get("workspaceName"),
+            }
+            # Only include description column if any item has a description
+            if has_descriptions:
+                entry["description"] = item.get("description") or ""
+            display_items.append(entry)
+        utils_ui.print_output_format(args, data=display_items, show_headers=True)
+
+    # Output continuation token if more results available
+    if continuation_token:
+        utils_ui.print_grey("")
+        utils_ui.print_grey(f"To get more results, use: --next-token \"{continuation_token}\"")

src/fabric_cli/core/fab_parser_setup.py

@@ -14,6 +14,7 @@
 from fabric_cli.parsers import fab_config_parser as config_parser
 from fabric_cli.parsers import fab_describe_parser as describe_parser
 from fabric_cli.parsers import fab_extension_parser as extension_parser
+from fabric_cli.parsers import fab_find_parser as find_parser
 from fabric_cli.parsers import fab_fs_parser as fs_parser
 from fabric_cli.parsers import fab_global_params
 from fabric_cli.parsers import fab_jobs_parser as jobs_parser
@@ -218,6 +219,7 @@ def create_parser_and_subparsers():
     api_parser.register_parser(subparsers)  # api
     auth_parser.register_parser(subparsers)  # auth
     describe_parser.register_parser(subparsers)  # desc
+    find_parser.register_parser(subparsers)  # find
     extension_parser.register_parser(subparsers)  # extension
 
     # version