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

docs/commands/acls/index.md

@@ -1,122 +1,149 @@
-# Access Control List (ACL) Commands
+# ACL Commands
 
-The access control list (`acl`) commands let you manage permissions and security settings for workspaces, items, and OneLake resources.
-
-**Supported Types:**
-
-- `.Workspace` (workspace-level ACLs)
-- All workspace item types (item-level ACLs)
-- OneLake storage sections (RBAC)
+The `acl` commands manage access control lists (ACLs) for Fabric resources. Use these commands to view, set, and manage access permissions.
 
 ## Available Commands
 
-| Command         | Description             | Usage                                              |
-|-----------------|------------------------|----------------------------------------------------|
-| `acl ls` (dir)  | List ACLs              | `acl ls <path> [-l]`                               |
-| `acl set`       | Set access controls     | `acl set <path> [-I <identity>] [-R <role>] [-f]`  |
-| `acl rm` (del)  | Remove an ACL          | `acl rm <path> [-I <identity>] [-f]`               |
-| `acl get`       | Get ACL details        | `acl get <path> [-q <query>] [-o <output_path>]`   |
+| Command    | Description                    | Usage                                             |
+|------------|--------------------------------|---------------------------------------------------|
+| `acl get`  | Get ACL entries for a resource | `acl get <path> [-q QUERY]`                      |
+| `acl ls`   | List ACL entries              | `acl ls <path> [-l] [-q QUERY]`                  |
+| `acl set`  | Set ACL entry                 | `acl set <path> --identity ID --role ROLE [-f]`  |
+| `acl rm`   | Remove ACL entry              | `acl rm <path> --identity ID [-f]`               |
 
 ---
 
 ### ls (dir)
 
-List access control entries for a workspace, item, or OneLake resource.
+List ACL entries for a resource.
 
 !!! info "Listing ACLs for a workspace or item requires tenant-level Fabric Administrator"
 
 **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.
+- `<path>`: Resource path
+- `-l, --long`: Show detailed output including object IDs and names. Optional.
+- `-q, --query`: JMESPath query to filter and project fields. Optional.
 
 **Examples:**
 
+```bash
+# List basic ACL entries
+fab acl ls ws1.Workspace
+
+# List detailed ACL information
+fab acl ls ws1.Workspace -l
+
+# Project single field using array projection
+fab acl ls ws1.Workspace -q "[*].identity"
+
+# Project multiple fields using array syntax  
+fab acl ls ws1.Workspace -q "[identity, type]"
+
+# Project and rename fields using object syntax
+fab acl ls ws1.Workspace -q "{principalInfo: identity, accessLevel: role}"
+
+# Filter specific roles and project fields
+fab acl ls ws1.Workspace -q "[?role=='Member'].{id: identity, role: role}"
 ```
-fab acl ls workspace1.workspace
-fab acl ls lh1.lakehouse -l
-fab acl ls /Files/data -l
-```
+
+**Notes:**
+
+- The `-q` parameter accepts JMESPath query expressions (https://jmespath.org)
+- Array projection `[*].field` returns an array of values
+- Array syntax `[field1, field2]` selects multiple fields 
+- Object syntax `{newName: field}` renames fields in output
+- Filter expressions `[?field=='value']` filter results
+- Query projection takes precedence over `-l` flag field selection
 
 ---
 
-### set
+### get
 
-Set access control permissions for a resource.
+Get ACL entries for a resource.
 
 **Usage:**
 
 ```
-fab acl set <path> [-I <identity>] [-R <role>] [-f]
+fab acl get <path> [-q QUERY]
 ```
 
 **Parameters:**
 
-- `<path>`: Path to the resource.
-- `-I, --identity`: Object ID of the Microsoft Entra identity to set or update.
-- `-R, --role`: ACL role (admin, member, contributor, viewer).
-- `-f, --force`: Skip confirmation prompt. Optional.
+- `<path>`: Resource path
+- `-q, --query`: JMESPath query to filter and project fields. Optional.
 
 **Examples:**
 
-```
-fab acl set ws1.Workspace/lh1.Lakehouse -I 11111111-2222-3333-4444-555555555555 -R viewer
+```bash
+# Get all ACL entries
+fab acl get ws1.Workspace
+
+# Query specific roles
+fab acl get ws1.Workspace -q "[?role=='Admin']"
+
+# Project role information
+fab acl get ws1.Workspace -q "[].role"
 ```
 
 ---
 
-### rm (del)
+### set
 
-Remove access permissions for an identity.
+Set an ACL entry for a resource.
 
 **Usage:**
 
 ```
-fab acl rm <path> [-I <identity>] [-f]
+fab acl set <path> --identity ID --role ROLE [-f]
 ```
 
 **Parameters:**
 
-- `<path>`: Path to the resource.
-- `-I, --identity`: Object ID of the Microsoft Entra identity to remove.
+- `<path>`: Resource path
+- `--identity`: Principal ID (user ID, service principal ID, or security group ID)
+- `--role`: Role to assign (e.g., Admin, Member, Viewer)
 - `-f, --force`: Skip confirmation prompt. Optional.
 
 **Examples:**
 
-```
-fab acl rm ws1.Workspace/lh1.Lakehouse -I 11111111-2222-3333-4444-555555555555
+```bash
+# Set member role for a user
+fab acl set ws1.Workspace --identity "user@contoso.com" --role Member
+
+# Set admin role for a service principal (force)
+fab acl set ws1.Workspace --identity "00000000-0000-0000-0000-000000000000" --role Admin -f
 ```
 
 ---
 
-### get
+### rm
 
-Get detailed ACL information with optional filtering.
+Remove an ACL entry from a resource.
 
 **Usage:**
 
 ```
-fab acl get <path> [-q <query>] [-o <output_path>]
+fab acl rm <path> --identity ID [-f]
 ```
 
 **Parameters:**
 
-- `<path>`: Path to the resource.
-- `-q, --query`: JMESPath query to filter results. Optional.
-- `-o, --output`: Output path for results. Optional.
+- `<path>`: Resource path
+- `--identity`: Principal ID to remove
+- `-f, --force`: Skip confirmation prompt. Optional.
 
 **Examples:**
 
-```
-fab acl get ws1.Workspace
-```
-
----
+```bash
+# Remove ACL entry for a user
+fab acl rm ws1.Workspace --identity "user@contoso.com"
 
-For more examples and detailed scenarios, see [ACLs Examples](../../examples/acl_examples.md).
+# Force remove ACL entry
+fab acl rm ws1.Workspace --identity "00000000-0000-0000-0000-000000000000" -f

docs/commands/fs/ls.md

@@ -7,17 +7,43 @@ 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 QUERY`: JMESPath query to filter and project fields in output. Optional.
 
-**Example:**
+**Examples:**
 
 ```
+# List basic workspace info
 fab ls ws1.Workspace
-```
+
+# Project single field using array projection
+fab ls -q "[*].name"
+
+# Project multiple fields using array syntax
+fab ls -q [].[name, capacityName]
+
+# Project and rename fields using object syntax
+fab ls -q [].{displayName: name, capacity: capacityName}
+
+# Filter and project fields in a workspace
+fab ls ws1.Workspace -q [].[?type=='Notebook'].{name: name, id: id}
+
+# Show detailed output with specific fields
+fab ls -l -q [].[name, id, capacityName]
+```
+
+**Notes:**
+
+- The `-q` parameter accepts JMESPath query expressions (https://jmespath.org)
+- Array projection `[*].field` returns an array of values
+- Array syntax `[].[field1, field2]` selects multiple fields
+- Object syntax `[].{newName: field}` renames fields in output
+- Filter expressions `[].[?field=='value']` filter results
+- To project detailed output use `-l` flag

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 name"    # 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 "type role"   # Show type and role columns
 ```
 
 #### List OneLake RBAC Permissions

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.insert(0, ["id", "name"])
+
             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.insert(0, ["id", "name"])
             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

@@ -11,6 +11,10 @@ class CommonErrors:
     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}'"