Edit

Using the Kiota tool

  • Article

Note

For information on installing Kiota, see Get started with Kiota.

Configuration environment variables

The table below provides the list of environment variables that can be used to configure the experience for the Kiota CLI.

Environment variable name Description Default value
KIOTA_CONSOLE_COLORS_ENABLED Enable/disable output colorization true
KIOTA_CONSOLE_COLORS_SWAP Enable/disable inverting the color scheme of the output false
KIOTA_TUTORIAL_ENABLED Enable/disable displaying additional hints after commands execution true

Commands

Kiota offers the following commands to help you build your API client:

  • search: search for APIs and their description from various registries.
  • download: download an API description.
  • show: show the API paths tree for an API description.
  • generate: generate a client for any API from its description.
  • update: update existing clients from previous generations.
  • info: show languages and runtime dependencies information.
  • login: logs in to private API descriptions repositories.
  • logout: logs out from private API description repositories.

Kiota search accepts the following parameters while searching for APIs and their descriptions.

kiota search <searchTerm>
      [(--clear-cache | --cc)]
      [(--log-level | --ll) <level>]
      [(--version | -v) <version>]

Note

The search command requires access to internet and cannot be used offline.

Mandatory arguments

Search term

The term to use during the search for APIs and their descriptions.

If multiple results are found, kiota will present a table with the different results.

The following example returns multiple results.

kiota search github

Which will return the following display.

Key                                  Title               Description            Versions
apisguru::github.com                 GitHub v3 REST API  GitHub's v3 REST API.  1.1.4
apisguru::github.com:api.github.com  GitHub v3 REST API  GitHub's v3 REST API.  1.1.4
apisguru::github.com:ghes-2.18       GitHub v3 REST API  GitHub's v3 REST API.  1.1.4
apisguru::github.com:ghes-2.19       GitHub v3 REST API  GitHub's v3 REST API.  1.1.4
apisguru::github.com:ghes-2.20       GitHub v3 REST API  GitHub's v3 REST API.  1.1.4
apisguru::github.com:ghes-2.21       GitHub v3 REST API  GitHub's v3 REST API.  1.1.4
apisguru::github.com:ghes-2.22       GitHub v3 REST API  GitHub's v3 REST API.  1.1.4
apisguru::github.com:ghes-3.0        GitHub v3 REST API  GitHub's v3 REST API.  1.1.4
apisguru::github.com:ghes-3.1        GitHub v3 REST API  GitHub's v3 REST API.  1.1.4

If the search term is an exact match with one of the results' key, the search command will display a detailed view of the result.

kiota search apisguru::github.com

Key: apisguru::github.com
Title: GitHub v3 REST API
Description: GitHub's v3 REST API.
Service: https://support.github.com/contact
OpenAPI: https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json

Optional parameters

The search command accepts optional parameters commonly available on the other commands:

Description download

Kiota download downloads API descriptions to a local from a registry and accepts the following parameters.

It is not mandatory to download the description locally for the purpose of generation as the generation command can download the description directly. However, having a local copy of the description can be helpful to inspect it, determine which API paths are needed, and come up with the include/exclude filters for generation.

Note

The download command requires access to internet and cannot be used offline.

kiota download <searchTerm>
      [--clear-cache | --cc]
      [--clean-output | --co]
      [(--log-level | --ll) <level>]
      [(--version | -v) <version>]
      [(--output | -o) <path>]

Mandatory arguments

Search term

The search term to use to locate the description. The description will be downloaded only if an exact key match occurs. You can use the search command to find the key of the API description before downloading it.

kiota download apisguru::github.com

Optional parameters

The download command accepts optional parameters commonly available on the other commands:

Description show

Kiota show accepts the following parameters when displaying the API paths tree for a description.

kiota show [(--openapi | -d) <path>]
      [(--log-level | --ll) <level>]
      [--clear-cache | --cc]
      [(--version | -v) <version>]
      [(--search-key | -k) <searchKey>]
      [(--max-depth | --m-d) <maximumDepth>]
      [(--include-path | -i) <glob pattern>]
      [(--exclude-path | -e) <glob pattern>]

Example

The following command with the provided options will display the following result.

kiota show -d https://raw.githubusercontent.com/microsoftgraph/msgraph-sdk-powershell/dev/openApiDocs/v1.0/Mail.yml -i **/messages

/
 └─users
    └─{user-id}
       ├─mailFolders
       │  └─{mailFolder-id}
       │     ├─childFolders
       │     └─messages
       └─messages

Optional Parameters

The show command accepts optional parameters commonly available on the other commands:

Client generation

Kiota generate accepts the following parameters during the generation.

kiota generate (--openapi | -d) <path>
      (--language | -l) <language>
      [(--output | -o) <path>]
      [(--class-name | -c) <name>]
      [(--namespace-name | -n) <name>]
      [(--log-level | --ll) <level>]
      [--backing-store | -b]
      [--exclude-backward-compatible | --ebc]
      [--additional-data | --ad]
      [(--serializer | -s) <classes>]
      [(--deserializer | --ds) <classes>]
      [--clean-output | --co]
      [--clear-cache | --cc]
      [(--structured-mime-types | -m) <mime-types>]
      [(--include-path | -i) <glob pattern>]
      [(--exclude-path | -e) <glob pattern>]
      [(--disable-validation-rules | --dvr) <rule name>]

Note

The output directory will also contain a kiota-lock.json lock file in addition to client sources. This file contains all the generation parameters for future reference as well as a hash from the description. On subsequent generations, including updates, the generation will be skipped if the description and the parameters have not changed and if clean-output is false. The lock file is meant to be committed to the source control with the generated sources.

Mandatory parameters

Optional parameters

The generate command accepts optional parameters commonly available on the other commands:

--backing-store (-b)

Enables backing store for models. Defaults to false.

kiota generate --backing-store

--exclude-backward-compatible (--ebc)

Whether to exclude the code generated only for backward compatibility reasons or not. Defaults to false.

To maintain compatibility with applications that depends on generated clients, kiota emits additional code marked as obsolete. New clients do not need this additional backward compatible code. The code marked as obsolete will be removed in the next major version of kiota. Use this option to omit emitting the backward compatible code when generating a new client, or when the application using the existing client being refreshed does not depend on backward compatible code.

kiota generate --exclude-backward-compatible

--additional-data (--ad)

Will include the 'AdditionalData' property for generated models. Defaults to true.

kiota generate --additional-data false

--class-name (-c)

The class name to use for the core client class. Defaults to ApiClient.

Accepted values

The provided name MUST be a valid class name for the target language.

kiota generate --class-name MyApiClient

--deserializer (--ds)

The fully qualified class names for deserializers.

These values are used in the client class to initialize the deserialization providers.

Since version 1.11 this parameter also supports a none key to generate a client with no deserialization providers in order to enable better portability.

Defaults to the following values.

Language Default deserializers
C# Microsoft.Kiota.Serialization.Json.JsonParseNodeFactory, Microsoft.Kiota.Serialization.Json.JsonParseNodeFactory, Microsoft.Kiota.Serialization.Text.TextParseNodeFactory
Go github.com/microsoft/kiota-serialization-form-go/FormParseNodeFactory, github.com/microsoft/kiota-serialization-json-go/JsonParseNodeFactory, github.com/microsoft/kiota-serialization-text-go/TextParseNodeFactory
Java com.microsoft.kiota.serialization.TextParseNodeFactory, com.microsoft.kiota.serialization.JsonParseNodeFactory, com.microsoft.kiota.serialization.TextParseNodeFactory
PHP Microsoft\Kiota\Serialization\Json\JsonParseNodeFactory, Microsoft\Kiota\Serialization\Text\TextParseNodeFactory
Python kiota_serialization_json.json_parse_node_factory.JsonParseNodeFactory, kiota_serialization_text.text_parse_node_factory.TextParseNodeFactory
Ruby microsoft_kiota_serialization/json_parse_node_factory
TypeScript @microsoft/kiota-serialization-form.FormParseNodeFactory, @microsoft/kiota-serialization-json.JsonParseNodeFactory, @microsoft/kiota-serialization-text.TextParseNodeFactory
Accepted values

One or more module names that implements IParseNodeFactory.

kiota generate --deserializer Contoso.Json.CustomDeserializer

--disable-validation-rules (--dvr)

The name of the OpenAPI description validation rule to disable. Or all to disable all validation rules including the rules defined in OpenAPI.net.

Kiota runs a set of validation rules before generating the client to ensure the description contains accurate information to build great client experience.

Accepted values

Rules:

  • DivergentResponseSchema: returns a warning if an operation defines multiple different successful response schemas. (200, 201, 202, 203)
  • GetWithBody: returns a warning if a GET request has a body defined.
  • InconsistentTypeFormat: returns a warning if an inconsistent type/format pair is defined. (e.g. type: string, format: int32)
  • KnownAndNotSupportedFormats: returns a warning if a known formats is not supported for generation. (e.g. email, uri, ...)
  • MissingDiscriminator: returns a warning if an anyOf or oneOf schema is used without a discriminator property name.
  • MultipleServerEntries: returns a warning if multiple servers are defined.
  • NoContentWithBody: returns a warning if a response schema is defined for a 204 response.
  • NoServerEntry: returns a warning if no servers are defined.
  • UrlFormEncodedComplex: returns a warning if a response of type uri form encoded has a schema that contains complex properties.
kiota generate --disable-validation-rules NoServerEntry

--namespace-name (-n)

The namespace to use for the core client class specified with the --class-name option. Defaults to ApiSdk.

Accepted values

The provided name MUST be a valid module or namespace name for the target language.

kiota generate --namespace-name MyAppNamespace.Clients
Accepted values

A valid URI to an OpenAPI description in the local filesystem or hosted on an HTTPS server.

kiota generate --openapi https://contoso.com/api/openapi.yml

--serializer (-s)

The fully qualified class names for serializers.

These values are used in the client class to initialize the serialization providers.

Since version 1.11 this parameter also supports a none key to generate a client with no serialization providers in order to enable better portability.

Defaults to the following values.

Language Default deserializer
C# Microsoft.Kiota.Serialization.Form.FormSerializationWriterFactory, Microsoft.Kiota.Serialization.Json.JsonSerializationWriterFactory, Microsoft.Kiota.Serialization.Text.TextSerializationWriterFactory, Microsoft.Kiota.Serialization.Multipart.MultipartSerializationWriterFactory
Go github.com/microsoft/kiota-serialization-form-go/FormSerializationWriterFactory, github.com/microsoft/kiota-serialization-json-go/JsonSerializationWriterFactory, github.com/microsoft/kiota-serialization-text-go/TextSerializationWriterFactory, github.com/microsoft/kiota-serialization-multipart-go/MultipartSerializationWriterFactory
Java com.microsoft.kiota.serialization.FormSerializationWriterFactory, com.microsoft.kiota.serialization.JsonSerializationWriterFactory, com.microsoft.kiota.serialization.TextSerializationWriterFactory, com.microsoft.kiota.serialization.MultipartSerializationWriterFactory
PHP Microsoft\Kiota\Serialization\Json\JsonSerializationWriterFactory, Microsoft\Kiota\Serialization\Text\TextSerializationWriterFactory
Python kiota_serialization_json.json_serialization_writer_factory.JsonSerializationWriterFactory, kiota_serialization_text.text_serialization_writer_factory.TextSerializationWriterFactory
Ruby microsoft_kiota_serialization/json_serialization_writer_factory
TypeScript @microsoft/kiota-serialization-form.FormSerializationWriterFactory, @microsoft/kiota-serialization-json.JsonSerializationWriterFactory, @microsoft/kiota-serialization-text.TextSerializationWriterFactory, @microsoft/kiota-serialization-multipart.MultipartSerializationWriterFactory
Accepted values

One or more module names that implements ISerializationWriterFactory.

kiota generate --serializer Contoso.Json.CustomSerializer

--structured-mime-types (-m)

The MIME types to use for structured data model generation with their preference weight. Any type without a preference will have its preference defaulted to 1. Accepts multiple values. The notation style and the preference weight logic follow the convention defined in RFC 9110.

Default values :

  • application/json;q=1
  • application/x-www-form-urlencoded;q=0.2
  • multipart/form-data;q=0.1
  • text/plain;q=0.9

Note

Only request body types or response types with a defined schema will generate models, other entries will default back to stream/byte array.

Accepted values

Any valid MIME type which will match a request body type or a response type in the OpenAPI description.

Examples

kiota generate --structured-mime-types application/json

Language information

Kiota info accepts the following parameters when displaying language information like their maturity level or dependencies needed at runtime.

kiota info [(--openapi | -d) <path>]
      [(--language | -l) <language>]
      [(--log-level | --ll) <level>]
      [--clear-cache | --cc]
      [(--version | -v) <version>]
      [(--search-key | -k) <searchKey>]

Example - global

The following command with the provided options will display the following result.

kiota info

Language    Maturity Level
CLI         Preview
CSharp      Stable
Go          Stable
Java        Preview
PHP         Stable
Python      Stable
Ruby        Experimental
Swift       Experimental
TypeScript  Experimental

Example - with language

The following command with the provided options will display the following result.

kiota info -l CSharp

The language CSharp is currently in Stable maturity level.
After generating code for this language, you need to install the following packages:
dotnet add package Microsoft.Kiota.Abstractions --version 1.6.1
dotnet add package Microsoft.Kiota.Http.HttpClientLibrary --version 1.3.0
dotnet add package Microsoft.Kiota.Serialization.Form --version 1.1.0
dotnet add package Microsoft.Kiota.Serialization.Json --version 1.1.1
dotnet add package Microsoft.Kiota.Authentication.Azure --version 1.1.0
dotnet add package Microsoft.Kiota.Serialization.Text --version 1.1.0
dotnet add package Microsoft.Kiota.Serialization.Multipart --version 1.1.0

Using the --json optional parameter render the output in a machine parsable format:

kiota info -l CSharp --json

{
  "maturityLevel": "Stable",
  "dependencyInstallCommand": "dotnet add package {0} --version {1}",
  "dependencies": [
    {
      "name": "Microsoft.Kiota.Abstractions",
      "version": "1.6.1"
    },
    {
      "name": "Microsoft.Kiota.Http.HttpClientLibrary",
      "version": "1.2.0"
    },
    {
      "name": "Microsoft.Kiota.Serialization.Form",
      "version": "1.1.0"
    },
    {
      "name": "Microsoft.Kiota.Serialization.Json",
      "version": "1.1.1"
    },
    {
      "name": "Microsoft.Kiota.Authentication.Azure",
      "version": "1.1.0"
    },
    {
      "name": "Microsoft.Kiota.Serialization.Text",
      "version": "1.1.0"
    },
    {
      "name": "Microsoft.Kiota.Serialization.Multipart",
      "version": "1.1.0"
    }
  ],
  "clientClassName": "",
  "clientNamespaceName": ""
}

Optional Parameters

The info command accepts optional parameters commonly available on the other commands:

Client update

Kiota update accepts the following parameters during the update of existing clients. This command will search for lock files in the output directory and all its subdirectories and trigger generations to refresh the existing clients using settings from the lock files.

kiota update [(--output | -o) <path>]
      [(--log-level | --ll) <level>]
      [--clean-output | --co]
      [--clear-cache | --cc]

Optional parameters

The generate command accepts optional parameters commonly available on the other commands:

Login

Use kiota login to sign in to private repositories and search for/display/generate clients for private API descriptions. This command makes sub-commands available to sign in to specific authentication providers.

Login to GitHub

kiota login github <device|pat>
      [(--log-level | --ll) <level>]
      [(--pat) <patValue>]

Use kiota login github device to sign in using a device code, you will be prompted to sign-in using a web browser.

Use kiota login github pat --pat patValue to sign in using a Personal Access Token you previously generated. You can use both classic PATs or granular PATs (beta). Classic PATs need the repo permission and to be granted access to the target organizations. Granular PATs need a read-only permission for the contents scope under the repository category and they need to be consented for all private repositories or selected private repositories.

Note

For more information about adding API descriptions to the GitHub index, see Adding an API to search.

Optional parameters

The generate command accepts optional parameters commonly available on the other commands:

Logout

Use kiota logout to logout from a private repository containing API descriptions.

kiota logout github
      [(--log-level | --ll) <level>]

Optional parameters

The generate command accepts optional parameters commonly available on the other commands:

Common parameters

The following parameters are available across multiple commands.

--clean-output (--co)

Delete the output directory before generating the client. Defaults to false.

Available for commands: download, generate.

kiota <command name> --clean-output

--clear-cache (--co)

Clears the currently cached file for the command. Defaults to false.

Cached files are stored under %TEMP%/kiota/cache and valid for one (1) hour after the initial download. Kiota caches API descriptions during generation and static index files during search.

kiota <command name> --clear-cache

--exclude-path (-e)

A glob pattern to exclude paths from generation. Accepts multiple values. Defaults to no value which excludes nothing.

kiota <command name> --exclude-path **/users/** --exclude-path **/groups/**

You can also filter specific HTTP methods by appending #METHOD to the pattern, replacing METHOD with the HTTP method to filter. For example, **/users/**#GET.

Tip

An exclude pattern can be used in combination with the include pattern argument. A path item is included when (no include pattern is included OR it matches an include pattern) AND (no exclude pattern is included OR it doesn't match an exclude pattern).

--include-path (-i)

A glob pattern to include paths from generation. Accepts multiple values. Defaults to no value which includes everything.

kiota <command name> --include-path **/users/** --include-path **/groups/**

You can also filter specific HTTP methods by appending #METHOD to the pattern, replacing METHOD with the HTTP method to filter. For example, **/users/**#GET.

Tip

An include pattern can be used in combination with the exclude pattern argument. A path item is included when (no include pattern is included OR it matches an include pattern) AND (no exclude pattern is included OR it doesn't match an exclude pattern).

--openapi (-d)

The location of the OpenAPI description in JSON or YAML format to use to generate the SDK. Accepts a URL or a local path.

Available for commands: info, show, generate.

kiota <command name> --openapi https://description.url/description.yml

--language (-l)

The target language for the generated code files or for the information.

Available for commands: info, generate.

Accepted values

  • csharp
  • go
  • java
  • php
  • python
  • ruby
  • shell
  • swift
  • typescript
kiota <command name> --language java

--log-level (--ll)

The log level to use when logging events to the main output. Defaults to warning.

Available for commands: all.

Accepted values

  • critical
  • debug
  • error
  • information
  • none
  • trace
  • warning
kiota <command name> --log-level information

--output (-o)

The output directory or file path for the generated code files. Defaults to ./output for generate and ./output/result.json for download.

Available for commands: download, generate.

Accepted values

A valid path to a directory (generate) or a file (download).

kiota <command name> --output ./src/client

--search-key (-k)

The search key to use to fetch the Open API description, can be used in combination with the version option. Should not be used in combination with the openapi option. Default empty.

Available for commands: info, show.

kiota <command name> --search-key apisguru::github.com:api.github.com

--version (-v)

Select a specific version of the API description. No default value.

Available for commands: download, search.

kiota <command name> --version beta