The CLI lets you start and build your application.

# Installation

```yarn
yarn add @commercetools-frontend/mc-scripts
```

```npm
npm --save install @commercetools-frontend/mc-scripts 
```

You could also install the CLI globally, but we recommend local installation instead.

# Commands

## start

This command starts the application in `development` mode. It uses Webpack Dev Server with hot-code reloading, error reporting, and more.

```console
mc-scripts start
```

By default the application starts at `http://localhost:3001`.

## build

This command bundles the application in `production` mode and creates an optimized production build of your application in the `public` folder.

```console
mc-scripts build
```

By default, the `build` command compiles the `index.html`, included in the `public` folder. You can opt-out of the compilation step by using the option `--build-only`. For more information, see [Going to production](https://docs.commercetools.com/merchant-center-customizations/development/going-to-production).

### Options

- `--build-only`: Generates production bundles without compiling the `index.html`. To compile it, run `compile-html`.

## compile-html

This command compiles the `index.html.template` file into an `index.html` file according to the [Custom Application config](https://docs.commercetools.com/merchant-center-customizations/tooling-and-configuration/custom-application-config) or [Custom View config](https://docs.commercetools.com/merchant-center-customizations/tooling-and-configuration/custom-view-config). The production assets are then copied to the `public` folder and are ready to be deployed.

```console
mc-scripts compile-html
```

See [Going to production](https://docs.commercetools.com/merchant-center-customizations/development/going-to-production) for more information.

By default, compiling the `index.html` is implicitly done in the `build` command, unless the option `--build-only` is used. In that case, you need to execute the `compile-html` command separately.

### Options

- `--transformer <path>`: the path to a JavaScript module exporting a function. This can be used as a way to programmatically configure something based on the compiled information, for example, related to your deployment or hosting provider. The function is called with the following signature.

  ```ts
  type TransformerFunctionOptions = {
    // The runtime environment specified within the customization config.
    env: Json;
    // The compiled HTTP headers, including the Content-Security-Policy headers.
    headers: Json;
    // The final HTML content of the `index.html`.
    indexHtmlContent: string;
  };
  type TransformerFunction = (options: TransformerFunctionOptions) => void;
  ```

## serve

This command starts a HTTP server to serve the previously built and compiled customization, from the `public` folder. This is useful for testing the production build locally.

```console
mc-scripts serve
```

We recommend to set up the following scripts in your `package.json`:

```json title="package.json"
{
  "scripts": {
    "compile-html:local": "MC_APP_ENV=development mc-scripts compile-html --transformer @commercetools-frontend/mc-dev-authentication/transformer-local.js",
    "start:prod:local": "yarn compile-html:local && mc-scripts serve"
  }
}
```

By default the application starts at `http://localhost:3001`.

## login

This command enables users to authenticate with their Identity account through the CLI.

A web page will open to perform the authorization flow. Upon login, an API token is generated and used by other CLI commands that require a valid API token.

```console
mc-scripts login
```

To perform the authorization request, the command requires the Merchant Center API URL and, optionally, the Project key and OAuth scopes to issue an API access token for. The information can be provided to the CLI in different ways, in the following order:

1. CLI options
2. Environment variables
3. Customization configuration

### CLI options

- `--mc-api-url <url>`: the URL of the Merchant Center API.
- `--project-key <key>`: the project key to issue an API access token for.
- `--oauth-scope <scope...>`: the OAuth scope to request when generating an API access token. Multiple flags are allowed.
- `--headless`: uses Puppeteer to automate browser-based authentication. Requires `IDENTITY_EMAIL` and `IDENTITY_PASSWORD` environment variables. Puppeteer is an optional peer dependency and must be installed separately. Useful for CI/CD environments.

The `--headless` option does not support SSO authentication. For organizations using SSO, use a service account without SSO for CI/CD workflows.

Example usage:

```console
npx mc-scripts login
npx mc-scripts login --mc-api-url=https://mc-api.europe-west1.gcp.commercetools.com
npx mc-scripts login --mc-api-url=https://mc-api.europe-west1.gcp.commercetools.com --project-key=my-project --oauth-scope=view_products
```

Headless login example:

```console
IDENTITY_EMAIL="user@example.com" IDENTITY_PASSWORD="password" npx mc-scripts login --headless
```

The `IDENTITY_EMAIL` and `IDENTITY_PASSWORD` credentials provide full access to your account. Treat them as highly sensitive secrets. Always store them securely in your CI/CD platform's secret management system and never commit them to version control.

### Environment variables

- `MC_API_URL`: the URL of the Merchant Center API.
- `CTP_PROJECT_KEY`: the project key to issue an API access token for.
- `CTP_OAUTH_SCOPES`: a comma-separated list of API OAuth scopes to request when generating an API access token.
- `IDENTITY_EMAIL`: the user email for headless authentication.
- `IDENTITY_PASSWORD`: the user password for headless authentication.

### Customization configuration

The API token is stored at `~/.commercetools/mc-credentials.json`. It is scoped by the Merchant Center API URL to allow you to authenticate against different environments.

The command must be executed from the folder where the Merchant Center Customization configuration file is located, as the data is extracted from that file.

## config:sync

This command lets users synchronize the local [Custom Application config](https://docs.commercetools.com/merchant-center-customizations/tooling-and-configuration/custom-application-config) or [Custom View config](https://docs.commercetools.com/merchant-center-customizations/tooling-and-configuration/custom-view-config) with the Merchant Center. The sync implies that a new customization will be created or an existing one will be updated.

Developers can use the `config:sync` command to automatically manage the configuration of a customization from the config file instead of having to manually fill out the information in the Merchant Center.

If a new customization needs to be created, an interactive prompt will ask the user to select the Organization where the customization should be configured to.

Additionally, after creating a new customization using the `config:sync` command, you must add the customization identifier to the appropriate config file, then follow the instructions in the terminal:

- For Custom Applications: add the generated [Custom Application ID](https://docs.commercetools.com/merchant-center-customizations/tooling-and-configuration/custom-application-config#envproductionapplicationid) to the Custom Application config.

- For Custom Views: you must add the generated [Custom View ID](https://docs.commercetools.com/merchant-center-customizations/tooling-and-configuration/custom-view-config#envproductioncustomviewid) to the Custom View config file.

Note that this command requires a valid API token. You can get one by using the `mc-scripts login` command.

```console
mc-scripts config:sync
```

The command uses the [cloud Region](https://docs.commercetools.com/merchant-center-customizations/concepts/merchant-center-api#cloud-regions) environment information from the [Custom Application config](https://docs.commercetools.com/merchant-center-customizations/tooling-and-configuration/custom-application-config) or [Custom View config](https://docs.commercetools.com/merchant-center-customizations/tooling-and-configuration/custom-view-config).

## config:sync:ci

This command synchronizes the local [Custom Application config](https://docs.commercetools.com/merchant-center-customizations/tooling-and-configuration/custom-application-config) or [Custom View config](https://docs.commercetools.com/merchant-center-customizations/tooling-and-configuration/custom-view-config) with the Merchant Center in non-interactive mode. It is designed for CI/CD environments where interactive prompts are not possible.

```console
mc-scripts config:sync:ci
```

Unlike `config:sync`, this command uses environment variables for authentication and organization selection instead of interactive prompts.

### Environment variables

- `MC_ACCESS_TOKEN`: a valid session token for authentication (required). You can obtain this token by running `mc-scripts login` and copying the `token` value from `~/.commercetools/mc-credentials.json`.
- `CT_ORGANIZATION_ID`: the Organization ID to use when creating a new customization. Required if the user belongs to multiple Organizations.
- `CT_ORGANIZATION_NAME`: the Organization name to use when creating a new customization. Can be used instead of `CT_ORGANIZATION_ID`.

If the user belongs to only one Organization, it is selected automatically.

### Options

- `--dry-run`: previews the changes without applying them.

### Example CI/CD workflow

1. Authenticate locally to obtain a session token:

   ```console
   mc-scripts login
   ```

2. Copy the token from `~/.commercetools/mc-credentials.json` and store it as a secret in your CI system (for example, `MC_ACCESS_TOKEN` in GitHub Actions).

3. Run `config:sync:ci` in your pipeline:

   ```console
   MC_ACCESS_TOKEN=${{ secrets.MC_ACCESS_TOKEN }} CT_ORGANIZATION_NAME="My Organization" mc-scripts config:sync:ci
   ```

Alternatively, use `mc-scripts login --headless` at the start of your pipeline to obtain a fresh token automatically.

When a new customization is created, the command outputs the ID in the format `ID: <id>`. You can capture this in CI scripts for use in subsequent steps.

Session tokens expire after approximately 8 hours. For long-running or scheduled pipelines, use the `--headless` login option with `IDENTITY_EMAIL` and `IDENTITY_PASSWORD` to obtain a fresh token at the start of each run.

# Use dotenv files

The `mc-scripts` CLI has the dotenv features built-in.

By default, the following dotenv files are loaded according to the current environment values specified on each command: `process.env.MC_APP_ENV` or `process.env.NODE_ENV`. The files are merged and overwritten prioritized from top to bottom (highest defined variable overrides lower).

- `.env.development.local`, `.env.test.local`, `.env.production.local`: local overrides of environment-specific settings.
- `.env.development`, `.env.test`, `.env.production`: environment-specific settings.
- `.env.local`: local overrides. This file is loaded for all environments except test.
- `.env`

Refer to the [dotenv documentation](https://github.com/motdotla/dotenv) for more details.

## Custom dotenv files

You can pass additional dotenv files by using the global CLI option `--env` or `-e`: `--env=<path>`. Multiple flags are allowed.

These files will take higher priority over the standard environment dotenv files.

When using the global option `--env` (one or multiple times) before a command, you need to declare it the following way:

- Separate the global options from the command with `--`, otherwise the command is considered an option of `--env`:

  ```console
  mc-scripts --env .env.local -- start
  ```

- Use the `=` separator for each `--env` option:

  ```console
  mc-scripts --env=.env.local --env=.env.defaults start
  ```