play

📋 Shared Instructions: shared-instructions.md — Cross-cutting concerns.

Play

Opens a Microsoft App in the browser by fetching its cloud play URL and launching it. No local dev server required.

Mode	Command	What opens
`live` (default)	`ms app play`	The most recently deployed version. A snapshot — does not update until `ms app deploy` is run again.
`preview` (main)	`ms app play --mode preview`	Built from the `main` branch on demand — always reflects the latest pushed code, even without a deploy.
`preview` (commit)	`ms app play --mode preview --commit <sha>`	App as of a specific commit SHA — useful for code review or regression testing.

Live vs. preview: Live requires a prior ms app deploy. Preview builds from source on demand — it works without any deployment and always reflects unpublished code.

Workflow

Memory Bank → 2. Verify Project + Env → 3. Resolve Mode → 4. Run → 5. Surface URL

Step 1: Check Memory Bank

Read memory-bank.md per shared-instructions.md for the app's environment/app identifiers, if recorded.

Step 2: Verify Project + Env

test -f ms.config.json || { echo "Not in a Microsoft App workspace."; exit 1; }
BIN=ms
$BIN auth status                                         # must report the expected UPN

--app and --environment-id can be passed explicitly to run from outside a project directory — ms.config.json is only needed for the defaults.

Step 3: Resolve Mode

If not already clear from the user's request, ask:

"Do you want to open the live deployed version, a preview of the latest code on main, or a preview of a specific commit?"

Map intent to mode:

User says	Mode
"live", "deployed", no qualifier	`live` (default — no flag needed)
"preview", "latest", "unpublished", "before deploy"	`--mode preview`
"preview at commit X" / specific SHA provided	`--mode preview --commit <sha>`

Step 4: Run

Live (default):

$BIN app play

Preview — latest code on main:

$BIN app play --mode preview

Preview — specific commit:

$BIN app play --mode preview --commit <sha>

Full flag reference:

Flag	Alias	Default	Description
`--mode`	`-m`	`live`	`live` or `preview`.
`--commit`	`-c`	HEAD on main	Preview only. The commit SHA to open. Ignored for live mode (CLI throws if combined).
`--app`		`appId` from `ms.config.json`	App name override for running outside the project directory.
`--no-browser`		false	Print the URL without opening a browser tab.
`--json`			Emit `{ success, appName, mode, url, commitHash }` instead of human-readable output.

Step 5: Surface URL

Present the URL the CLI printed. For live mode, surface the CLI's built-in warning:

Live URL for 'my-app':
  https://apps.powerapps.com/play/e/<env-id>/app/<guid>

⚠ Live does not auto-update. Run /deploy to publish new code to the live URL.

For preview:

Preview URL for 'my-app' (main):
  https://apps.powerapps.com/play/e/<env-id>/app/<guid>/branch/main

For commit-pinned preview:

Preview URL for 'my-app' (commit abc1234):
  https://apps.powerapps.com/play/e/<env-id>/app/<guid>/commit/abc1234

Edge Cases

Situation	Action
`No live build available — run 'ms app deploy' first`	The app has never been deployed. Tell the user to run `/deploy`, then retry `ms app play`.
`--commit` passed with `--mode live`	Hard `UsageError` from the CLI. Explain that `--commit` only works with `--mode preview`.
No `appPlayUri` for preview mode	App record exists but play URI is missing. Surface the error verbatim and stop.
User wants URL without opening a browser	Pass `--no-browser`; the CLI prints the URL and exits without launching a tab.
User is outside a project directory	Pass `--app <name>` and `--environment-id <id>` explicitly.