[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
fab find "revenue" -P type=Lakehouse

# Multiple types (bracket syntax)
fab find "monthly" -P type=[Report,Warehouse]

# Exclude types
fab find "data" -P type!=Dashboard
fab find "data" -P type!=[Dashboard,Datamart]

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

# Combine filters
fab find "finance" -P type=[Warehouse,Lakehouse] -l

# JMESPath client-side filtering
fab find "sales" -q "[?type=='Lakehouse']"

Flags

Flag	Description
-P/--params	Parameters in key=value format. Supported: type= (eq) and type!= (ne)
-l/--long	Show detailed output with IDs
-q/--query	JMESPath expression for client-side filtering

Search Matching

The search query matches against any of these fields:

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

Default Output (interactive mode)

fab > find 'sales report'
Searching catalog for 'sales report'...

50 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
...

Press any key to continue... (Ctrl+C to stop)

34 item(s) found

name             type       workspace          description
───────────────  ─────────  ─────────────────  ─────────────────────────────────
Sales Data       Lakehouse  Analytics Team     Raw sales data lakehouse
...

84 total item(s)

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'. Valid types: ..."
Invalid param	ERROR_INVALID_INPUT	"Invalid parameter format: 'foo'. Expected key=value."
Unknown param	ERROR_INVALID_INPUT	"Unknown parameter: 'foo'. Supported: type"
API failure	(from response)	"Catalog search failed: {error message}"
Empty results	(info)	"No items found."

Pagination

Pagination is handled automatically based on CLI mode:

• Interactive mode: Fetches 50 items per page. After each page, if more results are available, prompts "Press any key to continue... (Ctrl+C to stop)". Displays a running total at the end.
• Command-line mode: Fetches all pages automatically (1,000 items per page). All results are accumulated and displayed as a single table.

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)
• Type filtering via -P type=Report,Lakehouse using key=value param pattern; supports negation (type!=Dashboard) and bracket syntax (type=[Report,Lakehouse])
• Type names are case-insensitive (normalized to PascalCase internally)
• Interactive mode: pages 50 at a time with continuation tokens behind the scenes
• Command-line mode: fetches all pages automatically (1,000 per page)
• Descriptions truncated to terminal width in compact view; full text available via -l
• The API currently does not support searching: 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'.
• Uses print_output_format() for output format support
• Uses show_key_value_list=True for -l/--long vertical layout
• 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

[nadavs123]

Updated the implementation based on review feedback and alignment with existing CLI patterns:

Removed flags

• --type — replaced by -P type=<ItemType>[,<ItemType>...] (consistent with -P key=value pattern used in mkdir)
• --max-items — removed; pagination is now automatic
• --next-token — removed; continuation tokens are handled behind the scenes

New pagination behavior

Interactive mode: Fetches 50 items per page. After each page, if more results exist, prompts:

Press any key to continue... (Ctrl+C to stop)

Uses Ctrl+C for cancellation, consistent with the existing CLI convention (fab_auth.py, fab_interactive.py, main.py all use KeyboardInterrupt). Displays a running total at the end.

Command-line mode: Fetches up to 1,000 items in a single request (pageSize=1000). All results displayed at once — no pagination needed.

Updated command syntax

# Basic search
fab find 'sales report'

# Filter by type (using -P)
fab find 'data' -P type=Lakehouse

# Multiple types
fab find 'dashboard' -P type=Report,SemanticModel

# Detailed output
fab find 'sales' -l

# Combined
fab find 'finance' -P type=Warehouse,Lakehouse -l

Updated flags

Flag	Description
-P/--params	Parameters in key=value format. Supported: type=<ItemType>[,<ItemType>...]
-l/--long	Show detailed output with IDs

The issue body above has been updated to reflect these changes.