New version of Office 365 CLI (v0.4.0)

We have just published a new version of the Office 365 CLI with more commands, support for building scripts and completing your input when using the CLI directly in the shell.

Office 365 CLI

Office 365 CLI is a cross-platform CLI that allows you to manage various configuration settings of Office 365 no matter which operating system 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. The Office 365 CLI allows them to configure their tenants no matter which operating system they use.

New version of Office 365 CLI – v0.4.0

After a busy holiday season, we are proud to share with you a new version of the Office 365 CLI (v0.4.0) packed with new capabilities.

Working with custom actions

If you’re working with modern sites in Office 365 you can extend their capabilities by building SharePoint Framework client-side web parts and extensions. If you want to use your extensions consistently across the different sites, you will most likely deploy them using a tenant-wide deployment and register them in the different sites using a custom action.

Velin Georgiev did an awesome job shipping commands for the Office 365 CLI that allow you to manage custom actions in your sites. Using the Office 365 CLI you can see which custom actions are configured on your sites, get detailed information about each custom action and register new custom action, which is exactly what you need to install SharePoint Framework extensions on your sites.

For example, to enable a tenant-wide deployed SharePoint Framework application customizer, you would execute:

o365 spo customaction add -u https://contoso.sharepoint.com/sites/test --title "YourAppCustomizer" 
         --name "YourName" --location "ClientSideExtension.ApplicationCustomizer" 
         --clientSideComponentId b41916e7-e69d-467f-b37f-ff8ecf8f99f2 
         --clientSideComponentProperties '{"testMessage":"Test message"}'

For more information and examples of managing custom actions using the Office 365 CLI, see the documentation at aka.ms/o365cli.

Managing site collection app catalogs

Using site collection app catalogs, SharePoint tenant administrators can decentralize the management and scope the deployment of SharePoint add-ins and SharePoint Framework solutions to specific sites. For more information on working with site collection app catalogs, see the official documentation at https://docs.microsoft.com/en-us/sharepoint/dev/general-development/site-collection-app-catalog.

For this latest release, Andrew Connell contributed commands that allow you to manage site collection app catalogs in your tenant.

To add a site collection app catalog to your site, execute:

o365 spo site appcatalog add --url https://contoso.sharepoint/sites/site

To disable the site collection app catalog, execute:

o365 spo site appcatalog remove --url https://contoso.sharepoint/sites/site

For more information and examples of managing site collection app catalogs using the Office 365 CLI, see the documentation at aka.ms/o365cli.

Working with modern team and communication sites

Office 365 customers can create modern team and communication sites to collaborate and communicate more effectively.

Using the Office 365 CLI you can now manage a modern team and communication sites in your Office 365 tenant.

To create a modern team site with a public group, execute:

o365 spo site add --type TeamSite --alias team1 --title "Team 1" --isPublic

To create a communication site for your team or department, you would use:

o365 spo site add --type CommunicationSite --url https://contoso.sharepoint.com/sites/marketing --title Marketing

Office 365 CLI commands for managing sites in Office 365 are very useful if you want to automate creating sites or have to create a number of sites in a bulk.

For more information and examples of managing modern sites using the Office 365 CLI, see the documentation at aka.ms/o365cli.

Managing SharePoint Online service principal

When working on the CLI, we’re trying to balance including functionality that you can use already today with functionality that you will be able to use very soon. Office 365 is evolving continuously and we strive to keep up with changes so that you can benefit from the latest capabilities introduced in Office 365.

In the latest version of the Office 365, we added a few commands related to service principal and permission requests as well as managing the Azure Active Directory. More information about these commands is coming soon, once the related Office 365 capabilities have been made publicly available.

Build scripts using the Office 365 CLI

Initially, when we started working on the CLI, it could be used only in immersive (interactive) mode. In the command line, you would type office365 or o365, which would take you to a separate command prompt where you could execute the different commands available as a part of the Office 365 CLI.

If you look at how developers and administrators use PowerShell, you’ll see two different scenarios. They manage their tenant by executing cmdlets directly in the shell or they build scripts that they can execute to perform a number of tasks. The way the Office 365 CLI was built initially, supported the first scenario. With the improvements included in this release (v0.4.0), the Office 365 CLI supports being used directly in the shell and building scripts.

For example, to deploy all apps not yet deployed in the tenant app catalog, you could execute in Bash:

# get all apps available in the tenant app catalog 
apps=$(o365 spo app list -o json) 

# get IDs of all apps that are not deployed notDeployed
AppsIds=($(echo $apps | jq -r '.[] | select(.Deployed == false) | {ID} | .[]')) 
  # deploy all not deployed apps 
for appId in $notDeployedAppsIds; do 
  o365 spo app deploy -i $appId --skipFeatureDeployment 
done

You could do the same even easier in PowerShell:

# get all apps available in the tenant app catalog 
$apps = o365 spo app list -o json | ConvertFrom-Json 

# get all apps that are not yet deployed and deploy them 
$apps | ? Deployed -eq $false | % { o365 spo app deploy -i $_.ID --skipFeatureDeployment }

Notice though that if you are using PowerShell, you can also use the native PnP PowerShell cmdlets to achieve this exactly the same operation, which would be absolutely the recommended pattern in Windows platform.

For more information about how Office 365 CLI supports building scripts, see the blog post introducing the capability at https://blog.mastykarz.nl/building-scripts-office-365-cli/.

Command completion

As we’re adding more and more commands to the Office 365 CLI, we find it important that you can keep working with it efficiently. To help you navigate between the different commands, we added support for completing your input: when typing a command, either press TAB twice to see the list of available options, of start typing and press TAB once, to complete your input.

Office 365 CLI command completion works in Zsh, Bash and Fish as well as in Clink (cmder) on Windows. You can find information on how to set it up in the documentation.

Bug fixes and improvements

The latest release includes a number of bug fixes and minor improvements. For the full list of changes see the release notes in the Office 365 CLI documentation.

Sharing is caring

This release wouldn’t be possible without community contributions from Andrew Connell, Velin Georgiev and many others who tried our betas and provided their feedback, as well as past contributions to other PnP efforts, such as PnP PowerShell, PnP Core Component and PnP JavaScript Core Library.

Next steps

Install the latest version of the Office 365 CLI from npm using:

npm i -g @pnp/office365-cli

or yarn:

yarn global add @pnp/office365-cli

We regularly publish a beta version with the latest additions and improvements which you can install using:

npm i -g @pnp/office365-cli@next

If you have any feedback or questions, don’t hesitate to reach out on twitter with hashtag #Office365CLI or on the Office 365 CLI Gitter.

“Sharing is caring”

SharePoint PnP Team – 10th of January 2018