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

# Configuration

> Setting what text and formats the CLI pulls down

## Overview

The `config.yml` file is the source of truth for a given directory about how the CLI should fetch and store data from Ditto based on the specified properties. It includes information about which Ditto components the CLI should pull text from, the string file formats, and more.

This is the default configuration file that is generated the first time that the CLI is run in a given directory:

```yml theme={null}
sources:
  components:
    enabled: true
format: flat
variants: true
```

## Supported Properties

Listed below are each of the properties that you can specify in your CLI config.

### `sources`

A list of places the CLI should pull text data from. For the CLI to function, at least one source type (`components` or `projects`) is required.

#### `sources.components`

A boolean or configuration object indicating how component data should be pulled from your component library.

The simplest configuration is a boolean, which indicates that all components in your component library should be fetched:

```yml theme={null}
sources:
  components: true
```

You can also pass an object that supports two complementary properties: `root` and `folders`.

* `root` controls behavior for components that are NOT in folders (i.e. that are at the *root* of the component library)
* `folders` controls behavior for components that are ARE in folders

Further examples on how to use the two properties to specify the components fetched:

<AccordionGroup>
  <Accordion title="Only components not in folders">
    If `root` is `true` and `folders` is unspecified, **only components not in folders** will be fetched:

    ```yml theme={null}
    sources:
      components:
        root: true
    ```
  </Accordion>

  <Accordion title="Only components in folders">
    If `root` is `false` and `folders` is unspecified, **only components in any folder** will be fetched:

    ```yml theme={null}
    sources:
      components:
        root: false
    ```
  </Accordion>

  <Accordion title="Only components in specified folders">
    If `root` is unspecified and `folders` contains a list of component folders, **only components in the specified folders** will be fetched:

    ```yml theme={null}
    sources:
      components:
        folders:
          - id: folder-api-id-1
            name: Folder 1
          - id: folder-api-id-2
            name: Folder 2
    ```
  </Accordion>

  <Accordion title="Only components in specified folders and not in a folder">
    If `root` is `true` and `folders` contains a list of component folders, **non-folder components and components in the specified folders** will be fetched:

    ```yml theme={null}
    sources:
      components:
        root: true
        folders:
          - id: folder-api-id-1
            name: Folder 1
          - id: folder-api-id-2
            name: Folder 2
    ```
  </Accordion>

  <Accordion title="Only components not in folders with a given status">
    `root` can also be specified as a configuration object with a `status` property to indicate that non-folder components should be fetched that have the indicated status:

    ```yml theme={null}
    sources:
      components:
        root:
          status: WIP
    ```
  </Accordion>
</AccordionGroup>

#### `sources.projects`

A list of projects to pull text from.

```yml theme={null}
sources:
  projects:
    - id: 61b8d26105f8f400e97fdd14
      name: Landing Page Copy
    - id: 606cb89ac55041013d552f8b
      name: User Settings
```

* The `name` property is used for display purposes when referencing a project in the CLI, but does not have to be an exact match with the project name in Ditto.

An `exclude_components` property can be added on a per-project basis to indicate that text items should only be pulled which are not associated with a component:

```yml theme={null}
sources:
  projects:
    - id: 61b8d26105f8f400e97fdd14
      name: Landing Page Copy
      exclude_components: true
```

### `variants`

Enables including variant information when pulling text data for configured sources.

Defaults to `false` if not specified.

```yml theme={null}
variants: true
```

### `format`

The format that text data should be generated in. For examples of each format, see [JSON](/string-formats/json), [iOS Strings](/string-formats/ios), and [Android XML](/string-formats/android) in the String Formats documentation.

Accepted values:

* `structured`
* `flat`
* `nested`
* `android`
* `ios-strings`
* `ios-stringsdict`

Defaults to `flat` if not specified.

```yml theme={null}
format: flat
```

Also accepts a list of values:

```yml theme={null}
format:
  - ios-strings
  - ios-stringsdict
```

You should not specify multiple JSON formats in the same configuration, as they will overwrite one another when writing to disk.

### `status`

If specified, only source data with the indicated status will be fetched. Accepted values:

* `NONE`
* `WIP`
* `REVIEW`
* `FINAL`

If `status` is specified at the top level of the configuration, it will apply to all sources:

```yml theme={null}
status: FINAL
sources:
  components: true
  projects:
    - id: project-1
      name: Project 1
```

`status` can also be specified at the level of individual sources:

```yml theme={null}
sources:
  components:
    root:
      status: REVIEW
    folders:
      - id: folder-api-id-1
        name: Folder 1
        status: NONE
  projects:
    - id: project-1
      name: Project 1
      status: WIP
```

If both are specified, a source-level `status` overrides a top-level `status`.

More information about Ditto statuses can be found [here](https://dittov3.notion.site/Tips-for-cross-team-collaboration-256cc8865c7a8041a922f2d3838c61ec).

### `richText`

If defined with the `flat` format, output values will be HTML strings (rich text) for each piece of source data.

If defined with the `structured` format, output data will include a `rich_text` property that is an HTML string (rich text) for each piece of source data.

You can read more about Ditto's rich text feature [here](https://dittov3.notion.site/Rich-Text-Formatting-in-Ditto-256cc8865c7a808b9837c1bfb7728dba).

```yml theme={null}
richText: true
```

### `iosLocales`

A property that maps [variant](https://dittov3.notion.site/Variants-256cc8865c7a80e38671e6f9206001af) IDs in Ditto to [iOS locale IDs](https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPInternational/LanguageandLocaleIDs/LanguageandLocaleIDs.html), intended to simplify the process of integrating Ditto with an iOS project.

This property should only be defined in conjunction with one or both of the `ios-strings` or `ios-stringsdict` formats.

When this property is defined, iOS string files written to disk by the CLI are grouped into `lproj` localization bundles, and a `Ditto.swift` driver file is generated.

```yml theme={null}
iosLocales:
  - base: en
  - spanish: es
```

The `base` property is required, and should map to the locale ID corresponding to the default language of your iOS project.

See [iOS format-specific files](/cli-reference/files#ios) for more information.

### `disableJsDriver`

A boolean property that disables the generation of the `index.js` and `index.d.ts` driver files when working with JSON formats.

```yml theme={null}
disableJsDriver: true
```

## Full Configuration Example

```yml theme={null}
sources:
  components:
    root: true
    folders:
      - id: onboarding
        name: Onboarding
      - id: onboarding-2
        name: Onboarding 2
        status: WIP
  projects:
    - name: Landing Page Copy
      id: 61b8d26105f8f400e97fdd14
    - name: User Settings
      id: 606cb89ac55041013d552f8b
      status: WIP
variants: true
format: structured
status: FINAL
richText: false
disableJsDriver: false
```