CLI for Microsoft 365 v3.2

Microsoft 365 PnP Team

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.2

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.

Changes

In this release, we have made changes to the internal code of CLI.

Removal of 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.

Replacing request with axios

When we started building CLI for Microsoft 365, we used the request npm package to help simplify the HTTP calls made to Microsoft 365 APIs.

Unfortunately, request was placed in maintenance mode and has since been deprecated, since 11th February 2020 no changes have been made to the library.

To avoid using outdated dependencies, we decided to remove request and replace it with axios.

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.

New Commands

Retrieve SharePoint Knowledge Hub site

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

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

m365 spo knowledgehub get

Retrieve Microsoft Teams Tab

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 organizations, who often had to speed up their rollout plans and let their employees work from home.

One of the main ways to share information in a Microsoft Teams Channel is to display that information in a Microsoft Teams Tab.

Nanddeep Nachan contributed a command to return information about a specific Microsoft Teams Tab.

To retrieve a Microsoft Teams Tab, execute:

m365 teams tab list --teamName "Team Name" --channelName "Channel Name" --tabName "Tab Name"

List installed personal Microsoft Teams apps

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 discover apps that are being used by employees, Sébastien Levert contributed a command to list personal apps installed for a specific employee.

To retrieve Microsoft Teams personal apps installed by an employee, execute:

m365 teams user app list --userName admin@contoso.com

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

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.

Deploy a Microsoft Teams personal app and add it to users

As many organizations start to leverage the extensibility of Microsoft Teams, they will want to install Microsoft Teams apps for their users, however this is not easily done through the Microsoft Teams admin center.

Sébastien Levert contributed a sample script that deploys a Microsoft Teams app and installs it for specified users.

Uninstall Microsoft Teams personal app from users and remove from Microsoft Teams app catalog

As many organizations start to leverage the extensibility of Microsoft Teams, they will want to remove Microsoft Teams apps installed by there users and remove that app from the app catalog preventing users from reinstalling, however this is not easily done through the Microsoft Teams admin center.

Sébastien Levert contributed a sample script that uninstalls a Microsoft Teams app from users and removes it from the Microsoft Teams app catalog.

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.

Contributors

This release wouldn’t be possible without the help of (in alphabetical order) Aakash Bhardwaj, Sébastien Levert, Waldek Mastykarz, Arjun U Menon, Nanddeep Nachan, Smita Nachan, Mark Powney, Albert-Jan Schot and Garry Trinder. 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.

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.

Friendlier commands

Whilst there are now over 350 commands available to use in CLI for Microsoft 365 to help you manage your Microsoft 365 tenant, a lot of commands expect you to provide object ids to perform actions.

We understand that this is not as intuitive as being able to provide a the name of an object and the command work out what the required object ids for you based on the object name given.

We are actively creating new issues to address this, updating our commands to be more user friendly and provide a better user experience.

We’ll start to implement new name options on our Microsoft Teams commands and will start to appear in the next release.

Quicker and easier developer onboarding

CLI for Microsoft 365 is a community project and it relies upon contributions from developers around the world to help add new commands and enhance existing commands in every release.

As part of our ongoing improvements to the project, we want to make the onboarding process of new developers to the project as quick and easy as possible.

We will be looking to release a remote development container, that will provide a one click approach for developers to configure a development environment with all dependencies and tools required to contribute to the project.

The release will also support use of GitHub Codespaces, enabling developers to spin up dedicated development environments in the cloud and contribute to the project using nothing but a web browser.

Run CLI for Microsoft 365 in a Docker container

The CLI for Microsoft 365 has been designed from the beginning to be platform agnostic, continuing on this theme we will be looking to publish a Docker image to the Docker Hub registry.

This will enable administrators and developer to run an isolated Linux container with the CLI for Microsoft 365 pre-installed and ready to use.

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/cli-m365. If you see any room for improvement, please, don’t hesitate to reach out to us either on GitHub or twitter.

Feedback usabilla icon