We have just published a new major version of CLI for Microsoft 365 v3. Here is what has changed.
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 major version
As we kept extending CLI for Microsoft 365 with new functionality during the last year, we noticed a few areas that we could improve to simplify using the CLI. As such, this new major version is evolutionary. Following is the overview of the most noteworthy changes introduced in CLI for Microsoft 365 v3. For the full list of changes, see the release notes.
To help you upgrade to v3, we prepared a summary of breaking changes and the recommended actions. For more information see the v3 Upgrade Guidance in our docs.
New name: Office 365 CLI becomes CLI for Microsoft 365
Earlier this year, Microsoft renamed Office 365 to Microsoft 365 to better address the complete suite of their productivity technology. To stay consistent with the new name, we renamed Office 365 CLI to CLI for Microsoft 365. We hope that the new name clearly illustrates our ambition to offer you one CLI to manage all of your Microsoft 365 tenant and its services.
To start the CLI, in the past you’d execute in the command line office365 or o365 for short. In the latest version 2 we’ve already introduced the new executable names microsoft365 or m365. Starting from v3, the office365 and o365 executables are no longer available and you can execute CLI for Microsoft 365 commands only using microsoft365 or m365.
Starting from version 3, CLI for Microsoft 365 is available on npm at @pnp/cli-microsoft365. Version 2 of the CLI available at @pnp/office365-cli will remain available on npm, but will be deprecated. We won’t be updating it anymore and recommend that you upgrade to version 3 to benefit of the latest additions and improvements.
We also renamed our GitHub repo which is now available at https://github.com/pnp/cli-microsoft365. Our docs are published at https://pnp.github.io/cli-microsoft365 or https://aka.ms/cli-m365 for short.
Removed immersive mode
In the past you could use CLI for Microsoft 365 in two ways. You could either execute a specific command, like o365 spo site list or you could start the CLI in immersive mode by running o365 and get a CLI-specific command prompt.
In the past year we found out that the immersive mode isn’t used as much as we initially had thought it would be. While it gives instant access to command completion, it prevents you from using other shell commands. What’s more, immersive mode depends on Vorpal which the community stopped maintaining.
Thinking about the future, we decided to remove immersive mode and start preparing for removing Vorpal. This will allow us to keep all our dependencies up-to-date.
Removed obsolete aliases and options
Despite our best efforts to review specs for all commands that we implement in CLI for Microsoft, over the course we picked up some inconsistencies. While we adjusted them as quickly as possible to offer you a consistent experience across all commands, we haven’t removed the original names to avoid breaking changes.
In this major version, we removed these previously deprecated aliases and options to keep our code base clean and maintainable for the coming releases.
New commands
Aside from changes, we’ve also introduced a few new commands for managing Microsoft 365.
Manage Microsoft To Do lists
In August Microsoft released a preview version of new APIs for Microsoft To Do. Following this release, Yannick Plenevaux contributed commands to list, remove and update to do lists.
To retrieve all Microsoft To Do lists, execute:
m365 todo list list
To rename a list, execute:
m365 todo list set --id "AAMkAGI3NDhlZmQzLWQxYjAtNGJjNy04NmYwLWQ0M2IzZTNlMDUwNAAuAAAAAACQ1l2jfH6VSZraktP8Z7auAQCbV93BagWITZhL3J6BMqhjAAD9pHIhAAA=" --newName "My updated task list"
Finally, to remove a specific list, execute:
m365 todo list remove --name "My task list"
For more information about working with Microsoft To Do using CLI for Microsoft 365, see the docs at aka.ms/cli-m365.
Uninstall personal Teams app
In the past few months, there’s been a huge increase in Microsoft Teams usage. After the pandemic forced our hand, Teams became the primary tool to facilitate collaboration in many organization, who often had to speed up their rollout plans and let their employees work from home.
While deploying Teams, many organizations want to go beyond the standard setup and offer their employees a set of additional applications they can use to work more effectively. But managing these applications at scale can quickly become cumbersome. To help organizations remove unnecessary apps, Aakash Bhardwaj contributed a command to uninstall personal apps.
To uninstall a personal Teams app, execute:
m365 teams user app remove --appId YzUyN2E0NzAtYTg4Mi00ODFjLTk4MWMtZWU2ZWZhYmE4NWM3IyM0ZDFlYTA0Ny1mMTk2LTQ1MGQtYjJlOS0wZDI4NTViYTA1YTY= --userId 2609af39-7775-4f94-a3dc-0dd67657e900
For more information about managing Microsoft Teams using CLI for Microsoft 365, see the docs at aka.ms/cli-m365.
List groups from specific web
One of the most complex areas of governing Microsoft 365 is permission management. Across Microsoft 365, different services have a different way of managing their permissions and which all require separate configuration. One of such services is SharePoint, where each site, list or a file can be secured separately.
To help you keep track of permissions in your sites, Dipen Shah contributed a command that lets you list groups from the specific web.
To get groups from a specific web, execute:
m365 spo group list --webUrl "https://contoso.sharepoint.com/sites/contoso"
Set Knowledge Hub Site
Preparing for the rollout of Knowledge Hub Sites, Arjun Menon contributed a command that lets you set the knowledge hub site for your tenant.
To set a knowledge hub site for your tenant, execute:
m365 spo knowledgehub set --url https://contoso.sharepoint.com/sites/knowledgesite
As the functionality is released, you can expect more commands related to managing knowledge sites in CLI for Microsoft 365.
Contributors
This release wouldn’t be also possible without the help of (in alphabetical order) Aakash Bhardwaj, Velin Georgiev, Arjun Menon, Waldek Mastykarz, Nanddeep Nachan, Yannick Plenevaux, Roman Rozinov, Albert-Jan Schot, Dipen Shah, Garry Trinder, Joseph Velliah and Rabia Williams as well as all other contributors we had to date. There wouldn’t be a v3 without the v2 and v1, which you helped to build. Thank you all so much for the time you chose to spend on CLI for Microsoft 365!
What’s next
With the big refactoring behind us, we’re going to focus on adding more commands and improving the existing ones. Like always, we’re listening for feedback and ideas for improvements. We can’t promise we’ll implement everything, but we will definitely engage in the discussion to better understand your suggestions.
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 CLI for Microsoft 365, we introduce new commands for managing Microsoft 365. With almost 400 commands across the different Microsoft 365 services, 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 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 to 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 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 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/cli-m365. If you see any room for improvement, please, don’t hesitate to reach out to us either on GitHub, or on twitter with the #CLIMicrosoft365 hashtag.
