Import components

The experiences import command is the recommended way to run the component import pipeline. It guides you through extraction, scope review, credentials, generation, final review, and push in a single session.

If you need to re-run a specific stage or integrate steps into a custom pipeline, see Run the pipeline step by step. For the full flag reference, see Command reference.

Import with the interactive TUI

Run the full pipeline interactively:

$
experiences import

The wizard prompts you for your project path, uses your configured coding agent (defaults to Claude), and walks you through the following steps:

1. Welcome / run picker — When you have prior runs recorded, the wizard opens on a picker so you can push or modify one of them. Skipped in non-interactive shells and when a routing flag is passed. See Run history and replay.
2. Project path — Prompts for the project root (pre-filled by --project).
3. Extract — Scans your local source files (.tsx, .ts, .jsx, .js, .vue, .astro) to extract component metadata.
4. AI auto-filter — If credentials are already loaded and auto-filter is enabled, an AI agent runs in the background to recommend which components to include. The result seeds the scope gate.
5. Scope gate — Review which components to import. See Scope gate below.
6. Credentials — Collected before generation and pre-filled from experiences setup. Generation prefetches in parallel with credential entry so the two steps overlap. Skip credentials to run in save-only mode — see Skip credentials for a save-only flow.
7. Generate — The AI agent generates a CDF definition for each accepted component.
8. Final review — Inspect and edit the generated components before push. See Final review below.
9. Save path — Prompts for a directory to save components.json and tokens.json (or pass --out-dir). When files already exist at that path, the wizard shows a conflict gate that lets you overwrite them or save to a timestamped subdirectory instead. Skip the gate in headless mode with --on-conflict <overwrite|skip|fail>.
10. Push decision — Save-and-push is the default. Pushing prints a Contentful webapp URL to the components view.
11. Done — The run is recorded to ~/.config/experiences/runs.json. See Run history and replay.

Caching behavior

Two of the AI-driven steps in the pipeline cache differently:

• AI auto-filter (step 4) — Cached per component. The decision for each component is keyed on a hash of the extractor’s output — component name, framework, prop names and types, slot names — so subsequent runs against the same source reuse prior decisions and skip the LLM. Cache entries are invalidated automatically when the source changes. Bypass the cache for a run with --no-cache.
• Generate (step 7) — Runs the LLM every time the session is fresh. Each experiences import invocation creates a fresh session, so generation re-runs against every accepted component even when the source is unchanged. To reuse a prior generation without re-running the agent, replay the recorded run with experiences import --push-from-run <id> or re-open it for edits with --modify <id> (see Run history and replay).

Scope gate

The scope gate is a single review screen with two sections: AI-recommended exclusions (with the AI’s reasoning shown inline) and Components. The AI-recommended exclusions section appears at the top so you can review each of the AI’s exclusion decisions before accepting the rest of the components.

Features:

• Toggle any component’s include/exclude state, one at a time or across the whole list.
• Read the AI’s rationale for each recommendation without leaving the screen.
• Detailed component and slot rationale is available on the Final review step.
• If a batched AI response omitted a component’s decision, that component surfaces as failed in the AI-recommended-exclusions section and defaults to excluded — you can still include it manually.

Final review

The final review step lets you inspect each generated component — its properties, their types (string, richtext, media, enum, token), and the AI’s rationale — and edit before push.

Switch into the field editor to inspect and change the generated props and slots directly. Edits are saved to the session so they carry through to save and push.

Features:

• Agent rationale — View why the AI chose each property or slot, at both the component/slot level and the individual prop level.
• Original JSON — Toggle to the raw generated CDF JSON for a component to see the full generated definition.
• Source view — Open the extracted source-code snippet the AI used as input, so you can compare the generated definition against the original component.
• Edit fields — Change property names, descriptions, types, defaults, and allowed values directly in the field editor. Edits are saved back into the session so they carry through to save and push.
• Preview diff banner — A banner at the top of the screen reflects the aggregate diff between your generated manifest and the current state of your Contentful environment. Counts update as you edit fields.
• Removed-list overlay — Open a pop-up listing the components that will be deleted from Contentful on push — these are components that exist in your target space but are absent from the manifest you’re about to submit (for example, because you rejected them at the scope gate).
• Live preview — When credentials are configured, saving a change in the field editor re-runs the manifest preview against your Contentful environment and updates the diff banner inline. Disable with --no-live-preview. Live preview is unavailable when you skipped credentials at step 6 — the field editor still edits fields, but you won’t see server-side diffs until you push.

Skip credentials for a save-only flow

You can skip the credentials step to run the wizard in save-only mode. The wizard writes components.json (and tokens.json when applicable) to disk, records the run as not pushed, and preserves the prefetched generation so you can push later with experiences import --push-from-run <id>.

Push decision and diff preview

After the final review, the wizard prompts you to save components.json to disk, push to your Contentful space, or do both. Save-and-push is the default.

Before the push commits, the wizard shows a diff summary of what will be created, updated, and removed. You can expand the diff to review every field-level change before confirming.

Manifest deletion safety

Manifest preview and apply are non-destructive by default. Components and design tokens that exist in the target environment but are missing from the manifest are omitted from the diff, so no delete actions are emitted.

To include removals, pass --allow-deletions to experiences import, experiences apply select, or experiences apply push. This opt-in can produce delete actions for missing components and design tokens. Published entities are excluded from deletion, and components referenced by Fragments remain protected.

experiences apply preview is read-only and always uses the default behavior of skipping deletions. Preview and apply use the same removal gate when the deletion opt-in is enabled.

Once the push completes, the wizard prints a summary and a direct URL to the components view in the Contentful web app.

Run in headless mode

Pass --space-id, --yes, --auto-accept-scope, or other automation flags to run without interactive prompts. This is suited for CI pipelines:

$
experiences import \
>
  --project /path/to/your/component-library \
>
  --space-id $CONTENTFUL_SPACE_ID \
>
  --environment-id $CONTENTFUL_ENVIRONMENT_ID \
>
  --cma-token $CONTENTFUL_MANAGEMENT_TOKEN \
>
  --agent claude \
>
  --auto-accept-scope \
>
  --yes

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

Verify in Contentful

After pushing, follow the URL printed by apply push to jump directly to your imported components. To navigate there manually instead:

1. Log in to the Contentful web app.
2. Navigate to your space and environment.
3. Go to Design system > Components to view the imported components.

Design tokens are surfaced on the components that reference them — open a component to see the tokens it uses on its design properties.

Next steps

• Import design tokens — Import colors, spacing, typography, and other design tokens alongside your components.
• Coded components — Preserve embedded-component hierarchies with composite mode.
• Run history and replay — List, push, or edit prior runs.
• Run the pipeline step by step — Run each stage as an individual command.
• Command reference — Full flag reference.
• Debug logging — Capture a trace of a run for troubleshooting.
• FAQ — Common questions and behaviors that surprise operators the first time through.