# Configuration file

## Overview

The Frontitude CLI uses a local configuration file called `frontituderc.json` to determine which text sources to pull from your Frontitude workspace and where to write the output.

> **Note:** This file is managed by the Frontitude CLI. While you can edit it manually, it's recommended to run `frontitude init`, or `frontitude source set` if you’ve already completed `init`, to updated it.

## File location

`frontituderc.json` is created at the root of your project directory. It is safe — and recommended — to commit this file to version control so that your team shares the same CLI configuration.

## Properties

| Property       | Type      | Required | Description                                        |
| -------------- | --------- | -------- | -------------------------------------------------- |
| `filePath`     | `string`  | Yes      | Relative path to the output strings file.          |
| `library`      | `boolean` | No       | Whether to include texts from the Copy Library.    |
| `projects`     | `array`   | No       | Frontitude projects to pull texts from.            |
| `folders`      | `array`   | No       | Frontitude workspace folders to pull texts from.   |
| `xliffVersion` | `string`  | No       | XLIFF version when using `.xlf` / `.xliff` output. |

> At least one text source (`library`, `projects`, or `folders`) must be configured for `frontitude pull` to work.

#### `filePath`

**Type:** `string`

The relative path where the CLI writes the pulled texts (e.g. `./strings.json`). The file extension determines the output format:

| Extension  | Format        |
| ---------- | ------------- |
| `.json`    | JSON          |
| `.xml`     | Android XML   |
| `.xlf`     | XLIFF         |
| `.xliff`   | XLIFF         |
| `.strings` | Apple Strings |

**Default:** `./strings.json`

#### `library`

**Type:** `boolean`

Set to `true` to include texts from your workspace's Copy Library as a source. When `false` or omitted, the Copy Library is not included.

#### `projects`

**Type:** `Array<{ name: string, id: string }>`

A list of Frontitude projects to pull texts from. Each entry contains:

* `name` — The display name of the project. Stored for readability so you can identify entries without looking up UUIDs. Not sent to the API.
* `id` — The unique project identifier used by the CLI to fetch texts.

These values are populated automatically by `frontitude init` or `frontitude source set` — you should not need to look up or edit IDs manually. If a project is renamed in Frontitude, the `name` in the config will be stale until you re-run `frontitude source set`.

#### `folders`

**Type:** `Array<{ name: string, id: string }>`

A list of workspace folders to pull texts from. When a folder is selected, all projects inside that folder are included at pull time. Each entry contains:

* `name` — The display name of the folder. Stored for readability only and not sent to the API.
* `id` — The unique folder identifier used by the CLI to resolve projects at pull time.

As with projects, if a folder is renamed in Frontitude the `name` here will be stale until you re-run `frontitude source set`.

#### `xliffVersion`

**Type:** `string` — `"1.2"` or `"2.0"`

Only relevant when `filePath` uses a `.xlf` or `.xliff` extension. Specifies which version of the XLIFF standard to use for the output file. Defaults to `"1.2"` if not set.

## Examples

#### Full example

```json
{
  "filePath": "./locales/strings.json",
  "library": true,
  "projects": [
    {
      "name": "Authentication feature",
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  ],
  "folders": [
    {
      "name": "Mobile",
      "id": "79a64273-69c3-40bb-8a6a-5e405981707c"
    }
  ]
}
```

#### Minimal example

```json
{
  "filePath": "./strings.json",
  "library": false,
  "projects": [
    {
      "name": "My Project",
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  ]
}
```

#### XLIFF output

```json
{
  "filePath": "./translations/strings.xlf",
  "xliffVersion": "1.2",
  "library": false,
  "projects": [
    {
      "name": "My Project",
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  ]
}
```

## How it's generated

Running `frontitude init` walks you through an interactive setup:

1. **Select sources:** pick which projects, folders, or the Copy Library to pull texts from.
2. **Set output path:** choose the file path and format for the pulled strings.

The CLI writes your selections to `frontituderc.json`. To update your sources later without re-running the full init flow, use `frontitude source set`.