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 the Office 365 CLI, you can manage your SharePoint Framework projects.
New version of Office 365 CLI - v1.7.0
New version of the Office 365 CLI with a few new commands and extended support for upgrading SharePoint Framework projects.
Manage modern pages
Microsoft is heavily investing in modern SharePoint experiences. One of the central building blocks are pages that allow you to publish and aggregate information on your intranet.
In this release of the Office 365 CLI, we’ve extended support for managing modern pages. Rodrigo Romano continued his work, by adding the ability to retrieve information about page columns. This capability is invaluable if you want to automate provisioning pages and want to control how the different elements are layed out on the page.
To get information about the specific page column, execute:
spo page column get --webUrl https://contoso.sharepoint.com/sites/team-a --name home.aspx --section 1 --column 1
To correctly layout the different elements on the page, you might need to create sections. Modern pages supports sections with different layouts that give you flexibility in designing your pages and presenting information to your users. Balamurugan Kailasam contributed a command to add sections to modern pages.
To add a section to modern page, execute:
spo page section add --name home.aspx --webUrl https://contoso.sharepoint.com/sites/newsletter --sectionTemplate OneColumn --order 1
In some cases, when upgrading your solution, you might need to remove old pages and replace them with new ones. Yannick Plenevaux added support for deleting modern pages using the Office 365 CLI.
To remove a modern page, execute:
spo page remove --name page.aspx --webUrl https://contoso.sharepoint.com/sites/a-team
For more information about working with modern pages using the Office 365 CLI, see the documentation at aka.ms/o365-cli.
Manage site collections
As you migrate your intranet to modern SharePoint sites, once the migration is completed and the content has been moved over, you will do good by deleting the old sites. In this release, Albert-Jan Schot contributed a command to delete classic SharePoint sites.
To delete a classic site, execute:
spo site classic remove --url https://contoso.sharepoint.com/sites/demosite
When deleting classic sites you can choose if you want to move them to the Recycle Bin first or remove the immediately.
For more information about working with SharePoint sites using the Office 365 CLI, see the documentation at aka.ms/o365-cli.
When building SharePoint applications, a common requirement is to be able to respond to activities in SharePoint, such as creating or editing a list item or document. In SharePoint Online, next to using Remote Event Receivers, you can use webhooks to get notified of changes in SharePoint content and configuration.
To help you keep track of the webhooks configured in your lists, Arjen Bloemsma contributed a command to list webhooks registered in a particular list.
To list webhooks configured on a particular list, execute:
spo list webhook list --webUrl https://contoso.sharepoint.com/sites/project-x --title Documents
Arjen is working on additional commands that will allow you to get more information about webhooks but also to create and edit them.
For more information about managing webhooks using the Office 365 CLI, see the documentation at aka.ms/o365-cli.
Managing list items
List items are one of the core building blocks in SharePoint. They can store regular content but also application settings or log information. Mark Powney continued his work adding a command to retrieve list items matching the given criteria.
You can retrieve list items using a CAML query:
spo listitem list --title "Demo List" --webUrl https://contoso.sharepoint.com/sites/project-x --query "<View><Query><Where><Eq><FieldRef Name='Title' /><Value Type='Text'>Demo list item</Value></Eq></Where></Query></View>"
Alternatively, you can also use an OData filter:
spo listitem list --title "Demo List" --webUrl https://contoso.sharepoint.com/sites/project-x --filter "Title eq 'Demo list item'"
For more information about working with list items using the Office 365 CLI, see the documentation at aka.ms/o365-cli.
Managing tenant settings
As new capabilities are introduced in SharePoint and Office 365, they need to be configured for you to make the best use of them. Understanding and automating the configuration allows you to deploy new capabilities in your organization with more confidence. In this release of the Office 365 CLI, Velin Georgiev added support for retrieving the current configuration of tenant settings.
To get the current configuration of tenant settings, execute:
spo tenant settings list
For more information about managing tenant settings using the Office 365 CLI, see the documentation at aka.ms/o365-cli.
Manage taxonomy term groups
SharePoint taxonomy is one of the most popular content management capabilities. Not only it’s used for tagging content but also for storing hierarchical information such as navigation. In this version of the Office 365 CLI, we’re proud to introduce the first step towards support managing SharePoint taxonomy, starting with term groups.
To list all taxonomy term groups, execute:
spo term group list
To get more information about the particular term group, execute:
spo term group get --id 0e8f395e-ff58-4d45-9ff7-e331ab728beb
You can expect more commands for working with SharePoint taxonomy in the future releases of the Office 365 CLI.
For more information about managing taxonomy term groups using the Office 365 CLI, see the documentation at aka.ms/o365-cli.
Manage Azure AD group settings
Azure Active Directory offers administrators a number of advanced settings to manage their tenants. These settings are exposed through group settings and group settings templates and allow administrators to define the information classification in their tenant, control guess access or naming policies to name a few. In this release of the Office 365 CLI, Paweł Hawrylak completed the support for group settings by adding commands for updating and removing them.
To update a group setting, execute:
graph groupsetting set --id c391b57d-5783-4c53-9236-cefb5c6ef323 --UsageGuidelinesUrl https://contoso.sharepoint.com/sites/compliance --ClassificationList 'HBI, MBI, LBI, GDPR' --DefaultClassification MBI
To remove the particular group setting, execute:
graph groupsetting remove --id 28beab62-7540-4db1-a23f-29a6018a3848
For more information about managing Azure AD group settings using the Office 365 CLI, see the documentation at aka.ms/o365-cli.
Manage Microsoft Flow flows
More and more organizations every day start using the Microsoft Flow. And, while it remains primarily an end-user tool, at some point you will want to be able to manage Flows in your organization.
For this release of the Office 365 CLI, Arjen Bloemsma contributed commands to get information about Flow runs.
To list runs of the particular Flow, execute:
azmgmt flow run list --environment Default-d87a7535-dd31-4437-bfe1-95340acd55c5 --flow 5923cb07-ce1a-4a5c-ab81-257ce820109a
To get more details about the particular run, execute:
azmgmt flow run get --environment Default-d87a7535-dd31-4437-bfe1-95340acd55c5 --flow 5923cb07-ce1a-4a5c-ab81-257ce820109a --name 08586653536760200319026785874CU62
But there is more. Using this version of the Office 365 CLI you can automate exporting Flows. Whether for keeping a backup or to move them between the environments, CLI can help you automate the task, which will be invaluable as your organization starts adopting Microsoft Flow. For this release, Mark Powney contributed a command to export Microsoft Flows.
To export a Microsoft Flow to file, execute:
azmgmt flow export --environment Default-d87a7535-dd31-4437-bfe1-95340acd55c5 --id 3989cb59-ce1a-4a5c-bb78-257c5c39381d
You can choose whether you want to export the Flow as a ZIP archive or a JSON file.
For more information about managing Microsoft Flow using the Office 365 CLI, see the documentation at aka.ms/o365-cli.
Added support for upgrading SharePoint Framework projects to v1.6.0
Recently, Microsoft released a new version of the SharePoint Framework. This latest version includes a numbers of improvement around communicating with APIs secured with Azure AD. Many organizations who build solutions using the SharePoint Framework, will find the release invaluable and will likely want to benefit of it.
Depending on the version, sometimes upgrading a SharePoint Framework project from one version to another is as easy as installing the latest npm packages. But sometimes, you need to adjust your project config files or other settings. Because there are no step-by-step instructions you either end up missing steps and having a broken project, or spending precious time manually trying to determine what has changed in the latest version of the SharePoint Framework. Office 365 CLI significantly simplifies the upgrade process, by providing you with a report with instructions tailored to your project.
To ease upgrading existing SharePoint Framework projects to version 1.6.0, we’ve extended Office 365 CLI’s capabilities to include this latest version in its upgrade analysis.
If you haven’t done it yet, try upgrading your SharePoint Framework projects using the Office 365 CLI and tell us what you think!
For more information about upgrading SharePoint Framework projects using the Office 365 CLI, see the documentation at aka.ms/o365-cli.
Log in instead of connect
As we were analyzing the usage of the Office 365 CLI, we noticed, that we might have made a mistake when naming the commands to authenticate with Office 365 services. Originally, before you could communicate with an Office 365 service such as Microsoft Graph or SharePoint, you would call the corresponding
connect command. The problem is, that connect in SharePoint has a special meaning that originates from CSOM and PnP PowerShell. Unlike CSOM or PowerShell, Office 365 CLI doesn’t require you to connect to a specific site before you can work with it. Instead, you connect only once to obtain an access token, and from that moment on, you can operate on any site in your tenant.
To clarify this detail, we renamed the connect commands to login. To avoid breaking changes, you can still use connect commands, but they will display a message recommending you to use the new login commands instead. The behavior of the connect and login commands is the same so you don’t need to change any of your scripts immediately, although we would highly recommend it.
This release wouldn’t be possible without the help of (in alphabetical order) Vincent Biret, Arjen Bloemsma, Velin Georgiev, Paweł Hawrylak, Balamurugan Kailasam, Yannick Plenevaux, Mark Powney, Rodrigo Romano, Albert-Jan Schot and Pete Skelly.
Thank you all for the time you chose to spend on the Office 365 CLI and your help to advance it! We wouldn’t be able to do it without you.
Work in progress
Here are some things that we’re currently working on.
Setup script for the PnP SharePoint Starter Kit
Recently, the SharePoint PnP team released the SharePoint Starter Kit: an end-to-end solution illustrating how to use the latest capabilities to build a modern intranet on Office 365. This starter kit will keep evolving as new capabilities are added to Office 365.
To help you setup the solution in your tenant, the PnP team released a setup script based on PnP PowerShell. Due to the current limitations of PnP PowerShell this script can be used only on Windows.
What if we had an equivalent script built in bash, using the Office 365 CLI which you could use on any platform?
I’ve already started working on this script in a separate repo. The basic structure is almost in place and ready for external contributions. Would you be interested in helping out with it?
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.
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.