feat: add find command for catalog search

[nadavs123]

Pull Request

Closes #172

Summary

Adds a new find command that searches for Fabric items across all accessible workspaces using the Catalog Search API (POST /v1/catalog/search).

Usage

# Basic search
fab find "sales report"

# Filter by item type
fab find "data" -P type=Lakehouse

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

# Exclude a type
fab find "data" -P type!=Dashboard

# Show detailed output with IDs
fab find "sales" -l

# Filter results client-side with JMESPath
fab find "sales" -q "[?type=='Report']"

# Project specific fields
fab find "data" -q "[].{name: name, workspace: workspace}"

Flags

Flag	Description
-P/--params	Filter in key=value or key!=value format. Brackets for multiple values: type=[Lakehouse,Notebook]
-l/--long	Show detailed table with IDs (name, id, type, workspace, workspace_id, description)
-q/--query	JMESPath query for client-side filtering

Implementation details

• Follows existing CLI patterns: @fab_command decorator, print_output_format(), FabricCLIError
• Item type list in type_supported.yaml (matches command_supported.yaml pattern)
• Error messages in ErrorMessages.Find class (matches repo pattern)
• Interactive mode: page-by-page with "Press any key to continue..." prompt
• Commandline mode: fetches all pages automatically
• _split_params handles bracket syntax and legacy comma syntax (type=Report,Lakehouse)
• _fetch_results shared helper for response parsing
• truncate_descriptions moved to fab_util.py for reuse

Files added

• src/fabric_cli/client/fab_api_catalog.py — API client (search() function)
• src/fabric_cli/commands/find/__init__.py — Package init
• src/fabric_cli/commands/find/fab_find.py — Command logic
• src/fabric_cli/commands/find/type_supported.yaml — Supported/unsupported item types
• src/fabric_cli/errors/find.py — FindErrors class
• src/fabric_cli/parsers/fab_find_parser.py — Argument parser
• docs/commands/find.md — Command documentation
• tests/test_commands/test_find.py — 39 unit tests + 5 e2e VCR tests
• tests/test_commands/recordings/test_commands/test_find/*.yaml — VCR cassettes

Files modified

• src/fabric_cli/core/fab_parser_setup.py — Register find parser
• src/fabric_cli/errors/__init__.py — Register Find error class
• src/fabric_cli/utils/fab_util.py — Add truncate_descriptions()
• tests/test_commands/commands_parser.py — Register find parser + Windows PromptSession fix

Notes

• Dashboard is the only unsupported item type (not searchable)
• Dataflow Gen1/Gen2 are not searchable; only Dataflow Gen2 CI/CD is returned (as type Dataflow)
• Scorecards are returned as type Report
• Requires Catalog.Read.All scope (not yet added to CLI app registration)

[aviatco]

If you parse it with get_dict_from_params, I think you will need to use quats: type=["Lakehouse","Notebook"]

[nadavs123]

Since I'm keeping a dedicated parser, no quotes are needed.

[aviatco]

considering the option I suggest above, using get_dict_from_params, will required this change

[aviatco]

you should create e2e tests that call find command and record the tests and validate all different scenarios instead of those unit tests.

[nadavs123]

Done. Added 5 e2e tests with VCR cassettes covering basic search, type filter, long output, no results, and ne filter. I kept the unit tests for pure-function logic since those test edge cases and error paths that are hard to cover with e2e alone. Removed TestFindCommandline and TestFindInteractive.

[aviatco]

I think you should have only the e2e tests - and using that test all the different scenarios that will covered the unit tests.
@ayeshurun please keep me honest

[nadavs123]

I converted the test suite to be e2e-first (16 e2e tests now) and removed every unit test that was redundant with an e2e equivalent. 13 remaining unit tests cover edge cases that can't practically be e2e.

[aviatco]

Please update the description:

fab find "monthly" --type Report Warehouse - should be list

fab find "dashboard" --max-items 10 - flag doesnt exist

fab find --next-token "eyJTa2lwIjoy..." - flag doesnt exist

[aviatco]

should be updated once using get_dict_from_params - type=['Report','SemanticModel']

[nadavs123]

I updated the docs to use get_dict_from_params. I kept the unquoted bracket syntax (for example, type=[Report,SemanticModel]) so it stays consistent with other commands like mkdir -P paths=[Files/reports,Files/datasets].

[aviatco]

The example should show a working command example - so if running find command with -P type=[Report,SemanticModel] (without quotes) is working I'm om with it

[aviatco]

Isn’t this effectively the same as -P type='Report', but with poorer performance due to fetching all items before filtering? We might want to skip this example since it’s not a best practice.

[nadavs123]

I'm not even sure why we added -q in the first place, as all filters should be done server-side anyways imo... I added it as part of the initial review requests.

[aviatco]

-q is usefull for column filtering.
find command return the name, ws name. desc etc... if user want to see only the name, for example, user can use -q for that.

[aviatco]

you have mock_print_grey you can use, but I do believe also in mock_questionary_print you can see the output. if you dont see it that means something is wrong with the test

[nadavs123]

I updated the no-results test to assert through mock_print_grey that No items found. is printed.

[aviatco]

we should also test with multiple values like: type!=[Report,Notebook] and verify those types didn't return in the result

[nadavs123]

I added a test for multi-value negation with bracket syntax: type!=[Report,Notebook].

[aviatco]

From the test I can see it is working without the quotes... did you verify it in command_line as well? I dontmran here in the tests, I mean manually from the console

[aviatco]

missing failure scenarios where the API return an error, where the json parse failed, where the type is unknomn etc...
any error we have in the code should be tested.

[nadavs123]

I added failure scenario tests for API error responses, malformed JSON responses, and unknown type errors.

[aviatco]

Relevant for all tests - the name should have prefix of failure or success - depend on the test. you can see examples in any other test's file

[nadavs123]

I renamed all test methods to use _success or _failure suffixes.

[aviatco]

When recording no private information should be visible in the recording.
Please use this guide: https://github.com/microsoft/fabric-cli/blob/main/tests/authoring_tests.md

[nadavs123]

Sanitized all cassettes with mock values from static_test_data.py

[aviatco]

we don't want to have a sample response - we should trigger the API and confirm the actual response.
In each test we should add a setup phase where we created/set/update the needed items them call find and rely on the items we created to verify they are in the results. also it's better to use 'mock' data and not actual values of items

[nadavs123]

See above responses on this issue.

[nadavs123]

@aviatco , while testing locally I noticed that print_output_format breaks the table layout when item names exceed the terminal width. I did a small patch for "description" but the issue also reproduces with long item names. I think a more robust fix would be terminal-width-aware column sizing in the shared table renderer (_print_output_format_result_text). I prefer not to do it as part of this PR as I don't know what other functions it might affect. Filed as #201 .

[Copilot]

Pull request overview

Adds a new top-level fab find command that searches Fabric items across all accessible workspaces via the Catalog Search API (POST /v1/catalog/search), integrating with existing CLI output/error patterns and adding unit + VCR-backed E2E coverage.

Changes:

• Introduces find command implementation, parser registration, and supported-type allow/deny lists.
• Adds a dedicated Catalog API client wrapper for catalog/search.
• Extends shared utilities (get_dict_from_params to support !=, plus a new truncate_columns helper) and adds tests + VCR recordings + docs.

Reviewed changes

Copilot reviewed 26 out of 26 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/fabric_cli/commands/find/fab_find.py	Implements find command logic, paging, filtering, JMESPath support, and output formatting.
src/fabric_cli/commands/find/type_supported.yaml	Declares searchable vs unsupported item types for catalog search.
src/fabric_cli/commands/find/__init__.py	Adds find command package.
src/fabric_cli/client/fab_api_catalog.py	Adds API client wrapper for POST /v1/catalog/search.
src/fabric_cli/parsers/fab_find_parser.py	Adds argparse parser, flags, help, and examples for find.
src/fabric_cli/core/fab_parser_setup.py	Registers find with the global parser setup.
src/fabric_cli/errors/find.py	Adds FindErrors message helpers.
src/fabric_cli/errors/__init__.py	Registers ErrorMessages.Find.
src/fabric_cli/errors/common.py	Adds common error helpers used by param parsing (unsupported_parameter, invalid_parameter_format).
src/fabric_cli/errors/config.py	Removes config-specific invalid_parameter_format helper (superseded by common).
src/fabric_cli/utils/fab_util.py	Updates param parsing to accept != and adds truncate_columns() for table-fit truncation.
docs/commands/find.md	Documents find usage, flags, and examples.
tests/test_commands/commands_parser.py	Registers find parser in test CLI harness and adjusts Windows PromptSession handling.
tests/test_commands/test_find.py	Adds unit tests + VCR-backed E2E tests for find behaviors.
tests/test_commands/recordings/test_commands/test_find/test_find_basic_search_success.yaml	VCR cassette for basic search.
tests/test_commands/recordings/test_commands/test_find/test_find_with_type_filter_success.yaml	VCR cassette for type= filtering.
tests/test_commands/recordings/test_commands/test_find/test_find_type_case_insensitive_success.yaml	VCR cassette for case-insensitive type=.
tests/test_commands/recordings/test_commands/test_find/test_find_with_long_output_success.yaml	VCR cassette for --long output.
tests/test_commands/recordings/test_commands/test_find/test_find_no_results_success.yaml	VCR cassette for empty results.
tests/test_commands/recordings/test_commands/test_find/test_find_with_ne_filter_success.yaml	VCR cassette for type!= filtering.
tests/test_commands/recordings/test_commands/test_find/test_find_ne_multi_type_success.yaml	VCR cassette for type!=[...].
tests/test_commands/recordings/test_commands/test_find/test_find_multi_type_eq_success.yaml	VCR cassette for type=[...].
tests/test_commands/recordings/test_commands/test_find/test_find_with_jmespath_query_success.yaml	VCR cassette for -q/--query behavior.
tests/test_commands/recordings/test_commands/test_find/test_find_json_output_success.yaml	VCR cassette for --output_format json.
tests/test_commands/recordings/test_commands/test_find/test_find_search_summary_success.yaml	VCR cassette for summary output.
.changes/unreleased/added-20260209-171617.yaml	Adds unreleased changelog entry for the new command.

[Copilot]

The new parameter-regex allows key!=value by treating it as a key! key. Since this changes get_dict_from_params() behavior (and error text) across the CLI, it would help to document the != support directly here (docstring/comment), and consider whether downstream callers should be insulated from !-suffixed keys unless they explicitly opted into that behavior.

[Copilot]

This test file contains a couple of very long f-strings (e.g., the assertion messages in _assert_strings_in_mock_calls) that don't appear to be Black-formatted and may fail black --check in CI. Reformat these assertions (let Black wrap them) to keep the file compliant with the repo formatter.

Suggested change

	assert match_found, f"Expected strings {strings} to {'all be present together' if require_all_in_same_args else 'be present'} in mock calls, but not found."
	else:
	assert not match_found, f"Expected strings {strings} to {'not all be present together' if require_all_in_same_args else 'not be present'} in mock calls, but found."
	assert match_found, (
	f"Expected strings {strings} to "
	f"{'all be present together' if require_all_in_same_args else 'be present'} "
	"in mock calls, but not found."
	)
	else:
	assert not match_found, (
	f"Expected strings {strings} to "
	f"{'not all be present together' if require_all_in_same_args else 'not be present'} "
	"in mock calls, but found."
	)

[Copilot]

The prompt says "Press any key to continue..." but the implementation uses input(...), which requires pressing Enter (and will echo a newline). Either adjust the prompt text to reflect this, or use an input mechanism that truly reads a single keypress (or a consistent fab_ui prompt helper) in interactive mode.

Suggested change

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

[Copilot]

_display_items() truncates columns unconditionally for non---long output, which will also mutate the data returned in --output_format json (and can affect -q/--query results). Truncation should be applied only for text/table output (and ideally after any JMESPath filtering/projection), leaving JSON output unmodified for scripting.

Suggested change

	if not show_details:
	utils.truncate_columns(display_items, ["description", "workspace", "name"])
	if getattr(args, "query", None):
	display_items = utils_jmespath.search(display_items, args.query)
	if getattr(args, "query", None):
	display_items = utils_jmespath.search(display_items, args.query)
	# Apply truncation only for non-detailed, non-JSON outputs, after any JMESPath filtering.
	output_format = getattr(args, "output", None) or getattr(args, "output_format", None)
	is_json_output = output_format == "json"
	if not show_details and not is_json_output:
	utils.truncate_columns(display_items, ["description", "workspace", "name"])

[Copilot]

When paging, the code replaces the request payload with only {"continuationToken": ...}. This drops pageSize (and any filter), which can change paging behavior (e.g., command-line mode may fall back to the API default page size on subsequent requests) and increases request count. Keep pageSize/filter consistent across pages (or explicitly include them alongside continuationToken) rather than relying on continuation token semantics.

Suggested change

	payload = {"continuationToken": continuation_token}
	payload["continuationToken"] = continuation_token

[aviatco]

From the test I can see it is working without the quotes... did you verify it in command_line as well? I dontmran here in the tests, I mean manually from the console

[aviatco]

please use the message from ErrorMessage constants you used in the code - so in case the values will changes it will not affect the tests.
in other tests as well

[aviatco]

why did you concat the prints values?
It is better to verify your expected error is in the correct steam - mock_fab_ui_print_error and even better to verify mock_questionary_print was not called.

same for other tests

[aviatco]

_assert_strings_in_mock_calls get "strings" as value.. why not passing both report and lakehouse while other values are identical. you can avoid calling it twice this why.

[aviatco]

once you call find command you dont need those tests. you can verify the values in the command response

[aviatco]

you can verify this in the other tests as part of the assertion avoiding having a specific test for it