October 4th, 2020

CLI for Microsoft 365 v3.1

We’ve just published a new version of the CLI for Microsoft 365 with new commands for working with and managing Microsoft 365 tenants and SharePoint Framework projects on any platform.

Manage Microsoft 365 and SharePoint Framework projects on any platform

CLI for Microsoft 365 is a cross-platform CLI that allows you to manage various configuration settings of Microsoft 365 and SharePoint Framework projects no matter which operating system or shell you use.

While building solutions for Microsoft 365 expands beyond the Windows operating system, managing many of the platform settings is possible only through PowerShell on Windows. As more and more users work on non-Windows machines, it’s inconvenient for them to have to use a Windows virtual machine to configure their tenants. With the CLI for Microsoft 365, you can configure your tenant no matter which operating system you use. Additionally, using CLI for Microsoft 365, you can manage your SharePoint Framework projects.

New version of CLI for Microsoft 365 – v3.1

Following our monthly release cadence, we’ve released a new version of the CLI for Microsoft 365 with some new capabilities. Here are a few of the most noteworthy additions.

Monitor Microsoft 365 tenant

To successfully use Microsoft 365 in your organization, you need to stay on top of what’s coming and what impact it could have on your users. Information about upcoming changes is displayed in the Microsoft 365 admin center.

To help you automate tracking and responding to the different messages, we’ve introduced in this version a number of commands.

First, Aakash Bhardwaj contributed a command that allows you to retrieve the list of different services that you have enabled in your Microsoft 365 tenant. This is useful for filtering service messages in the admin center.

To get the list of services available in your Microsoft 365 tenant, execute:

m365 tenant service list

Next, Nanddeep Nachan introduced a command to retrieve service messages from the Microsoft 365 Message Center. This is very powerful, because it allows you to watch for specific messages. Embedded for example in an Azure Function it allows you to automatically triage and take action on specific types of messages which can save you a lot of time monitoring your tenant!

To get the list of messages from Microsoft 365 Message Center, execute:

m365 tenant service message list

Finally, Arjun Menon contributed a command to retrieve the historical status of the different services in Microsoft 365. In cases there were any availability incidents in your tenant, this command can help you to build a report for your organization.

To get the historical service status for your tenant, execute:

m365 tenant service report historicalservicestatus

For more information about monitoring the status of your Microsoft 365 tenant using CLI for Microsoft 365, see the documentation at aka.ms/cli-m365.

Manage Outlook e-mails

While many organizations use Microsoft Teams to facilitate collaboration and communication, e-mail remains a highly used communication channel. If you use e-mail a lot, you can now use CLI for Microsoft to manage your messages.

In this release of CLI for Microsoft, Waldek Mastykarz contributed two commands to retrieve and move e-mails.

To retrieve messages from a specified folder, like Inbox, execute:

m365 outlook message list --folderName inbox

If you want to bulk-move messages from one folder to another, which isn’t possible in Outlook on the web for large number of messages, execute:

m365 outlook message move --messageId AAMkAGVmMDEzMTM4LTZmYWUtNDdkNC1hMDZiLTU1OGY5OTZhYmY4OABGAAAAAAAiQ8W967B7TKBjgx9rVEURBwAiIsqMbYjsT5e-T7KzowPTAAAAAAEMAAAiIsqMbYjsT5e-T7KzowPTAALdyzhHAAA= --sourceFolderName inbox --targetFolderName archive

For more information about managing e-mails using CLI for Microsoft 365, see the documentation at aka.ms/cli-m365.

Retrieve Power Apps

Power Platform empowers organizations on the Microsoft cloud to build powerful solutions to automate their business processes. To help you manage Power Apps created by your users, Garry Trinder contributed a command to retrieve all Power Apps from the given environment.

To retrieve Power Apps, execute:

m365 pa app list

For more information about managing Power Apps using CLI for Microsoft 365, see the documentation at aka.ms/cli-m365.

Remove SharePoint Knowledge Hub Site

Preparing for the rollout of Knowledge Hub Sites, Arjun Menon contributed a command that lets you remove the knowledge hub site in your tenant.

To remove a knowledge hub site for your tenant, execute:

m365 spo knowledgehub remove

As the functionality is released, you can expect more commands related to managing knowledge sites in CLI for Microsoft 365.

New script samples

CLI for Microsoft 365 is a great tool both for quick adjustments to the configuration of your Microsoft 365 tenant as well as automating more complex tasks. Because CLI for Microsoft 365 is cross-platform you can use it on any OS and in any shell. To help you get started using the CLI for Microsoft 365 for automation scenarios, we started gathering some sample scripts. Here are the latest additions to the collection.

If you have any scripts that you use frequently, please share them with us so that we can learn more about the common automation scenarios.

Remove orphaned redirect sites

Changing the URL of a site results in a new site type: a Redirect Site. However this redirect site does not get removed if you delete the newly renamed site. This could result in orphaned redirect site collections that redirect to nothing.

Albert-Jan Schot contributed a sample script that removes orphaned redirect sites.

Contributors

This release wouldn’t be possible without the help of (in alphabetical order) Aakash Bhardwaj, Pramod Ghuge, Bassem Khalil, Waldek Mastykarz, Arjun U Menon, Nanddeep Nachan, Roman Rozinov, Albert-Jan Schot, Garry Trinder and Rabia Williams. Thank you all for the time you chose to spend on the CLI for Microsoft 365 and your help to advance it!

Work in progress

Here are some things that we’re currently working on.

Removing Vorpal

When we started building CLI for Microsoft 365, we used Vorpal to get the basic CLI functionality such as git-style commands, aliases, parsing arguments, help, etc. Unfortunately, over time Vorpal got less and less active support and the repository became stale.

To avoid using outdated dependencies, we decided to remove Vorpal and build the necessary functionality ourselves. Aside from decreasing security risks, this allows us greater functionality as we now control how commands are executed and how they return output.

As a user of CLI for Microsoft 365 you shouldn’t see any negative effect of this change. What’s more, in the future versions of CLI for Microsoft 365 you can expect enhancements that will make working with the CLI more intuitive and convenient.

We’ll release the changes in the coming days and will use all of October 2020 to verify that everything is working as expected.

More commands, what else

Microsoft 365 is evolving and new capabilities are being released every day. With CLI for Microsoft 365, we aim to help you manage your tenant on any platform in a consistent way, no matter which part of Microsoft 365 you interact with. While we keep adding new commands to CLI for Microsoft 365 each release, we still barely scratched the surface with what’s possible in Microsoft 365. In the upcoming versions of the CLI for Microsoft, you can expect us to add more commands across the different workloads in Microsoft 365.

Script examples

In every release of the CLI for Microsoft 365, we introduce new commands for managing Microsoft 365. With 360 commands across the different Microsoft 365 services, the CLI for Microsoft 365 has become a powerful tool, not just for managing your tenant but also for automating your daily work.

We’d love to show you how you can use the CLI for Microsoft 365 to build automation scripts in PowerShell Core and Bash. If you have any scripts using SPO or PnP PowerShell that you use frequently, please share them with us so that we can learn more about the common automation scenarios.

ensure commands

Currently, CLI for Microsoft 365 has dedicated commands for retrieving, creating and updating resources. If you were to create a script that ensures a specific configuration, for each resource you’d need to see if it exists, create it if it doesn’t or update it if it does.

We’re thinking about simplifying this scenario by introducing commands with a new verb named ensure. For example, to ensure that a particular site collection exists, instead of executing a combination of spo site list/spo site get, spo site add and spo site set, you’d execute spo site ensure with the necessary parameters which would automatically verify if the particular site exists and matches your configuration. If the site doesn’t exist, it would create it. If it does, the command would check if the properties you specified match the retrieved site and update them if necessary.

We’ll start to implement this idea on the spo site commands. We’d love to hear from you if it’s something that you’d find helpful and what other objects we should take into account.

Setting arbitrary properties on SharePoint objects

At this moment, the most of SharePoint set commands in the CLI for Microsoft 365 support only a handful of options that correspond to the properties of their SharePoint class, like Web, Site, List, etc. This is similar to how the Set-PnP* cmdlets work. However, because PnP PowerShell works with CSOM, this limitation there is often circumvented, by retrieving the CSOM object, updating its properties and calling $object.ExecuteQuery() to persist the changes outside of PnP cmdlets. Because the CLI doesn’t use CSOM, this isn’t possible and users are limited to using whatever options are exposed by the CLI commands.

We’re thinking about addressing this limitation by allowing you to set the value of any property exposed on the SharePoint object. This would work only for properties that have values of simple types like bool, string or int because complex values likely can’t be serialized to string without additional logic.

We would offer rudimentary logic of checking if the specified properties are valid, by examining the latest version of the SPO CSOM assemblies and checking which properties on the particular SharePoint class have setters and values of the supported types and thus can be used.

What do you think of this approach? Would this help to solve a problem you have? In the previous release, we have extended the spo web set command with this functionality. We’d love you to try it and tell us what you think.

Try it today

Get the latest release of the CLI for Microsoft 365 from npm by executing in the command line:

npm i -g @pnp/cli-microsoft365

If you need more help getting started or want more details about the commands, the architecture or the project, go to aka.ms/o365cli. If you see any room for improvement, please, don’t hesitate to reach out to us either on GitHub or twitter.

Author

We coordinate the Microsoft 365 Patterns and Practices (PnP) open-source and community activities.