@microsoft/managed-apps-cli

Command-line interface for Microsoft managed apps. Create, build, deploy, share, and manage apps and their data sources from your terminal.

Install

npm install -g @microsoft/managed-apps-cli

Run commands with ms <command>.

Commands

• ms app … — app lifecycle and configuration: create, clone platform-managed repositories, init, list, info (show is a deprecated alias), build, build-status, pack, deploy, play (including branch or commit previews), dev, delete, share/unshare, share list, share link (create, list, revoke), add config (preview, requires the alm feature; registers a project deployment and creates its local overlay), add data-source (including repeated --table flags for adding multiple tables with per-table partial-success reporting, and preview --deployment <name> --for <logical-name> binding updates), remove data-source, refresh data-source (--offline), and settings (get-settings, set-setting).
• ms project … — project-related command groups. Managed project commands (create, info, list, add deployment-target, build, build-status, deploy, deployment-status, pack, add approval, list approval, remove approval) are preview and require the projects feature; project creation supports a platform-managed repository or --repo <github-url>. State commands are experimental and require the state feature.
• ms project add|remove|list approval — manage who can approve deployments to a project's Prod target (preview, requires the projects feature). Approvers are Microsoft Entra object IDs or user/group email addresses; remove --all clears the list. Use --project and --environment-id outside a managed project directory.
• ms deployment list|status — list project-scoped or environment-wide deployment history, or show the latest or selected deployment (preview, requires the projects feature). Use --project <project-id> to select project history explicitly; otherwise a local project config or the current app's live project association is used when available. Use --environment-id alone for environment-wide history and --target to select prod or a named target. Use --continuation-token to resume when the output reports more history. Latest-deployment detail includes created time, source links, requester and approval metadata, and build status when available.
• ms deployment approve|reject|cancel --target <name> — act on a deployment that is awaiting approval (preview, requires the projects feature). approve and reject accept an optional --comment. They run only where the service's approvals feature is enabled.
• ms connector … — list connectors and discover connector actions and functions in the environment.
• ms project state … — clear Preview state or define and inspect the app's configured state schema (add, alter, remove, list-schema, list-settings, set-setting), or generate standalone TypeScript with generate-code. Experimental and off by default; turn it on with ms feature enable --name state or MS_CLI_FEATURE_STATE=1. It is also on for an app whose ms.config.json sets state.enabled: true.
• ms auth … — sign in/out and manage cached accounts (login, logout, status, switch).
• ms git auth … — refresh or establish the Entra↔GitHub identity mapping for external repos.
• ms telemetry … — enable, disable, or check CLI telemetry.
• ms feature … — list, inspect, enable, disable, or reset experimental and preview CLI features.

Run ms <command> --help for the options on any command.

TLS certificate errors

If the CLI reports TlsCertificateTrustFailure, configure your operating system and Node.js to trust your organization's certificate authority, or contact your network administrator. Do not disable TLS certificate validation. TlsCertificateValidationFailure indicates that the service certificate could not be validated; try again later, then contact Microsoft support with the reported session ID if the problem continues.

Use ms --version or ms -v to print the CLI version. The version option is available only on the root command, not on commands such as ms app list.

Managed project and deployment commands require the projects feature. Enable it with ms feature enable --name projects; it is also enabled automatically inside a managed project or an app associated with one. Project state commands additionally require the state feature.

ms app deploy guards git-backed deployments when the working tree has uncommitted changes or local main is ahead of origin/main. Interactive runs can confirm and continue; non-interactive runs must pass --force to bypass the guard.

On the default /appframework route, a deployment that needs app data migration is accepted as an operation. ms app deploy waits for that operation (up to 20 minutes) and reports success only after the service confirms the deployment. With the Managed DevOps route enabled, the service instead returns a durable deployment ID and the CLI polls until the deployment succeeds or reaches AwaitingApproval. Approval is a handoff point: the CLI returns the deployment ID instead of waiting for a human decision.

ms app deploy --no-wait is available when the projects feature is enabled. It skips deployment polling, but still waits for a queued prerequisite build on git-backed apps and still packs/uploads external artifacts before submitting the deployment. After the service accepts the deployment, the command returns its stable deployment ID for later tracking.

ms app deploy --target <name> requires the alm feature; without the feature the option is not registered and is rejected as unknown. Enable it with ms feature enable --name alm or MS_CLI_FEATURE_ALM=1. The target name is validated locally before any build or deploy call. After a successful targeted deploy, human output and the JSON appPlayUri field report the target-specific /target/<name> play URL rather than the base production URL.

ms project deploy requires the projects feature and is a temporary single-app alias for the app deployment pipeline. Unless --project is supplied, it prefers the current app and its server-side project association before falling back to ms.project.config.json. The fallback project route requires the project to contain exactly one app. --environment-id takes precedence over app config, project config, and developer-environment routing. The final deploy uses Managed DevOps, matching ms app deploy when the projects feature is enabled, so --no-wait is available for the command. The command does not expose --app or --artifact. Without --no-wait, it waits until deployment succeeds or reaches AwaitingApproval, then returns the deployment ID instead of waiting for a human approval decision. When --target is supplied, successful output reports that target's /target/<name> play URL instead of the production URL. Multi-app project deployment will move to a dedicated service API.

ms project deployment-status shows the latest deployment for the resolved project, or a specific deployment when --deployment-id is supplied. It prefers the current app's server-side project association, then falls back to local app/project configuration; use --project to select a project explicitly. Use --environment-id to route that project lookup to a specific environment; when an explicit project ID has no environment flag, the default environment is used. ms deployment status is an alias with the same flags and behavior.

The complete ms project state command group is experimental and requires MS_CLI_FEATURE_STATE=1; without it the group is hidden from help and rejected as an unknown command.

ms project state clear [--app <app-id>] [--environment-id <id>] discards the app's Preview state for all users and all item types. Live data, source code, and the app itself are unchanged. The app ID defaults from ms.config.json; an explicit real, non-zero app GUID (without -dev) works outside a checkout. The environment is resolved before confirmation, without inheriting an unrelated config environment.

JSON/non-interactive runs require explicit --force acknowledgement, for example ms project state clear --app <app-id> --force --json --non-interactive. This skips local confirmation only, never Update authorization or server locks. A valid 200 returns exit 0 with the exact wasAlreadyEmpty, observedEmpty, and isComplete Booleans; request success does not mean purge completion. The current service normally returns isComplete: false, which produces a stderr warning. Missing or invalid completion fields are errors. The client waits up to 120 seconds, never automatically retries or polls, and reports unknown outcome on interruption or connection loss. Do not chain Preview, writes, reindex, or deploy while completion is unconfirmed; there is no public reset-status endpoint.

To include a schema in ms app pack, set state.schemaPath in the base app config to a project-relative JSON file. data.schemaPath and the legacy db.schemaPath alias remain supported; when multiple aliases are present, they must either all omit schemaPath or set path strings that match exactly (no normalization). Invalid aliases fail even if another alias is valid. These settings are base-only and cannot be overridden by a deployment overlay. Pack writes dataSchema.json and points the unchanged manifest.dataSchemaPath field to it, regardless of which alias was configured. schemaPath is optional: without it, pack writes no schema file and no dataSchemaPath.

Optionally set state.enabled, data.enabled, or legacy db.enabled to a boolean to copy it to manifest.dataEnabled. Both true and false are preserved; if unset, the manifest field is omitted. When both aliases specify enabled, their values must agree; if only one specifies it, that value is used. This flag is also base-only and does not skip schema validation or packaging: a configured schemaPath is still validated and packaged when enabled is false, and { "data": { "enabled": true } } enables data without a schema.

For ms project state commands, state.schemaPath is the preferred state schema location. state.enabled is also accepted and copied to manifest.dataEnabled during pack.

ms app pack also includes package-inventory.json beside the manifest (not under client/). The CLI selects the app's direct production dependencies and records their installed names and versions, following npm, pnpm, and Bun node_modules layouts and package symlinks without reading lockfiles. Dev and transitive-only dependencies are excluded. The versioned artifact distinguishes an explicit zero-package inventory from unavailable data and reports unresolved required dependencies and truncation. It does not include registry URLs, attest to bundled code, or select the build's package manager. Collection failures warn on stderr without failing the build or changing JSON stdout. See the pack artifact contract for the schema, limits, and consumer requirements.

With the alm feature enabled, ms project pack uses the directory containing ms.project.config.json as the project root. When components.apps is present, only those listed directories are searched for app configs; each path must be the project root or a descendant, and symlinks that resolve outside that boundary are rejected. This supports apps nested anywhere within the project. When the list is absent, pack falls back to discovering app configs at the root and in immediate child directories. When no project config is present, it treats the directory containing the current app config as a single-app project. An empty app set fails before staging begins. ms.config.json takes precedence when both supported app config names exist in a directory. Packing logs which discovery mode it selected, remains local, and does not retrieve live app information. Apps without package.json and apps with buildType: "none" skip dependency installation. Output is written to .ms/packed/apps/<appId>/ alongside .ms/packed/project.manifest.json, preserving the existing artifact if validation, an app build, or artifact promotion fails.

ms project pack --json returns a discriminated project result. Successful responses include the promoted project paths, app pack results under components.apps, and install/pack/finalization timings. Success and failure responses include logFile when available, pointing to captured stdout and stderr from dependency-install and app-build commands, plus app-pack failure diagnostics, up to a 50 MB limit. Log creation and capture are best-effort and never change the command result. The five newest logs are retained, and staging directories older than 24 hours are removed. Failed responses include partial app results and timings, including elapsed app-pack phases measured before failure, but omit project artifact paths; dependency-install or app-pack failures do not prevent remaining project apps from being attempted.

ms project state generate-code reads that schema locally and writes models, validators, and typed data services to generated-typescript/ beside it. It needs no login or network connection, including in CI; there are no command-specific flags. Use --json for relative paths, item types, file count, and any cleanup warnings. Keep handwritten code outside the output directory: replacement requires a valid ownership manifest and refuses untracked files.

Generated update methods send a complete writable document using PUT. Use edit for a fresh read/merge/conditional PUT with bounded conflict retries. Per-user services preserve private/shared scope. The generated services require Preview or a deployed app, not ms app dev; code generation does not deploy or provide a local state store. Attachment upload/clear and undocumented query operators are not generated. See the command reference for output ownership, rollback, validation, and paging behavior.

Global options

| Option | Description | | ------------------- | -------------------------------------------------- | | --non-interactive | Run without prompts (all values must be supplied). | | --json | Format output as JSON. | | --no-color | Disable coloured output. |

Full documentation is available in the Microsoft managed apps documentation.