Office 365 CLI v1.2.0


We have just published the v1.2.0 of the Office 365 CLI with new commands for managing Office 365 tenants on any platform.

Manage Office 365 on any platform

Office 365 CLI is a cross-platform CLI that allows you to manage various configuration settings of Office 365 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.

New version of Office 365 CLI - v1.2.0

Continuing the effort of extending the CLI, we bring you a new version with new commands for managing your Office 365 tenant. Since we didn’t have any breaking changes in this release, we only have a minor version number increase. Still, we have some cool updates to share with you.

Authenticate using credentials

Originally, when we introduced the Office 365 CLI, we supported only the interactive way of authenticating using the OAuth device code flow. After connecting to an Office 365 service, the CLI would provide you with an authentication code. In your web browser, you would navigate to https://microsoft.com/devicecode and after entering the code, you would authenticate the CLI to communicate with Office 365 on your behalf.

We chose to use this authentication flow, because it’s optimized for console-based applications and allows you to use advanced Azure AD security capabilities such as multi-factor authentication or conditional access.

One of the consequences of using the device code flow is, that it’s interactive. Once established, the connection to Office 365 is persisted, but still it’s inconvenient to use in continuous integration/deployment (CI/CD) scenarios, where you can’t interact with the CLI.

To better support using the Office 365 CLI in CI/CD scenarios, we added support for authenticating using credentials. To authenticate using credentials, specify the password authentication option and the credentials:

spo connect https://contoso.sharepoint.com --authType password --userName admin@contoso.com --password pass@word1

Authenticating using credentials is very convenient if you want to use the Office 365 CLI in CI/CD scenarios. For more information about authentication in the Office 365 CLI, see the documentation at https://sharepoint.github.io/office365-cli/user-guide/connecting-office-365/#connect-to-an-office-365-service.

Manage modern pages

Microsoft is continuously adding more capabilities to modern pages in SharePoint. Many organizations have already migrated their portals to use modern pages and many more are planning migrations.

To support the increasing need to manage modern pages, in this release of the Office 365 CLI we extended the support for managing modern pages. Previously, we provided the ability to list, create and update modern pages. In this release, we added the ability to get more information about a modern page and its contents.

After you listed all modern pages in the particular site using the spo page list command, you can get more information about a particular page using the spo page get command:

o365$ spo page get --name home.aspx --webUrl https://contoso.sharepoint.com/sites/team-a

This will give you some basic information about the page such as its title, layout, whether it has comments enabled and how many sections on controls are on it.

Next, you can get more information about what controls are added to that page. For this, use the spo page control list command.

o365$ spo page control list --name home.aspx --webUrl https://contoso.sharepoint.com/sites/team-a

For each control on the page, this command will show its id, type and title.

Finally, you can get more information about each control using the spo page control get command:

o365$ spo page control get --id 3ede60d3-dc2c-438b-b5bf-cc40bb2351e1 --name home.aspx --webUrl https://contoso.sharepoint.com/sites/team-a

We hope that these commands will help you manage your tenant as your organization moves to use modern pages in your portal. For more information about managing modern pages using the Office 365 CLI, see the documentation at aka.ms/o365-cli.

Work with client-side web parts

SharePoint Framework is the most popular model for extending SharePoint. Many organizations use it to integrate additional functionality in their SharePoint portal and better support their business.

SharePoint Framework solutions can be deployed in a number of ways. You can deploy them to all sites in the tenant through the tenant app catalog or install it only in specific sites. You can also choose to enable site collection app catalog, and deploy the solution only in that particular site.

To help you govern your SharePoint Framework solutions and make it possible for you to build more robust automation scenarios, Balamurugan Kailasam contributed the spo web clientsidewebpart list command. Using this command, you can discover which client-side web parts are available in the particular site and could be added to pages:

o365$ spo web clientsidewebpart list --webUrl https://contoso.sharepoint.com/sites/team-a

For each web part, this command will show its id, name and title. For more information about working with client-side web parts using the Office 365 CLI, see the documentation at aka.ms/o365-cli.

Manage files

When automating governance of your portal or provisioning of your sites, sometimes it might be necessary for you to remove some files. In this release, fellow SharePoint MVP, Rodrigo Romano, contributed a command to remove files:

o365$ spo file remove --webUrl https://contoso.sharepoint.com/sites/project-x --url SharedDocuments/Test.docx

As organizations are moving their classic portals to the modern SharePoint UI, this command will be helpful to clean the migrated sites of obsolete master pages, CSS styles, JavaScript scripts and other assets that are no longer needed.

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

Manage list items

Features come and go, but SharePoint lists are one that have been around for a long time and are very likely to stay. Used to store everything from user data to configuration information for SharePoint customizations, lists are one of the basic building blocks found in every SharePoint tenant.

As a part of your provisioning automation, you might want to create list items that represent specific settings for your solutions. In that case, you will find the command contributed by Mark Powney invaluable. Using the spo listitem add command, you can easily create a new item in a list:

o365$ spo listitem add --listTitle "Demo List" --webUrl https://contoso.sharepoint.com/sites/project-x --Title "Demo Item"

The spo listitem add command is highly flexible and allows you to create items based on a specific content type, specify values for all kinds of field types and even create items in folders if necessary.

The command contributed by Mark is complimented by another command contributed by the fellow SharePoint MVP, Rodrigo Romano, which allows you to remove an existing list item:

o365$ spo listitem remove --webUrl https://contoso.sharepoint.com/sites/project-x --listTitle 'List 1' --id 1

When removing a list item, you can choose if you want to delete it permanently or move to the recycle bin.

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

Manage your hub sites

Recently, Microsoft released a preview of hub sites: a new way of organizing related sites and managing information in SharePoint intranets built on Office 365. Using hub sites, organizations can link related sites together and have them share consistent look and feel and navigation. While hub sites are still in preview, many organizations are experimenting with them and thinking how they should restructure the information architecture in their portal to benefit of hub sites.

In the past already, we released support for managing hub sites using the Office 365 CLI. In this release, we continue the effort to offer you a complete suite of tools by adding two new commands contributed by SharePoint MCM, Robert Jaakke from Mavention.

Using the spo hubsite data get command, you can quickly retrieve hub site information for the particular site:

o365$ spo hubsite data get --webUrl https://contoso.sharepoint.com/sites/project-x

If the site is connected to a hub site or is a hub site itself, the command will return the information about the hub site such as its logo, name, URL, navigation and theme. This is very helpful whenever you need to quickly determine if the site is connected to a hub site and if so, to which one.

When working with hub sites, you can configure a theme, that should be applied to the hub site and its connected sites. This allows you to provide your users with a consistent user experience across the related sites. After changing the theme, it could take a moment for the changes to be propagated across the connected sites. Using the spo hubsite theme sync command you can force the changes to be applied immediately:

o365$ spo hubsite theme sync --webUrl https://contoso.sharepoint.com/sites/project-x

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

Set property bag values

While many organizations are in the process of migrating their portals to modern SharePoint UI, many others are still using the classic experiences. Solutions working with classic experiences, often store their configuration in property bag and sometimes, especially when upgrading the solutions, it’s necessary to update these values manually.

In this release, Velin Georgiev contributed the spo propertybag set command, that allows you to set the value of the specific property in the property bag:

o365$ spo propertybag set --webUrl https://contoso.sharepoint.com/sites/test --key key1 --value value1

This last command completes Velin’s effort in the Office 365 CLI to provide a complete set of CRUD operations for property bag values. For more information about working with property bags using the Office 365 CLI, see the documentation at aka.ms/o365-cli.

Get information about users

When managing a tenant or building solutions for Office 365, sometimes you need to retrieve a set of users matching specific criteria. Whether they work in a certain department, share a job title or live in a particular region, you can easily retrieve their information using the Office 365 CLI.

Using the graph user list command, you can quickly list all users whose profiles match certain criteria:

o365$ graph user list --jobTitle 'Account manager'

Then, for each user, using the graph user get command, you can get additional information:

o365$ graph user get --userName AarifS@contoso.onmicrosoft.com

Both commands are highly flexible and allow you to specify which information you would like to retrieve exactly. For more information on how they work, see the documentation at aka.ms/o365-cli.

Contributors

This release wouldn’t be possible without the help of (in alphabetical order) Velin Georgiev, Robert Jaakke, Balamurugan Kailasam, Mark Powney and Rodrigo Romano.

Thank you all for the time you chose to spend on the Office 365 CLI and your help to advance it. It’s a real pleasure to work with you.

What’s next

Over the last few weeks we’ve been discussing and researching a couple of things.

Additional ways to authenticate with Office 365

In this version, we added the support for authenticating using credentials. Another way to authenticate against Azure AD is by using a certificate, which allows you to interact with Office 365 in app-only context. Would you find it a valuable addition to the Office 365 CLI?

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. So far, we 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.

Managing SharePoint Framework projects

What if you could use the Office 365 CLI not only to manage your Office 365 tenant but also to improve the developer experience of your Office 365 solutions?

Another area, that we’ve been researching recently, is the ability for the Office 365 CLI to manage your SharePoint Framework projects. SharePoint Framework is a popular development model backed by a vibrant community and there are some great opportunities for the CLI to improve how you build solutions. We’re making progress with our research and hope to have something to show you relatively fast, so stay tuned for updates.

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.

Others found also helpful: