When working with the Office 365 CLI, you need to connect to SharePoint only once.
What is Office 365 CLI
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. For more information about the Office 365 CLI, see its documentation at aka.ms/o365cli.
Connecting to Office 365 in the Office 365 CLI
Before you can use the Office 365 CLI to manage your tenant, you have to connect to Office 365. Office 365 exposes many services like Azure AD, Microsoft Graph or SharePoint. Each of these services requires specific authentication and to follow this model, the different commands in the Office 365 CLI are organized by services they interact with. For example, all commands that interact with SharePoint begin with
spo site list, and commands that use the Microsoft Graph, start with
graph o365group list.
Before you can use any of these commands, you have to authenticate with the corresponding service. To connect to the Microsoft Graph you would execute the
graph connect command. To connect to SharePoint, you would use the
spo connect command, specifying the URL of your site. And this is where things often go wrong.
SharePoint vs. everything else in Office 365
One of the things that separates SharePoint from other services in Office 365 is the fact, that each SharePoint tenant is located on a unique URL. When you want to connect to the Microsoft Graph, you use
https://graph.microsoft.com. This URL is the same for everybody. To connect to the Azure AD Graph, you would use
https://graph.microsoft.net, again the same URL for each Office 365 tenant. But to connect to SharePoint, you need to specify the unique URL of your tenant. What complicates things even more, is the fact that each SharePoint tenant has three domains: https://contoso-admin.sharepoint.com - which points to the tenant admin site, https://contoso.sharepoint.com - which points to regular sites and https://contoso-my.sharepoint.com - which points to OneDrive for Business sites. And each of these domains requires separate authentication as well. But there is even more.
If you've worked with the SharePoint Client-Side Object Model (CSOM) or PnP PowerShell, you're likely familiar with the concept of context. Before you perform any action, you establish a context by connecting to the site on which you want to operate. If you want to operate on a different site, you connect to that site, and so on. Exactly this behavior, combined with our poor choice of name for the command to authenticate the Office 365 CLI with Office 365, leads to confusion and overhead.
Connect == log in
Office 365 CLI doesn't have the notion of a context. If the command operates on site collection- or site-specific resources, it requires you to specify the URL of the site (collection). Because of that, when using the Office 365 CLI to manage SharePoint, you only need to connect once to authenticate with SharePoint in your tenant. After that, you can work on any site in your tenant, without having to connect to it first.
Tip: Some commands in the Office 365 CLI require connection to the tenant admin site. Because of that, if possible, you should always connect to the tenant admin site. When operating on different sites, Office 365 CLI will automatically obtain access token to the specified site URL.
Because Microsoft Graph or Azure AD are exposed under a single domain, there is no confusion with what connect means in that context. But SharePoint works differently, and using connect for authentication is confusing.
So to help clarify things, we decided to rename the
connect commands, to
login, which hopefully will be a clearer indication, that you only need to use it once. To authenticate with SharePoint, you will now call
spo login https://contoso-admin.sharepoint.com. To communicate with the Microsoft Graph, you will login using
graph login, and so forth.
The login and logout verbs replacing respectively connect and disconnect follow the naming convention of the Azure CLI.
logout commands work identically as their
disconnect predecessors. To avoid breaking changes, you can still use the
disconnect but we the CLI will display a deprecation message suggesting using
This change is reflected in the latest beta of the Office 365 CLI which you can install from npm using
npm install -g @pnp/office365-cli@next. It will be released in the next version of the Office 365 CLI v1.7.0 end of September/begin of October '18.
Big thanks to Andrew Connell for bringing this issue up and his thoughts on suggestions for improvement. If you like this change or have some concerns, please let us know on GitHub.
Hopefully this change in the Office 365 CLI clarifies things a little and will help you use it more efficiently.