Navigating the Microsoft Graph command-line interface (CLI)

Article
07/05/2023

The Microsoft Graph API is huge, and it's growing all the time. Therefore, the number of commands in the Microsoft Graph command-line interface (CLI) is also large. Finding the right command for what you want to achieve can be challenging, especially if you're not already familiar with Microsoft Graph. This topic looks at some ways to help find a particular command.

Note

Some requests for Microsoft Entra resources require the use of advanced query capabilities. If you get a response indicating a bad request, unsupported query, or a response that includes unexpected results, including the $count query parameter and ConsistencyLevel header may allow the request to succeed. For details and examples, see Advanced query capabilities on directory objects.

Command naming conventions

The commands in the CLI are generated directly from the REST API, so the names are influenced by the API. You don't have to understand the details of the API to use the Microsoft Graph CLI, but it helps to understand the naming convention.

The Microsoft Graph CLI commands represent resources in Microsoft Graph and the actions that can be taken on those resources. The general structure of the commands follow this pattern:

mgc <path-to-resource> <action>

The <path-to-resource> is one or more commands that follow the URL structure of the target API. The <action> is the final command in the sequence, and indicates the action to take on the target resource.

Path to resource commands

The path to the target resource is constructed by sequencing one or more commands to represent the URL to the resource, as specified by the REST API. For a simple API like GET /me, a single command (me) is enough to represent the path.

Next, look at a more complex example: the get message API. Look at the HTTP requests for this API. If you ignore the requests with /me in the URL, there are two other ways to call this API.

GET /users/{id | userPrincipalName}/messages/{id}
GET /users/{id | userPrincipalName}/mailFolders/{id}/messages/{id}

The equivalent CLI commands map to the segments in the URLs. For example, the first URL's segments map to the following commands:

/users maps to users
/{id | userPrincipalName} maps to --user-id (more on this below)
/messages maps to messages
/{id} maps to --message-id

Putting that all together, the equivalent commands would be users messages --user-id <user-id> --message-id <message-id>.

Accessing an item in a collection

URL segments in an API that use a plural noun indicate a collection. When an API acts on a specific item in that collection, the URL will contain a segment with an ID. In the previous example, the segments /users/{id | userPrincipalName} combine to access a specific user in the collection of users. These "ID segments" are represented in the Microsoft Graph CLI by a required ID option, which is named like --<name of resource>-id. These options appear after the action command. Use the --help option to see required options for a given command.

Action commands

For basic REST operations, the verb is determined by the HTTP method used for the API.

HTTP method	Command verb	Example
GET (single item)	`get`	`mgc me get` API reference
GET (collection)	`list`	`mgc users list` API reference
POST	`create`	`mgc me messages create` API reference
PUT	`put`	`mgc drives items content put` API reference
PATCH	`patch`	`mgc me events patch` API reference
DELETE	`delete`	`mgc drives items delete` API reference

Consider the get message API example from the previous section. The path to the resource is represented by users messages, and the HTTP method for this API is GET, returning a single item. That means the resulting command for this API is mgc users messages get --user-id <user-id> --message-id <message-id>.

Listing parameters

After you've found the right command, you can examine all the available parameters by using the --help option. For example, the following command lists all the available parameters for the mgc users messages get command.

mgc users messages get --help

Finding available commands

Sometimes just knowing the naming conventions isn't enough to guess the right command. In this case, you can use the --help option iteratively to search the available commands in the CLI. For example, mgc --help returns the full list of available commands that are valid as the first command in the sequence. You can choose one of the available commands, then add it to the previous command to find the next level of commands.

Example

$ mgc --help
Description:
  Microsoft Graph CLI

Usage:
  mgc [command] [options] [[--] <additional arguments>...]]

Options:
  -?, -h, --help  Show help and usage information
  --version       Show version information

Commands:
  admin
  agreement-acceptances
  agreements
  app-catalogs
  applications
  ...

$ mgc applications --help
Description:
  Provides operations to manage the collection of application entities.

Usage:
  mgc applications [command] [options]

Options:
  -?, -h, --help  Show help and usage information

Commands:
  add-key                             Provides operations to call the addKey method.
  add-password                        Provides operations to call the addPassword method.
  app-management-policies             Provides operations to manage the appManagementPolicies property of the
                                      microsoft.graph.application entity.
  check-member-groups                 Provides operations to call the checkMemberGroups method.
  ...

Share via