What is Microsoft Power Platform CLI?

Note

Effective June 2021, Microsoft Power Apps CLI is rebranded to Microsoft Power Platform CLI. More information: Blog: Microsoft Power Platform is the best way for teams to build together.

Microsoft Power Platform CLI is a simple, single-stop developer command-line interface that empowers developers and ISV to perform various operations in Microsoft Power Platform related to environment lifecycle features, authenticate and work with Dataverse environments, solution packages, portals, code components, and so on.

Install Microsoft Power Platform CLI

To get Microsoft Power Platform CLI, do the following:

  1. Install Microsoft Power Platform CLI.

  2. To take advantage of all the latest capabilities, update Microsoft Power Platform CLI tooling to the latest version using this command (not applicable for Visual Studio Code Extension):

    pac install latest
    

Note

  • Currently, Microsoft Power Platform CLI is supported only on Windows 10.
  • Power Platform Extension for Visual Studio Code is in public preview and works on both Windows 10 and macOS.

Install Power Platform Extension for Visual Studio Code

You can also install the Power Platform Extension for Visual Studio Code which installs Microsoft Power Platform CLI for use within Visual Studio Code. The Power Platform extension makes it easy to manage Power Platform environments and allows the developer to create, build packages, deploy solutions, and portals.

Important

  • Power Platform Extension for Visual Studio Code is in public preview.
  • Preview features aren’t meant for production use and may have restricted functionality. These features are available before an official release so that customers can get early access and provide feedback.
  • Microsoft Power Platform CLI version that is included with this extension may also be a public preview version. We recommend you to install the latest version using the steps mentioned above.

Common commands

This table lists some of the common commands used in the CLI:

Command Description
admin Commands for environment lifecycle features.
auth Commands to authenticate to Dataverse.
canvas Commands for working with canvas app source files.
org Commands for working with Dataverse environment.
package Commands for working with Solution Packages.
paportal Commands for working with Power Apps portals (Preview).
pcf Commands to work with Power Apps component framework.
plugin Command to create a plug-in project.
solution Commands for working with Microsoft Dataverse solution projects.
telemetry Manages the telemetry settings.

Admin

Commands to work with environment lifecycle features. It has the following parameters:

Parameters

Property Name Description
list Lists all environments from the tenant. It has the following parameters
- environment-id: List all environments that contain a given string in their ID (alias: -id).
- url: List all environments that contain a given string in their url (alias -u).
- type: Lists all environments of the given type (alias: -t).
- name: List all environments that contain a given string in their name (alias: -n).
- organization-id: List all environments that contain a given string in their organization ID (alias: -oi).
create Creates a new environment. It has the following parameters:
- name: Sets the name of the environment (alias: -n).
- region: Sets the environment's region name. Defaults to unitedstates if not specified (alias -r).
- type: Sets the type of the environment. Available values are Trial, Sandbox, Production, SubscriptionBasedTrial (alias: -t).
- currency: Sets the default currency used in the environment. Defaults to USD if not specific (alias: -c).
- language: Sets the default language of the environment. Defaults to english if not specified (alias: -l).
- templates: Sets the Dynamics 365 apps that should be deployed to the environment. Pass as comma-separated values (alias: -t).
- domain: Sets the domain name that is part of the environment URL. If domain name is already in use, a numeric value will be appended to the domain name. For example, if contoso is already in use, then the environment URL will become https://contoso0.crm.dynamics.com (alias -d).
- input-file: Arguments can be passed in a .json input file instead of through the command line. For example, {"name" : "contoso"}. The arguments passed through command-line will take precedence over arguments from the .json input file (alias: -if).
backup Takes the backup of an environment. It has the following parameters:
- url: Url of the environment to be backed up. (alias: -u).
- label: Sets the backup label as provided (alias: -l).
- environment-id: ID of the environment to be backed up (alias: -id).
- notes: Additional notes provided for the backup (alias: -n).
delete Deletes an environment. It has the following parameters:
- url: Url of the environment to be deleted (alias: -u).
- environment-id: ID of the environment to be deleted (alias: -id).
reset Resets an environment. It has the following parameters:
- url: Url of the environment to reset (alias: -u)
- name: Sets the name of the environment (alias: -n).
- currency: Sets the default currency used in the environment. Defaults to USD if not specific (alias: -c)
- purpose: Sets the description used to associate the environment with a specific intent (alias: -p)
- language: Sets the default language of the environment. Defaults to english if not specified (alias: -l).
- templates: Sets the Dynamics 365 apps that should be deployed to the environment. Pass as comma-separated values (alias: -t).
- domain: Sets the domain name that is part of the environment URL. If domain name is already in use, a numeric value will be appended to the domain name. For example, if contoso is already use, then the environment URL will become https://contoso0.crm.dynamics.com (alias -d).
- input-file: Arguments can be passed in a .json input file instead of through the command line. For example, {"name" : "contoso"}. The arguments passed through command-line will take precedence over arguments from the .json input file (alias: -if).
list-backups Lists all available backups. environment. It has the following parameters:
- url: Url of the environment for which you want to list backups (alias: -u).
- environment-id: ID of the environment for which you want to list backups (alias: -id).
restore Restores an environment from a given backup. It has the following parameters:
- source-url: Url of the source environment to be restored from (alias: -s).
- target-url: Url of the target environment to be restored to (alias: -t).
- selected-backup: DateTime of the backup in mm/dd/yyyy hh:mm format or latest (alias: -sb).
- name: Optional name of the restored environment (alias: -n).
copy Copies a source environment to a destination environment. It has the following parameters:
- source-url: Url of the source environment to be copied from (alias: -su).
- target-url: Url of the target environment to be copied to (alias: -tu).
- source-environment-id: ID of the source environment to be copied from (alias: -si).
- target-environment-id: Id of the target environment to be copied to (alias: -ti).
- name: Name to be used for the target environment. (alias: -n).
- type: Type of copy. Available values are: None, MinimalCopy, Fullcopy (alias: -t).

Canvas

Commands for working with canvas app source files. Edit, manage, and collaborate on your app outside of Power Apps Studio with tools such as VS Code and GitHub.

Note

The Canvas commands are in public preview. They may not be available in the version of Microsoft Power Platform CLI that you are using currently.

Parameters

Property Name Description Example
unpack Unpacks the .msapp source file.
Download the .msapp file from Power Apps Studio by navigating to File > Save as > This computer.
If the sources parameter is not specified, a directory with the same name and location as the .msapp file is used with _src suffix.
pac canvas unpack --msapp HelloWorld.msapp --sources MyHelloWorldFiles
pac canavs unpack --msapp HelloWorld.msapp
unpacks to default HelloWorld_src directory
pack Creates an .msapp file from the previously unpacked source files.
The result can be opened in Power Apps Studio by navigating to File > Open > Browse.
The source files can be edited and managed with external tools after being unpacked, such as Visual Studio Code and GitHub.
pac canvas pack --sources MyHelloWorldFiles --msapp HelloWorld.msapp

Folder structure

Unpack and pack use the following folder structure:

  • \src - Control and component files. This contains the sources.
    • *.fx.yaml - The formulas extracted from the control.json file. This is the place to edit your formulas.
    • CanvasManifest.json - A manifest file that contains the information normally present in the header, properties, and publishInfo.
    • *.json - The raw control.json file.
    • \EditorState*.editorstate.json - Cached information for studio to use.
  • \DataSources - All the data sources used by the app.
  • \Connections - Connection instances saved with the app and used when reloading into the studio.
  • \Assets - Media files embedded in the app.
  • \pkgs - A downloaded copy of external references, such as templates, API definition files, and component libraries. These are similar to NuGet/NPM references.
  • \other - All miscellaneous files needed to recreate the .msapp.
    • entropy.json - Volatile elements (like timestamps) are extracted to this file. This helps reduce noisy differences in other files while ensuring that we can still round trip.
    • Holds other files from the msapp, such as what is in \references.

File format

The .fx.yaml files uses a subset of YAML. Similar to Excel, all the expressions should begin with an = sign. More information: Power Fx YAML Formula Grammar.

Merging changes with Power Apps Studio

When merging changes, that are made in two different studio sessions:

  • Ensure that all the control names are unique. For example, inserting a button in two different sessions can result in two Button1 controls. We recommend to name the controls soon after you create them. The tool doesn't accept two controls with the same name.
  • For these files, merge them as you normally do:
    • \src*.fx.yaml
  • If there are conflicts or errors, you can delete these files:
    • \src\editorstate*.json - These files contain optional information in studio.
    • \other\entropy.json
  • For any conflict in these files, it’s ok to accept the latest version:
    • \checksum.json
  • If there are any merge conflicts under these paths, it is not safe to merge. Let us know if this happens often and we will work on restructuring the file format to avoid conflicts.
    • \Connections*
    • \DataSources*
    • \pkgs*
    • CanvasManifest.json

Open source

The canvas commands in Microsoft Power Platform CLI are open source. Discuss improvements, raise issues, and access the code from Power Apps language tooling repository.

Package

Command to work with solution packages. It has the following parameters:

Parameters

Property Name Description Example
init Initializes a new package project. It has the following parameter:
- outputdirectory: Output directly where the package is created.
pac package init --outputdirectory c:\samplepackage
add-reference Sets the reference path to the solution project folder by passing the path parameter. pac package add-reference --path c:\Users\Downloads\SampleSolution
show Shows the content of a package dll or a zip file with a package.
It has the following parameter:
- package: The path location to the package dll (library) or the zip file.
pac package show c:\samplepackage.dll
deploy Deployes the package dll or the zip file with a package.
It has the following parameters:
- logFile: Path to a log file location where the logs are redirected.
- logConsole: This option is used if you want to direct the logs to the console.
- package: The path location to the package dll (library) or a zip file with a package.
Note: You can use both logFile and logConsole parameters together or use one parameter or the other.
pac package deploy --logFile c:\samplelogdata --package c:\samplepackage

Paportal

Commands to work with Power Apps portals (Preview). It has the following parameters:

Parameters

Property Name Description Example
list Lists all portal websites from the current Dataverse environment. pac paportal list
download Download portal website content from the current Dataverse environment. It has the following parameters:
- path: Path where the website content will be downloaded (alias: -p).
- webSiteId: Portal website ID to download (alias: -id).
- overwrite: (Optional) true - to overwrite existing content, false - to fail if the folder already has website content (alias: -o).
pac paportal download --path "C:\portals" --webSiteId f88b70cc-580b-4f1a-87c3-41debefeb902
upload Upload portal website content to the current Dataverse environment. It has the following parameter:
- path: Path where the website content is stored (alias: -p)
pac paportal upload --path "C:\portals\starter-portal"

PCF

Commands to work with Power Apps component framework. It has the following parameters:

Parameters

Property Name Description Example
init Initializes the code component project. It has the following parameters:
- namespace: Namespace of the code component.
- name: Name of the code component.
- template: Field or dataset
pac pcf init --namespace SampleNameSpace --name SampleComponent --template field
push Pushes the code component to the Dataverse instance with all the latest changes. It has the following parameter:
- publisher-prefix: Publisher prefix of the organization.
pac pcf push --publisher-prefix dev
version Updates the component manifest file with the specified patch version. It has the following parameters:
- patchversion: Patch version of the code component. patchversion will only take value of the third part of the version tuple: Major.Minor.Patch.
- path: Absolute or relative path of the component manifest file.
- allmanifests: Updates the patch version for all the component manifest files.
- updatetarget: Updates the specified manifest file. It has two values, build and project.
- strategy: Updates patch version for the manifest files using specified strategy values. It has the following values:
- gittags: Use git tags to decide if a particular component’s patch version needs to be updated.
filetracking: Use .csv file to decide if a particular component’s patch version needs to be updated.
- manifest: Increments the patch version by 1 for all the components.
pac pcf version --patchversion 1.0.0.0 --path c:\Users\Downloads\SampleComponent --allmanifests

pac pcf version --strategy gittags

Solution

Commands for working with Dataverse solution projects. It has the following parameters:

Parameters

Property Name Description Example
init Initializes the solution project. It has the following parameters:
- publisher-name: Publisher name of the organization.
- publisher-prefix: Publisher prefix of the organization.
pac solution init --publisher-name developer --publisher-prefix dev
add-reference Sets the reference path to the component project folder by passing the path parameter. pac solution add-reference --path c:\Users\Downloads\SampleComponent
clone Creates a solution project based up on the existing solution project. It has the following parameters:
-name: The name of the solution to be exported.
-targetversion: The version that the exported solution supports.
-include: Settings that should be included in the solution being exported.
It has the following values: autonumbering, calendar, customization, emailtracking, externalapplications, general, isvconfig, marketing, outlooksynchronization, relationshiproles, sales
pac solution clone -–name sampleSolution --version 1.0.0.2 --include general
import Imports a Dataverse solution to an environment. It requires that you are connected to an environment Auth commands and has the following parameters:
-activate-plugins: Activates plug-ins and workflows in the environment after the import (alias: -ap).
-async: Imports the solution asynchronously (alias: -a).
-force-overwrite: Forces an overwrite of unmanaged customizations (alias: -f).
-import-as-holding: Imports the solution as a holding solution (alias: -h).
-max-async-wait-time: Maximum asynchronous wait time in minutes. Default value is 60 mintues (alias: -wt).
-path: Path to solution zip file. If not specified, assumes the current folder (alias: -p).
-publish-changes: Publishes changes after successful import (alias: -pc).
-skip-dependency-check: Skips dependency check against dependencies flagged as product update (alias: -s).
pac solution import --path c:\Users\Documents\Solution.zip
export Exports a Dataverse solution from an environment. It requires that you are connected to an environment Auth commands and has the following parameters:
-path: Complete file name where the exported solution zip file will be saved.
- name: Name of the solution that needs to be exported.
- managed: Defines whether the solution should be exported as a managed solution or not.
-targetversion: The version that the exported solution supports.
-include: Settings that should be included in the solution being exported.
pac solution export --path c:\Users\Documents\Solution.zip -- name SampleComponentSolution --managed true --targetversion 10.0.03 --include general
list List all Solutions from a Dataverse environment. It requires that you are connected to an environment Auth commands. This command has no parameters: pac solution list

Auth

Commands to authenticate to Dataverse. It has the following parameters:

Parameters

Parameter Name Description Example
create Creates the authentication profile for your organization by passing the url parameter. Pass the organization url for the url parameter. pac auth create --url https://Myorg.crm.dynamics.com
list Provides the list of authentication profiles. pac auth list
select Provides a way to switch between previously created authentication profiles by passing the index parameter. pac auth select --index 2
delete Deletes the authentication profile created by passing the index parameter. pac auth delete --index 2
clear Clears all the authentication profile created on the local machine. pac auth clear

Telemetry

Manages the telemetry settings. It has the following parameters:

Parameters

Parameter Name Description Example
enable Enables the telemetry option. pac telemetry enable
disable Disables the telemetry option. pac telemetry disable
status Returns whether the telemetry is enabled or disabled. pac telemetry status

Org

Command to work with Dataverse organizations.

Parameters

Parameter Name Description Example
who Displays information about the current Dataverse organizations. pac org who

Plugin

Manages to create a plug-in project.

Parameters

Parameter Name Description Example
init Initializes a directory with a new plugin class library. pac plugin init

Uninstall Microsoft Power Platform CLI

To uninstall Microsoft Power Platform CLI tooling, run the MSI from here.

If you are a Private Preview participant and have an older version of CLI, follow these steps:

  1. To find out where Microsoft Power Platform CLI is installed, open a command prompt and type where pac.

  2. Delete the PowerAppsCLI folder.

  3. Open the Environment Variables tool by running the command rundll32 sysdm.cpl,EditEnvironmentVariables in the command prompt.

  4. Double-click Path under the User variable for... section.

  5. Select the row containing the PowerAppsCLI path and select the Delete button on the right-hand side.

  6. Select OK twice.

See also

Power Apps component framework