From 775b2d3dd2c6a2d776db3d7fcdda3cfd8a87d441 Mon Sep 17 00:00:00 2001 From: Jeremy Hoover Date: Sun, 28 Dec 2025 13:26:17 +0200 Subject: [PATCH 1/6] docs: Improve homepage structure and clarity - Reorder sections: Install/Auth before Common Tasks - Remove decorative emojis for better accessibility - Add 'Why use the CLI?' and 'What you can do' sections - Expand 'Common tasks' with practical examples - Add automation examples (GitHub Actions, Azure Pipelines) - Reorganize 'Get help' section with clearer categories - Use sentence case for all headings - Add context to all code blocks - Apply active voice and concise language throughout --- docs/index.md | 176 ++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 136 insertions(+), 40 deletions(-) diff --git a/docs/index.md b/docs/index.md index 6b2208ee..6ec14dbe 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,90 +1,186 @@ ---- +--- hide: - navigation --- -# Fabric CLI +# Fabric CLI -The Fabric CLI (`fab`) is a fast, file‑system‑inspired command‑line interface for Microsoft Fabric. Explore, automate, and script your Fabric environment—right from your terminal. +The Fabric CLI (`fab`) gives you command-line access to Microsoft Fabric. Manage workspaces, run pipelines, and automate data workflows - all from your terminal. --- +## Why use the CLI? + +Get powerful control over your Fabric resources: + +- **Navigate like a file system** - Browse workspaces and items using familiar commands +- **Automate workflows** - Run pipelines and notebooks from scripts or CI/CD pipelines +- **Integrate with DevOps** - Add Fabric to GitHub Actions, Azure Pipelines, and other tools +- **Work your way** - Use Unix or Windows command styles on any platform -## ✨ Key features +## What you can do -- File‑system navigation – `ls`, `cd`, `mkdir`, `cp`, `rm`, `run`. Work seemlesly in both Unix-style and Windows-style command names for file system operations. You can use whichever style you're most familiar with. For more details see [File System Commands](./commands/index.md#file-system-operations-fs). -- Scripting & interactive modes – switch fluidly between live shell and one‑off commands. -- Autocompletion – Enable [tab completion](./essentials/autocompletion.md) for commands, subcommands, and flags. -- Automation ready – ideal for GitHub Actions, Azure Pipelines, or any Bash/PowerShell/Python workflow. -- Cross‑platform – Windows Terminal, macOS Terminal, Linux shells. -- Built on public APIs – Fabric REST, OneLake, and Microsoft.Fabric ARM endpoints. +- **File system navigation** - `ls`, `cd`, `mkdir`, `cp`, `rm`, `run`. Work seamlessly in both Unix-style and Windows-style command names for file system operations. You can use whichever style you're most familiar with. For more details see [File System Commands](./commands/index.md#file-system-operations-fs). +- **Scripting & interactive modes** - Switch fluidly between live shell and one-off commands. +- **Autocompletion** - Enable [tab completion](./essentials/autocompletion.md) for commands, subcommands, and flags. +- **Cross-platform** - Windows Terminal, macOS Terminal, Linux shells. +- **Built on public APIs** - Fabric REST, OneLake, and Microsoft.Fabric ARM endpoints. -## 🚀 Install +## Get started -Prerequisites: +### What you need - - Python version 3.10, 3.11, or 3.12 is installed on your machine. - - Ensure `python` (defined in the `PATH` environment variable) is accessible from your terminal, by opening a terminal and run `python`. +- Python 3.10, 3.11, or 3.12 +- `python` in your `PATH` environment variable -Open a terminal and run: +Check if Python is ready: +```bash +python --version ``` + +### Install the CLI + +Use pip on Windows, macOS, or Linux: + +```bash pip install ms-fabric-cli ``` -This installs the latest version of `fab` on Windows, MacOS, and Linux. -If you’re upgrading from an earlier version, simply run the same command with `‑‑upgrade`. +This installs the latest version of `fab` on Windows, macOS, and Linux. -*Need a different method?* See the [release notes](./release-notes.md) for standalone binaries and package managers as they become available. +Upgrade an existing installation: + +```bash +pip install --upgrade ms-fabric-cli +``` + +Make sure it installed correctly: + +```bash +fab --version +``` +**Note:** Looking for other installation options? Check the [Release Notes](./release-notes.md) for standalone binaries and package managers as they become available. -## 🔐 Authenticate -`fab` supports **user**, **service principal**, and **managed identity** identity types for sign‑in. +### Sign in -| **Identity Type** | **Scenario** | **Command Usage** | +Before you can use the CLI, sign in to Microsoft Fabric. Choose the authentication method that works for your scenario. + +#### Authentication methods + +`fab` supports **user**, **service principal**, and **managed identity** identity types for sign-in. + +| **Identity Type** | **Scenario** | **Command Usage** | |----------------------|------------------------------------|------------------------------------------------------------------------------------------------| | **User** | Interactive browser login | `fab auth login` and select *Interactive with a web browser* | -| **Service Principal**| Secret | `fab auth login -u -p --tenant ` | +| **Service Principal**| Secret | `fab auth login -u -p --tenant ` | | | Certificate | `fab auth login -u --certificate --tenant ` | | | Certificate + password | `fab auth login -u --certificate -p --tenant ` | | | Federated token | `fab auth login -u --federated-token --tenant ` | -| **Managed Identity** | System‑assigned | `fab auth login --identity` | -| | User‑assigned | `fab auth login --identity -u ` | +| **Managed Identity** | System-assigned | `fab auth login --identity` | +| | User-assigned | `fab auth login --identity -u ` | For more details and scripts, see the [auth examples](./examples/auth_examples.md). -## 🏁 Run Your First Command +#### Sign in interactively -Once you’re signed in, you’re one command away from exploring Fabric. Try and run `ls` command to list all workspaces: +For local development, sign in with your Microsoft account: +```bash +fab auth login ``` + +Select *Interactive with a web browser*. This opens your browser to complete authentication. + +## Common tasks + +### Browse workspaces and items + +```bash +# See all workspaces +fab ls /workspaces + +# Go to a workspace +fab cd "Sales Analytics.Workspace" + +# See what's inside fab ls ``` -For a detailed list of available commands, see [Commands](./commands/index.md), or explore advanced scenarios in our [Usage examples](./examples/index.md). +### Run notebooks and pipelines -## 💬 Feedback & Support +```bash +# Run a pipeline +fab run pipeline /workspaces//pipelines/ + +# Start a notebook +fab start /workspaces//notebooks/ +``` + +### Move files to OneLake + +```bash +# Upload a local file +fab cp ./local/data.csv /workspaces//lakehouses//Files/ + +# Download from OneLake +fab cp /workspaces//lakehouses//Files/data.csv ./local/ +``` + +## Use in automation + +Add Fabric CLI to GitHub Actions, Azure Pipelines, and other DevOps tools. The same commands you use locally work in CI/CD. + +### GitHub Actions example + +```yaml +- name: Deploy to Fabric + run: | + pip install ms-fabric-cli + fab auth login -u ${{ secrets.CLIENT_ID }} -p ${{ secrets.CLIENT_SECRET }} --tenant ${{ secrets.TENANT_ID }} + fab cp ./artifacts/* /workspaces/Production/lakehouses/Data/Files/ +``` + +### Azure Pipelines example + +```yaml +- script: | + pip install ms-fabric-cli + fab auth login -u $(CLIENT_ID) -p $(CLIENT_SECRET) --tenant $(TENANT_ID) + fab run pipeline /workspaces/ETL/pipelines/DailyRefresh + displayName: 'Run Fabric pipeline' +``` + +## Run your first command + +Once you're signed in, you're one command away from exploring Fabric: + +```bash +fab ls +``` + +For a detailed list of available commands, see [Commands](./commands/index.md), or explore advanced scenarios in our [Usage examples](./examples/index.md). -**Have thoughts on the Fabric CLI?** We review every submission and your input directly shapes the Fabric CLI roadmap. +## Get help -- **Submit feedback** - Use our short [Microsoft Form](https://forms.office.com/r/uhL6b6tNsi) to report issues, request enhancements, or ask questions. +**Found a bug or have a suggestion?** -- **Stay in the loop** - Join the conversation in [r/MicrosoftFabric on Reddit](https://www.reddit.com/r/MicrosoftFabric/) — follow updates, share tips, and connect with other CLI users. +- [Report an issue](https://github.com/microsoft/fabric-cli/issues) +- [Request a feature](https://github.com/microsoft/fabric-cli/discussions) -- **Share feature ideas** - Post and vote on suggestions in the [Fabric Ideas Portal](https://ideas.fabric.microsoft.com/). +**Need help using the CLI?** -- **Get community help** - Ask technical questions in the [Developer Community Forum](https://community.fabric.microsoft.com/t5/Developer/bd-p/Developer) — the Fabric team and community experts are ready to help. +- See [Troubleshooting](./troubleshooting.md) for common problems and solutions +- Ask questions in [GitHub Discussions](https://github.com/microsoft/fabric-cli/discussions) +- Connect with the community on [r/MicrosoftFabric](https://www.reddit.com/r/MicrosoftFabric/) -- **Need enterprise assistance?** - Reach out to your Microsoft account manager or open a ticket with the [Fabric Support Team](https://support.fabric.microsoft.com/). +**Need enterprise assistance?** -*Thank you for helping us build the best CLI experience possible!* +- Contact your Microsoft account manager +- Open a ticket with the [Fabric Support Team](https://support.fabric.microsoft.com/) From 1705cd738ca5dd809d1a86c660bfab0329d5ba3c Mon Sep 17 00:00:00 2001 From: Jeremy Hoover Date: Sun, 4 Jan 2026 09:41:31 +0200 Subject: [PATCH 2/6] docs: Add changie entry for homepage documentation improvements --- .changes/unreleased/docs-20260104-094108.yaml | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 .changes/unreleased/docs-20260104-094108.yaml diff --git a/.changes/unreleased/docs-20260104-094108.yaml b/.changes/unreleased/docs-20260104-094108.yaml new file mode 100644 index 00000000..f60924eb --- /dev/null +++ b/.changes/unreleased/docs-20260104-094108.yaml @@ -0,0 +1,3 @@ +kind: docs +body: Improve homepage documentation clarity and structure with better headings, simplified examples, and enhanced getting started instructions +time: 2026-01-04T09:41:08.4529672Z From 624bd44ac6e525f896afc11ec0b9498ff3ed071b Mon Sep 17 00:00:00 2001 From: Jeremy Hoover Date: Wed, 7 Jan 2026 15:43:17 +0200 Subject: [PATCH 3/6] Fix index.md based on PR feedback - use CLI-style paths, reorder sections, add community resources --- docs/index.md | 44 ++++++++++++++++++++++---------------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/docs/index.md b/docs/index.md index 6ec14dbe..c228bfad 100644 --- a/docs/index.md +++ b/docs/index.md @@ -95,39 +95,46 @@ fab auth login Select *Interactive with a web browser*. This opens your browser to complete authentication. +## Run your first command + +Once you're signed in, you're one command away from exploring Fabric: + +```bash +fab ls +``` + +This lists all workspaces you have access to. For a detailed list of available commands, see [Commands](./commands/index.md), or explore advanced scenarios in our [Usage examples](./examples/index.md). + ## Common tasks ### Browse workspaces and items ```bash # See all workspaces -fab ls /workspaces - -# Go to a workspace -fab cd "Sales Analytics.Workspace" - -# See what's inside fab ls + +# See what's inside a workspace +fab ls "Sales Analytics.Workspace" ``` ### Run notebooks and pipelines ```bash # Run a pipeline -fab run pipeline /workspaces//pipelines/ +fab run .Workspace/.DataPipeline -i # Start a notebook -fab start /workspaces//notebooks/ +fab start .Workspace/.Notebook ``` ### Move files to OneLake ```bash # Upload a local file -fab cp ./local/data.csv /workspaces//lakehouses//Files/ +fab cp ./local/data.csv .Workspace/.Lakehouse/Files/data.csv # Download from OneLake -fab cp /workspaces//lakehouses//Files/data.csv ./local/ +fab cp .Workspace/.Lakehouse/Files/data.csv ./local/ ``` ## Use in automation @@ -141,7 +148,7 @@ Add Fabric CLI to GitHub Actions, Azure Pipelines, and other DevOps tools. The s run: | pip install ms-fabric-cli fab auth login -u ${{ secrets.CLIENT_ID }} -p ${{ secrets.CLIENT_SECRET }} --tenant ${{ secrets.TENANT_ID }} - fab cp ./artifacts/* /workspaces/Production/lakehouses/Data/Files/ + fab import Production.Workspace/Data.Lakehouse -i ./artifacts/ ``` ### Azure Pipelines example @@ -150,32 +157,25 @@ Add Fabric CLI to GitHub Actions, Azure Pipelines, and other DevOps tools. The s - script: | pip install ms-fabric-cli fab auth login -u $(CLIENT_ID) -p $(CLIENT_SECRET) --tenant $(TENANT_ID) - fab run pipeline /workspaces/ETL/pipelines/DailyRefresh + fab run ETL.Workspace/DailyRefresh.DataPipeline displayName: 'Run Fabric pipeline' ``` -## Run your first command - -Once you're signed in, you're one command away from exploring Fabric: - -```bash -fab ls -``` - -For a detailed list of available commands, see [Commands](./commands/index.md), or explore advanced scenarios in our [Usage examples](./examples/index.md). - ## Get help **Found a bug or have a suggestion?** - [Report an issue](https://github.com/microsoft/fabric-cli/issues) - [Request a feature](https://github.com/microsoft/fabric-cli/discussions) +- [Share feedback via Microsoft Form](https://forms.office.com/r/uhL6b6tNsi) +- [Submit ideas to Fabric Ideas Portal](https://ideas.fabric.microsoft.com/) **Need help using the CLI?** - See [Troubleshooting](./troubleshooting.md) for common problems and solutions - Ask questions in [GitHub Discussions](https://github.com/microsoft/fabric-cli/discussions) - Connect with the community on [r/MicrosoftFabric](https://www.reddit.com/r/MicrosoftFabric/) +- Join the [Microsoft Developer Community](https://community.fabric.microsoft.com/t5/Developer/bd-p/Developer) **Need enterprise assistance?** From 76fdad2bf51237ca4c1563b1c6469d09ce848526 Mon Sep 17 00:00:00 2001 From: Alon Yeshurun <98805507+ayeshurun@users.noreply.github.com> Date: Thu, 15 Jan 2026 09:30:15 +0200 Subject: [PATCH 4/6] Update docs/index.md --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index c228bfad..44e53171 100644 --- a/docs/index.md +++ b/docs/index.md @@ -148,7 +148,7 @@ Add Fabric CLI to GitHub Actions, Azure Pipelines, and other DevOps tools. The s run: | pip install ms-fabric-cli fab auth login -u ${{ secrets.CLIENT_ID }} -p ${{ secrets.CLIENT_SECRET }} --tenant ${{ secrets.TENANT_ID }} - fab import Production.Workspace/Data.Lakehouse -i ./artifacts/ + fab import Production.Workspace/Data.Lakehouse -i ./artifacts/DataToImport.Lakehouse ``` ### Azure Pipelines example From 411062aa4eeaa090dd19c2281d3cf956f91aac87 Mon Sep 17 00:00:00 2001 From: Alon Yeshurun <98805507+ayeshurun@users.noreply.github.com> Date: Thu, 15 Jan 2026 09:31:26 +0200 Subject: [PATCH 5/6] Apply suggestion from @ayeshurun --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 44e53171..eae66911 100644 --- a/docs/index.md +++ b/docs/index.md @@ -31,7 +31,7 @@ Get powerful control over your Fabric resources: ### What you need -- Python 3.10, 3.11, or 3.12 +- Python 3.10, 3.11, 3.12 or 3.13 - `python` in your `PATH` environment variable Check if Python is ready: From ded1001992eafa845d1ae07a460424630a22f3fe Mon Sep 17 00:00:00 2001 From: Alon Yeshurun <98805507+ayeshurun@users.noreply.github.com> Date: Thu, 15 Jan 2026 09:34:38 +0200 Subject: [PATCH 6/6] Apply suggestion from @ayeshurun --- .changes/unreleased/docs-20260104-094108.yaml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.changes/unreleased/docs-20260104-094108.yaml b/.changes/unreleased/docs-20260104-094108.yaml index f60924eb..cf2d63b1 100644 --- a/.changes/unreleased/docs-20260104-094108.yaml +++ b/.changes/unreleased/docs-20260104-094108.yaml @@ -1,3 +1,6 @@ kind: docs body: Improve homepage documentation clarity and structure with better headings, simplified examples, and enhanced getting started instructions time: 2026-01-04T09:41:08.4529672Z +custom: + Author: jeremydhoover-blip + AuthorLink: https://github.com/jeremydhoover-blip