[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" --max-items 10

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

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

# Get next page of results
fab find --next-token "eyJTa2lwIjoy..."

Flags

Flags use Azure CLI naming convention for pagination.

Flag	Description
--type	Filter by item type(s), space-separated
--max-items	Maximum results per page (1-1000, default: 50)
-l/--long	Show detailed output with IDs
--next-token	Continuation token to get next page of results

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 (more available)

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

To get more results, use: --next-token "eyJTa2lwIjoz..."

Long Output (-l/--long)

Searching catalog for 'sales report'...

3 item(s) found

Name: Sales Report Q1
ID: 0acd697c-1550-43cd-b998-91bfb12347c6
Type: Report
Workspace: Finance Reports
Workspace ID: 18cd155c-7850-15cd-a998-91bfb12347aa
Description: Quarterly sales analysis for Q1

Name: Sales Report Q2
ID: 1bde708d-2661-54de-c009-02cgc23458d7
Type: Report
Workspace: Finance Reports
Workspace ID: 29de266d-8961-26de-b009-02cgc23458bb

Note: Empty fields (e.g., Description) are hidden for cleaner output.

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 or key-value 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.
Unknown type	ERROR_INVALID_ITEM_TYPE	"Unknown item type: 'FakeType'. Use tab completion to see valid types."
Invalid max-items	(argparse)	"must be between 1 and 1000, got {value}"
Missing query	ERROR_INVALID_INPUT	"Either a search query or --next-token is required."
API failure	(from response)	"Catalog search failed: {error message}"
Empty results	(info)	"No items found."

Pagination

• Use --max-items to control page size (1-1000, default: 50)
• When more results exist, output shows "(more available)" and the --next-token command
• Use --next-token with the provided token to fetch the next page
• When using --next-token, do not provide query or --type (they're encoded in the token)

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)
• Pagination via --next-token flag (continuation token from API)
• The API currently does not support searching: Dashboard, Dataflow (Gen1/Gen2)
• Uses print_output_format() for output format support
• Uses show_key_value_list=True for -l/--long vertical layout
• 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

   • Added --next-token flag to fetch next page using continuation token
   • --max-items controls page size (1-1000, default: 50)
   • Output shows the --next-token command when more results are available:

     To get more results, use: --next-token "eyJTa2lwIjoy..."
     

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
   • 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)

7. Changed --detailed to -l/--long
   Matches CLI convention used by ls -l and other commands.

8. Long output uses vertical key-value layout
   Uses show_key_value_list=True for cleaner display of all fields.

   • Empty fields are hidden for cleaner output
   • Field order: Name, ID, Type, Workspace, Workspace ID, Description