feat: Add query parameter support to ls and acl ls commands

.changes/unreleased/added-20251120-143304.yaml

@@ -0,0 +1,3 @@
+kind: added
+body: Support filtering base on JMESPath for ls using -q flag
+time: 2025-11-20T14:33:04.564732218Z

docs/commands/acls/index.md

@@ -28,20 +28,22 @@ List access control entries for a workspace, item, or OneLake resource.
 **Usage:**
 
 ```
-fab acl ls <path> [-l]
+fab acl ls <path> [-l] [-q <query>]
 ```
 
 **Parameters:**
 
 - `<path>`: Path to the resource.
 - `-l, --long`: Show detailed output. Optional.
+- `-q, --query`: JMESPath query to filter results. Optional.
 
 **Examples:**
 
 ```
 fab acl ls workspace1.workspace
 fab acl ls lh1.lakehouse -l
 fab acl ls /Files/data -l
+fab acl ls workspace1.workspace -q [].[?role=='Admin']
 ```
 
 ---

docs/commands/config/index.md

@@ -27,6 +27,11 @@ List all configuration settings and their current values.
 fab config ls
 ```
 
+Filter the configuration list using JMESPath
+
+```
+fab config ls -q  [?setting=='mode']
+```
 ---
 
 ### get

docs/commands/fs/ls.md

@@ -7,17 +7,24 @@ List workspaces, items, and files.
 **Usage:**
 
 ```
-fab ls <path> [-l] [-a]
+fab ls <path> [-l] [-a] [-q <query>]
 ```
 
 **Parameters:**
 
 - `<path>`: Path to list. Optional.
 - `-l, --long`: Show detailed output. Optional.
 - `-a, --all`: Show hidden entities. Optional.
+- `-q, --query`: JMESPath query to filter results. Optional.
 
-**Example:**
+**Examples:**
 
 ```
 fab ls ws1.Workspace
+fab ls -l
+
+# Using JEMSPath to filter items within ws1 workspace
+fab ls -l -q [].{name:name}
+fab ls ws1.Workspace -q [?contains(name, 'report')]
+fab ls -l -q [?id=='123456']
 ```

docs/examples/acl_examples.md

@@ -38,6 +38,10 @@ fab acl ls ws1.Workspace
 
 # List detailed workspace permissions
 fab acl ls ws1.Workspace -l
+
+# List specific columns using query parameter
+fab acl ls ws1.Workspace -q identity           # Show only identity column
+fab acl ls ws1.Workspace -q [].[identity,type]    # Show identity and name columns
 ```
 
 #### List Item Permissions
@@ -47,6 +51,10 @@ fab acl ls ws1.Workspace/lh1.Lakehouse
 
 # List detailed item permissions
 fab acl ls ws1.Workspace/lh1.Lakehouse -l
+
+# List specific columns for item permissions
+fab acl ls ws1.Workspace/lh1.Lakehouse -q [].type     # Show only type column
+fab acl ls ws1.Workspace/lh1.Lakehouse -q [].{name:name,type:type}   # Show type and name columns
 ```
 
 #### List OneLake RBAC Permissions

docs/examples/config_examples.md

@@ -35,7 +35,6 @@ Retrieve a list of configuration keys and values
 fab config ls
 ```
 
-
 ## Set Configuration Settings
 
 ### Enable/Disable Cache

docs/examples/item_examples.md

@@ -134,6 +134,15 @@ Show items with comprehensive metadata.
 fab ls ws1.Workspace -l
 ```
 
+#### Query List Items in Workspace
+
+```
+fab ls ws1.Workspace -q [].name
+fab ls ws1.Workspace -q [].{name:name,id:id}
+fab ls ws1.Workspace -q [?contains(name, 'Notebook')]
+fab ls ws1.Workspace -l -q [?contains(name, 'Dataflow')].{name:name, id:id}
+```
+
 #### List Item Contents
 
 Browse contents of items that support folder structures.

src/fabric_cli/commands/acls/fab_acls_ls.py

@@ -81,11 +81,10 @@ def _ls_acls_workspace(workspace: Workspace, args: Namespace) -> None:
                     }
                 )
             sorted_acls = sorted(sorted_acls, key=lambda acl: acl["acl"])
-            columns = (
-                ["acl", "identity", "type", "objectId", "name"]
-                if show_all
-                else ["acl", "identity", "type"]
-            )
+            columns = ["acl", "identity", "type"]
+
+            if show_all:
+                columns.extend(["objectId", "name"])
 
             utils_ls.format_and_print_output(
                 data=sorted_acls,
@@ -132,11 +131,11 @@ def _ls_acls_gateway(gateway: VirtualWorkspaceItem, args: Namespace) -> None:
                 )
 
             sorted_acls = sorted(sorted_acls, key=lambda acl: acl["role"])
-            columns = (
-                ["id", "role", "principalId", "principalType"]
-                if show_all
-                else ["role", "principalId", "principalType"]
-            )
+
+            columns = ["role", "principalId", "principalType"]
+            if show_all:
+                columns.insert(0, "id")
+
             utils_ls.format_and_print_output(
                 data=sorted_acls,
                 columns=columns,
@@ -169,11 +168,10 @@ def _ls_acls_connection(connection: VirtualWorkspaceItem, args: Namespace) -> No
                 )
 
             sorted_acls = sorted(sorted_acls, key=lambda acl: acl["role"])
-            columns = (
-                ["id", "role", "principalId", "principalType"]
-                if show_all
-                else ["role", "principalId", "principalType"]
-            )
+
+            columns = ["role", "principalId", "principalType"]
+            if show_all:
+                columns.insert(0, "id")
 
             utils_ls.format_and_print_output(
                 data=sorted_acls,
@@ -221,11 +219,11 @@ def _ls_acls_item(item: Item, args: Namespace) -> None:
                 )
 
             sorted_acls = sorted(sorted_acls, key=lambda acl: acl["acl"])
-            columns = (
-                ["acl", "identity", "type", "id", "name"]
-                if show_all
-                else ["acl", "identity", "type"]
-            )
+
+            columns = ["acl", "identity", "type"]
+            if show_all:
+                columns = ["id", "name"] + columns
+
             utils_ls.format_and_print_output(
                 data=sorted_acls,
                 columns=columns,
@@ -292,11 +290,9 @@ def _ls_acls_onelake(context: OneLakeItem, args: Namespace) -> None:
                     )
 
             sorted_acls = sorted(sorted_acls, key=lambda acl: acl["acl"])
-            columns = (
-                ["acl", "identity", "type", "details"]
-                if show_all
-                else ["acl", "identity", "type"]
-            )
+            columns = ["acl", "identity", "type"]
+            if show_all:
+                columns = ["id", "name"] + columns
             utils_ls.format_and_print_output(
                 data=sorted_acls,
                 columns=columns,

src/fabric_cli/commands/fs/ls/fab_fs_ls_item.py

@@ -8,7 +8,7 @@
 from fabric_cli.core.hiearchy.fab_folder import Folder
 from fabric_cli.core.hiearchy.fab_hiearchy import Item, Workspace
 from fabric_cli.utils import fab_cmd_fs_utils as utils_fs
-from fabric_cli.utils import fab_ui as utils_ui
+from fabric_cli.utils import fab_cmd_ls_utils as utils_ls
 
 
 def exec(workspace: Workspace, args):
@@ -21,9 +21,10 @@ def exec(workspace: Workspace, args):
         show_all or fab_state_config.get_config(fab_constant.FAB_SHOW_HIDDEN) == "true"
     )
 
-    utils_ui.print_output_format(
+    utils_ls.format_and_print_output(
+        sorted_elements_dict,
         args,
-        data=sorted_elements_dict,
-        hidden_data=VirtualItemContainerType if show_hidden else None,
-        show_headers=show_details,
+        show_details,
+        sorted_elements_dict[0].keys() if sorted_elements_dict else [],
+        VirtualItemContainerType if show_hidden else None,
     )

src/fabric_cli/core/fab_constant.py

@@ -256,6 +256,7 @@
 ERROR_INVALID_PATH = "InvalidPath"
 ERROR_INVALID_PROPERTY = "InvalidProperty"
 ERROR_INVALID_DETLA_TABLE = "InvalidDeltaTable"
+ERROR_INVALID_QUERY_FIELDS = "InvalidQueryFields"
 ERROR_INVALID_WORKSPACE_TYPE = "InvalidWorkspaceType"
 ERROR_INTERNAL_SERVER_ERROR = "InternalServerError"
 ERROR_UNSUPPORTED_ITEM_TYPE = "UnsupportedItemType"

src/fabric_cli/errors/common.py

@@ -15,6 +15,10 @@ def invalid_entries_format() -> str:
     def invalid_jmespath_query() -> str:
         return f"Invalid jmespath query (https://jmespath.org)"
 
+    @staticmethod
+    def invalid_parameter(invalid_fields: list, valid_columns: list) -> str:
+        return f"Invalid query field(s): {', '.join(invalid_fields)}. Available fields: {', '.join(valid_columns)}"
+
     @staticmethod
     def invalid_hostname(hostname: str) -> str:
         return f"Invalid hostname for '{hostname}'"

src/fabric_cli/parsers/fab_acls_parser.py

@@ -51,6 +51,13 @@ def register_parser(subparsers: _SubParsersAction) -> None:
         action="store_true",
         help="Show detailed output. Optional",
     )
+    ls_parser.add_argument(
+        "-q",
+        "--query",
+        metavar="",
+        required=False,
+        help="JMESPath query to filter. Optional",
+    )
 
     ls_parser.usage = f"{utils_error_parser.get_usage_prog(ls_parser)}"
     ls_parser.set_defaults(func=acls.ls_command)

src/fabric_cli/parsers/fab_fs_parser.py

@@ -15,7 +15,10 @@ def register_ls_parser(subparsers: _SubParsersAction) -> None:
         "# list all workspaces with details",
         "$ ls -l\n",
         "# list lakehouse tables",
-        "$ ls ws1.Workspace/lh1.Lakehouse/Tables",
+        "$ ls ws1.Workspace/lh1.Lakehouse/Tables\n",
+        "# list items with name matching a pattern",
+        "$ ls -q [].name",
+        "$ ls -q [?contains(name, 'Report')]\n",
     ]
 
     ls_parser = subparsers.add_parser(
@@ -43,6 +46,13 @@ def register_ls_parser(subparsers: _SubParsersAction) -> None:
         action="store_true",
         help="Show all. Optional",
     )
+    ls_parser.add_argument(
+        "-q",
+        "--query",
+        metavar="",
+        required=False,
+        help="JMESPath query to filter. Optional",
+    )
 
     ls_parser.usage = f"{utils_error_parser.get_usage_prog(ls_parser)}"
     ls_parser.set_defaults(func=fs.ls_command)

src/fabric_cli/utils/fab_cmd_ls_utils.py

@@ -7,8 +7,8 @@
 from fabric_cli.client import fab_api_capacity as capacity_api
 from fabric_cli.client import fab_api_workspace as workspace_api
 from fabric_cli.core.hiearchy.fab_hiearchy import VirtualWorkspaceItem
-from fabric_cli.utils import fab_ui as utils_ui
-
+from fabric_cli.utils import fab_ui as utils_ui, fab_util
+from fabric_cli.utils import fab_jmespath as utils_jmespath
 
 def sort_elements(
     elements: list[dict[str, str]], key: str = "name"
@@ -76,11 +76,11 @@ def format_and_print_output(
     columns: list[str] = [],
     hidden_data=None,
 ) -> None:
-
-    filtered_data = [
-        {key: item[key] for key in columns if key in item} for item in data
-    ]
+    
+    args.query = fab_util.process_nargs(getattr(args, "query", None))
+    # Project the columns requested by the user based on JMESPath if query is provided else project the columns requested based on item type
+    filtered_data = utils_jmespath.search(data, args.query) if args.query else [{key: item[key] for key in columns if key in item} for item in data]
 
     utils_ui.print_output_format(
         args, show_headers=show_details, data=filtered_data, hidden_data=hidden_data
-    )
+    )

src/fabric_cli/utils/fab_jmespath.py

@@ -9,7 +9,6 @@
 from fabric_cli.core import fab_constant
 from fabric_cli.core.fab_exceptions import FabricCLIError
 from fabric_cli.errors import ErrorMessages
-from fabric_cli.utils import fab_ui
 
 # Redis and others built some custom functions
 # https://redis.io/docs/latest/integrate/redis-data-integration/reference/jmespath-custom-functions/

src/fabric_cli/utils/fab_ui.py

@@ -252,7 +252,7 @@ def display_help(
 
 
 def get_visual_length(entry: Any, field: Any) -> int:
-    return _get_visual_length(str(entry.get(field, "")))
+    return _get_visual_length(str(entry.get(field, "") if isinstance(entry, dict) else entry))
 
 
 # Prints a list of entries in Unix-like format based on specified fields
@@ -355,7 +355,10 @@ def _print_output_format_result_text(output: FabricCLIOutput) -> None:
             or show_headers
         ):
             data_keys = output.result.get_data_keys() if output_result.data else []
-            print_entries_unix_style(output_result.data, data_keys, header=show_headers)
+            if len(data_keys) > 0:
+                print_entries_unix_style(output_result.data, data_keys, header=(len(data_keys) > 1 or show_headers))
+            else:
+                _print_raw_data(output_result.data)
         elif output.show_key_value_list:
             _print_entries_key_value_list_style(output_result.data)
         else:
@@ -465,7 +468,7 @@ def _format_unix_style_entry(
     formatted = ""
     # Dynamically format based on the fields provided
     for i, field in enumerate(fields):
-        value = str(entry.get(field, ""))
+        value = str(entry.get(field, "") if isinstance(entry, dict) else entry)
         # Adjust spacing for better alignment
         length = len(value)
         visual_length = _get_visual_length(value)