Keeping up with the pace of change in Microsoft Azure can be challenging. Every week there are more than 50 pull requests against the Azure Representational State Transfer (REST) API. Over the past 6 months, we’ve been building the AI-powered extension, Azure Aladdin, to help make using Azure easier. The first interface was a Microsoft docs extension that provided users content recommendations.

Today we are excited to offer the next interface to the Aladdin knowledge base, an experimental Azure Command-line interface (CLI) extension that provides insight and examples based on how other user have seen success using Microsoft Azure.

Install the Azure CLI “Find” extension

We’ve made it straightforward to install experimental extensions in Azure CLI. If you want to install the new “Find” extension, run the following command:

For users of the Azure Cloud Shell, any extension installed will persist between sessions. Below we’re going to examine some of the capabilities of this new extension.

Explains CLI commands

For some features and previews, such as Azure Web App for Containers, there may only be auto-generated reference content without examples.

Shows common commands in a group

The extension can also break down complex groups, such as Azure Monitor (az monitor), and provide the most common commands used:

Help find commands

With more than 2,300 commands, it can be hard to find the right one. This extension replaces the existing Azure CLI “Find” command search capability with one powered by the knowledge base. Today, we provide a simple text search ordered by popularity with an example for each result but expect to see improvements over time.

Examples, always up-to-date

When building tools for software development, reference documentation continues to be one of the most challenging areas to get right. Good reference documentation needs to be simple enough to allow beginners access, yet technical enough to enable professionals to support niche scenarios. Having up-to-date examples is key to providing good reference documentation.

By using the knowledge base and applying machine learning to generate examples, we’re able to ensure quality examples across our Azure management products and documentation. For example, creating a VM with “az vm create” offers 53 unique parameters used in hundreds of different ways. 

Today, only 42 percent of CLI commands have examples. Over the coming months, we will be integrating Aladdin-generated examples into the Azure CLI documentation, with a goal to reach 95 percent of all commands that come with usage examples.

How does this work?

To serve examples and related documentation, our robot is consulting a new knowledge base, called the Aladdin Knowledge Base. Aladdin is built by compiling information from many sources including our own documentation, code, and usage data, as well as Azure-related GitHub issues. This knowledge base is a continuation of our previous experiment, the Aladdin Doc Helper Chrome extension.

“az find” consults this knowledge base to create the most relevant examples for each CLI command. If you’re one of the first few to learn a new command or service, you might not know it, but you are contributing by adding new entries to the knowledge base and helping make others successful. Each time Azure is used in a new way, our system incorporates that usage, along with docs.microsoft.com content to generate example ‘guide-posts’ to help future users along the way. It tracks the success of users who view our examples, a topic worthy of its own post and using the results to fine tune examples and recommendations. Our knowledge base is agnostic to any specific tool. In the future, we intend to create a  similar help module for Azure PowerShell that utilizes the same knowledge base.

This service is built entirely on Azure resources! Behind the scenes, we employ an Azure Search Service customized for our retrieval task and utilize Language Understanding Intelligent Service (LUIS) to allow our robots to understand humans.

Help us improve with your feedback

Help us make the tools that you love and use every day even better. How can you help? Provide feedback. With each Find result, you can provide feedback to let us know when Aladdin is useful, has lost its way or is giving bad advice. These reports are used to identify incorrect or out-of-date examples. Our robot will incorporate your feedback and will improve the quality and accuracy of examples, especially those related to uncommon scenarios.

What’s next?

Our goal is to integrate this extension into the Azure CLI as a core feature. However, we’re also investigating some additional features:

• Personalization – Customize examples based on your profile, resources, and defaults.

• Keep up to date – The cloud changes fast, we’ll help you keep aware of services and features that are important to you.

• Migration information – When you are ready to migrate to a new feature or service, we will make sure you know your options, based on others who have previously migrated to Azure.

• Try this next – As you get more comfortable with the CLI, we’ll help you scale your solutions by showing you how others have scaled from where you are now.

We will continue to improve the Azure Aladdin knowledge base and offer more experiences and tools for managing Azure. If you have any suggestions or ideas, we encourage you to share with the team by sending an email to aladdindoc@microsoft.com.