Microsoft Power Platform CLI support for Power Pages

Microsoft Power Platform CLI (command line interface) is a simple, single-stop developer command-line interface that empowers developers and app makers to create code components.

Microsoft Power Platform CLI tooling is the first step toward a comprehensive application life-cycle management (ALM) story where the enterprise developers and ISVs can create, build, debug, and publish their extensions and customizations quickly and efficiently. For more information, see What is Microsoft Power Platform CLI?

With this feature, the Microsoft Power Platform CLI enables CI/CD (Continuous Integration/Continuous Deployment) of a Power Pages site configuration. You can now check in the website configuration to source control and move the website configuration to any environment using Microsoft Power Platform CLI.

Note

• This feature is generally available starting with Power Platform CLI version 1.9.8. To learn about installing the latest version, see Install Microsoft Power Platform CLI.
• Starting with the Power Platform CLI version 1.27, the pac paportal command is changed to pac powerpages. paportal continues to work, but we recommend using powerpages going forward. This article will soon be updated to use powerpages instead of paportal.

Why use Microsoft Power Platform CLI for website development?

With the Microsoft Power Platform CLI, you can now use offline-like capability for website customization by making changes to the website content. And once all customizations or changes are saved, you can upload the website configuration back to Microsoft Dataverse. When you download website content using Microsoft Power Platform CLI, the content is structured in YAML and HTML formats making it easy to customize, enabling a pro-development experience.

Here's a list of features and capabilities that portals benefits from with the support for Microsoft Power Platform CLI:

Ease of use

• Support for download/upload of website configuration data to/from the local file system

• Build on existing Microsoft Power Platform CLI tool.

Application lifecycle management (ALM)

• Track changes to website configuration within an organization

• Move configuration files across organizations or tenants

Pro-dev and enterprise support

• Helps integrate seamlessly with any source control tools, such as "git"

• Easily set up CI/CD pipelines

Install Microsoft Power Platform CLI

For step-by-step instructions, refer to Install Microsoft Power Platform CLI.

Supported tables

Portals support for Microsoft Power Platform CLI is limited to the tables listed below.

adx_ad

adx_adplacement

adx_blog

adx_blogpost

adx_botconsumer

adx_communityforum

adx_communityforumaccesspermission

adx_contentsnippet

adx_entityform

adx_entityformmetadata

adx_entitylist

adx_entitypermission

adx_forumthreadtype

adx_pagetemplate

adx_poll

adx_polloption

adx_pollplacement

adx_portallanguage

adx_publishingstate

adx_redirect

adx_shortcut

adx_sitemarker

adx_sitesetting

adx_tag

adx_urlhistory

adx_webfile

adx_webform

adx_webformmetadata

adx_webformstep

adx_weblink

adx_weblinkset

adx_webpage

adx_webpageaccesscontrolrule

adx_webrole

adx_website

adx_websiteaccess

adx_websitebinding (only download)

adx_websitelanguage

adx_webtemplate

annotation

Important

• Custom tables and portal template-specific tables (such as blog, community, or ideas portal) are not supported for customization using Microsoft Power Platform CLI.
• Image file attachments to ad (adx_ad) records are not downloaded using the Power Platform CLI. As a workaround, use the Image URL field, or by adding an HTML reference in the Copy field to a web file record containing an image file.

Install and verify Microsoft Power Platform CLI for portals

To learn about installing Microsoft Power Platform CLI, go to Install Microsoft Power Platform CLI.

After installing Microsoft Power Platform CLI, open a command-prompt and run pac to verify that the output contains "paportal" - the command for Power Apps portals.

Microsoft Power Platform CLI commands for portals

Microsoft Power Platform CLI command for portals is "paportal".

The following sections provide more details about different properties of the "paportal" command.

Parameters

Property Name	Description	Example
list	Lists all portal websites from the current Dataverse environment. Preview You can add the -v parameter to indicate if the site is using the standard or enhanced data model	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) Preview - modelVersion: 1 or 2 to indicate if the site data to be downloaded will use the the standard (1) or enhanced data model (2).	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) -deploymentProfile: Upload portal data with environment details defined through profile variables in deployment-profiles/[profile-name].deployment.yaml file Preview - modelVersion: 1 or 2 to indicate if the site data to be uploaded will use the the standard (1) or enhanced data model (2).	pac paportal upload --path "C:\portals\starter-portal" --deploymentProfile "profile-name"

Use deployment profile

The deploymentProfile switch allows you to define a set of variables for the environment in YAML format. For example, you can have different deployment profiles (such as dev, test, prod) that have different schema details defined in the profile.

If you're creating test profile, you can create file under deployment-profiles with the name "test.deployment.yml" (that is, <profileTag>.deployment.yml). And you can run command with tag (<profileTag>) to use this profile:

pac paportal upload --path "C:\portals\starter-portal" --deploymentProfile test

In this file, you can have the table (entity) name with table ID, list of attributes, and the values that you want to override while uploading the portal configuration using the deploymentProfile parameter.

Additionally, you can use the OS variable to access the operating system's environment variables.

Here's an example of this "test.deployment.yml" profile YAML file that has unique schema details:

adx_sitesetting:
    - adx_sitesettingid: 4ad86900-b5d7-43ac-1234-482529724970
      adx_value: ${OS.FacebookAppId} 
      adx_name: Authentication/OpenAuth/Facebook/AppId
    - adx_sitesettingid: 5ad86900-b5d7-43ac-8359-482529724979
      adx_value: contoso_sample
      adx_name: Authentication/OpenAuth/Facebook/Secret
adx_contentsnippet:
    - adx_contentsnippetid: b0a1bc03-0df1-4688-86e8-c67b34476510
      adx_name: PowerBI/contoso/sales
      adx_value:  https://powerbi.com/group/contoso/sales

Note

To learn about all commands used in CLI in addition to portals, go to Common commands in Microsoft Power Platform CLI.

Manifest files

When you download the website content using pac paportal download CLI command, along with downloading the site content it will also generate two manifest files;

• Environment manifest file (org-url-manifest.yml)
• Delete tracking manifest file (manifest.yml)

Environment manifest file (org-url-manifest.yml)

The environment manifest file is generated every time when the pac paportal download command is run.

After every download, the PAC CLI tool reads the existing environment manifest file and updates the entries deleted in the environment, or creates the environment manifest file if it doesn't exist.

When you run the pac paportal upload command to upload the portal website content. It reads the environment manifest file and identifies the changes made since last download and only uploads the updated content. This helps in optimizing the upload process as only updated website content get uploaded, instead of uploading the all the content on every upload command.

The environment manifest file will be readonly when it connects to the same environment (environment URL matches with file name), to avoid accidental changes.

Note

• The environment manifest file is not designed to track the changes when deploying the website to different environments.
• The environment manifest file is designed to be used by developers for deploying locally in their developer environment and should be added to git ignore list.

Delete tracking manifest file (manifest.yml)

This file is used for tracking the deleted records from the environment.

When website content is downloaded with pac paportal download command, this will add the deleted records from environment manifest file (org-url-manifest.yml) to manifest.yml file. So, when you upload the website content using the pac paportal upload command it will delete the files from the environment (even to a different environment). This file isn't deleted, and it gets used regardless which environment you're connected. This file needs to be considered when pushing changes to the source control in order to consider deleting items in the target environment.

Note

In order to delete the site content records in one environment and also delete the same content records in another environment using the PAC CLI, you will need to run the pac paportal download command before and after the deleting the website record content. The manifest.yml will track these changes and remove the corresponding records in the target environment when the pac paportal upload command is run.

Use the Visual Studio Code extension

You can also use VS Code extension Power Platform VS Code Extension to benefit built-in Liquid language from IntelliSense, code completion assistance, hinting, and interact with the Microsoft Power Platform CLI using the VS Code Integrated Terminal. More information: Use the Visual Studio Code extension (preview)

More considerations

• An error is reported if your file path exceeds the maximum path length limitation. More information: Maximum path length limitation in Windows
• For duplicate records such as a duplicate web page name, Microsoft Power Platform CLI creates two different folders—one with the name of the web page, and the other with the same name prefixed with a hash code. For example, "My-page" and "My-page-hash-code".

Next steps

Tutorial: Use Microsoft Power Platform CLI with portals

See also

• Microsoft Power Platform CLI
• Use the Visual Studio Code extension (preview)