---
title: "CLI commands and configuration"
slug: "cli-commands-and-configuration"
abstract: "Overview of the Content SDK command-line interface (CLI), including supported commands and how you can configure its behaviour"
---
# CLI commands and configuration

The Content SDK CLI provides commands and supports scripts for common tasks during the development of projects using the Content SDK. To use the CLI, you must first [install it globally](https://doc.sitecore.com/sai/en/developers/content-sdk/20/install-the-content-sdk-cli.html "Install the Content SDK CLI") on your local machine.

The CLI is configured using the `sitecore.cli.config.ts` file by default. When this file is created as part of an app using a starter template, it contains the following configuration settings:

```ts
import { generateSites, generateMetadata } from '@sitecore-content-sdk/nextjs/tools';
import { defineCliConfig } from '@sitecore-content-sdk/nextjs/config-cli';
import config from './sitecore.config';

export default defineCliConfig({
  config,
  build: {
    commands: [
      generateMetadata(),
      generateSites(),
    ],
  },
});
```

> [!note]
> The build and scaffold commands support the `--config` flag that you can use to provide the location of a config file.

## The build command

The `sitecore-tools project build` CLI command prepares app-specific build artifacts, such as those required for the app to connect to SitecoreAI. It does this by sequentially executing the functions listed in the `build:` section of your CLI config file.

```shell
sitecore-tools project build
```

Your app's `package.json` file includes a `build` script that calls this CLI command, so it runs every time your app is built.

By default, the CLI will try to use a file named `sitecore.cli.config.ts` in the folder where you run the command. If that file does not exist the CLI will try to use `sitecore.cli.config.js` instead.

If you're running the command in a folder that doesn't contain either of these files, you need to specify the name and (relative) location of the file by using the `--config` argument, as shown in the following example where a custom file is used in the current folder:

```shell
sitecore-tools project build --config=custom.sitecore.cli.config.ts
```

Within the config file's `build.commands:` section, you can add custom functionality as shown with `myBuildCommand()` in the following example:

```csharp
import { defineCliConfig } from '@sitecore-content-sdk/nextjs/config-cli';
import { SitecoreConfig } from '@sitecore-content-sdk/nextjs/config';
import { generateSites, generateMetadata } from '@sitecore-content-sdk/nextjs/tools';
import config from './sitecore.config';

const myBuildCommand = (
  param: string
): (({ scConfig }: { scConfig: SitecoreConfig }) => Promise<void>) => {
  return async ({ scConfig }) => {
    console.log(param, scConfig.defaultSite);
    return Promise.resolve();
  };
};

export default defineCliConfig({
  config,
  build: {
    commands: [generateMetadata(), generateSites(), myBuildCommand('this is my build command!')],
  },
});
```

You can configure the default `generateMetadata` method using a [`GenerateMetadataConfig`](https://github.com/Sitecore/content-sdk/blob/v1.4.1/packages/core/src/tools/generateMetadata.ts#L16) object. It accepts two optional parameters:

<table style="width:100%;" class="informaltable frame-void rules-rows"><thead><tr><th class="th"><p>Parameter</p></th><th class="th"><p>Type</p></th><th class="th"><p>Description</p></th></tr></thead><tbody><tr><td class="td"><p><code class="code">destinationPath</code></p></td><td class="td"><p>string</p></td><td class="td"><p>Specify the path to store the generated metadata. If no value is provided, the default path is used.</p><p>Default: <span class="emphasis"><em>.sitecore/metadata.json</em></span></p></td></tr><tr><td class="td"><p><code class="code">allowWorkspaces</code></p></td><td class="td"><p>boolean</p></td><td class="td"><p>Specify whether to allow metadata generation for npm monorepos.</p><p>Default: <span class="emphasis"><em>false</em></span></p></td></tr></tbody></table>

For additional examples of customization, look at the implementations of `generateMetadata` and `generateSites` in the `core` package.

## The experimental list command

The `sitecore-tools project experimental list` command lists the experimental features available in your Content SDK app and whether each feature is enabled. It reads the features from the app's installed `@sitecore-content-sdk` packages, including `@sitecore-content-sdk/nextjs`.

Run the command from the root folder of your app:

```shell
sitecore-tools project experimental list
```

For each feature, the output includes:

| Detail | Description |
| --- | --- |
| Name | The feature's display name and ID. |
| Status | `enabled` or `disabled`. |
| Environment variable | The variable used to enable the feature. |
| Description | A short description of the feature. |

The command also prints instructions for enabling features. For example, the following output shows a sample feature:

```text
Experimental features available in @sitecore-content-sdk/nextjs:

  Dummy Feature (dummy-feature)
    Status:               disabled
    Environment variable: CSDK_EXPERIMENTAL_DUMMY_FEATURE
    Sample experimental feature used to verify the visibility API.

Set an environment variable to "true" to enable a single feature, or CSDK_GLOBAL_EXPERIMENTAL_FEATURES_ENABLED="true" to enable all of them.
```

Sample dummy features are available to verify the command. Actual experimental features appear in the same format as they become available.

To enable experimental features:

- To enable one feature, set its environment variable to `true`.
- To enable all features, set `CSDK_GLOBAL_EXPERIMENTAL_FEATURES_ENABLED=true`.

Use the lowercase value `true`. Values such as `TRUE` and `1` do not enable features. Run the command again after changing the environment variables to see the updated status.

If the installed packages have no experimental features, the command reports that none are available in the current version. If you run it outside a Content SDK app, it prints the following error:

```text
Content SDK app not found. Run this command from the root folder of a Content SDK app.
```

## The scaffold command

The `sitecore-tools project component scaffold` command generates a new named component in the `src/components/` folder of your app, based on the default template for the framework.

For example, the following command would create a new file named `MyComponent.tsx`.

```shell
sitecore-tools project component scaffold MyComponent
```

When using this command, in addition to the new component's name you can also include a path. This path is relative to where you run the command, so running the following example in `src/components/` will create `YourComponent.tsx` in `src/components/marketing/`.

```shell
sitecore-tools project component scaffold marketing/YourComponent
```

There are two default templates available by default:

- One template for standard components.
- One template for Sitecore BYOC components.

> [!note]
> By default (even with no other customizations to the CLI config file) these templates are merged into the `scaffold.templates:` section of the config file by the `defineCliConfig` function of the base package.

To scaffold a BYOC component, add the `--byoc` flag to your command, as shown in the following example:

```shell
sitecore-tools project component scaffold MyBYOCComponent --byoc
```

If you want to use a custom template file to scaffold your component, specify its name (and optionally its path) with the `--templateName` argument, as shown in the following example:

```shell
sitecore-tools project component scaffold MyCustomComponent --templateName=myTemplate
```

> [!important]
> To use custom templates for components, you must define them in your CLI config file within the `scaffold.templates:` section.

When using this command, you can include the `--config` argument to specify the path of a custom CLI configuration file if needed, as shown in the following example:

```shell
sitecore-tools project component scaffold MyComponent --config=custom.sitecore.cli.config.ts
```

Within the config file, a `scaffold:` section can be added if you want to define additional templates.

In the following example, a `scaffold:` section has been added to the default CLI config file, including a `templates:` section that provides a list defining custom component templates of type `ScaffoldTemplate`. Any of these custom templates can then be used instead of the default ones by including the `templateName` argument in your `scaffold` command.

```csharp
import { defineCliConfig } from '@sitecore-content-sdk/nextjs/config-cli';
import { generateSites, generateMetadata } from '@sitecore-content-sdk/nextjs/tools';
import config from './sitecore.config';

export default defineCliConfig({
  config,
  build: {
    commands: [
      generateMetadata(),
      generateSites(),
    ],
  },
  scaffold: {
    templates: [
      {
        name: 'myTemplate',
        generateTemplate: (componentName: string) => {
          return `this is my new ${componentName}`;
        },
        getNextSteps: (componentOutputPath: string) => {
          return ['this is the next step', `component path is here: ${componentOutputPath}`];
        },
        fileExtension: 'tsx',
      },
    ],
  },
});
```

## The add command

The `sitecore-tools project add` command generates and adds a new component from the [Design studio](https://doc.sitecore.com/sai/en/users/sitecoreai/design-studio.html) to your application. It simplifies component generation and ensures consistent component mappings throughout your project.

You invoke the command with a component identifier, and an authentication token as shown:

```text
sitecore-tools project component add <component-id> --token <auth-token> [options]
```

You can optionally direct output to a specific path, skip map generation, or allow overwriting.

<table style="width:100%;" class="informaltable frame-void rules-rows"><thead><tr><th class="th"><p>Parameter</p></th><th class="th"><p>Description</p></th></tr></thead><tbody><tr><td class="td"><p><code class="code">&lt;component-id&gt;</code></p></td><td class="td"><p>The unique identifier of the component to add.</p><p><span class="emphasis"><em>Required</em></span></p></td></tr><tr><td class="td"><p><code class="code">--token</code></p></td><td class="td"><p>Authentication token authorizing the operation.</p><p><span class="emphasis"><em>Required</em></span></p></td></tr><tr><td class="td"><p><code class="code">--target-path</code></p></td><td class="td"><p>The relative path to store the generated component. If omitted, the CLI attempts to resolve a path based on existing components. On failure, it prompts for manual input.</p><p><span class="emphasis"><em>Optional</em></span></p></td></tr><tr><td class="td"><p><code class="code">--skip-component-map</code></p></td><td class="td"><p>When present, skips component map generation. Use if you intend to update the map manually later.</p><p><span class="emphasis"><em>Optional</em></span></p></td></tr><tr><td class="td"><p><code class="code">--overwrite</code></p></td><td class="td"><p>Overwrites an existing component with the same name. Without this flag, the CLI stops and asks for confirmation.</p><p><span class="emphasis"><em>Optional</em></span></p></td></tr></tbody></table>