We’ve just published a new version of the Office 365 CLI with new commands for working with and managing Office 365 tenants and SharePoint Framework projects on any platform.
Manage Office 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 Office 365 and SharePoint Framework projects no matter which operating system or shell you use.
While building solutions for Office 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.11
Following our monthly release cadence, we’ve released a new version of the Office 365 CLI with some new capabilities.
SharePoint Framework project upgrade improvements
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 version of the Office 365 CLI, we’ve included a number of bug fixes and improvements.
Suggesting all optional packages
SharePoint Framework consists of a number of packages. Some of them contain the core functionality and are must be referenced in every solution. Others are optional, and you use them only if you build web parts or extensions. In this version of Office 365 CLI, we’ve extended suggesting upgrading packages with all optional packages that are a part of the SharePoint Framework, which means that your upgrade reports will be even more helpful.
More accurate upgrades of on-prem projects
Using SharePoint Framework you can build solutions for both SharePoint Online as well as SharePoint Server 2019 and 2016. In this version, we’ve improved the accuracy of detecting projects built for SharePoint Server.
Simplified removing SharePoint sites
SharePoint exists almost 20 years now. In all these years, it evolved from a portal product you’d install on your server to a cloud platform supporting collaboration and communication. Most recent investments in SharePoint include modern sites and pages that offer organizations rich and user-friendly content management experiences. From the technology point of view, there are some differences between modern and classic sites. And so, in all tools, including Office 365 CLI, you will find a separate set of tools to manage classic and modern sites and pages.
In the Office 365 CLI team, we believe that it’s a complexity that you shouldn’t be bothered with. Instead, it’s something that should be handled by the tooling as much as possible, allowing you to focus on the job at hand. In this version of Office 365 CLI, we’ve set the first step in consolidating commands for managing sites. No matter if you want to remove a modern or a classic site, you can do it using the spo site remove command, instead of using two different commands.
In the future versions of Office 365 CLI, you can expect further consolidation of commands that will make it even easier to use the CLI.
Creating Microsoft Teams teams using templates
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. Typically, teams are meant to serve a specific purpose like facilitate team collaboration or communication. To ensure consistency, it means creating Teams with specific settings and apps.
Microsoft Teams support creating teams using a template. In this version of Office 365 CLI, we’ve extended the existing ability to create teams with using templates.
To create a team using a template, execute:
teams team add --name 'Architecture' --description 'Architecture Discussion' --templatePath 'template.json'
For more information about managing Microsoft Teams using Office 365 CLI see the documentation at https://aka.ms/o365cli.
Removing all site columns from the given group
When managing documents in SharePoint, organizations often organize their metadata using content types and columns. As the organization evolves and their processes change, so does their need to store metadata. To keep the information architecture relevant, you might need to remove obsolete columns.
In this version of Office 365 CLI, we’ve introduced the ability to remove all columns from the specific group. To do that, execute:
spo field remove --webUrl https://contoso.sharepoint.com/sites/contoso-sales --group 'MyGroup'
For more information about managing fields using Office 365 CLI, see the documentation at https://aka.ms/o365cli.
microsoft365 and m365 executables
To align with Microsoft’s marketing we’ll be renaming Office 365 CLI to Microsoft 365 CLI. This change will become effective in v3 of Office 365 CLI that we plan to release in the fall of this calendar year.
To help you prepare for this change, in this version we’ve introduced the microsoft365 and m365 executables that you can use to run Office 365 CLI. You can start using Office 365 CLI with its new name already today and when you upgrade to v3 later this year, you shouldn’t be affected.
New script samples
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.
Remove the Wiki tab in a Microsoft Teams channel
Many organizations choose to use OneNote notebook instead of the Wiki when collaborating in Microsoft Teams to store unstructured data.
Rabia Williams contributed a sample script that allows you to remove the Wiki tab from a Microsoft Teams channel.
Insert pictures in a SharePoint Document Library into a Word document
Customers have multiple pictures in a SharePoint Document Library, and they need to automatically insert the pictures in Word as it will take a lot of time if operating from UI. So, they need a script to accomplish that.
Joseph Velliah contributed a sample script that automates inserting pictures from a document library into a Word document.
Contributors
This release wouldn’t be possible without the help of (in alphabetical order) Aakash Bhardwaj, Velin Georgiev, Patrick Lamber, Waldek Mastykarz, Albert-Jan Schot, 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.
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
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.
