We have just published a new major version of the Office 365 CLI (v2). Here is what has changed.

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 major version

As we kept extending the Office 365 CLI with new functionality for over a year, we noticed a few areas that we could improve to simplify using the CLI.

Grouping per service vs. grouping per API

Originally, commands in the CLI were grouped by the API they used to connect to the corresponding service in Office 365. For example, Microsoft Teams commands would start with graph teams, because they used the Microsoft Graph but Microsoft Flow commands would start with azmgmt flow because they were built using the Azure Management API. While it was clear to us, it required the user to know how the particular command was implemented. Also, should the implementation change, we’d need to introduce the alias to represent the new API used in our code.

So to simplify the command naming for the users, we removed the API name from the command name. In Office 365 CLI v2 all command names start with the name of the service to which they belong. Check out the docs at aka.ms/o365cli for the updated list of commands.

One login

When we started working on the Office 365 CLI, we thought it would be a good idea to let you log in separately to each API. Theoretically, it would give you the flexibility to use different accounts with different services. In practice, it turned out, that no one really used the CLI that way. What was meant to be a convenience turned out to be a nuisance. So in Office 365 CLI v2, we decided to move away from the per-service/-API log in and have one login in the CLI that automatically takes care of the authorization when switching between services.

To login in Office 365 CLI v2, all you need to do is to run the login command. Once you’re signed in, you can start using all commands in the CLI.

Auto-detect SharePoint URL

Comparing to other Office 365 services, SharePoint Online is an odd-duck as it has a unique URL on every tenant. Where the Microsoft Graph, for example, is always available at https://graph.microsoft.com, SharePoint needs to be called using its unique URL, like https://contoso.sharepoint.com.

In the previous version of the Office 365 CLI, when logging in to SharePoint Online, you would specify the URL of your tenant to which you wanted to connect, eg. spo login https://contoso.sharepoint.com. If you wanted to use admin-level commands, you had to specify the tenant admin URL instead or these commands would fail, eg. spo login https://contoso-admin.sharepoint.com.

In Office 365 CLI v2 we simplified all this. After logging in to your Office 365 tenant using the login command, the CLI will automatically detect the URL of SharePoint Online and automatically switch between the root site or the tenant admin URL depending on the commands you use.

While this approach should work in most cases, it could lead to undesired results when you, for example, work with a multi-geo tenant and want to manage specific geography. In such a case you can use the spo set --url https://contosoeur.sharepoint.com command to specify the URL of the geography you want to manage.

Breaking changes

Renaming commands and changing the login approach introduces several breaking changes. When migrating your existing scripts, please check the aka.ms/o365cli for the updated list of commands.

New commands and improvements

Aside from big architectural changes, we shipped quite a few new commands for SharePoint, Teams, Flow, Office 365 Groups and the Microsoft Graph. Check out the release notes for a full list of what has changed.

Contributors

Office 365 CLI v2 introduced the biggest refactoring to date. We wouldn’t have it if it wasn’t for the help of Velin Georgiev, who, next to contributing commands, helped refactoring existing code, processing incoming PRs and refactoring them to the v2. It’s a pleasure to have you on the team, sir, and help to lead the CLI project.

This release wouldn’t be also possible without the help of (in alphabetical order) Stefan Bauer, Stijn Brouwers, Mark Priem, Albert-Jan Schot, Peter Tane, Joseph Velliah and Rabia Williams as well as all other contributors we had to date. There wouldn’t be a v2 without the v1, which you helped to build. Thank you all so much for the time you chose to spend on the Office 365 CLI!

What’s next

With the big refactoring behind us, we’re going to focus on adding more commands and improving the existing ones. Like always, we’re listening for feedback and ideas for improvements. We can’t promise we’ll implement everything, but we will definitely engage in the discussion to better understand your suggestions.

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.