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.7
Following our monthly release cadence, we’ve released a new version of the Office 365 CLI with some new capabilities.
PowerShell command completion
Office 365 CLI is a cross-platform command-line tool that works in any shell. Following our recent non-scientific research, it seems like the majority of our users are on Windows and use the CLI in PowerShell.
You can use the Office 365 CLI in two modes: immersive, where you launch it as an application and it takes over the command prompt and non-immersive, where instead of launching the CLI you execute a specific command. The non-immersive mode is convenient if you build automation scripts or want to quickly execute a command.
Until recently, that quickly part was debatable in PowerShell. Because CLI is not a PowerShell cmdlet or a module, PowerShell doesn’t automatically offer command completion for it. So instead you need to either know the different commands and options by heart or look up relevant examples in the help.
In this release, we’re proud to announce command completion for PowerShell and PowerShell Core! After setting it up, type o365[space][tab] and you will get the list of all available commands.
Continue typing, and the command completion will automatically provide you with relevant suggestions.
If you use the Office 365 CLI in PowerShell, we hope you’ll enjoy the command completion. For more information about how it works and how to set it up, see the documentation.
Support for uploading large files and handling files with special characters
One of the most popular use cases for Office 365 CLI is the management of files and folders thanks to its speed and robustness.
In this version, we continue our improvements in this area. Steve Mücklisch contributed support for uploading large files (larger than 250MB). There is no difference in how you upload small and large files using the Office 365 CLI and it automatically picks the most efficient method based on the size of your file. Additionally, we added support for handling files with special characters.
We hope that these improvements will help you to put the Office 365 CLI to even better use and if there are any edge cases that we don’t support yet, don’t hesitate to let us know.
List app role assignments
The foundation of Microsoft 365 solutions is authentication. Before you can connect to the Microsoft cloud, you need to authenticate. There are several ways in which you can do it, depending on your requirements. Typically though, you will register an Azure AD application and assign it some delegated and/or application permissions.
Previously, you could verify delegated permissions assigned to your application using the aad sp get command. For this release, Paul Schaeflein contributed the aad approleassignment list command that allows you to verify the application permissions assigned to your application.
To list the assigned app roles for your application using its ID, execute:
aad approleassignment list --appId b2307a39-e878-458b-bc90-03bc578531d6
You can also retrieve the assigned app roles using your application’s name:
aad approleassignment list --displayName 'MyAppName'
For more information about managing Azure AD applications using the Office 365 CLI see the documentation.
Update 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, Yannick Plenevaux contributed a command to update existing schema extensions.
To update an existing schema extension, execute:
graph schemaextension set --id MySchemaExtension --owner 62375ab9-6b52-47ed-826b-58e47e0e304b --description "My schema extension"
For more information about working with schema extensions using the Office 365 CLI, see the documentation at aka.ms/o365cli.
Report tenant and Office 365 groups 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 Office 365 groups. For more information about which reports are available, see the documentation.
Retrieve Teams messages
As a part of your reporting or automation processes, you might need to look into recent Teams messages. To help you in these scenarios, Bruce Albany extended the teams message list command with support for retrieving messages since a specific date:
teams message list --teamId fce9e580-8bba-4638-ab5c-ab40016651e3 --channelId 19:eb30973b42a847a2a1df92d91e37c76a@thread.skype --since 2019-12-31T14:00:00Z
This addition can be very helpful in case you’re looking for recent messages or need to report on the recent usage of Teams.
List sites that are in the recycle bin or have already been removed
When working with SharePoint, you create sites to facilitate collaboration in your organization. While some sites are there to stay, many are temporary and need to be cleaned up when they’re no longer necessary.
To help you keep track of which sites have been recently deleted, Joakim Högberg extended the existing spo site list command with support for retrieving deleted sites.
To retrieve deleted site, execute:
spo site list --deleted
In some cases, you want to see which sites have been moved to the tenant-level recycle bin. You can do this by using the spo tenant recyclebinitem list command contributed by Joakim Hagström:
spo tenant recyclebinitem list
For more information about managing sites using the Office 365 CLI, see the documentation at aka.ms/o365cli.
Remove organization assets libraries
Recently, Microsoft introduced organization assets libraries where organizations using Office 365 can store their branding and communication assets in a centralized location. Organizations 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 the past, we’ve introduced support for retrieving the list of all organization assets libraries in your tenant. In this version, Albert-Jan Schot contributed a command to remove the specific organization assets library designation.
To remove the specific organization assets library, execute:
spo orgassetslibrary remove --libraryUrl "/sites/branding/assets"
For more information about managing organization assets libraries using the Office 365 CLI, see the documentation at aka.ms/o365cli.
Add Teams tab
Microsoft Teams play a key role in facilitating collaboration for organizations using Microsoft 365. In their base, Teams are built around communication, but organizations can extend the user experience to offer their employees a richer experience. One way to extend Teams is by adding tabs, which can offer quick access to a specific location or even a whole application.
In this release of the Office 365 CLI, Rabia Williams contributed a command to add Teams tabs which is invaluable if you want to script provisioning Teams in your organizations or provision them in a structured and repeatable way.
To add a Teams tab, execute:
teams tab add --teamId 00000000-0000-0000-0000-000000000000 --channelId 19:00000000000000000000000000000000@thread.skype --appId 06805b9e-77e3-4b93-ac81-525eb87513b8 --appName 'My Contoso Tab' --contentUrl 'https://www.contoso.com/Orders/2DCA2E6C7A10415CAF6B8AB6661B3154/tabView'
For more information about managing Microsoft Teams using the Office 365 CLI, see the documentation at aka.ms/o365cli.
Post Yammer message
Organizations on Office 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 a command to post a yammer message.
To post a message to Yammer, execute:
yammer message add --body "Hello everyone!"
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.
Prettify JSON output
By default, Office 365 CLI returns its output in a human-readable text format. This output mode is trimmed for readability in a small terminal window. If you’re building automation scripts or want to have access to all properties of the particular Office 365 object, you can change the output to JSON. By default, the serialized JSON string is printed in a single line which makes it hard to inspect. For this release, Garry Trinder contributed support for prettifying the JSON output without using any additional tools like jq.
To prettify the JSON output add the --pretty flag:
spo site list --output json --pretty
We’re debating if JSON output should be prettified by default. What do you think? Let us know!
Contributors
This release wouldn’t be possible without the help of (in alphabetical order) Bruce Albany, Velin Georgiev, Joakim Hagström, Joakim Högberg, Patrick Lamber, Steve Mücklisch, Yannick Plenevaux, Paul Schaeflein, Albert-Jan Schot, Garry Trinder 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.
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.
Script examples
In every release of the Office 365 CLI, we introduce new commands for managing Office 365. With almost 350 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. In the coming weeks, we want to spend some time 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.
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, either in the comments below or on twitter @office365cli.
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, on twitter with the #office365cli hashtag or on gitter.
