What is the CLI for Microsoft 365  

The CLI for Microsoft 365 is a Command-line interface. A computer program that processes commands as lines of text. CLI programs are often used in the Unix world but are commonly used in cross-platform scenarios as well. The CLI for Microsoft 365 is a cross-platform solution that allows users on any platform to manage various configuration settings of Microsoft 365. Whilst 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 is inconvenient for them to have to use a Windows virtual machine to configure their tenants. The CLI for Microsoft 365 allows them to configure their tenants no matter which operating system they use.    

Why do you need the CLI for Microsoft 365? 

I believe this is part of what makes my role as community lead special. I am part of the Microsoft Teams Quality and Customer Obsession Team within Teams Engineering, led by Alex Olsen. Our team is responsible for connecting our communities with our engineering team to gather feedback and investigate issues. We meet regularly with the feature teams responsible for prioritizing and building these features or experiences to ensure community feedback is a big part of the development process.

A few years back I was setting up a new machine and started playing around with the Windows Subsystem for Linux (WSL) for my SharePoint Framework (SPFx) development. I quickly learned that the CLI for Microsoft 365 would allow me to run from that same WSL instance and from that point on I was hooked. Having to write your scripts only once and being able to run them on any device. And more important; being able to run them in containers or release pipelines as well!  

The CLI for Microsoft allows you to manage various settings on your tenant and provides a set of commands to speed up your SPFx development process. Working with the CLI is straightforward, it uses a prefix: m365 and supports both commands like m365 status  and command groups m365 spo site that list different commands together. The CLI thus provides a cross platform set of scripts you can use in different scenarios, all with a single login experience.   

Getting started  

The CLI for Microsoft 365 is distributed as an NPM package. Make sure your environment is prepared by installing the LTS version of Node. To use the CLI, install it globally using: npm i -g @pnp/cli-microsoft365. Once installed you can login to the tenant you want to manage using m365 login. To get an overview of all commands you can use m365 help.  

Reporting scenarios  

Now that you are connected to your environment you can start executing commands. You can use the m365 spo site list to list all modern site collections in your tenant. You can also link different commands together and write complex reports. One could for instance easily list all App Catalogs using PowerShell core,  

$appCatalogs = m365 spo search –query “contentclass:STS_List_336” –selectProperties SPSiteURL –allResults –output json | ConvertFrom-Json 

$appCatalogs | ForEach-Object { Write-Host $_.SPSiteURL } 

Write-Host ‘Total count:’ $appCatalogs.Count 

Or achieve the same with Bash. Within bash you need the jq tool to work with JSON data.  

#!/bin/bash 

# requires jq: https://stedolan.github.io/jq/ 

appCatalogs=$(m365 spo search –query “contentclass:STS_List_336” –selectProperties SPSiteURL –allResults –output json) 

echo $appCatalogs | jq -r ‘.[].SPSiteURL’ 

echo “Total count:” $(echo $appCatalogs | jq length) 

Retrieving data in the CLI is just one command away, but you could work with complex scenarios. You can use the –query parameter to pass in a so called JMESPath query. This expression allows you to query against the returned JSON and filter down the dataset. In the sample above while the m365 spo search returns everything the filter makes sure to only retrieve results of type STS_List_336.  

Developer scenarios  

You can also use the CLI for Microsoft 365 to upgrade your SPFx packages. The m365 spfx project upgrade allows you to get a report on how to upgrade a SPFx package to a newer version. Simply run m365 spfx project upgrade –output md > report.md and get yourself an overview of all steps to upgrade your project,  

Or use the m365 spfx project upgrade –output tour to get an interactive experience using the Code Tour plugin:  

For me this is one of my most used features, every project where SPFx packages are built, it takes me quite some time whenever I get back to them a year later. I always need to update them to the latest bits if we are adding new functionality. Having a report makes that way easier; I do not need to remember all the steps. Just run the report and check the steps and actions.  

Azure Cloud Shell  

Besides running the CLI for Microsoft 365 on your machine, you can install it into the Azure Cloud Shell as well. Unfortunately, the Shell itself currently has a bug, so running the CLI native in the Shell is not possible. However, you can install it yourself. The outline is described on our issue page (https://github.com/pnp/cli-microsoft365/issues/2017) but the gist is to simply install nvm using curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.37.2/install.sh | bash. Then run the nvm install to install the latest Node version using nvm install —lts and then run npm i -g @pnp/cli-microsoft365. Once those steps are done your Azure Cloud Shell image will keep the installed CLI version working for you, and you can run commands directly in the browser.

Containers 

You can also use Docker to run a standalone Linux container with CLI for Microsoft 365 and PowerShell pre-installed, with command completion (tab) automatically configured for you in both bash and PowerShell, without having to install any of the required dependencies on your host machine. Simply run docker run –rm -it m365pnp/cli-microsoft365:latest to get started. And since docker containers can run in Azure Container Instances as well you are not only limited to run them locally. Just setup Azure Container Instances, load in the image and execute the commands you want.  

Conclusion 

The CLI for Microsoft 365 is a great way to manage your tenant from any platform. You can easily reuse your scripts whether you are on a Mac, Linux, or Windows. There is a range of useful commands and samples that you can find on https://aka.ms/cli-m365 and if you want to get involved, we have an active GitHub project with over 30 issues that are a great way to start your journey into opensource software.