[FEATURE] Preserve Workspace Folder Structure on 'export'

[akhilannan]

Use Case / Problem

Problem Statement

I'm exporting a Fabric workspace to my local filesystem for backup and version control. My workspace uses folders to organize items logically—by feature, department, or data source—but the current export functionality strips away this structure entirely.

Current Limitation

The export command flattens the folder hierarchy. When I export an item located at MyWorkspace/Sales Reports/Q1_Report.Report, it creates Q1_Report.Report/ directly in the output directory, completely discarding the Sales Reports/ parent folder. This eliminates the organizational context that's critical for understanding the project.

Impact on Workflow

This limitation breaks DevOps and GitOps practices. In code-managed Fabric environments, folder structure isn't just organizational—it's fundamental to the project architecture. Without it, I can't:

• Navigate locally: The flat structure makes it nearly impossible to find items quickly or understand relationships between assets.
• Conduct meaningful code reviews: Git diffs lose context when the logical grouping disappears, making it harder for teams to review changes effectively.
• Automate deployments: Re-importing assets while preserving the intended workspace organization becomes manual and error-prone.

Requested Enhancement

Preserve the full folder hierarchy during workspace export. If an item exists at MyWorkspace/Sales Reports/Q1_Report.Report, the export should create Sales Reports/Q1_Report.Report/ in the output directory, maintaining the complete path structure.

This would enable seamless integration with modern development workflows and make Fabric workspaces truly manageable as code.

Proposed Solution

Specific commands or functionality:

Extend the existing export command with a --preserve-folders flag to maintain the workspace's folder hierarchy during export.

fab export <workspace_name> -o <output_path> --preserve-folders

Expected behavior and output:

With the --preserve-folders flag enabled, the export command replicates the complete folder structure from the Fabric workspace to the local filesystem.

Example:

Starting with this workspace structure in Fabric:

/MyWorkspace.Workspace/
├── Reports/
│   └── Sales_Report.Report
└── Notebooks/
    └── Data_Processing.Notebook

Current Behavior (fab export MyWorkspace.Workspace -o ./local_export --all):

./local_export/
├── Sales_Report.Report/
│   └── ... (item files)
└── Data_Processing.Notebook/
    └── ... (item files)

All items export to a flat structure, losing the original folder organization.

Expected Behavior (fab export MyWorkspace.Workspace -o ./local_export --all --preserve-folders):

./local_export/
├── Reports/
│   └── Sales_Report.Report/
│       └── ... (item files)
└── Notebooks/
    └── Data_Processing.Notebook/
        └── ... (item files)

The original folder hierarchy is preserved, making it easier to understand project organization.

Integration with existing fabric-cli features:

This enhancement naturally extends the export command and strengthens the CLI's filesystem metaphor established by commands like ls, cd, and mkdir. It also sets the foundation for a complementary import enhancement that could automatically recreate folder structures in target workspaces, enabling true round-trip workflows.

Alternatives Considered

No response

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

• Relevant Fabric REST APIs:

This feature can be efficiently implemented using three core APIs that minimize the number of calls needed:

1. GET /v1/workspaces/{workspaceId}/folders?recursive=True: Found in src/fabric_cli/client/fab_api_folders.py, this single call retrieves the entire folder hierarchy for a workspace—no recursive GET /folders/{folderId} calls required. The response includes each folder's id, displayName, and parentFolderId.

2. GET /v1/workspaces/{workspaceId}/items: This API (in fab_api_workspace.py) returns a flat list of all workspace items. The critical property is folderId, which links each item to its parent folder in the hierarchy. Root-level items won't have a folderId.

3. POST /v1/workspaces/{workspaceId}/items/{itemId}/getDefinition: The existing API used by the export command (fab_api_item.py) to fetch an item's actual definition content. This part of the logic would remain unchanged.

• Command Structure or Argument Patterns:

  A new optional flag should be added to the export command in src/fabric_cli/parsers/fab_fs_parser.py. A good name would be --preserve-folders.

• Compatibility Concerns:

  To ensure backward compatibility, this new behavior should only be triggered when the --preserve-folders flag is present. The default behavior of the export command (flattening the directory structure) should remain unchanged to avoid breaking existing user scripts and workflows.

[HasanAboShally]

/triaged

Hi @akhilannan,

Thanks for this incredibly detailed feature request! Really appreciate the thoroughness—the use case, implementation notes, and API references are super helpful.

This is a great idea and aligns well with our vision for making the CLI more developer-friendly. Preserving folder structure on export is definitely something we want to support, especially for the GitOps and version control scenarios you mentioned.

Before we move forward with implementation, I want to make sure we think through all the scenarios and edge cases properly. A few things we'll need to spec out:

• How this interacts with exporting individual items vs. entire workspaces
• Behavior when exporting specific items from different folders
• Round-trip workflow (how import should handle folder structure)
• Edge cases around nested folders and naming conflicts

We'll put together a proper spec for this and share it here for community feedback before implementation. In the meantime, if you have any additional thoughts on how this should work with import, or specific edge cases you've encountered, feel free to add them here.

Thanks again for the detailed proposal!

[microsoft-github-policy-service]

Triage has been completed for this issue.