Office 365 CLI v2.12
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.12
With the announcement of SharePoint Framework v1.11, we released a new version of Office 365 CLI to help you upgrade your SharePoint Framework projects to use the latest version of SPFx.
Upgrade SharePoint Framework projects to SPFx v1.11
Microsoft has just released SharePoint Framework v1.11. Using this version of Office 365 CLI, you can upgrade your existing projects to this latest version of SPFx and benefit of its latest additions and fixes.
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.
To upgrade your SharePoint Framework project to the latest version of SPFx, in the command line, change the working directory to your SharePoint Framework project and execute:
m365 spfx project upgrade --output md > report.md
This will produce a Markdown report with all steps necessary to upgrade your project. Alternatively, if you prefer a more interactive experience, you can use the VSCode CodeTour report, by executing:
m365 spfx project upgrade --output tour
For more information about upgrading SharePoint Framework projects using Office 365 CLI, see the documentation.
Rename SharePoint Framework projects
If you have a base project structure that use to create new SharePoint Framework projects in your team or would like to start a new project from an existing one, you can easily copy then. Before continuing with development, you have to rename it though, to avoid collisions with the original.
To help you rename your SharePoint Framework project, Aakash Bhardwaj contributed a command to rename SharePoint Framework projects.
To rename your project, in the command line, change the working directory to your SharePoint Framework project and execute:
m365 spfx project rename --newName my-new-project --generateNewId
Get Microsoft Graph schema extensions
Using the Microsoft Graph, developers can store additional information about objects like users or messages. Developers can define the shape of these additional pieces of information through schema extensions. For this release of the Office 365 CLI, Rabia Williams contributed a command to retrieve existing schema extensions.
To retrieve existing schema extensions in your tenant, execute:
m365 graph schemaextension list
For more information about working with schema extensions using the Office 365 CLI, see the documentation at aka.ms/o365cli.
Create SharePoint app catalog
When you create a new Microsoft 365 tenant, by default, it doesn’t have the SharePoint app catalog. Since the app catalog is the prerequisite for extending SharePoint and Microsoft Teams to your needs, it’s quite likely that you will need to create it as a part of the base setup of your tenant.
If you can have an existing setup script, you can now extend it with creating a SharePoint tenant app catalog, using the command contributed by Waldek Mastykarz.
To create a SharePoint tenant app catalog, execute:
m365 spo tenant appcatalog add --url https://contoso.sharepoint.com/sites/apps --owner admin@contoso.com --timeZone 4
For more information about automating creating tenant app catalog, see the documentation.
Manage site users
As a part of ongoing operations of your SharePoint sites, you might need to get information about their users. To help you with that, Dipen Shah and Siddharth Vaghasia contributed commands to get information about and remove site users.
To get information about the particular site user, execute:
m365 spo user get --webUrl https://contoso.sharepoint.com/sites/project-x --email john.doe@mytenant.onmicrosoft.com
To remove the particular user from the site, execute:
m365 spo user remove --webUrl "https://contoso.sharepoint.com/sites/HR" --loginName "i:0#.f|membership|john.doe@mytenant.onmicrosoft.com"
For more information about managing site users with the Office 365 CLI see the documentation.
Get site groups
Next to managing site users, when maintaining sites, you might need to get information about groups used in the particular site. To help with you that, Nanddeep Nachan contributed a command to get information about a site group.
To get information about a site group, execute:
m365 spo group get --webUrl https://contoso.sharepoint.com/sites/project-x --name "Team Site Members"
For more information about managing site users with the Office 365 CLI see the documentation.
New sample scripts
Office 365 CLI is a great tool both for quick adjustments to the configuration of your Office 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.
Sync SharePoint Document Library Documents with Azure Storage Container
When managing your SharePoint data, you might want to synchronize some of it with an Azure Storage account.
Joseph Velliah contributed a sample script that allows you to sync the contents of a document library with an Azure Store account.
Contributors
This release wouldn’t be possible without the help of (in alphabetical order) Aakash Bhardwaj, Velin Georgiev, Waldek Mastykarz, Nanddeep Nachan, Dipen Shah, Siddharth Vaghasia, 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.
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 CLI for Microsoft 365 to align with Microsoft’s marketing and removing the immersive mode which could allow us to modernize CLIs engine in the near future.
Recently, we have released a first preview version of Office 365 CLI v3, which you can install by executing:
npm i -g @pnp/office365-cli@three
We encourage you to give it a try and test your scripts to ensure that they will work when we release v3 later this year.
More commands, what else
Office 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 Office 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 Office 365. In the upcoming versions of the Office 365 CLI, you can expect us to add more commands across the different workloads in Office 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.
Script examples
In every release of the Office 365 CLI, we introduce new commands for managing Office 365. With 360 commands across the different Office 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.
ensure commands
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.
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 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 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.
Light
Dark