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

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

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

# Project specific fields with JMESPath
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: @handle_exceptions decorator, print_output_format(), FabricCLIError
• Item type list in type_supported.yaml (included in package-data, matching command_supported.yaml pattern)
• Error messages in ErrorMessages.Find class (matches repo pattern)
• Interactive mode: page-by-page with "Press Enter to continue..." prompt
• Command-line mode: fetches all pages automatically
• _parse_type_from_params uses get_dict_from_params for parameter parsing with != regex support
• _fetch_results shared helper for response parsing and pagination
• truncate_columns in fab_util.py for terminal-width-aware column sizing (reusable by other commands)
• JMESPath filtering applied before column truncation; truncation only affects text output

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 — 15 e2e VCR tests
• tests/test_commands/recordings/test_commands/test_find/*.yaml — VCR cassettes
• tests/test_commands/api_processors/catalog_search_api_processor.py — Cassette processor for catalog search responses

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_columns(), != regex support in get_dict_from_params
• tests/test_commands/commands_parser.py — Register find parser + Windows PromptSession fix (scoped with try/finally)
• tests/test_commands/api_processors/api_processor_handler.py — Register CatalogSearchAPIProcessor
• pyproject.toml — Add type_supported.yaml to package-data
• MANIFEST.in — Add type_supported.yaml to source distribution

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

[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

[nadavs123]

Since I adopted get_dict_from_params with the updated regex, bracket values like type=[Report,SemanticModel] work without quotes. The regex treats brackets as part of the value.

[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]

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.

[nadavs123]

Updated the docs example to focus on column filtering.

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

[nadavs123]

Added a docstring note in get_dict_from_params documenting the != operator support and the !-suffixed key convention (already present at line 72-73 of fab_util.py).

[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."
	)

[nadavs123]

Fixed. Ran black on the test file and source file. Both pass black --check now.

[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)")

[nadavs123]

The code already says "Press Enter to continue..." (fixed in a prior commit). Updated the docs to match.

[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"])

[nadavs123]

Fixed. JMESPath filtering now runs before truncation, and truncation is guarded with output_format == "text".

[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

[nadavs123]

Fixed. continuation payloads now preserve pageSize. The filter is embedded in the continuation token by the API, so re-sending it isn't needed (and the API ignores it on continuation requests).

[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

[Copilot]

Pull request overview

Copilot reviewed 29 out of 29 changed files in this pull request and generated 7 comments.

[Copilot]

type_supported.yaml is loaded via a direct filesystem path at import time. In the current packaging config, only fabric_cli.core.fab_config/command_support.yaml and fabric_cli.commands.fs/payloads/* are included as package data, so this YAML is likely missing in the installed distribution and will raise FileNotFoundError on import. Consider loading it via importlib.resources (or similar) and ensure the YAML is included in package data/MANIFEST so the command works when installed from PyPI.

[nadavs123]

Fixed. Added type_supported.yaml to both pyproject.toml package-data and MANIFEST.in (69451ec).

[Copilot]

The PR description mentions supporting legacy comma syntax like type=Report,Lakehouse, but _parse_type_from_params only splits multiple values when the bracket form ([A,B]) is used. As written, type=Report,Lakehouse will be treated as a single type and fail validation. Either add support for comma-separated values here or update the documented behavior.

[nadavs123]

By design — bracket syntax (type=[Report,Lakehouse]) is the documented way to specify multiple types, consistent with other CLI commands like mkdir -P paths=[Files,Tables]. The comma in get_dict_from_params is a key-value pair separator, not a value list separator, so type=Report,Lakehouse would be ambiguous.

[Copilot]

JMESPath querying is applied after truncate_columns, and non-list query results are discarded (return ... if isinstance(..., list) else []). This can break valid queries that return a dict/scalar and can also cause filtering/projection to operate on already-truncated strings. Apply the JMESPath query before truncation, and pass through dict/scalar results to print_output_format instead of forcing a list.

[nadavs123]

Fixed. Same as #21 above. JMESPath now runs first (69451ec).

[Copilot]

--params/-P is defined with nargs='?', so a user can pass -P with no value and the command will silently ignore the flag (no validation error, no filter applied). If -P is intended to always take a value, define it without an optional nargs and/or validate that args.params is not None when the flag is present.

Suggested change

nargs="?",

[nadavs123]

This is consistent with how optional params work in the CLI. Passing -P alone is equivalent to not passing it. Adding validation for this edge case would break the argparse pattern used by other commands.

[Copilot]

Docs say interactive mode prompts "Press any key to continue...", but the implementation currently prompts with "Press Enter to continue...". Please align the documentation with the actual prompt (or update the prompt to match the docs) so users aren’t confused.

Suggested change

	- In interactive mode (`fab` shell), results are paged 50 at a time with "Press any key to continue..." prompts.
	- In interactive mode (`fab` shell), results are paged 50 at a time with "Press Enter to continue..." prompts.

[nadavs123]

Fixed — docs now say "Press Enter to continue..." (69451ec).

[Copilot]

This API processor isn’t currently wired into APIProcessorHandler (which only registers capacities/workspaces/gateways/etc.), so it will never run and the catalog/search responses won’t be scrubbed/trimmed during recording. Register this processor in the handler so the find VCR cassettes only include deterministic, test-generated catalog entries (and avoid leaking unrelated tenant data).

[nadavs123]

Fixed — CatalogSearchAPIProcessor is now registered in APIProcessorHandler (69451ec). It will scrub catalog search responses during future recordings.

[Copilot]

The Windows workaround patches fabric_cli.core.fab_interactive.PromptSession at module scope and never restores it. This can leak into other tests in the same process and make failures harder to diagnose. Consider restoring _interactive_mod.PromptSession to _orig_ps after InteractiveCLI(...) is constructed (or patch via a fixture/monkeypatch context) to keep the change scoped to this executor.

Suggested change

	self._interactiveCLI = InteractiveCLI(customArgumentParser, self._parser)
	try:
	self._interactiveCLI = InteractiveCLI(
	customArgumentParser, self._parser
	)
	finally:
	_interactive_mod.PromptSession = _orig_ps
	else:
	self._interactiveCLI = InteractiveCLI(customArgumentParser, self._parser)

[nadavs123]

Fixed — wrapped in try/finally so the original PromptSession is restored after the singleton is created (69451ec).

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[aviatco]

why did you change it back to while Ture? better to use has_more since this is the exit condition

[aviatco]

same here -

while continuation_token:

[aviatco]

redundent - you have invalid_json_format error in ErrorMessages.Common

[aviatco]

what can be the values of response.text? json/string?
cause if we got to this point this is not ERROR_UNEXPECTED_ERROR it is ERROR_INVALID_JSON

[aviatco]

consider print the error message from the API with logger.debug and for the user use something simple and clear

[aviatco]

nit - consider rewrite the function (considering response.text is always a json object and getting json.JSONDecodeError is always thrown cause the response.text is an invalid json format ):

"""Parse a successful API response or raise FabricCLIError on failure."""
    try:
        data = json.loads(response.text)

        if response.status_code == 200:
            return data

        raise FabricCLIError(
            ErrorMessages.Find.search_failed(data.get("message", response.text)),
            data.get("errorCode", fab_constant.ERROR_UNEXPECTED_ERROR),
        )

    except json.JSONDecodeError:
        if response.status_code == 200:
            raise FabricCLIError(
                ErrorMessages.Find.invalid_response(),
                fab_constant.ERROR_INVALID_JSON,
            )

[aviatco]

you shouldn't use output_format in any command logic.
fab_ui is the only component that should be aware of this field.

[aviatco]

paraphs move this logic to fab_ui where output_format is text and show_details is false.
but need to verify this will not cause regression in other commands
Or any other solution, but you should not use output_format value here