[FEATURE] Add `find` command for catalog search

[nadavs123]

Use Case / Problem

Currently, there's no way to search for Fabric items across workspaces from the CLI.
Users must either:

• Navigate to each workspace individually with ls
• Use the Fabric portal's OneLake catalog UI
• Make direct API calls

This creates friction when users need to quickly locate items by name or description across their tenant.

Proposed Solution

Add a new find command to search across all accessible workspaces.

Command Syntax

# Basic search
fab find "sales report"

# Filter by item type (space-separated)
fab find "data" --type Lakehouse

# Multiple types
fab find "monthly" --type Report Warehouse

# Limit results
fab find "dashboard" --limit 10

# Detailed view (shows IDs for scripting)
fab find "sales" --detailed

# Combine filters
fab find "finance" --type Warehouse Lakehouse --limit 20

Flags

Flag	Description
--type	Filter by item type(s), comma-separated
--limit	Maximum results (default: 50)
--detailed	Show all item properties including IDs

Search Matching

The search query matches against any of these fields:

• displayName - Item name
• workspaceName - Workspace containing the item
• description - Item description

Default Output

Searching catalog for 'sales report'...
3 item(s) found

name             type       workspace          description
───────────────  ─────────  ─────────────────  ─────────────────────────────────
Sales Report Q1  Report     Finance Reports    Quarterly sales analysis for Q1
Sales Report Q2  Report     Finance Reports    Monthly sales summary
Sales Data       Lakehouse  Analytics Team     Raw sales data lakehouse

Detailed Output (--detailed)

Searching catalog for 'sales report'...
3 item(s) found

id                                    name             type       workspaceId                           workspace          description
────────────────────────────────────  ───────────────  ─────────  ────────────────────────────────────  ─────────────────  ─────────────────────────────────
0acd697c-1550-43cd-b998-91bfb12347c6  Sales Report Q1  Report     18cd155c-7850-15cd-a998-91bfb12347aa  Finance Reports    Quarterly sales analysis for Q1
...

Users can then reference items using the standard CLI path format:

fab get "Finance Reports.Workspace/Sales Report Q1.Report"

Output Format Support

The command supports the global --output_format flag:

• --output_format text (default): Table output
• --output_format json: JSON output for scripting

Error Handling

The command uses structured errors via FabricCLIError:

Error	Code	Message
Unsupported type	ERROR_UNSUPPORTED_ITEM_TYPE	"Item type 'Dashboard' is not searchable via catalog search API. Unsupported types: Dashboard, Dataflow, Scorecard"
Unknown type	ERROR_INVALID_ITEM_TYPE	"Unknown item type: 'FakeType'. Use tab completion to see valid types."
Invalid limit	(argparse)	"must be between 1 and 1000, got {value}"
API failure	(from response)	"Catalog search failed: {error message}"
Empty results	(info)	"No items found."

Pagination

• Pagination is handled automatically by do_request() using continuation tokens
• --limit acts as pageSize in the request
• When more results exist, the output shows "(more available)"

Alternatives Considered

• ls with grep: Requires knowing the workspace, doesn't search descriptions
• Admin APIs: Requires admin permissions, overkill for personal discovery
• Portal search: Not scriptable, breaks CLI-first workflows

Impact Assessment

• This would help me personally
• This would help my team/organization
• This would help the broader fabric-cli community
• This aligns with Microsoft Fabric roadmap items

Implementation Attestation

• I understand this feature should maintain backward compatibility with existing commands
• I confirm this feature request does not introduce performance regressions for existing workflows
• I acknowledge that new features must follow fabric-cli's established patterns and conventions

Implementation Notes

• Uses Catalog Search API (POST /v1/catalog/search)
• The API currently does not support searching: Dashboard, Dataflow (Gen1/Gen2), Scorecard
• Uses print_output_format() for output format support
• Uses nargs="+" for --type flag following CLI conventions
• Tab-completion via argcomplete for --type flag
• Structured error handling with FabricCLIError and existing error codes

[microsoft-github-policy-service]

Thank you for submitting this issue, @nadavs123.
A member of the Fabric CLI team will review your submission and provide feedback shortly.

[HasanAboShally]

Thanks for the detailed proposal, @nadavs123! Catalog search from the CLI is a solid use case. A few observations comparing the proposal against existing CLI patterns:

1. --type flag format

The proposal uses comma-separated values (--type Report,Warehouse). Our CLI convention uses either repeatable flags or nargs="+" via argparse. Recommend changing to:

fab find "monthly" --type Report --type Warehouse

or:

fab find "monthly" --type Report Warehouse

This keeps consistency with how other multi-value flags are handled in the codebase.

2. --endpoint flag should be removed

We already have an internal mechanism for overriding the endpoint used in testing. No need to add a user-facing flag for this — recommend removing it from the proposal.

3. Pagination support

The --limit flag is a good start, but the Catalog Search API likely returns paginated results. The proposal should address how pagination is handled — either via an --offset / --page flag, or automatic pagination with --limit as the total cap. Without this, users searching large tenants will get silently truncated results.

4. Output format

The mockup shows a table-style output, but the proposal doesn't mention support for the existing --output_format json|text global flag. This should be supported out of the box via the existing print_output_format() utility rather than a custom renderer.

5. Error handling

No new error codes or messages are specified. The implementation would need at a minimum:

• Invalid/unsupported item type errors
• Catalog API failure handling (e.g., permission denied, API unavailable)
• Empty result handling

These should follow the existing structured error pattern (FabricCLIError + error codes in fab_constant).

6. Command naming — find is the right choice

A standalone find command makes sense here. ls is scoped to a specific workspace, folder, or item and isn't designed to return results across different workspaces. Since catalog search is inherently cross-workspace, it doesn't fit ls semantics. find also has clear UNIX precedent for cross-directory search, so this feels natural.

Overall this is a useful feature request. The API surface (POST /v1/catalog/search) and core UX are sound — the above is mostly about aligning with existing CLI conventions before implementation.

[nadavs123]

Thanks for the detailed feedback @HasanAboShally!

I've addressed all points and updated the proposed solution accordingly:

1. --type flag format
   Changed from comma-separated to nargs="+" (space-separated):

   fab find "monthly" --type Report Warehouse
   

2. --endpoint flag removed
   Removed entirely from both parser and client code.

3. Pagination support

   • do_request() already handles continuation tokens automatically
   • --limit acts as pageSize in the request
   • Output shows "(more available)" when continuation token is present

4. Output format
   Already using print_output_format() - supports --output_format json|text out of the box.

5. Error handling
   Added structured errors using FabricCLIError:

   • ERROR_UNSUPPORTED_ITEM_TYPE for Dashboard, Dataflow, Scorecard
   • ERROR_INVALID_ITEM_TYPE for unknown types
   • --limit validation (must be 1-1000)
   • API failure handling with error code/message from response

6. Tab-completion for --type
   Added shell completion via argcomplete:

   fab find "data" --type La<TAB>  # completes to "Lakehouse"

   • Case-insensitive prefix matching
   • Only suggests searchable types (excludes Dashboard, Dataflow, Scorecard)