Office 365 CLI v2.9
We’ve just published a new version of the Office 365 CLI 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
Office 365 CLI 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 Office 365 CLI, you can configure your tenant no matter which operating system you use. Additionally, using Office 365 CLI, you can manage your SharePoint Framework projects.
New version of Office 365 CLI – v2.9
Following our monthly release cadence, we’ve released a new version of the Office 365 CLI with some new capabilities and improvements.
Improved upgrading SharePoint Framework projects
With each release, SharePoint Framework introduces new capabilities. Whenever possible, you should strive to update to the latest version of the SharePoint Framework to benefit from these improvements and new features. But upgrading your project isn’t always straight-forward and involves more than just upgrading the SPFx packages. Office 365 CLI simplifies the upgrade process by scanning your project and providing you with a thorough report listing all the necessary steps to fully upgrade your project.
In this version of the Office 365 CLI, we have done a number of improvements to upgrading SharePoint Framework projects especially around support for publishing web parts to Teams. For the complete set of improvements see the release notes. We’ll continue improving the upgrade experience in the coming releases of Office 365 CLI.
Remove Teams tabs
More and more organizations use Teams to facilitate collaboration. Teams is more than just a communication tool. Thanks to its integration capabilities, you can expose other applications in Teams providing your employees with a single location to support their work.
To ensure consistency or drive change in your Teams, you might need to change the tabs available in the different channels. To help you with that, Rabia Williams contributed a command that allows you to remove a Teams tab from the specific channel. To remove a tab execute:
teams tab remove --teamId 00000000-0000-0000-0000-000000000000 --channelId 19:firstname.lastname@example.org --tabId 06805b9e-77e3-4b93-ac81-525eb87513b8
For more information about managing Microsoft Teams using the Office 365 CLI, see the documentation at aka.ms/o365-cli.
Check the health status of the different services in Microsoft 365
Organizations choose Microsoft 365 for its reliability and ability to scale to support the rapid demand changes. Over the past few weeks, Microsoft 365 has been put to a test with the usage across the different services increased significantly. Microsoft 365 proved to be reliable and continues to deliver on its promise of a platform that can support organizations in digital collaboration.
In a rare event of degraded service performance, it’s good to know of it as soon as possible and communicate it timely in your organization. Setting up automation for monitoring and alerting is crucial to keep your operations going. For this release of the Office 365 CLI, Anoop Tatti contributed a command that allows you to check the state of the different services in Microsoft 365.
To check the status of the different services in Microsoft 365, execute:
tenant status list
For more information about managing your Microsoft 365 tenant using the Office 365 CLI, see the documentation at aka.ms/o365-cli.
Validate SharePoint themes before applying them
Intranets play a crucial role in digital collaboration. They support organizations in storing information according to their business processes and governance plans and communicating with their employees. A part of the success of each intranet is how it’s perceived in the organization. Custom themes help to express the organization’s identity on the intranet and make the intranet feel ‘ours’.
Modern SharePoint sites support changing the look and feel through themes. These themes are defined as JSON files that can be uploaded to your tenant by admins. And while you’re unlikely to write a whole theme manually, it’s easy to make a typo or miss a required property and get stuck in why the particular theme isn’t working.
To help you verify that your theme will work, Garry Trinder extended the existing
spo theme set command with validating the theme before applying it. If you miss a required property, specified invalid color code, or miss a comma, the CLI will warn you about rather than giving you a cryptic error code.
For more information about working with SharePoint themes using the Office 365 CLI, see the documentation at aka.ms/o365-cli.
Report Yammer and Microsoft 365 Groups usage
Many organizations that use Microsoft 365 need to track and report on how their employees use the different services provided by Microsoft. The Microsoft 365 Admin Center, as well as the admin centers dedicated to managing the different services, offer several reports that illustrate the usage from different perspectives.
In case you need to automate reporting in scripts, Patrick Lamber continued his great work introducing commands for reporting the usage of Yammer and Microsoft 365 Groups. For more information about which reports are available, see the documentation.
Register organizational asset library
Organizations using Microsoft 365 can store their branding and communication assets in an organizational asset library – a centralized location accessible to others in the organization. In each tenant, you can designate one or more libraries as organization asset libraries so that you can have for example one for the whole organization and then specific libraries, perhaps with different permissions, for the different departments.
In this version, Albert-Jan Schot contributed a command to designate the specific document library as an organization assets library.
To register the specific document library as an organization assets library, execute:
spo orgassetslibrary add --libraryUrl "https://contoso.sharepoint.com/assets"
For more information about managing organization assets libraries using the Office 365 CLI, see the documentation at aka.ms/o365cli.
New script samples
Office 365 CLI is a great tool both for quick adjustments to the configuration of your Microsoft 365 tenant as well as automating more complex tasks. Because Office 365 CLI is cross-platform you can use it on any OS and in any shell. To help you get started using the Office 365 CLI 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.
Scan Microsoft 365 Groups created with User’s First or Last Name
We can use the group naming policy to enforce a consistent naming strategy for groups created by users in our organization. A naming policy can help us and our users identify the function of the group. We can use the policy to block specific words from being used in group names and aliases. But what if we need to find out the list of Microsoft 365 groups created with the user’s given name or surname as their mail?
Joseph Velliah contributed a sample script that detects Microsoft 365 Groups created with the user’s first or last name.
Ensure site assets library is created
There are occasions when creating a new modern SharePoint site using the CLI/REST API that the Site Assets library isn’t created, use this script to ensure that the Site Assets library is created.
Phillip Allan-Harding contributed a sample script that ensures that the site assets library is created.
List all tenant-wide extensions
Using SharePoint Framework you can build extensions that can be deployed to all sites.
Shantha Kumar T contributed a sample script that lists all globally deployed extensions.
This release wouldn’t be possible without the help of (in alphabetical order) Aakash Bhardwaj, Velin Georgiev, Joakim Hagström, Phil Harding, Shantha Kumar, Patrick Lamber, Waldek Mastykarz, Albert-Jan Schot, Anoop Tatti, Garry Trinder, Joseph Velliah and Rabia Williams. Thank you all for the time you chose to spend on the Office 365 CLI 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 the Office 365 CLI, 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 the Office 365 CLI each release, we still barely scratched the surface with what’s possible in Microsoft 365. In the upcoming versions of the Office 365 CLI, you can expect us to add more commands across the different workloads in Microsoft 365.
To make it easier for you to see how the CLI commands compare to the different PowerShell cmdlets, we’ve extended the comparison sheet with cmdlets for Flow, PowerApps, and Teams.
In every release of the Office 365 CLI, we introduce new commands for managing Microsoft 365. With 375 commands across the different Microsoft 365 services, the Office 365 CLI 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 Office 365 CLI 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.
Consolidate site commands
To improve usability and offer a new set of features, SharePoint introduced the concept of modern sites. While in theory, they’re still site collections, they’re created and managed in a slightly different way. Additionally, if you choose to create a modern team site, your site will be linked to a Microsoft 365 Group.
Because of the differences between modern and classic sites, we’d offer two sets of commands to manage them:
spo site and
spo site classic. While there are indeed some differences, there are also similarities and in the end, we believe that having separate commands is irrelevant to our users. So to simplify things, we decided to consolidate the functionality of
spo site classic commands into their
spo site equivalents. When the consolidation is done, we’ll deprecate
spo site classic commands and remove them in v3 of the Office 365 CLI.
Our goal is to keep all functionality intact. If you have any concerns about this decision, please don’t hesitate to let us know.
One of the scenarios for using the CLI is to get information about a specific object in Microsoft 365: a site, team, flow, etc. Typically, before you can get to that information, you need to execute the corresponding
list command to retrieve all available objects, copy the ID of the object that you’re interested in, and paste it to the corresponding
We’ve been thinking about simplifying this workflow by extending the
get commands. If you don’t specify the identity of an object that you will retrieve, the CLI will present you with a list of all available objects (or objects that match your filter). After selecting the specific object, the CLI will then retrieve it for you and show its properties without you having to run the
list command separately and copy & paste the object’s identifier between commands.
Would this be helpful for you? Let us know!
Currently, Office 365 CLI 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.
Setting arbitrary properties on SharePoint objects
At this moment, the most of SharePoint
set commands in the Office 365 CLI support only a handful of options that correspond to the properties of their SharePoint class, like
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
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 Office 365 CLI from npm by executing in the command line:
npm i -g @pnp/office365-cli
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.