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

# Configu Interface Configuration File

> The `.configu` file is an optional configuration file used by the various Configu interfaces to customize its behavior. The file should be named `.configu` regardless of the format used: JSON or YAML.

## Location

Configu interfaces recursively search for the `.configu` file starting from the current working directory and continuing up to the user's home directory. Once it finds a `.configu` file, it uses it in conjunction with the locally stored `.configu` file in the user's home directory (`$HOME/.configu/.configu`) and stops searching.

Alternatively, you may provide an explicit `.configu` file by passing a path as an environment variable via `CONFIGU_CONFIG` or `CONFIGU_CONFIGURATION`.

## Format

The `.configu` file can be written in one of the following formats: `YAML` or `JSON`. The file should be named `.configu` regardless of the format used.

## \$schema

include the `$schema` property at the beginning of the file to specify the `Cfgu` version to communicate to other readers and tooling which specification version is intended.
Also, most modern editors will use this property to provide IntelliSense and validation for the `Cfgu` file.

<CodeGroup>
  ```yaml YAML theme={null}
  $schema: https://files.configu.com/schema/.configu.json
  ```

  ```json JSON theme={null}
  {
    "$schema": "https://files.configu.com/schema/.configu.json"
  }
  ```

  ```yaml vscode-yaml theme={null}
  # yaml-language-server: $schema=https://files.configu.com/schema/.configu.json
  ```
</CodeGroup>

## Properties

### stores

The `.configu` file allows you to save `ConfigStore` configurations as friendly names, which can be later used as values for the `--store` flag in all the commands.

To define a `ConfigStore`, add a new key-value pair to the `stores` section of the `.configu` file, where the key represents the friendly name, and the value is an object with the `type` and `configuration` properties. The `type` property represents the store type, and the `configuration` property contains the specific configuration options for the store.

You can activate backup for a specific store by adding the `backup` property to the store configuration object and set it to `true`.

If you want to mark a `ConfigStore` as your default store whenever you choose to omit a `ConfigStore` as an input when performing actions with Configu's high-level interfaces, add the `default` property to a store configuration object and set it to `true`. If your `.configu` file only has a single store, it is automatically behaves as your default store.

For detailed information about the available store options, please refer to the relevant store on the [integrations section](/integrations/overview#configstore).

### backup

The `.configu` file allows you to define the backup file path for the Configu CLI. The backup is used to store the results of the `configu eval` command to provide failsafe and faster access to the results.

To define the backup configuration, add a new key-value pair to the `.configu` file, where the key is `backup`, and the value is path to the backup file.

By default, the backup file is stored in the os cache directory as follows:

* macOS: `~/Library/Caches/configu/config.sqlite`
* Unix: `~/.cache/configu/config.sqlite`
* Windows: `%LOCALAPPDATA%\configu\config.sqlite`

### schemas

The `.configu` file allows you to save `ConfigSchema` paths as friendly names, which can be later used as values for the `--schema` flag in all the commands.

To define a custom script, add a new key-value pair to the `schemas` section of the `.configu` file, where the key represents the friendly name, and the value is the schema absolute or relative path.

### scripts

The `.configu` file allows you to save `Configu CLI` snippets as friendly names, which can be later used as values for the `--script` flag in the `configu run --script <label>` command.

To define a custom script, add a new key-value pair to the `scripts` section of the `.configu` file, where the key represents the friendly name, and the value is the script content. The script content should consist of `Configu CLI` commands or a pipe of commands.

<Tip>
  The `.configu` configuration file provides a way to customize the behavior of the Configu CLI. By defining custom
  stores and scripts in this file, you can easily reference them in CLI commands, making it more convenient to manage
  and collaborate on software configurations.

  <br />

  Remember that the `.configu` file is optional, and if present, it will be automatically discovered by the CLI during
  its recursive search process.
</Tip>

## Example

<CodeGroup>
  ```yaml YAML theme={null}
  $schema: https://files.configu.com/schema/.configu.json
  stores:
    store1:
      backup: true
      type: storeType1
      configuration:
        option1: value1
        option2: value2
    store2:
      type: storeType2
      configuration:
        option3: value3
        option4: value4
  backup: /path/to/db.sqlite
  schemas:
    schema1: ../path/to/schema1.json
    schema2: /path/to/schema2.json
  scripts:
    script1: 'configu command1 --option1 value1'
    script2: 'configu command2 --option2 value2 | configu command3'
  ```

  ```json JSON theme={null}
  {
    "$schema": "https://files.configu.com/schema/.configu.json",
    "stores": {
      "store1": {
        "backup": true,
        "type": "storeType1",
        "configuration": {
          "option1": "value1",
          "option2": "value2"
        }
      },
      "store2": {
        "type": "storeType2",
        "configuration": {
          "option3": "value3",
          "option4": "value4"
        }
      }
    },
    "backup": "/path/to/db.sqlite",
    "schemas": {
      "schema1": "../path/to/schema1.json",
      "schema2": "/path/to/schema2.json"
    },
    "scripts": {
      "script1": "configu command1 --option1 value1",
      "script2": "configu command2 --option2 value2 | configu command3"
    }
  }
  ```
</CodeGroup>

## Environment Variables

The `.configu` file allows you to use environment variables in its different sections. This comes in handy for `store configuration options` or `scripts` when you want to avoid explicitly writing sensitive authentication credentials etc. and you want to inject them from the outside before running Configu. To use an environment variable, you can utilize [`ConfigExpression`](/introduction/concepts#configexpression) as such:

```yaml theme={null}
$schema: https://files.configu.com/schema/.configu.json
stores:
  store1:
    type: 'storeType1'
    configuration:
      option1: 'value1'
      password: '{{PASSWORD}}'
```

You can then pass the environment variable to the CLI using any method of setting environment variables to replace the `ConfigExpression` with the environment variable value. Here is an example of passing an environment variable to the CLI by using an operating system specific prefix:

<CodeGroup>
  ```bash Linux/MacOS theme={null}
  PASSWORD=password configu eval --store store1 --set <value> --schema <value> [-c <value>]
  ```

  ```bash Windows theme={null}
  set PASSWORD=password && configu eval --store store1 --set <value> --schema <value> [-c <value>]
  ```
</CodeGroup>