> 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-staging.ferndocs.com/developers/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://contentful-staging.ferndocs.com/developers/docs/_mcp/server.

# Import components

> Import design system Component Types into Contentful using the CLI interactive TUI or individual commands.

The `experiences import` command is the recommended way to run the Component Type import pipeline. It guides you through extraction, review, generation, preview, and push in a single session. For cases where you need to re-run a specific stage, inspect intermediate results, or integrate steps into a custom pipeline, you can also [run each step individually](#run-individual-pipeline-steps).

## Import with the interactive TUI

Run the full pipeline interactively:

```bash
experiences import
```

![experiences import TUI](/developers/docs/_fern-img/0a046cf32bbd04e53ec75987ffa3602d57500c716040a328ed1b4b5c88e42396.webp)

The TUI prompts you for your project path, uses your configured coding agent (defaults to Claude), and guides you through credentials and all review steps. When this command runs, it:

1. Scans your local source files (`.tsx`, `.ts`, `.jsx`, `.js`, `.vue`, `.astro`) to extract Component Type metadata.
2. Prompts you to review extracted Component Types — accept, reject, or edit individual items. You can also approve all and skip this step.
3. Invokes the AI agent to generate CDF definitions for each accepted Component Type — describing their properties, types, and categories.
4. Prompts you to review and correct the generated definitions before pushing.
5. Displays a preview diff showing what will be created or updated in your Contentful environment.
6. Pushes the definitions to your Contentful environment.

Pass `--project` to pre-fill the project path or `--agent` to override the default coding agent:

```bash
experiences import --project /path/to/your/component-library --agent codex
```

> **Info**
>
> If you configured credentials via `experiences setup`, the TUI pre-fills your space ID, environment ID, and CMA token automatically.

### Run in headless mode

Pass `--space-id`, `--yes`, or other automation flags to run without interactive prompts or review gates. This is suited for CI pipelines:

```bash
experiences import \
  --project /path/to/your/component-library \
  --space-id $CONTENTFUL_SPACE_ID \
  --environment-id $CONTENTFUL_ENVIRONMENT_ID \
  --agent claude \
  --yes
```

In headless mode, the pipeline runs: analyze extract → analyze select-agent → generate components → apply push. No review gates or preview step are run.

## Run individual pipeline steps

Use individual commands when you need to re-run a specific stage, inspect intermediate results, or integrate steps into a custom pipeline. All intermediate data flows through a local SQLite session database — no JSON files are written between steps.

### 1. Extract Component Types from source

```bash
experiences analyze extract --project /path/to/your/component-library
```

![experiences analyze extract](/developers/docs/_fern-img/db6cec618a6b7c98d7a05bdb55661cb432a40d011f5cc8e1cc09a7722f4d71d2.webp)

Scans your local source files and stores extracted Component Type metadata in the session database. The command prints a session ID that subsequent commands consume automatically (defaulting to the most recent completed extraction session).

To scan a specific subdirectory within your project:

```bash
experiences analyze extract --project /path/to/your/component-library --dir src/components
```

The extractor supports React, Vue, Astro, Stencil, and Web Components. It ignores `node_modules`, `dist`, `build`, `.next`, `.nuxt`, and test/story files automatically.

### 2. Select Component Types

Use **Option A** (agent) for automated pipelines, **Option B** (TUI) for first-time review, or **Option C** (pattern flags) for scripted re-runs.

**Option A — AI agent selection:**

```bash
experiences analyze select-agent --agent claude
```

The agent reviews each Component Type candidate and accepts those that render visible UI (atoms, molecules, and organisms). It rejects non-visual infrastructure like hooks, context providers, and analytics wrappers.

Additional options:

* `--model <name>` — Override the default model for the selected agent.
* `--verbose` — Display detailed agent output.
* `--dry-run` — Show what the agent would select without writing to the session.

**Option B — Interactive TUI:**

```bash
experiences analyze select
```

![experiences analyze select](/developers/docs/_fern-img/326dcb3d9d27a27bda5541e803ac85ee555d6978f0bc5144001e17a620671178.webp)

Launches a full-screen terminal interface where you can review each Component Type, accept or reject it, and edit its extracted definition.

**Option C — Pattern-based selection:**

```bash
experiences analyze select --select-all
```

Or target specific Component Types:

```bash
experiences analyze select --select Button --select Card --deselect Icon
```

> **Info**
>
> You can combine approaches — run `select-agent` first, then `select` to review and override the agent's decisions in the TUI.

### 3. Generate CDF definitions

```bash
experiences generate components --agent claude
```

![experiences generate components](/developers/docs/_fern-img/da004f9b0c838eb9e716c641d89b031e77c12462b170aa6e3c42a8b0d5eb70cb.webp)

For each accepted Component Type, the AI agent generates a CDF definition describing its properties, their types (string, richtext, media, enum, token), and their categories (content, design, or state).

Additional options:

* `--tokens <path>` — Pass a design token file for prop resolution (see [Import design tokens](/experience-orchestration/import-design-tokens)).
* `--token-map <path>` — Pass a token map file for token-to-prop binding.
* `--model <name>` — Override the default model for the selected agent.
* `--no-cache` — Bypass cached results and regenerate all definitions.
* `--verbose` — Display detailed agent output.
* `--dry-run` — Show what the agent would generate without writing to the session.

### 4. Preview changes

```bash
experiences apply preview \
  --space-id $CONTENTFUL_SPACE_ID \
  --environment-id $CONTENTFUL_ENVIRONMENT_ID
```

Shows a diff of what will be created or updated in your Contentful space without making any changes. In an interactive terminal, a TUI displays entities grouped by status (new, changed, unchanged). In non-interactive mode, the CLI writes structured JSON to stdout.

To preview from exported JSON files instead of the session:

```bash
experiences apply preview \
  --space-id $CONTENTFUL_SPACE_ID \
  --environment-id $CONTENTFUL_ENVIRONMENT_ID \
  --components components.json
```

### 5. Select entities to push (optional)

```bash
experiences apply select \
  --space-id $CONTENTFUL_SPACE_ID \
  --environment-id $CONTENTFUL_ENVIRONMENT_ID
```

Launches a TUI where you can select a subset of entities from the preview to push. Skip this step to push the full batch.

Additional options:

* `--select-all` — Select all entities without an interactive prompt.
* `--select <pattern>` — Select entities matching a pattern (repeatable).
* `--deselect <pattern>` — Deselect entities matching a pattern (repeatable).
* `--force` — Skip confirmation for breaking changes (field removals, type changes).

### 6. Push to Contentful

```bash
experiences apply push \
  --space-id $CONTENTFUL_SPACE_ID \
  --environment-id $CONTENTFUL_ENVIRONMENT_ID
```

Sends your generated Component Type definitions to Contentful in a single batch operation. The server returns counts of created, updated, and failed entities.

To include design tokens in the push, pass `--tokens` with a generated DTCG token file (see [Import design tokens](/experience-orchestration/import-design-tokens)):

```bash
experiences apply push \
  --space-id $CONTENTFUL_SPACE_ID \
  --environment-id $CONTENTFUL_ENVIRONMENT_ID \
  --tokens tokens.json
```

Additional options:

* `--yes` — Skip the interactive confirmation prompt.
* `--verbose` — Display detailed push output.
* `--force` — Skip confirmation for breaking changes (for CI pipelines).
* `--dry-run` — Show what would be pushed without making changes.

> **Info**
>
> Running `apply push` again after updating your component library creates or updates Component Types as needed. The CLI does not automatically delete Component Types that you removed from the selection.

### Export to file

To write generated CDF definitions to a JSON file for inspection or version control:

```bash
experiences print components --out components.json
```

You can pass this file to `apply push` in a later session:

```bash
experiences apply push \
  --components components.json \
  --space-id $CONTENTFUL_SPACE_ID \
  --environment-id $CONTENTFUL_ENVIRONMENT_ID
```

## Verify in Contentful

After pushing, verify that your Component Types appear in experiences:

1. Log in to the [Contentful web app](https://app.contentful.com).
2. Navigate to your space and select **Experiences**.
3. Go to an experience or create one.
4. In the editor, navigate to the **Components** panel — your imported Component Types are displayed under their configured categories.

## Next steps

Continue with this guide:

* **[Import design tokens](/experience-orchestration/import-design-tokens)** — Import colors, spacing, typography, and other design tokens alongside your Component Types.