Add Start-FinOpsMultitool — cross-platform terminal UI for FinOps scanning

.build/BuildHelper/Build-PsModule.ps1

@@ -20,8 +20,8 @@ function Build-PsModule
     $moduleName = 'FinOpsToolkit'
     $moduleFullName = "$moduleName.psm1"
     $modulePath = Join-Path -Path $rootPath -ChildPath "src/powershell/$moduleFullName"
-    $privatePath = Join-Path -Path $rootPath -ChildPath "src/powershell/private"
-    $publicPath = Join-Path -Path $rootPath -ChildPath "src/powershell/public"
+    $privatePath = Join-Path -Path $rootPath -ChildPath "src/powershell/Private"
+    $publicPath = Join-Path -Path $rootPath -ChildPath "src/powershell/Public"
     $stringsPath = Join-Path -Path $rootPath -ChildPath 'src/powershell/en-US'
     $releasePath = Join-Path -Path $rootPath -ChildPath "release/$moduleName/$baseVersion"
     $manifestPath = Join-Path -Path $releasePath -ChildPath "$moduleName.psd1"

.github/workflows/dev.yml

@@ -3,6 +3,11 @@ name: 'PowerShell Tests'
 on:
   pull_request:
     paths:
+      - '.github/workflows/dev.yml'
+      - '.build/BuildHelper/**'
+      - '.build/BuildHelper.psm1'
+      - 'package.json'
+      - 'src/scripts/Get-Version.ps1'
       - 'src/powershell/**'
       # KQL sources are covered by unit tests (HubsKqlOperators.Tests.ps1)
       - 'src/templates/finops-hub/**/*.kql'
@@ -11,6 +16,10 @@ on:
       - 'src/templates/finops-hub/**/timeZones.bicep'
       - 'docs/deploy/finops-hub-latest.json'
       - 'docs/deploy/finops-hub-preview.json'
+
+permissions:
+  contents: read
+
 jobs:
   run_pester_tests:
     name: Pester
@@ -25,3 +34,124 @@ jobs:
       - name: Run Tests
         shell: pwsh
         run: .build/start.ps1 -Task Test.PowerShell.All
+
+  multitool_native:
+    name: Multitool (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [windows-latest, ubuntu-latest, macos-latest]
+    env:
+      DOTNET_CLI_TELEMETRY_OPTOUT: '1'
+      DOTNET_NOLOGO: '1'
+    steps:
+      - name: Install and cache test dependencies
+        uses: potatoqualitee/psmodulecache@9e4b63833c22c1768d648e115a9c849afdda22a5 # v6.3
+        with:
+          modules-to-cache: Pester:6.0.0, Az.Accounts, Az.Resources, Az.ResourceGraph, Az.Storage
+          shell: pwsh
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Install SDK for native Parquet restore
+        if: runner.os == 'Linux'
+        uses: actions/setup-dotnet@26b0ec14cb23fa6904739307f278c14f94c95bf1 # v5
+        with:
+          dotnet-version: '8.0.x'
+      - name: Run native multitool tests
+        shell: pwsh
+        env:
+          TMPDIR: ${{ runner.temp }}
+        run: |
+          $ErrorActionPreference = 'Stop'
+          Import-Module Pester -RequiredVersion 6.0.0 -Force
+          $names = @(
+              'AzGraphPagination', 'BudgetCoverage', 'CommitmentUtilizationDedupe'
+              'CostQueryPagination', 'CurrencyLabel', 'FOHubProvider', 'HubSizeProbe'
+              'MultitoolSafety', 'ParquetPackageClient', 'PolicyEffect'
+              'RetryJitter', 'Start-FinOpsMultitool'
+          )
+          $paths = @($names | ForEach-Object {
+              Join-Path 'src/powershell/Tests/Unit' "$_.Tests.ps1"
+          })
+          foreach ($path in $paths) {
+              if (-not (Test-Path -LiteralPath $path -PathType Leaf)) { throw "Missing test: $path" }
+          }
+          $configuration = New-PesterConfiguration
+          $configuration.Run.Path = $paths
+          $configuration.Run.PassThru = $true
+          $configuration.Run.Exit = $false
+          $configuration.Output.Verbosity = 'Detailed'
+            $configuration.TestResult.Enabled = $true
+            $configuration.TestResult.OutputFormat = 'NUnitXml'
+            $configuration.TestResult.OutputPath = Join-Path $env:RUNNER_TEMP 'multitool-unit.xml'
+          $result = Invoke-Pester -Configuration $configuration
+          $result | Select-Object Result, TotalCount, PassedCount, FailedCount, SkippedCount, FailedContainersCount
+            @(
+              '## Multitool validation'
+              "Tested merge commit: $env:GITHUB_SHA"
+              "Host: $([Runtime.InteropServices.RuntimeInformation]::OSDescription); PowerShell: $($PSVersionTable.PSVersion)"
+              "Unit tests: $($result.Result); passed $($result.PassedCount), failed $($result.FailedCount), skipped $($result.SkippedCount)."
+            ) | Add-Content -LiteralPath $env:GITHUB_STEP_SUMMARY
+          if ($null -eq $result -or $result.Result -ne 'Passed' -or
+              $result.TotalCount -le 0 -or $result.PassedCount -le 0 -or
+              $result.FailedCount -ne 0 -or $result.FailedContainersCount -ne 0 -or
+              $result.FailedBlocksCount -ne 0 -or $result.Containers.Count -ne $paths.Count) {
+              throw 'Native multitool tests failed or discovery was incomplete.'
+          }
+          exit 0
+      - name: Run package and real Parquet integration tests
+        if: ${{ !cancelled() }}
+        shell: pwsh
+        env:
+          TMPDIR: ${{ runner.temp }}
+        run: |
+          $ErrorActionPreference = 'Stop'
+          Import-Module Pester -RequiredVersion 6.0.0 -Force
+            $paths = @('src/powershell/Tests/Integration/MultitoolPackage.Tests.ps1')
+            $minimumPassed = 3
+            $parquetCoverage = 'Not run on macOS: NuGet signed-package verification is not supported. https://learn.microsoft.com/dotnet/core/tools/nuget-signed-package-verification#macos'
+            if (-not $IsMacOS) {
+              $paths += 'src/powershell/Tests/Integration/MultitoolParquet.Tests.ps1'
+              $minimumPassed += 2
+              $parquetCoverage = 'Real signed Parquet restore and cold/cached reads in separate processes.'
+            }
+          foreach ($path in $paths) {
+              if (-not (Test-Path -LiteralPath $path -PathType Leaf)) { throw "Missing test: $path" }
+          }
+          $configuration = New-PesterConfiguration
+          $configuration.Run.Path = $paths
+          $configuration.Run.PassThru = $true
+          $configuration.Run.Exit = $false
+          $configuration.Output.Verbosity = 'Detailed'
+          $configuration.TestResult.Enabled = $true
+          $configuration.TestResult.OutputFormat = 'NUnitXml'
+          $configuration.TestResult.OutputPath = Join-Path $env:RUNNER_TEMP 'multitool-integration.xml'
+          $result = Invoke-Pester -Configuration $configuration
+          $result | Select-Object Result, TotalCount, PassedCount, FailedCount, SkippedCount, FailedContainersCount
+          @(
+              "Integration tests: $($result.Result); passed $($result.PassedCount), failed $($result.FailedCount), skipped $($result.SkippedCount)."
+              'Checks: isolated module build and public launch; CSV, HTML, and text reports.'
+              "Parquet coverage: $parquetCoverage"
+              'Azure access is replaced with synthetic responses. Package downloads and signature verification require network access.'
+          ) | Add-Content -LiteralPath $env:GITHUB_STEP_SUMMARY
+          if ($null -eq $result -or $result.Result -ne 'Passed' -or
+              $result.PassedCount -lt $minimumPassed -or $result.FailedCount -ne 0 -or
+              $result.SkippedCount -ne 0 -or $result.NotRunCount -ne 0 -or
+              $result.FailedContainersCount -ne 0 -or $result.FailedBlocksCount -ne 0 -or
+              $result.Containers.Count -ne $paths.Count) {
+              throw 'Multitool integration tests failed, were skipped, or discovery was incomplete.'
+          }
+          exit 0
+      - name: Upload multitool test evidence
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: multitool-tests-${{ matrix.os }}
+          path: |
+            ${{ runner.temp }}/multitool-unit.xml
+            ${{ runner.temp }}/multitool-integration.xml
+          if-no-files-found: error
+          retention-days: 14

docs-mslearn/TOC.yml

@@ -196,6 +196,12 @@
           href: toolkit/alerts/finops-alerts-overview.md
         - name: Configure alerts
           href: toolkit/alerts/configure-finops-alerts.md
+    - name: FinOps multitool
+      items:
+        - name: Overview
+          href: toolkit/multitool/finops-multitool-overview.md
+        - name: Commands
+          href: toolkit/powershell/multitool/finops-multitool-commands.md
     - name: Optimization engine
       items:
         - name: Overview
@@ -242,6 +248,12 @@
               href: toolkit/powershell/cost/remove-finopscostexport.md
             - name: Start-FinOpsCostExport
               href: toolkit/powershell/cost/start-finopscostexport.md
+        - name: FinOps multitool
+          items:
+            - name: FinOps multitool commands
+              href: toolkit/powershell/multitool/finops-multitool-commands.md
+            - name: Start-FinOpsMultitool
+              href: toolkit/powershell/multitool/start-finopsmultitool.md
         - name: FinOps hubs
           items:
             - name: FinOps hubs commands

docs-mslearn/toolkit/changelog.md

@@ -3,7 +3,7 @@ title: FinOps toolkit changelog
 description: Review the latest features and enhancements in the FinOps toolkit, including updates to FinOps hubs, Power BI reports, and more.
 author: MSBrett
 ms.author: brettwil
-ms.date: 09/11/2026
+ms.date: 09/24/2026
 ms.topic: reference
 ms.service: finops
 ms.subservice: finops-toolkit
@@ -54,6 +54,19 @@ The following section lists features and enhancements that are currently in deve
 - **Fixed**
   - Made the idle application gateway and idle public IP query join kinds explicit so they no longer rely on the `innerunique` default ([#2225](https://github.com/microsoft/finops-toolkit/pull/2225)).
 
+### [FinOps multitool](multitool/finops-multitool-overview.md)
+
+- **Added**
+  - Added the FinOps multitool, which scans an Azure environment for cost optimization, governance, and FinOps insights through a PowerShell 7 terminal UI ([#2155](https://github.com/microsoft/finops-toolkit/pull/2155)).
+    - Included 30 read-only scan modules, with 26 available in the menu, covering orphaned resources, idle VMs, storage tier advice, Azure Hybrid Benefit, tag and policy inventory and recommendations, cost data, cost trend, cost by tag, resource costs, reservation advice, commitment utilization, estimated savings, budget status and history, anomaly alerts, Advisor recommendations, billing structure, and contract info.
+    - Added a companion set of agent skills that carry the investigation routing, the queries, and the interpretation rules so AI agents can run the same analysis through Azure CLI or an Azure MCP server.
+    - Added engine-side aggregation through the FinOps hub's Azure Data Explorer or Microsoft Fabric Kusto database for large environments, with a storage reader as a small-dataset fallback.
+    - Added a non-interactive mode for an already-authenticated pipeline or scheduled job, and automatic private CSV, HTML, and text reports. Consoles that can't render the arrow-key menus, such as PowerShell remoting sessions, fall back to numbered prompts.
+    - Added a searchable KPI reference and in-report calculation details for cost shares, unit rates, VM and storage screening, and budget coverage and forecast availability.
+- **Fixed**
+  - Fixed storage-backed Parquet imports returning empty values or misaligning costs when an export contains nested metadata.
+  - Fixed measured zero unit-cost KPIs appearing unavailable.
+
 ### [Power BI reports](power-bi/reports.md)
 
 - **Changed**

docs-mslearn/toolkit/finops-toolkit-overview.md

@@ -3,7 +3,7 @@ title: FinOps toolkit overview
 description: Learn how the FinOps toolkit helps you automate and extend the Microsoft Cloud with starter kits, scripts, and advanced solutions to improve FinOps practices.
 author: flanakin
 ms.author: micflan
-ms.date: 08/05/2026
+ms.date: 09/16/2026
 ms.topic: concept-article
 ms.service: finops
 ms.subservice: finops-toolkit
@@ -33,6 +33,7 @@ The FinOps toolkit is an ever-evolving collection of tools and resources. The fo
   - [Governance workbook](./workbooks/governance.md) – Central hub for governance.
 - [Azure Optimization Engine](./optimization-engine/overview.md) – Extensible solution for custom optimization recommendations.
 - [PowerShell module](./powershell/powershell-commands.md) – Automate and manage FinOps solutions and capabilities.
+- [FinOps multitool](./powershell/multitool/finops-multitool-commands.md) – Scan an Azure environment for cost, governance, and optimization insights from a terminal UI, with agent skills so AI assistants can run the same analysis.
 - [Bicep Registry modules](./bicep-registry/modules.md) – Official repository for Bicep modules.
 - [Open data](open-data.md) – Data available for anyone to access, use, and share without restriction.
   - [Pricing units](open-data.md#pricing-units) – Microsoft pricing units, distinct units, and scaling factors.

docs-mslearn/toolkit/multitool/finops-multitool-overview.md

@@ -0,0 +1,90 @@
+---
+title: FinOps multitool overview
+description: FinOps multitool scans an Azure environment for cost optimization, governance, and FinOps insights from a terminal UI, with agent skills so AI assistants can run the same analysis.
+author: z-larsen
+ms.author: zlarsen
+ms.date: 09/20/2026
+ms.topic: concept-article
+ms.service: finops
+ms.subservice: finops-toolkit
+ms.reviewer: micflan
+#customer intent: As a FinOps practitioner, I need to learn about the FinOps multitool.
+---
+
+# FinOps multitool
+
+FinOps multitool scans an Azure environment for cost optimization, governance, and FinOps insights, grounded in your live resource state. It reports on cost trends, orphaned resources, idle VMs, tag hygiene, reservation and savings plan utilization, Azure Hybrid Benefit opportunities, budgets, anomaly alerts, and policy compliance. Run it from an interactive terminal, or call it as tools from an AI agent.
+
+## How it works
+
+FinOps multitool provides 30 scan modules, with 26 available in the terminal menu, and renders findings for the subscriptions you select:
+
+- **Interactive scanning** <br> Choose the subscriptions and scan modules you want, then review results in the terminal. Every completed run automatically saves CSV files, an HTML report, and a text summary to a private local folder. See [Report storage](../powershell/multitool/start-finopsmultitool.md#report-storage) for locations and privacy limits. Consoles that can't render the arrow-key menus fall back to numbered prompts. Non-interactive runs require an existing Azure sign-in context.
+
+- **AI agent support** <br> Agent skills describe the same investigations, the queries behind them, and how to read the results, so AI assistants can answer cost questions from your environment's data.
+
+- **Cost data sources** <br> When a [FinOps hub](../hubs/finops-hubs-overview.md) is available, cost scans query the hub's Azure Data Explorer or Microsoft Fabric database and push aggregation into the engine, returning only summarized results. A storage reader covers smaller datasets, and the Cost Management API is used when no hub is present.
+
+- **Read-only** <br> The multitool never creates, changes, or deletes a resource.
+
+## Benefits
+
+FinOps multitool provides the following benefits:
+
+- Choose from 26 menu scans across optimization, governance, cost analysis, commitments, monitoring, and sustainability, with four more modules for direct investigations.
+- Scope each scan to the subscriptions you select.
+- Get a CSV file per selected scan, an HTML report, and a text summary saved automatically to a private local folder.
+- Read costs from a FinOps hub or the Cost Management API, with resource inventory from Azure Resource Graph.
+- Run the same scans from a pipeline or a scheduled job with `-NonInteractive`.
+- Run the same investigations from an AI assistant through agent skills.
+
+## Why FinOps multitool?
+
+[FinOps workbooks](../workbooks/finops-workbooks-overview.md) and the [Azure Optimization Engine](../optimization-engine/overview.md) surface optimization opportunities in the Azure portal. FinOps multitool reports the same kinds of findings in the terminal and through AI agent skills, so you can scan an environment during a working session without leaving the command line.
+
+## Required permissions
+
+Most scans need [Reader](/azure/role-based-access-control/built-in-roles#reader) or [Cost Management Reader](/azure/role-based-access-control/built-in-roles#cost-management-reader) on the target scope. Account scans (billing structure, contract info, and Microsoft Azure Consumption Commitment balance) also need agreement-specific billing access: [Billing account reader or Billing profile reader for a Microsoft Customer Agreement](/azure/cost-management-billing/manage/understand-mca-roles), or [Enterprise Administrator (read only) for an Enterprise Agreement](/azure/cost-management-billing/manage/understand-ea-roles), at the scope the scan reads.
+
+Commitment utilization reads reservation and savings plan usage at billing account or billing profile scope, so it needs the same access as account scans. Reader on a subscription isn't enough. Without it, the scan tells you it couldn't reach a billing scope instead of showing zero commitments.
+
+The carbon scan needs Reader or [Carbon Optimization Reader](/azure/carbon-optimization/permissions) assigned at the subscription. Carbon emissions permissions don't apply at resource group or resource scope.
+
+## Give feedback
+
+Let us know how we're doing with a quick review. We use these reviews to improve and expand FinOps tools and resources.
+
+<!-- prettier-ignore-start -->
+> [!div class="nextstepaction"]
+> [Give feedback](https://portal.azure.com/#view/HubsExtension/InProductFeedbackBlade/extensionName/FinOpsToolkit/cesQuestion/How%20easy%20or%20hard%20is%20it%20to%20use%20FinOps%20multitool%3F/cvaQuestion/How%20valuable%20are%20FinOps%20multitool%3F/surveyId/FTK/bladeName/Multitool/featureName/Overview)
+<!-- prettier-ignore-end -->
+
+If you're looking for something specific, vote for an existing or create a new idea. Share ideas with others to get more votes. We focus on ideas with the most votes.
+
+<!-- prettier-ignore-start -->
+> [!div class="nextstepaction"]
+> [Vote on or suggest ideas](https://github.com/microsoft/finops-toolkit/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22Tool%3A%20PowerShell%22%20sort%3Areactions-%2B1-desc)
+<!-- prettier-ignore-end -->
+
+<br>
+
+## Related content
+
+Related FinOps capabilities:
+
+- [Reporting and analytics](../../framework/understand/reporting.md)
+- [Workload optimization](../../framework/optimize/workloads.md)
+- [Rate optimization](../../framework/optimize/rates.md)
+
+Related products:
+
+- [Azure Resource Graph](/azure/governance/resource-graph/)
+- [Cost Management](/azure/cost-management-billing/)
+
+Related solutions:
+
+- [FinOps multitool commands](../powershell/multitool/finops-multitool-commands.md)
+- [FinOps hubs](../hubs/finops-hubs-overview.md)
+- [FinOps workbooks](../workbooks/finops-workbooks-overview.md)
+
+<br>