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.8

Following our monthly release cadence, we’ve released a new version of the Office 365 CLI with some new capabilities.

SPFx doctor

SharePoint Framework is the recommended model for extending SharePoint with extra functionality. SharePoint Framework follows many of the market-standard patterns for building modern web applications.

Since its inception three years ago, Microsoft has released several versions of the SharePoint Framework with improvements and additional functionality. And while all versions are supported in SharePoint Online, each version requires a specific version of Node.js and other tools to work properly.

If you build solutions for both SharePoint Online and SharePoint Server or need to switch between projects built using a different version of the SharePoint Framework, it can be cumbersome to keep track of which version of the different tools you need to have exactly for the given version of the SharePoint Framework. To help you set up your environment correctly, in the next version of the Office 365 CLI, we’ll be introducing a new command named spfx doctor.

After running, this command will try to determine the version of the SharePoint Framework that you use: either based on the current project or on the generator that you have installed locally. After detecting the version, it will check if you have all the necessary tools installed and if their versions match the requirements of the particular SharePoint Framework version.

If you miss one of the required tools or its version doesn’t meet the requirements, spfx doctor will provide you with recommendations for fixing these issues so that you can start building your solution.

We hope that you will find the spfx doctor command helpful and let us know if you have ideas for how we could improve it.

Remove SharePoint site design tasks

Site designs are the new way organizations can build custom site templates in Office 365. Using site designs, they can align with the preferred look and feel and structure as defined in the organizational information architecture.

Site designs are applied through scheduled tasks and if you want to cancel applying a site design, you can do it by removing the particular site design task. For this version of the CLI, Rabia Williams contributed a command to remove a scheduled site design task.

To remove a site design task, execute:

spo sitedesign task remove --taskId 6ec3ca5b-d04b-4381-b169-61378556d76e

For more information about working with site designs using the Office 365 CLI, see the documentation at aka.ms/o365-cli.

Report tenant, Skype and Yammer usage

Many organizations that use Office 365 need to track and report on how their employees use the different services provided by Microsoft. The Office 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 activity in the tenant and the usage of Skype and Yammer. For more information about which reports are available, see the documentation.

Add Microsoft Graph subscriptions

Microsoft Graph subscriptions offer a convenient way to stay on top of changes to the different resources in the Microsoft cloud like Azure Active Directory, Exchange or OneDrive.

For this version of the Office 365 CLI, Yannick Plenevaux contributed the command to create Microsoft Graph subscriptions. To create a new subscription for the specified type of notifications, execute:

graph subscription add --resource "me/mailFolders('Inbox')/messages" --changeType "updated" --notificationUrl "https://webhook.azurewebsites.net/api/send/myNotifyClient"

For more information about working with Microsoft Graph subscriptions using the Office 365 CLI, see the documentation at aka.ms/o365-cli.

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.

Add site collection app catalog

When you just want to deploy a certain SharePoint solution to a specific site, it’s required to create an app catalog for that site.

David Ramalho contributed a sample script that creates a site collection app catalog.

Delete custom SharePoint site scripts

Site designs and especially site scripts can be something that ends up just hanging around in your tenant for a long time even though you no longer need them for anything.

Siddharth Vaghasia adapted a script by Laura Kokkarinen to remove obsolete site scripts to use the Office 365 CLI.

Delete all Office 365 groups

There are so many different ways to create Office 365 groups. Teams, Planner, SharePoint team sites, etc. — you can accumulate a lot of them very fast.

Aakash Bhardwaj adapted another script by Laura Kokkarinen to remove obsolete Office 365 Groups to use the Office 365 CLI.

Hide list from site contents

If you need to hide the SharePoint list from the UI this simple PowerShell script will hide a specific list from the site contents. This will prevent users from easily accessing the list while, for example, you are still setting it up.

David Ramalho contributed a sample script that hides the specified list from the site contents overview.

Contributors

This release wouldn’t be possible without the help of (in alphabetical order) Bruce Albany, Aakash Bhardwaj, Velin Georgiev, Patrick Lamber, Yannick Plenevaux, David Ramalho, Albert-Jan Schot, Garry Trinder, Siddharth Vaghasia 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

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 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.