> This page is for Experience Orchestration.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://contentful.com/developers/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://contentful.com/developers/docs/_mcp/server.

# Getting started

> Install the CLI, run your first design system import, and check the result in Contentful.

This page shows the shortest path from your codebase to components in Contentful. For details on each screen, see [Import flow](/developers/docs/experience-orchestration/import-design-system/import-flow).

## Prerequisites

* **Node.js 24+** and **pnpm 10.27+**
* **A coding agent** that is installed and signed in. The CLI supports Claude Code, Codex, OpenCode, and Cursor.
* **A Contentful Management API (CMA) token.** Create one in the Contentful web app under **Settings > CMA tokens**.
* **A component library.** React, Vue, Astro, Stencil, and Web Components projects work.

## Step 1: Install the CLI

Install the CLI globally so the `experiences` command works in any directory:

```bash
npm install -g @contentful/experience-design-system-cli
```

## Step 2: Set up

Run the setup and follow the prompts. It checks your Node.js and pnpm versions, finds your coding agent, and saves your Contentful credentials.

```bash
experiences setup
```

To check your environment at any time, run `experiences doctor`.

## Step 3: Run the import

Start the import:

```bash
experiences import
```

The import asks for the path to your components and, if you have one, a design tokens file.

The flags are optional. To skip the prompts, pass the paths yourself:

```bash
experiences import --project ./src/components --tokens ./tokens.scss
```

| **Flag**           | **What it does**                                         |
| ------------------ | -------------------------------------------------------- |
| `--project <path>` | Path to your components. Defaults to the current folder. |
| `--tokens <path>`  | Path to a design tokens file (a file, not a folder).     |

## Step 4: Follow the prompts

The import walks you through these screens:

1. **Review excluded components.** The agent suggests components to leave out, such as `DebugPanel` or `Portal`. Change anything you disagree with, then confirm.
2. **Wait for generation.** This takes 2 to 25 minutes, depending on how many components you import.
3. **Review the generated components.** Check the properties and slots, and edit anything that looks wrong.
4. **Push.** The import saves `components.json`. Check the summary of what will be created, updated, and skipped, then confirm.

Components that are in Contentful but not in your import are skipped, not deleted.

To learn what each screen does, see [Import flow](/developers/docs/experience-orchestration/import-design-system/import-flow).

## Step 5: Check the result in Contentful

Open the link printed at the end of the push. To find your components yourself:

1. Log in to the [Contentful web app](https://app.contentful.com).
2. Go to your space and environment.
3. Go to **Design system > Components**.

## Next steps

* **[Import flow](/developers/docs/experience-orchestration/import-design-system/import-flow)** — Learn what each screen does, and how tokens are mapped to components.
* **[Command reference](/developers/docs/experience-orchestration/import-design-system/command-reference)** — See every command and flag.
* **[FAQ](/developers/docs/experience-orchestration/import-design-system/faq)** — Find answers to common questions.