# Configuration

Finqu CLI uses a `.env` file to store settings, credentials, and theme connections as `FINQU_`-prefixed environment
variables.

## Configuration File

By default, the CLI looks for `.env` in the current directory. You can override this with:

- The `--config <path>` global option
- The `FINQU_CONFIG` environment variable

## Configuration Structure

### Example Configuration

```env
FINQU_THEME_DIR=/path/to/theme/directory
FINQU_RESOURCE_URL=https://<your-env>.api.myfinqu.com
FINQU_API_VERSION=1.2
FINQU_ACCESS_TOKEN=<oauth_access_token>
FINQU_REFRESH_TOKEN=<oauth_refresh_token>
FINQU_EXPIRES_AT=1784447850458
FINQU_STORE_MERCHANT_ID=6
FINQU_STORE_ID=57704
FINQU_STORE_THEME_ID=870
FINQU_STORE_VERSION_ID=152bd77a7749171803307263acec8028
FINQU_STORE_DOMAIN=example.finqustore.com
```

### Configuration Keys

| Key               | Env Variable              | Description                                               |
| ----------------- | ------------------------- | --------------------------------------------------------- |
| `themeDir`        | `FINQU_THEME_DIR`         | Local directory path for theme files                      |
| `resourceUrl`     | `FINQU_RESOURCE_URL`      | Finqu API base URL (set by `finqu sign-in`)               |
| `apiVersion`      | `FINQU_API_VERSION`       | Finqu API version (optional, default: `1.2`)              |
| `accessToken`     | `FINQU_ACCESS_TOKEN`      | OAuth 2.0 access token (automatically managed)            |
| `refreshToken`    | `FINQU_REFRESH_TOKEN`     | OAuth 2.0 refresh token (automatically managed)           |
| `expiresAt`       | `FINQU_EXPIRES_AT`        | Access token expiration timestamp (automatically managed) |
| `appRealtimeUrl`  | `FINQU_APP_REALTIME_URL`  | Realtime websocket URL used by `finqu app listen`         |
| `storeMerchantId` | `FINQU_STORE_MERCHANT_ID` | Store merchant ID (set by `finqu theme configure`)        |
| `storeId`         | `FINQU_STORE_ID`          | Store ID (set by `finqu theme configure`)                 |
| `storeThemeId`    | `FINQU_STORE_THEME_ID`    | Theme ID (set by `finqu theme configure`)                 |
| `storeVersionId`  | `FINQU_STORE_VERSION_ID`  | Theme version ID (set by `finqu theme configure`)         |
| `storeDomain`     | `FINQU_STORE_DOMAIN`      | Store domain (set by `finqu theme configure`)             |
| `verbose`         | `FINQU_VERBOSE`           | Enable or disable verbose logging                         |

## Environment Variables

All configuration keys listed in the table above can be set as environment variables with a `FINQU_` prefix in screaming
snake case (e.g. `FINQU_THEME_DIR`, `FINQU_RESOURCE_URL`). Both the `.env` file and the process environment are
supported.

The following additional environment variables are also supported:

| Variable                  | Description                                                                   |
| ------------------------- | ----------------------------------------------------------------------------- |
| `FINQU_CONFIG`            | Override the default configuration file path                                  |
| `FINQU_API_CLIENT_ID`     | API Client key to use for authentication (alternative to using `--key`)       |
| `FINQU_API_CLIENT_SECRET` | API Client secret to use for authentication (alternative to using `--secret`) |

These are particularly useful in CI/CD environments where you want to avoid storing credentials in files.

## Configuration Precedence

The CLI resolves configuration values in the following order (highest to lowest priority):

1. **Command-line flags**: `--config`, `--verbose`
2. **Environment variables**: `FINQU_CONFIG`, `FINQU_API_CLIENT_ID`, `FINQU_API_CLIENT_SECRET`, and any
   `FINQU_`-prefixed config key
3. **Configuration file**: Values from `.env` (or the file specified by `--config`)

## Automatic Management

The configuration file is automatically created and updated by CLI commands:

- `finqu sign-in` stores authentication tokens
- `finqu theme configure` stores theme connection details
- Token refresh happens automatically when tokens expire

> **Note:** The `.env` file is automatically created and updated by the CLI commands. You typically don't need to edit
> it manually.

## Migrating from finqu.config.json

If you are upgrading from an older version that used `finqu.config.json`, run the migration command:

```bash
finqu migrate
```

This converts your existing JSON configuration to the new `.env` format. See [`finqu migrate`](#finqu-migrate) for
options.

---

## `finqu migrate`

Convert a legacy `finqu.config.json` configuration file to the new `.env` format.

### Usage

```bash
finqu migrate
```

### Options

| Option                 | Description                                    | Default             |
| ---------------------- | ---------------------------------------------- | ------------------- |
| `--json-config <path>` | Path to the legacy JSON configuration file     | `finqu.config.json` |
| `--output <path>`      | Output path for the generated `.env` file      | `.env`              |
| `--force`              | Overwrite the output file if it already exists | `false`             |

### Migration process

1. Reads the legacy `finqu.config.json` file
2. Extracts settings from the `production` environment (warns about other environments)
3. Flattens nested `store` object into individual keys
4. Writes all values as `FINQU_`-prefixed variables to the `.env` file
5. Preserves any existing non-`FINQU_` keys in the output file