Import design system

Install the design system CLI

Install the CLI

Clone the SDK repository and build from source:

$git clone https://github.com/contentful/experience-design-system-sdk-public.git
$cd experience-design-system-sdk-public
$pnpm install
$pnpm build

Link the CLI globally so the experiences binary is available on your PATH:

$cd packages/experience-design-system-cli
$pnpm link --global

Prerequisites

Before running the CLI, ensure you have the following:

  • Node.js 24+ — Installed on your machine.
  • pnpm 10.27+ — Installed on your machine.
  • A coding agent CLI — One of the following, installed and authenticated:
  • A Contentful Management API (CMA) token — Generate one in the Contentful web app under Settings > API keys > Content management tokens.
  • A Contentful space with Experiences enabled — Contact your Contentful representative to enable the feature on your space.

Run experiences setup to install a coding agent and configure your Contentful credentials automatically. See Set up your environment.

Set up your environment

Run the interactive setup wizard to install a coding agent and configure your Contentful credentials:

$experiences setup

Terminal output from experiences setup showing all six steps completed: Node.js and pnpm checks, install and build, coding-agent detection, Contentful credentials confirmation, and Step 6 optional preferences (auto-filter, EDS_EXTRACT_CONCURRENCY, custom skill prompts, debug logging, NO_COLOR), ending with a "Setup complete" summary.

The wizard walks you through the following steps:

  1. Node.js — Detects nvm or fnm and offers to install Node 24.
  2. pnpm — Installs via corepack or npm.
  3. Install and build — Runs pnpm install && pnpm build from the monorepo root.
  4. Coding agent — Detects claude, codex, or opencode on your PATH. If none are found, presents a menu to install one.
  5. Contentful credentials — Prompts for CMA token, space ID, environment ID, and optional host. Saves them to ~/.config/experiences/credentials.json so they pre-fill in future sessions. The values you save here take precedence over CONTENTFUL_* / EDS_HOST environment variables — env vars only apply where the saved value is empty.
  6. Optional extras — A short series of preference questions:
    • AI auto-filter default — Whether the wizard runs the AI scope pre-filter by default. Override per invocation with --auto-filter / --no-auto-filter.
    • EDS_EXTRACT_CONCURRENCY — Controls how many components are analyzed in parallel. Default is 4.
    • Custom skill prompt paths — Optional paths to custom .md prompts for the select and generate agents. When set, the bundled invariants (utility-wrapper rejection, description rules) don’t apply.
    • Debug logging default — Whether the CLI writes a JSONL trace of every decision by default. Off by default because traces are verbose. See Debug logging.
    • NO_COLOR — Set to 1 to disable ANSI color output. Useful in CI or plain terminals.

If you have CONTENTFUL_SPACE_ID, CONTENTFUL_ENVIRONMENT_ID, CONTENTFUL_MANAGEMENT_TOKEN, or EDS_HOST set in your shell, setup prints a warning. The values you enter here take precedence; env vars remain a fallback for fields you leave blank.

To skip individual steps:

$experiences setup --skip-build --skip-agent --skip-credentials --skip-optional

Verify your environment

To check your environment at any time, run:

$experiences doctor

Next steps

Continue with these guides: