---
title: Redocly CLI configuration
description: Learn how to configure Redocly CLI
redirectFrom:
  - /docs/cli/configuration/configuration-file/
  - /docs/cli/guides/lint/
  - /docs/cli/configuration/lint/
toc:
  maxDepth: 3
---

import { JsonSchema } from '@redocly/developer-portal/ui';
import Schema from './schema.yaml';
import ApiSchema from './api.yaml';
import MockServerSchema from './mockserver.yaml';
import ResolveSchema from './resolve.yaml';
import { StyledContent } from '../../components/styled.elements';

# Redocly configuration file

The Redocly configuration file is used by Redocly CLI and other Redocly apps to control their behavior — from the strictness of the `lint` command, to how Redocly renders your docs.

- Workflows uses it in the API registry to manage your APIs and control advanced features like region and link resolution.
- Workflows and on-premise tools use it to apply your features and theme when building API docs.
- Redocly's VS Code extension uses it for linting criteria, to apply custom settings for live documentation previews, and to identify the path API definition root files.

## Filename, location, and format

The Redocly configuration file must be named either `redocly.yaml` or `.redocly.yaml`.
It must be located in the root of your project directory, and it must be in the YAML format.
If you cloned the `openapi-starter` project, this is already set up for you.

Redocly CLI searches for the configuration file in the working directory.

:::warning

If you have a `redocly.yaml` and a `.redocly.yaml` file  in the same directory, Redocly shows a warning in the output and ask you to choose one file.

:::


## File structure

### Fixed properties
<StyledContent>
  <JsonSchema
    schema={Schema}
    options={{
      schemaExpansionLevel:0,
    }}
  />
</StyledContent>

### Example
```yaml
organization: testing_redocly

extends:
  - recommended

apis:
  core@v2:
    root: ./openapi/openapi.yaml
    rules:
      no-ambiguous-paths: error
  external@v1:
    root: ./openapi/external.yaml
    labels:
      - external
    theme:
      openapi:
        hideLogo: true

theme:
  openapi:
    schemaExpansionLevel: 2
    generateCodeSamples:
      languages:
        - lang: curl
        - lang: Python
```

### `extends` list

Use `extends` to list built-in configurations and other configuration files as the base settings.
If you don't [override this base configuration](#priority-and-overrides), it is used for all APIs specified in your configuration file.

If you don't have a Redocly configuration file, Redocly CLI automatically uses the `recommended` configuration.
To override the default settings, you can either configure different settings for specific rules in the `rules` object, or create your own configuration files and reference them in the `extends` list.


:::warning Important

The previous behavior (automatically defaulting to the `recommended` configuration) was deprecated since `v1.0.0-beta.113`.

The `extends` field has to be explicitly defined in the main configuration file for any extended configuration to apply.

:::


The `extends` list is structured as an array of strings.
It supports the following types of values:

- Built-in configuration name (`minimal` or `recommended`)
- A plugin's registered configuration name
- Path or URL to another Redocly configuration file

When providing values as URLs, they must be publicly accessible.

```yaml
extends:
  - built-in-configuration-name
  - local-plugin-name/configuration-name
  - ./path/to/another/redocly-configuration.yaml
  - https://url-to-remote/redocly.yaml
```


#### Nested configuration

Other configuration files linked in the `extends` list of your main Redocly configuration file may contain their own `extends` list.

Custom plugins can't contain the `extends` list because recursive extension is not supported in that case.

The following examples illustrate configuration nesting with multiple configuration files.

```yaml Main redocly.yaml
extends:
  - custom.yaml
```

```yaml custom.yaml
extends:
  - nested.yaml
rules:
  tags-alphabetical: error
  paths-kebab-case: warn
```

```yaml nested.yaml
rules:
  path-parameters-defined: error
  tag-description: warn
```


#### Priority and overrides

In case of conflict, individual API settings specified in the `apis` object always override settings globally specified.

Redocly CLI applies the `extends` configuration in the order in which items are listed, from top to bottom.
The further down an item appears, the higher its priority.

In case of conflicting settings, content in the `rules` and `decorators` objects always overrides any content in the `extends` list.

In the following example, the `rules` object and another configuration file in the `extends` list configure the same rule (`tags-alphabetical`).
Due to the conflict, priority goes to the inline `rules` over the `extends` list, and the `tags-alphabetical` has a resulting severity level of `error`.


```yaml redocly.yaml
extends:
  - custom.yaml
rules:
  tags-alphabetical: error
  paths-kebab-case: warn
```

```yaml custom.yaml
rules:
  tags-alphabetical: warn
  path-parameters-defined: warn
```


The same approach applies within the `extends` list.
If you have multiple configurations that try to configure the same rule, only the setting from the last configuration in the list applies.

In the following example, Redocly CLI uses the setting for the conflicting `tags-alphabetical` rule from the `testing.yaml` file, because that file is further down in the `extends` list.

This means you can control the priority of configurations by reordering them in the `extends` list, and override all lint configurations (custom and built-in) by specifying individual rule settings in the `rules` object.

```yaml redocly.yaml
extends:
  - custom.yaml
  - testing.yaml
```

```yaml custom.yaml
rules:
  tags-alphabetical: warn
  paths-kebab-case: warn
```

```yaml testing.yaml
rules:
  tags-alphabetical: error
  path-parameters-defined: warn
```

### `plugins` list

Use this list to import local plugins.
If you don't have any custom plugins, omit this list.

To prevent malicious code execution, custom plugins can't be imported from URLs, only from local files.
Find more information on the [Configs in plugins](../resources/custom-plugins.md#configs-in-plugins) page.

- **type**: `array of strings`

#### Examples

```yaml Import a single plugin
plugins:
  - './local-plugin.js'
```

```yaml Import multiple plugins
plugins:
  - './local-plugin.js'
  - './another-local-plugin.js'
```

### `apis` object

The `apis` object is used to configure one or more APIs.
Every API in the object is identified by its name and version in the format `name@version`.
The version is optional, and when not provided, Redocly apps interpret it as `latest` by default.
Every `name@version` combination listed in the object must be unique.

For every API listed in the object, you must provide the path to the OpenAPI definition using the `root` property.

If `rules`, `decorators`, or `preprocessors` aren't defined for an API, root settings are used.
If `rules`, `decorators`, or `preprocessors` are defined for an API, its settings apply together with the root configuration.
If per-API and root settings modify the same properties, per-API settings overrides root settings.


#### Patterned properties

<StyledContent>
  <JsonSchema
    schema={ApiSchema}
    options={{
      schemaExpansionLevel:2,
    }}
  />
</StyledContent>

#### Example
```yaml
apis:
  name@version:
    root: ./openapi/openapi.yaml
    labels:
      - production
    theme:
      openapi: {}
```

:::warning Important

Per-API configurations take priority over global settings.

:::


Some of the Redocly CLI commands, such as the [lint command](../commands/lint.md), use the API names from the `apis` object as shortcuts for referencing API definitions.
You can tell the `lint` command to validate specific API definitions by using their names from the `apis` object, like in the following example:

```shell
redocly lint core@v2
```

On the other hand, if you run the command without specifying any aliases, it applies to all API definitions listed in the `apis` object:

```shell
redocly lint
```

### theme object

The `theme` object configures OpenAPI features, mock server features, and others.

#### mockServer object

You can apply `mockServer` to individual APIs as well as at the root (default) level.
In case of conflict, API takes priority.

The API registry supports [the mock server feature](../../api-registry/guides/mock-server-quickstart.md) and allows project owners to enable it for all branches per API version.
When the mock server is enabled for an API, you can send test requests to it from any API client.

The `mockServer` object is a property of the `theme` object and allows additional configuration of the mock server behavior.
This object is optional.

#### Fixed properties
<StyledContent>
  <JsonSchema
    schema={MockServerSchema}
    options={{
      schemaExpansionLevel:1,
    }}
  />
</StyledContent>


#### openapi object

The `openapi` object is a property of the `theme` object and configures features and theming for API documentation generated from OpenAPI definitions.

If you need to apply different theming and functionality to individual APIs, add the theme `openapi` property to the appropriate API in the `apis` and `theme` object, and use the same options as the global `openapi` object.

Find the full list of supported options on the [Reference docs configuration page](../../api-reference-docs/configuration/functionality.mdx).


### resolve object

Redocly automatically resolves any API registry link or public URL in your API definitions.
If you want to resolve links that are neither API registry links nor publicly accessible, set the `resolve` object in your configuration file.

Redocly CLI supports one `http` header per URL.

#### Fixed properties
<StyledContent>
  <JsonSchema
    schema={ResolveSchema}
    options={{
      schemaExpansionLevel:2,
    }}
  />
</StyledContent>


#### Example

Here is an example for adding header definitions:

```yaml
resolve:
  http:
    headers:
      - matches: https://api.example.com/v2/**
        name: X-API-KEY
        envVariable: SECRET_KEY
      - matches: https://example.com/*/test.yaml
        name: Authorization
        envVariable: SECRET_AUTH
```
The first match takes priority when a URL matches multiple patterns.
Therefore, only the header from the first match is used in the request.