docs: add more ARM samples for JSON output and --initialPermissions flag#251
docs: add more ARM samples for JSON output and --initialPermissions flag#251bgdnext64 wants to merge 3 commits into
Conversation
bgdnext64
commented
Apr 9, 2026
bgdnext64
commented
- Add ARM JSON output example to installation-and-quickstart.md
- Add ARM --initialPermissions examples (comma-separated and @file.json) to installation-and-quickstart.md
- Add ARM --initialPermissions examples to commandline-flags-and-env-variables.md
- Fix --outputFormat json (non-existent flag) to --jsonOutput in display-options.MD
- Fix JSON output sample to match actual output format (flat map of scope to permissions)
- Add arm-initial-permissions.json sample file
There was a problem hiding this comment.
Pull request overview
Updates MPF documentation to better cover ARM JSON output and the --initialPermissions flag, including correcting the documented JSON flag name and output shape, and adding a reusable sample permissions file.
Changes:
- Add new ARM quickstart examples for
--jsonOutputand--initialPermissions(comma-separated and@file.json) usage. - Fix docs to use
--jsonOutput(instead of the non-existent--outputFormat json) and update JSON output examples to the flat scope→permissions map format. - Add a sample
arm-initial-permissions.jsontemplate file.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
samples/templates/arm-initial-permissions.json |
Adds a sample JSON file for seeding initial permissions via --initialPermissions @file. |
go.mod |
Bumps the Go version directive. |
docs/installation-and-quickstart.md |
Adds ARM JSON output and --initialPermissions examples to the quickstart. |
docs/display-options.MD |
Fixes the JSON output flag name and updates the ARM JSON output example format. |
docs/commandline-flags-and-env-variables.md |
Adds ARM --initialPermissions examples (comma-separated and JSON file). |
| $env:MPF_SPOBJECTID = "YOUR_SP_OBJECT_ID" | ||
|
|
||
| .\azmpf.exe arm --templateFilePath .\samples\templates\aks-private-subnet.json --parametersFilePath .\samples\templates\aks-private-subnet-parameters.json ` | ||
| --initialPermissions @arm-initial-permissions.json ` |
There was a problem hiding this comment.
In PowerShell, an unquoted argument starting with @ is parsed as splatting/hashtable syntax and will fail here. Quote the value so it’s passed through to the CLI (e.g., use a quoted string that starts with @...).
| --initialPermissions @arm-initial-permissions.json ` | |
| --initialPermissions "@arm-initial-permissions.json" ` |
There was a problem hiding this comment.
Fixed. I quoted the value in the PowerShell example so it now reads --initialPermissions "@arm-initial-permissions.json" and gets passed straight through to the CLI instead of being treated as splatting.
| $env:MPF_SPOBJECTID = "YOUR_SP_OBJECT_ID" | ||
|
|
||
| .\azmpf.exe arm ` | ||
| --initialPermissions @arm-initial-permissions.json ` |
There was a problem hiding this comment.
In PowerShell, --initialPermissions @arm-initial-permissions.json will be parsed as splatting syntax rather than a literal argument. Quote the @... value so the executable receives it as a string path.
| --initialPermissions @arm-initial-permissions.json ` | |
| --initialPermissions "@arm-initial-permissions.json" ` |
There was a problem hiding this comment.
Fixed. Same change here, the PowerShell example now wraps the value in quotes as --initialPermissions "@arm-initial-permissions.json" so it reaches the executable as a literal string path.
| ### Bicep JSON Output | ||
|
|
||
| Similar to ARM templates, Bicep deployments can produce JSON output which shows detailed permission breakdowns. The following is a sample of JSON output: |
There was a problem hiding this comment.
The Bicep --jsonOutput section still contains a description later in the section referring to the old JSON structure ("permissions" / "permissionsByResourceScope"). Please update the Bicep JSON Output text so it matches the current --jsonOutput format (flat map of scope → permissions), consistent with the ARM JSON example above.
There was a problem hiding this comment.
Done. I rewrote the Bicep JSON Output section so it describes the current flat map format, where the subscription key holds the aggregate permissions and each resource scope key holds its own, matching the ARM example above. The old references to the permissions array and permissionsByResourceScope are gone.
| --verbose | ||
| ``` | ||
|
|
||
| ### Example: ARM with JSON File Format |
There was a problem hiding this comment.
Should this be ARM with Known Permissions (JSON File format)
There was a problem hiding this comment.
Hi @bgdnext64 once this nit is addressed, we are good to go
There was a problem hiding this comment.
Good call, I updated the heading to read "ARM with Known Permissions (JSON File format)". That nit is taken care of now, so we should be good to go. Thanks Mani.
- Add ARM JSON output example to installation-and-quickstart.md - Add ARM --initialPermissions examples (comma-separated and @file.json) to installation-and-quickstart.md - Add ARM --initialPermissions examples to commandline-flags-and-env-variables.md - Fix --outputFormat json (non-existent flag) to --jsonOutput in display-options.MD - Fix JSON output sample to match actual output format (flat map of scope to permissions) - Add arm-initial-permissions.json sample file
- Add language specifiers to fenced code blocks (MD040) - Add blank line before heading (MD022)
- Rename ARM JSON heading to 'ARM with Known Permissions (JSON File format)' - Quote @file paths in PowerShell --initialPermissions examples - Update Bicep JSON output description to flat scope->permissions map
bgdnext64
force-pushed
the
bgdnext64/86-add-more-arm-samples
branch
from
44b9f1c to
3ee3f12
Compare
