Challenge 015 | Power Platform CLI

Last month, we went through the second episode of the Power Platform Testing Trilogy. We do need to wait for some additional pieces to be finalized by Microsoft in order to f, I thought it would be nice to take some time for some extra preparations.

For the closing piece of the Power Platform Testing Trilogy, we will depend on the Power Platform CLI. In earlier challenges this CLI has been mentioned and used a bit, but it might sound daunting for many low-code fans. That's why I thought it would be nice to have a dedicated challenge on this CLI so that everyone can understands it's power and can start using it.

Challenge Objectives

🎯 Get familiar with the Power Platform CLI

🎯 Understand how to use it in a functional way

🎯 Be extra prepared for the Power Platform Testing Trilogy climax

🤓 What is the Power Platform CLI?

If you are a regular visitor, you have adjusted some Power Platform settings before. Remember when you the link aka.ms/ppac? It directs you to the Power Platform admin portal where you can perform actions like creating environments, add an application user to an environment, and all sorts of other operations. This admin portal is an example of a graphical user-interface (GUI). A GUI is a visual way of interacting with a computer using items such as windows, icons and menus. It allows you to perform tasks by clicking on graphical icons and buttons. This is easy for an end-user to understand, but can cumbersome if you want to do some bulk operations or operations that happen very frequently.

Another option to interact with a computer is the command line interface (CLI). A CLI uses text input to perform operations. These pieces of text are called commands, hence the name command line interface. The disadvantage of a CLI is that it is expecting your command in a specific format in order to operate. This is the reason why a GUI is probably your preferred way of adjusting settings of a system like the Power Platform. However, there are some advantages to a CLI. The first is that you don't have to navigate through the GUI to trigger the operations, which can save you some time. The other, and in my opinion biggest, advantage is that this can be run from anywhere. This could be the terminal on your local machine, but also on virtual machines. This this latter option enables all sorts of automation scenarios.

The Power Platform CLI is a set of commands specifically for the Power Platform. To use these commands, the Power Platform CLI must be installed.

Getting Started

As mentioned, the Power Platform CLI must be installed in order to use it. There are two options available to get it installed. I highly recommend using the Power Platform Tools for Visual Studio Code option. You might already have it installed. If not, the Microsoft documentation in the last link explains how to get it. The Power Platform Tools adds some nice functionality that we will use in this challenge.

After you have installed it, you are ready to start using the CLI. Before we will give it a spin, I would like you to read through the list of command groups to get an understanding of the available options the Power Platform CLI has to offer. Note that there is a structure in the CLI. All commands start unambiguously with pac (top level), drills down into the command group (e.g. pac admin), and lastly the specific command within the group (e.g. pac admin create).

# All commands have follow the same structure:
# top_level command_group command

pac admin create
pac auth list
pac tool list

Also make sure you have Visual Studio Code installed, and know how to start a terminal in Visual Studio Code (Ctrl+Shift+`) before proceeding.

pac help

The first command I want to point out is the pac help command. This is a command that will return some helpful information for you. This can be helpful if you are within the terminal. This can limit the times you need to consult the Microsoft documentation for the Power Platform CLI.

You can use it at any level of of the CLI, so at the top level, command group level, or the command itself. On the top level it will return the available command groups, on the command group level it will return the available commands of the given command group, and on the command level it will return the possible command parameters with. All with a description.

# The top level help command
pac help

# The command group level help command
pac admin help

# The command level help command
pac admin create help

pac auth

As you know, Power Platform is a cloud service. Just like you need to be authenticated when you are using the GUI to perform certain actions, the CLI requires authentication as well. Where the GUI shows a nice dialog when you go to aka.ms/ppac, the CLI uses text command, as you've learned earlier. the command group for this is pac auth. The documentation shows the available individual commands for this. We obviously need to create an authorization profile.

This is the where the Power Platform Tools version of installing the CLI shows it's first advantage. You could simply type the following.

pac auth create

Select the profile and corresponding tenant on the dialog (see image below) to get an auth profile on you machine, and start using this auth profile for any following command. The downside of this way of using pac auth is that it is stored temporarily. When you close the terminal, or shut down and come back a day later, you need to recreate your auth profile. Not ideal.

If you open the Power Platform Tools extension, which I have already opened in the image above, you can see the Add Auth Profile button in AUTH PROFILES section. If you press it, you get a similar sign in pane. The benefit is that this profile is stored, and can be reused. You can also rename your profile, which comes in handy when you have multiple profiles. This can happen when you are managing multiple tenants.

The documentation describes you can add a URL when you are creating an auth profile. I recommend not using that, as that only gives access to that particular environment. The Power Platform Tools way of creating it doesn't use that function either, which is nice.

There is also a section called ENVIRONMENTS & SOLUTIONS. Here you will find all environments the active profile has access to, and the solutions in those environments. Let's see how we can start using this.

pac org

Many admin related tasks are executed on a specific environment. In the GUI, you would navigate to the environments and select an environment before execution. You now probably know you would need to do exactly the same in the CLI.

pac org list

the command pac org list will list all the available environments for the active auth profile. The result should be similar to what is shown in the ENVIRONMENTS & SOLUTIONS section.

pac org select

Once all the environments are listed (just like you would do using the GUI), its time to select an environment. pac org select is the command for this. As you can read in the documentation, this command requires a parameter in which you tell which environment to select. you can use the full parameter name, of the alias. You can identify the environment with the environment URL or the environment ID. The snippet below shows these options. Any option will do.

# Full parameter name with the environment ID as identifier
pac org select --environment 00000000-0000-0000-0000-000000000000

# Parameter alias with the environment ID as identifier
pac org select -env 00000000-0000-0000-0000-000000000000

# Full parameter name with the environment URL as identifier
pac org select --environment "https://yourorg.crm4.dynamics.com"

# Parameter alias with the environment URL as identifier
pac org select -env "https://yourorg.crm4.dynamics.com"

Note that the environment ID and URL are outputs of the pac org list command. You can run that command first, copy the ID or URL, and then run the pac org select command. However, we are using the Power Platform Tools extension for Visual Studio Code. If you right-click an environment in the ENVIRONMENTS & SOLUTIONS section, you can directly copy the environment ID or URL without having to run the pac org list command. This save you quite some time when you are switching between environments.

pac org who

This is the last command in this group. It allows you to check which environment currently is selected. You can run it at any time. As obvious as it might be, the default environment is the environment which is selected by default when you create a new auth profile.

pac admin

The pac admin group has a bit more functionality. I want to start with the pac admin create command. As y0u might have seen on the image above, I currently have two environments in my tenants (after some cleanup for this challenge). Personal Productivity, which is the renamed default environment, and Miguel Verweij's Environment, which is a developer environment. Earlier, we only had the option to add one developer environment. Microsoft changed it to a maximum of three developer environments, so that we all can start testing ALM pipelines. A very welcome feature, but I am still missing two developer environments for that. If you don't have three developer environments yet, I highly recommend you add them using the Power Platform CLI. Remember that you can run the help commands.

# List the available commands in the pac admin command group
pac admin help

# Get an overview of the available command parameters
pac admin create help

If you run the second command from the snippet above, you will get an output like the image below.

There are a few things I want to point out. The type parameter shows the different type of environments that we can create. Luckily for us, Developer is an option. You can also see we can easily create Dataverse for Teams environments when we enter Teams in the type parameter. Note that we should then also specify a team-id, which is a different parameter.

For now, we just want to add two Developer environments, so lets do so by running the command. For me, the command looks like this.

pac admin create -n "Miguel Verweij dev" -r europe -t Developer -c EUR

It will create an environment with a Dataverse database, so it can take a few seconds to complete. After completion, my terminal looks like the image below.

We have only created one environment, so we need to create another one. If you press the up arrow, you can browse through earlier executed commands. This is very helpful, as most settings will be identical. Only the name parameter needs to be different. Change it, and run it again.

pac admin create -n "Miguel Verweij test" -r europe -t Developer -c EUR

You should get a similar confirmation response. The two new developer environments are now ready to use. If you press the refresh button at the ENVIRONMENTS & SOLUTIONS section, you will see the newly created environments listed. If you need even more confirmation this works as it should, you can open the GUI and see them listed there too.

There are some more functional commands in the admin command group, but I will not go into them for now, as I think will now know how to use these.

pac application

If you are a regular visitor, you might know I am a big fan of the Creator Kit, which was the topic of the first challenge of the Power Platform summer camp 2022. For those who don't know, it is a package of components that you can add to a canvas app. These components significantly improve the development joy, make it look great easily and cut the development time even further. However, each canvas app depends on this Creator Kit solution. Practically, this means that when you are setting up a pipeline for a canvas app that uses these components, every environment of that pipeline should have the Creator Kit installed.

The one developer I already had at the beginning of this challenge already had the Creator Kit installed. The two new developer environments don't. So, we need to install it to these environments. That is what we will do in this section.

Earlier, the Creator Kit was only hosted on GitHub. The installation process required you to fork or download it from there, and then deploy the solution to the target environment. But the PowerCAT team has been so friendly to add it to AppSource. This is like an App Store for Business Applications. This makes deployment a bit easier, and the good thing is, it is supported by the CLI.

pac application help

You see there are only two options, list and install. Run the list command to see which applications are available.

pac application list

A list of all the possible applications is returned. Scroll through the list to find the Creator Kit and copy the Unique Name of the application.

Now it's time to install the application to the new environments. Run the help command for the install command.

pac application install help

The response shows four possible parameters. One is deprecated. One is the environment, which should be the ID or URL. We know how to get that for the new environments. The application-name and application-list remain. If you want to install multiple applications at once, you can use the list parameter. For now we only want to install the Creator Kit, so we will use the application-name parameter. The command will look like the snippet below.

pac application install -env 00000000-0000-0000-0000-000000000000 -an CreatorKitCore

Just like we did with the pac admin create command, press arrow up, adjust the environment ID to the second environment, and run the command again.

You now have created two developer environments, and installed the Creator Kit for these environments. Pretty cool stuff. These are the main commands that we will address in this challenge. Feel free to look into other command groups. The ones I really recommend are the pac canvas command group (to pack and unpack canvas apps), and the pac solution command group (which is perfect for ALM purposes).

Do it all at once (almost)

It's quite nice that we now know how to use the Power Platform CLI for creating an environment, and install the Creator Kit to it. But it's still quite some work, as we execute all the commands one by one. We can significantly ease our life by scripting it just a little further. In order to do this, we need to remove the newly created Developer environments, as we can only have three of these. You can do that with the following command. Run it for each environment you've created in this challenge.

pac admin delete -env 00000000-0000-0000-0000-000000000000

Just like we have the Apply to Each action to iterate over a list in Power Automate, we can use the foreach function in the terminal to do just that. How this works you will learn in a minute. But first, we need to create the list we want to iterate over. This list (or array) will contain the names of the environments we want to create. We can do that by running the following command. You can obviously change the names of the environments to you name.

$envNames = "Miguel Verweij dev", "Miguel Verweij test"

$envNames will be a variable that we can use. the = sign binds everything right from it to the variable. the , indicates we are dealing with two items. After running the command, you can run $envNames to see what it contains.

$envNames

As you can see, it will show a list of two, and show the names you just bound to it. Now we need to come up with some code that will do everything for us. But where do we even start? I the following section I will explain what I did to make everything work.

foreach ($envName in $envNames) {
    pac admin create -n $envName -r europe -t Developer -c EUR
    pac application install -env $envName.ID -an CreatorKitCore
}

First I want to explain what my aim is. The snippet above starts with a foreach function, which is similar to the Apply to Each from Power Automate. $envName will be each individual environment name in the list $envNames. For every $envName I want to create an environment, and install the application. But the snippet above won't work, as we don't know the ID of the environment which is to be created. That's why I created a new environment (again) to see what the response is. As you can see from the snippet below, I bind it to a new variable, so I can inspect the data.

$newEnv = pac admin create -n "Miguel Verweij Test" -r europe -t Developer -c EUR

If we now run the $newEnv variable, you will see the same output as is shown in the terminal after creation has finished.

We only need to get the Environment ID, not this whole list and other information. After some research I found out that the response is in JSON format. This is nice, because that means we can see what the properties are of the JSON object by running the following command.

$newEnv.PSObject.Properties 

The response you get is something like the image below. As you can see in the list, the property called SyncRoot contains the information we are after. the curly brackets { } indicate we are dealing with another object (or array). Let's drill a little further to get closer to just the ID.

By running the following command, you will only get the line of text that contains the environment ID.

$newenv.SyncRoot[3]

We are not there yet. We now have the right line of text, but the whole string is just too long. The Environment ID is somewhere in the middle. Again, Power Automate allows you to make substrings, so does the terminal. After some test I found out that the following command shows just the Environment ID. Try it yourself. This is quite something if you have followed along.

$newenv.SyncRoot[3].Substring(20, 56)

We just have to adjust our aim command slightly to have something functional. The snippet below is what I think should do the trick. The change is that we bind the output the the pac admin create command to a variable. That environment is used in the pac application install command to drill down into the environment ID. Sweet!

foreach ($envName in $envNames) {
    $newEnv = pac admin create -n $envName -r europe -t Developer -c EUR
    pac application install -env $newEnv.SyncRoot[3].Substring(20, 36) -an CreatorKitCore
}

Now before we can run our final masterpiece, we need to remove the environment we used for testing. You know how this works by now.

We started this challenge by saying that a CLI can come in handy for automating certain processes. The snippet below is something you would be after in such a case. You will only need to specify the environment name in the first line. The rest is dynamically handled. Shall we give it a spin?

$envNames = "Miguel Verweij dev", "Miguel Verweij test"

foreach ($envName in $envNames) {
    $newEnv = pac admin create -n $envName -r europe -t Developer -c EUR
    pac application install -env $newEnv.SyncRoot[3].Substring(20, 36) -an CreatorKitCore
}

Did you also get an error? Well, I did After inspecting the error message I found out that PowerShell is not waiting for an earlier command to finish. I tried to make it work with some wait options, but not successfully. What does make it a bit better is to put in a sequence.

# First we set the environments we want to create
$envNames = "Miguel Verweij dev", "Miguel Verweij test"

# Then we create these environments
foreach ($envName in $envNames) {
    pac admin create -n $envName -r europe -t Developer -c EUR
}

# Then we get the IDs from the newly created environments. This is a manual task at the moment. If you have a solution for this, please share.
$envIDs = "7fb85aa0-1eb0-e3dc-9464-200591f18a45", "09778d4b-6a54-ec3a-98ca-a55fe593b549"

# At last, we install the Creator Kit to the environments
foreach ($envID in $envIDs) {
    pac application install -env $envID -an CreatorKitCore
}

That's it for this challenge. I hope you find it interesting. We made it to 90%, as I just don't know how to resolve it. Not even with the lovely new Bing to my availability. If you know it please share. I learned something new already, but finishingw this off would be perfect.

Additional Information

Microsoft is putting a lot of effort in making more commands available for the CLI, and getting us familiar with the CLI. My friend Daniël Laskewitz maintains the YouTube playlist Power Platform CLI Exposed where in each video, he and a guest show a section of the possibilities of the CLI.

Also, last month the #30DaysOfLowCode took place. Here you can find blogs and videos about the Power Platform. If you like the posts I create, I am sure you would like that page too, especially from day 9.

Key Takeaways

👉🏻 A GUI is a visual way of interacting with a computer

👉🏻 A CLI uses the command line for interaction with a computer

👉🏻 A CLI can be used to automate certain processes

👉🏻 Many operations are available in the Power Platform CLI

👉🏻 The Power Platform Tools extension for Visual Studio Code is recommended

👉🏻 The help command can give you information at any level of the CLI