Office 365 CLI v2.10
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.10
Following our monthly release cadence, we’ve released a new version of the Office 365 CLI with some new capabilities.
New SPFx CodeTour project upgrade report
Upgrading SharePoint Framework projects from one version to another goes way beyond bumping package version numbers. For some versions, you need to update the contents of some files, for others, you need to remove files or add new ones. Keeping track of all the necessary changes is tedious and not something you should be bothered with. So exactly for this reason, in the Office 365 CLI, we offer a command to help you upgrade your SharePoint Framework projects.
In this release of the Office 365 CLI, we’re excited to offer you a new report based on the Visual Studio Code CodeTour extension summarizing the changes necessary to upgrade your project. The CodeTour report helps you to understand where in the project exactly you should apply the changes. Additionally, with just a single click, you execute the necessary commands!
To use the CodeTour report for upgrading your SharePoint Framework project, be sure you have the CodeTour Visual Studio Code extension installed and then execute:
o365 spfx project upgrade -o tour
The next time you open your project in Visual Studio Code, the CodeTour extension will start the tour walking you through the different steps to upgrade your project.
The CodeTour report offers a richer upgrade experience that we hope you will like. Big thanks to Hugo Bernier for contributing this new report type and don’t hesitate to let us know if you have any feedback or ideas for improvement.
Improved SPFx project upgrade
Next to introducing the new CodeTour SPFx project upgrade report, we have improved the project upgrade logic. While originally we’d suggest upgrading only the required dependencies, in this version we’ve extended the upgrade report to include some of the optional dependencies as well. In the future versions of the CLI, we’ll extend this list covering all
@microsoft dependencies that are a part of the SharePoint Framework. We’ve also improved the accuracy of our findings which should streamline the upgrade process.
Improved externalizing SPFx project dependencies
When building SharePoint Framework solutions, developers can use many of the 1 million packages published on npm to speed up their development process. By default, however, these packages get included in the generated solution bundle, unnecessarily increasing its size. While you can configure them to be stored externally, it’s not always trivial to use the right way of doing it. To simplify the process of separating packages from the solution bundle, Office 365 CLI offers a command that analyzes your solution and shows you code necessary to include in your project.
For this version of Office 365 CLI, Vincent Biret improved the logic to detect the type of package so that the CLI can offer you more accurate suggestions for the necessary code snippets.
To get suggestions on how to separate the dependencies from your SPFx project, execute:
o365 spfx project externalize
Added support for logging in using managed identity
Office 365 CLI is a versatile tool for managing your Microsoft 365 tenant. Whether you execute a single command on your desktop or build automation scripts integrated into builds or scheduled tasks. Before you can start communicating with your tenant, you need to log in to it. And often that’s a challenge. Where do you store securely the necessary credentials?
To simplify using Office 365 CLI in automation scenarios, in this version we introduce support for logging in to Microsoft 365 using managed identity. If you use the CLI on a VM or Azure Function that has managed identity set up or in Azure Cloud Shell, you can use the existing identity and don’t need any separate credentials to communicate with Microsoft 365!
All you need to do is to log in using managed identity, by executing:
o365 login --authType identity
For more information about using managed identity with Office 365 CLI, see the documentation. Big thanks to Velin Georgiev for contributing this new authentication method and Paul Schaeflein for assisting with the research.
Add Azure AD app role assignments
When building solutions on Microsoft 365, chances are that you will deploy some pieces of it to Azure. For these components to be able to communicate with Microsoft 365, they need to be granted access to the specific services.
To help you automate configuring these permissions, Velin Georgiev contributed a command to add app role assignments to service principals.
For example, to allow the specified service principal to read information about SharePoint sites, execute:
o365 aad approleassignment add --appId "57907bf8-73fa-43a6-89a5-1f603e29e451" --resource "SharePoint" --scope "Sites.Read.All"
For more information about managing Azure AD apps using the Office 365 CLI, see the documentation.
Add a Microsoft To Do list
Recently, during Build, Microsoft announced the preview of new Microsoft Graph APIs for managing To Dos. These APIs extend the task management capabilities of Graph that in the past allowed you to create Planner and Outlook tasks.
For this version of Office 365 CLI, Yannick Plenevaux contributed a command to add a To Do list. To add a To Do list using the CLI, execute:
o365 todo list add --name "My task list"
While the new To Do APIs already work, they haven’t been officially released. When the API becomes officially available, you can expect us to extend the support for To Do in Office 365 CLI.
Install personal Teams apps
Microsoft Teams gained a lot of popularity lately. Many organizations have started using Teams in their daily work and are now looking into extending them to their needs to get even more out of them. A part of that is the ability to allow users to use the different applications directly from the context of Teams.
To help you automate the process of configuring Microsoft Teams, Aakash Bhardwaj contributed a command to add personal Teams apps.
To add a personal Teams app, execute:
o365 teams user app add --appId 4440558e-8c73-4597-abc7-3644a64c4bce --userId 2609af39-7775-4f94-a3dc-0dd67657e900
For more information about managing Microsoft Teams using the Office 365 CLI, see the documentation.
Manage Yammer users and messages
Organizations on Microsoft 365 have plenty of choices when it comes to how to facilitate their collaboration. They can choose the good old e-mail, but also can use services like Microsoft Teams or Yammer. Each of these services shines in one or more specific scenarios and there is no right or wrong when it comes to using them in the workplace.
In this release of the Office 365 CLI, we continued to extend support for Yammer. Patrick Lambert contributed commands to manage Yammer groups’ users and (un)liking messages.
To add the current user to a Yammer group, execute:
o365 yammer group user add --id 5611239081
To remove the current user from a Yammer group, execute:
o365 yammer group user remove --id 5611239081
To like the specific Yammer message, execute:
o365 yammer message like set --id 5611239081
Since Yammer is not available in all tenants, we made its permissions optional in the Azure AD app used by the Office 365 CLI. Before you can start using Yammer commands in the Office 365 CLI, you need to consent the Azure AD app access to Yammer by executing:
consent --service yammer
For more information about managing Yammer using the Office 365 CLI, see the documentation.
New user guide Using your own Azure AD identity
Office 365 CLI contains nearly 400 commands allowing you to manage different services in Microsoft 365. Many of these commands require admin-level permissions and chances are, that you might not need to use all of them in your organization. By default, Office 365 CLI uses its own Azure AD application with all necessary permissions assigned to it. But if you want to have more control over the admin-level access in your tenant you can use your own Azure AD application instead.
To simplify the processing of setting up and using your own Azure AD application with Office 365 CLI, Garry Trinder contributed a detailed walkthrough taking you step-by-step through the whole configuration process. We hope you find it helpful and please don’t hesitate to reach out to us if we can clarify or improve anything.
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.
Bulk add/remove users to Microsoft Teams and Microsoft 365 Groups
When merging or migrating tenants, Microsoft 365 groups or Teams you might need to change memberships of these groups.
To simplify this process, Joseph Velliah contributed a sample script that allows you to add/remove users to Microsoft Teams and Microsoft 365 groups in bulk.
Disable the specified tenant-wide extension
Tenant Wide Extensions list from the App Catalog helps to manage the activation/deactivation of the tenant wide extensions.
Shantha Kumar T contributed a sample script helps to disable the specified tenant-wide extension.
Add custom client-side web part to modern page
You’ve built an amazing new web part and now you want to programmatically add it to a modern page.
Yannick Plenevaux contributed a sample script that helps you add your web part to the page with your custom properties that might be dynamic according to your script.
This release wouldn’t be possible without the help of (in alphabetical order) Hugo Bernier, Aakash Bhardwaj, Vincent Biret, Velin Georgiev, Shantha Kumar, Patrick Lamber, Waldek Mastykarz, Aleksandar Nikolić, Yannick Plenevaux, Paul Schaeflein, Albert-Jan Schot, Pete Skelly, Garry Trinder and Joseph Velliah. 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.
CLI v3: preparing for the next major version
Each month we release a new version of Office 365 CLI with new features and improvements. We strive to follow semantic versioning to help you understand which versions are backward-compatible and which aren’t. Last year, we released a new major version to improve some things that couldn’t have been done in a backward-compatible way. Right now, we’re starting planning another major release that will help us clean up Office 365 CLI from obsolete features and prepare it for at least the next year.
The most noteworthy changes are renaming Office 365 CLI to Microsoft 365 CLI to align with Microsoft’s marketing and removing the immersive mode which could allow us to modernize CLIs engine in the near future.
We’ll start the work on v3 of Office 365 CLI shortly and will keep you updated as we introduce new changes for you to try. Stay tuned!
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 360 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.
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 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 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.