Getting started

This guide explains how to import your design system into Contentful with the design system import CLI, a tool you run in a terminal on your own computer. Once you finish, your components and design tokens will be available in Contentful, ready to use in Experiences.

The guide covers the following topics:

1. What the CLI does with your code. What it reads, what it sends to your coding agent, and what it saves.
2. Prerequisites. The tools and details needed before installing the CLI.
3. Steps. Install the CLI, configure it, run your first import, and check the result.
4. Running an import again. What to expect the next time you import.

For more details on each step in the import, see Import flow.

Important: what the CLI does with your code

The CLI uses an AI coding agent to describe your components. Before you start, review how it handles your code:

• Reads your source files on your machine - scans your component library to find components, props, and slots.

• Sends prompts to the coding agent you choose - starts the agent on your machine. Each prompt includes:

  • Your component definitions.
  • Each component’s source code and a few nearby files.
  • Your design token data.
  • A summary of components and tokens already in your space, if you provided Contentful credentials.

  The agent and its provider determine how this data is handled. Review their data policy before selecting an agent.

• Tells the agent to work only from the prompt - instructs the agent not to read other files and not to write any files, and it uses only the text the agent prints. The agent runs in the folder where you started the CLI.

• Saves its output on your machine - each import writes its results to its own folder inside a .contentful folder. That folder is in your project, or in the Root Project Directory if you set one in Settings. A later import never overwrites the files from an earlier one. Each import folder contains these files:

  • components.json holds the component definitions the import generated. This is the file the CLI pushes to Contentful.
  • tokens.json holds your design tokens, converted to the W3C DTCG format.
  • .existing-entities.json holds a snapshot of the components and tokens already in your space. The CLI uses it to compare your import with what exists.

  While Debug Mode is on, which is the default, the CLI also writes a log for each screen. The logs never include your CMA token.

• Changes nothing in Contentful until you confirm - after you review the generated definitions, the CLI saves them and then compares them with your space. It shows a preview listing each component and design token it would create, update, or skip, and it flags changes that could break existing experiences with a warning. Nothing is pushed until you confirm the preview, and you can cancel at that point.

Prerequisites

Before you install the CLI, set up the following:

• Node.js v24 or higher and npm. Runs the CLI, and installs it.
• A coding agent. Analyzes your components.
• Your Contentful details. The space ID and environment ID that identify where the CLI imports to, a CMA token that authorizes the CLI to make changes in that space, and the API host for your region.
• Supported inputs. A component library the CLI can read, and optionally a design token file.

For each tool, run the check command to see whether you already have it, and install it if you don’t. If you already have all tools, skip ahead to the Steps section.

Node.js and npm

Node.js is the program that runs the CLI. npm comes with Node.js, and you use it to install the CLI. You need Node.js 24 or later.

Check what you have:

node -v
npm -v

If node -v prints v24 or higher and npm -v prints a version number, you are ready. If you see an error, or a Node.js version lower than 24, install the current LTS version:

1. Go to nodejs.org/en/download.
2. Download the LTS installer for your system and run it.

If you already use a package manager, you can run one of these commands instead:

• macOS with Homebrew: brew install node
• Windows with winget: winget install OpenJS.NodeJS.LTS

Then close your terminal, open a new one, and run node -v and npm -v again to confirm.

pnpm (optional)

Only needed if you build the CLI from its source code or your team already uses it. To install it, see pnpm.io/installation, or run:

npm install -g pnpm

A coding agent

This is the agent described in the previous section. Install one of the agents below, sign in to it, and make sure you can start it from your terminal:

After you install an agent, follow its own sign-in steps. In Step 3, you choose which agent the CLI uses, and the CLI shows whether it can find each one.

Your Contentful details

The CLI needs these to push to your space. You enter them in Step 3.

• Space ID and environment ID. These identify where the CLI imports to. The environment ID is usually master.
• CMA token. A Contentful Management API (CMA) token is a secret key that lets the CLI make changes in your space. Create one in the Contentful web app under Settings > CMA tokens.
• API host. If your space is hosted in the EU, use api.eu.contentful.com as the API host. Otherwise, leave the API host at its default.

Supported inputs

The last prerequisite is something for the CLI to read. The CLI imports components from your component library and, if you choose, design tokens from a token file. You give it the paths to both in Step 4.

Libraries and frameworks

The CLI reads components from these frameworks:

• React
• Vue
• Svelte
• Astro
• Stencil
• Web Components
• Angular

The CLI reads .tsx, .ts, .jsx, .js, .vue, .svelte, and .astro files. It skips type declaration files (.d.ts), stories, tests, and specs. It also skips folders named node_modules, dist, build, example, examples, demo, and demos.

Design token files (optional)

To import design tokens with your components, provide a single file that defines them.

The coding agent you installed reads the file and converts its contents to the W3C DTCG format, so the file can use a format your team already has, such as:

• SCSS or CSS variables
• JavaScript or TypeScript token modules
• JSON
• Style Dictionary configuration
• Tailwind configuration

For example, a file with these SCSS variables:

$brand-primary: #0066ff;
$spacing-sm: 8px;

becomes tokens with paths such as colors.brand.primary and spacing.sm. Because an agent performs the conversion, the token review screen in Step 4 is where you check the result.

Steps

Step 1: Install the CLI

Install the CLI globally so the experiences command works in any folder:

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

To confirm the install worked, run:

experiences --version

If the install fails with EEXIST, see What do I do when I run into the EEXIST error? in the FAQ.

Step 2: Open the CLI

With the CLI installed, open it:

experiences import

The CLI opens a full-screen guided tool. Its home screen has three options: Import, Settings, and Help. You use Settings in the next step and Import in the step after that.

If you see a “Terminal too small” message, make the terminal window larger.

Step 3: Set up your configuration

Before you import, tell the CLI which agent to use and where to push. From the home screen, choose Settings, then set up the following:

1. Configuration > Project. Enter your space ID, environment ID, CMA token, and API host. The CLI saves them, and the import screens use them as defaults.
2. Configuration > Agents. Move to the coding agent you installed and press Enter to make it the default. The screen shows whether the CLI can find each agent. For Claude Code, it also shows whether you are signed in. For the other agents, press the right arrow to open one and run a test to confirm.

Press Esc or q to go back to the home screen. For everything else in Settings, see the Command reference.

Step 4: Run an import

Your configuration is saved, so you are ready to import. From the home screen, choose Import. The CLI guides you through the import one screen at a time:

1. Choose what to import. Pick components, design tokens, or both.
2. Give the paths. Enter the path to your component library, which must be a folder, and, if you import tokens, the path to your token file, which must be a single file. Paths can be absolute, relative, or start with ~.
3. Check your credentials. The screen is pre-filled with what you saved in Step 3.
4. Review and choose. Check the tokens the agent generated. Then check which components the agent suggests including, and change anything you disagree with.
5. Wait for generation. The agent generates the component definitions. This takes several minutes, depending on how many components you import.
6. Review the components. Check the properties and slots, and edit anything that looks wrong.
7. Preview and push. The import saves components.json to your computer, then compares your definitions with your Contentful space and shows a preview. The preview lists each component and design token that will be created, updated, or skipped, and marks changes that could break existing experiences with a warning. It also lists components that are in your space but not in your import. Read the preview, then confirm to push to Contentful, or cancel to stop without changing anything in your space.

To learn more in depth about what each screen does, see Import flow.

Step 5: Check the result in Contentful

When the push finishes without errors, your components and design tokens have been successfully imported into Contentful. The CLI prints a summary and a link to your components. Open the link to see them, or find them yourself in the web app:

1. Log in to the Contentful web app. If your space is hosted in the EU, use app.eu.contentful.com.
2. Go to your space and environment.
3. Go to Design system > Components.

Run an import again

You will probably import more than once, for example after you change a component. You can run experiences import as often as you like. Each run reads your code and asks the agent again, so a description or default value can differ slightly from the last run.

• The CLI matches components by name. A component that has the same name as one already in your space is listed as updated or unchanged in the preview, not as created.
• You always see a preview before anything is pushed. Press d on the preview for a detailed view of each change. Changes that could break existing experiences are marked with a warning.
• Read the whole preview before you confirm. It also lists components that are in your space but not in your import. If one of them is a component you want to keep as it is, press q to cancel instead of confirming.
• Nothing changed means nothing pushed. If your space already matches the import, the CLI tells you everything is up to date and pushes nothing.

Next steps

• Import flow — Learn what each screen does, and how tokens are mapped to components.
• Command reference — Learn how to start the CLI, and understand the Settings menu.
• FAQ — Find answers to common questions.