> ## Documentation Index
> Fetch the complete documentation index at: https://lightdash-docs-many-to-many.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# lightdash.config.yml reference

> The lightdash.config.yml file allows you to configure project-wide settings for your Lightdash project, including spotlight and parameters.

## What is lightdash.config.yml?

The `lightdash.config.yml` file is an **optional** configuration file that allows you to define project-wide settings for your Lightdash project. Think of it as a way to customize and enhance your Lightdash experience beyond the basic setup.

<Warning>
  `lightdash.config.yml` is **not supported** when your project is connected directly to dbt Cloud.

  This file only works with projects that use direct git connections or deploy with the CLI (either from local dbt projects and/or continuous deployment).
</Warning>

## Do I need this file?

You **don't need** `lightdash.config.yml` to get started with Lightdash! This file is for users who want to:

* **Organize metrics in [Spotlight](/guides/metrics-catalog)** with custom categories and visibility settings
* **Create parameters** that users can change to modify data across multiple charts and dashboards

If you're just getting started with Lightdash, you can skip this file and come back to it later when you want these advanced features.

## Getting started

Before creating a `lightdash.config.yml` file, make sure you have:

1. ✅ A working Lightdash project (completed the [getting started guide](/get-started/setup-lightdash/intro))
2. ✅ A local dbt project (not connected to dbt Cloud)
3. ✅ The [Lightdash CLI](/get-started/setup-lightdash/get-project-lightdash-ready#step-1-install-the-lightdash-cli-tool) installed and configured

<Steps>
  <Step title="Create the file">
    Create a new file called `lightdash.config.yml` in the **root directory of your dbt project** - this is the same folder where your `dbt_project.yml` file is located.

    ```bash
    # Navigate to your dbt project directory
    cd /path/to/your/dbt/project

    # Create the config file
    touch lightdash.config.yml
    ```
  </Step>

  <Step title="Add your first configuration">
    Start with a simple configuration. Here's a basic example that sets up Spotlight categories:

    ```yaml
    # Basic lightdash.config.yml example
    spotlight:
      default_visibility: "show"
      categories:
        finance:
          label: "Finance"
          color: "green"
        marketing:
          label: "Marketing" 
          color: "blue"
    ```
  </Step>

  <Step title="Deploy your changes">
    After creating or updating your `lightdash.config.yml` file, deploy the changes to your Lightdash project:

    ```bash
    lightdash deploy
    ```

    That's it! Your configuration is now active in your Lightdash project.
  </Step>
</Steps>

## Configuration options

The `lightdash.config.yml` file supports the following top-level configuration options:

```yaml
# Configuration for project-wide spotlight settings
spotlight:
  # ...

# Configuration for project-wide parameters
parameters:
  # ...
```

## Spotlight configuration

The `spotlight` section allows you to configure project-wide spotlight settings. This section is required in the lightdash.config.yml file.

```yaml
spotlight:
  default_visibility: "show"
  categories:
    finance:
      label: "Finance"
      color: "green"
    user_engagement:
      label: "User Engagement"
      color: "blue"
```

| Property             | Required | Value       | Description                                                                                 |
| :------------------- | :------- | :---------- | :------------------------------------------------------------------------------------------ |
| `default_visibility` | No       | string enum | The default visibility of spotlight metrics. Defaults to `show`, can also be set to `hide`. |
| `categories`         | No       | Object      | Define the categories that can be used in Spotlight on your model yml files.                |

Each category in the `categories` object requires the following properties:

| Property | Required | Value       | Description                                                                                                                                                         |
| :------- | :------- | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `label`  | Yes      | string      | The label of the category as it will be displayed in Spotlight.                                                                                                     |
| `color`  | No       | string enum | The color of the category. If not provided, it will be set to gray. Allowed values: `gray`, `violet`, `red`, `orange`, `green`, `blue`, `indigo`, `pink`, `yellow`. |

## Parameters configuration

The `parameters` section allows you to define project-wide parameters that can be referenced in various parts of your Lightdash project.

```yaml
parameters:
  region:
    label: "Region"
    description: "Filter data by region"
    options:
      - "EMEA"
      - "AMER"
      - "APAC"
    default: ["EMEA", "AMER"]
    multiple: true
  department:
    label: "Department"
    description: "Filter data by department"
    options_from_dimension:
      model: "employees"
      dimension: "department"
```

Each parameter is defined as a key-value pair where the key is the parameter name (must be alphanumeric with underscores or hyphens) and the value is an object with the following properties:

| Property                 | Required | Value                      | Description                                                                                                |
| :----------------------- | :------- | :------------------------- | :--------------------------------------------------------------------------------------------------------- |
| `label`                  | Yes      | string                     | A user-friendly label for the parameter as it will be displayed in the UI.                                 |
| `description`            | No       | string                     | A description of the parameter.                                                                            |
| `options`                | No       | Array of strings           | A list of possible values for the parameter.                                                               |
| `default`                | No       | string or Array of strings | The default value(s) for the parameter.                                                                    |
| `multiple`               | No       | boolean                    | Whether the parameter input will be a multi-select.                                                        |
| `allow_custom_values`    | No       | boolean                    | Whether users can input custom values beyond predefined options.                                           |
| `options_from_dimension` | No       | Object                     | Get parameter options from a dimension in a model. Requires `model` and `dimension` arguments (see below). |

If using `options_from_dimension`, the object requires the following properties:

| Property    | Required | Value  | Description                         |
| :---------- | :------- | :----- | :---------------------------------- |
| `model`     | Yes      | string | The model containing the dimension. |
| `dimension` | Yes      | string | The dimension to get options from.  |

### Using parameters in your project

Parameters defined in the `lightdash.config.yml` file can be referenced in various parts of your Lightdash project using the syntax `${lightdash.parameters.parameter_name}` or the shorter alias `${ld.parameters.parameter_name}`.

For example, to reference a parameter named `region`:

```yaml
${lightdash.parameters.region}
```

Or using the shorter alias:

```yaml
${ld.parameters.region}
```

See the [Parameters guide](/guides/using-parameters) for more information on how to use parameters.