diff --git a/.changes/unreleased/docs-20260104-094108.yaml b/.changes/unreleased/docs-20260104-094108.yaml new file mode 100644 index 00000000..cf2d63b1 --- /dev/null +++ b/.changes/unreleased/docs-20260104-094108.yaml @@ -0,0 +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 diff --git a/docs/index.md b/docs/index.md index 6b2208ee..eae66911 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, 3.12 or 3.13 +- `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. + +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. -*Need a different method?* See the [release notes](./release-notes.md) for standalone binaries and package managers as they become available. +### Sign in -## 🔐 Authenticate +Before you can use the CLI, sign in to Microsoft Fabric. Choose the authentication method that works for your scenario. -`fab` supports **user**, **service principal**, and **managed identity** identity types for sign‑in. +#### Authentication methods -| **Identity Type** | **Scenario** | **Command Usage** | +`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. + +## 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). +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 -## 💬 Feedback & Support +```bash +# See all workspaces +fab ls + +# See what's inside a workspace +fab ls "Sales Analytics.Workspace" +``` + +### Run notebooks and pipelines + +```bash +# Run a pipeline +fab run .Workspace/.DataPipeline -i + +# Start a notebook +fab start .Workspace/.Notebook +``` + +### Move files to OneLake + +```bash +# Upload a local file +fab cp ./local/data.csv .Workspace/.Lakehouse/Files/data.csv + +# Download from OneLake +fab cp .Workspace/.Lakehouse/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 import Production.Workspace/Data.Lakehouse -i ./artifacts/DataToImport.Lakehouse +``` + +### Azure Pipelines example + +```yaml +- script: | + pip install ms-fabric-cli + fab auth login -u $(CLIENT_ID) -p $(CLIENT_SECRET) --tenant $(TENANT_ID) + fab run ETL.Workspace/DailyRefresh.DataPipeline + displayName: 'Run Fabric pipeline' +``` -**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 feedback via Microsoft Form](https://forms.office.com/r/uhL6b6tNsi) +- [Submit ideas to Fabric Ideas Portal](https://ideas.fabric.microsoft.com/) -- **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/) +- Join the [Microsoft Developer Community](https://community.fabric.microsoft.com/t5/Developer/bd-p/Developer) -- **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/)