Import design system

Command reference

This page lists every flag on experiences import and the individual pipeline commands (analyze extract, analyze select-agent, analyze select, generate components, apply preview, apply select, apply push). See Import components for the guided walkthrough and Run the pipeline step by step for the per-step recipes.

Manifest deletion safety

Manifest preview and apply skip deletions 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.

Pass --allow-deletions to experiences import, experiences apply select, or experiences apply push to include removals. Published entities are excluded from deletion, and components referenced by Fragments remain protected. experiences apply preview is read-only and always skips deletions.

Credential precedence

Credentials — --space-id, --environment-id, --cma-token, and --host — resolve in a fixed order. The order depends on which surface receives them:

Interactive experiences import (the wizard):

  1. Values you enter in the wizard’s Credentials step during this run.
  2. Values saved via experiences setup (stored on disk at ~/.config/experiences/credentials.json).
  3. Environment variables CONTENTFUL_SPACE_ID, CONTENTFUL_ENVIRONMENT_ID, CONTENTFUL_MANAGEMENT_TOKEN, EDS_HOST. Only used as a fallback when the disk value for that field is empty.

Saved (disk) values take precedence over environment variables so that credentials you deliberately configured with experiences setup are not silently overridden by whatever happens to be in your shell. When environment variables are set, experiences setup prints a warning to make the shadowing behavior visible.

Headless / individual commands (--push-from-run, --skip-*, apply preview, apply select, apply push, and non-TTY experiences import):

  1. Command-line flag values (--space-id, --environment-id, --cma-token, --host).
  2. Environment variables (CONTENTFUL_SPACE_ID, CONTENTFUL_ENVIRONMENT_ID, CONTENTFUL_MANAGEMENT_TOKEN, EDS_HOST).

Values saved via experiences setup are not consulted on the headless path — pass credentials via flags or environment variables. This mirrors typical CI conventions and keeps scripted runs deterministic.

experiences import

Common flags:

FlagPurpose
--project <path>Path to the project root to analyze.
--space-id <id>Contentful space ID. Required unless --skip-apply or --no-push. See Credential precedence.
--environment-id <id>Contentful environment ID. Required unless --skip-apply or --no-push. See Credential precedence.
--cma-token <token>CMA personal access token. See Credential precedence.
--host <url>Override the Contentful API base URL (for example, when targeting a non-production stack).
--agent <name>Coding agent to use (claude, codex, opencode, cursor). Overrides the stored preference.
--model <name>Model override for the selected agent. Supported across all four agents; each agent picks a default lightweight model when the flag is omitted.
--raw-tokens <path>Raw token source file (SCSS, CSS variables, JS/TS, Style Dictionary, Tailwind) to classify alongside components.
--tokens <path>Pre-classified DTCG tokens.json sidecar to push alongside components.
--auto-filter / --no-auto-filterForce the AI scope pre-filter on or off, overriding the stored preference.
--no-live-previewDisable the manifest preview that re-runs after each field edit in the wizard’s final-review step.
--auto-accept-scopeAccept all extracted components without prompting. Required when running in a non-interactive shell (for example, CI pipelines).
--out-dir <path>Save directory for components.json / tokens.json. Bypasses the inline save-path prompt.
--on-conflict <mode>overwrite, skip, or fail when files exist at the save path.
--no-savePush without writing files to disk.
--no-pushRun extract → scope → generate → final-review and exit without pushing.
--push-from-run <id-or-path>Push a prior recorded run without regenerating. See Run history and replay.
--modify <id-or-path>Re-open the wizard at final-review with a prior run pre-populated. See Run history and replay.
--allow-deletionsInclude components and design tokens missing from the manifest in removal actions. Disabled by default.
--overwrite / --save-as-newOnly with --modify: save back to the run’s recorded path, or always save to a new path.
--forceBypass staleness checks with --push-from-run / --modify.
--select-prompt-path <path>Custom .md skill prompt for analyze select-agent. A banner is shown when active.
--generate-prompt-path <path>Custom .md skill prompt for generate components. A banner is shown when active.
--no-cacheBypass the select and generate caches (forwards through spawned subprocesses).
--yesSkip the interactive confirmation prompt during the apply-push step.
--verboseShow full agent output and per-entity progress.
--print-promptPrint the generate prompt to stdout and exit without invoking the agent.
--debug / --no-debugEnable or force off the redacted JSONL trace at ~/.contentful/experience-design-system-cli/debug/. See Debug logging.

Advanced flags for headless pipelines and partial runs:

FlagPurpose
--out <path>Directory for pipeline artifacts (extract sessions, generated JSON). Distinct from --out-dir, which sets the final save-path for components.json / tokens.json.
--select-allAccept every extracted component without prompting. Headless equivalent of the scope gate’s accept-all action.
--select <pattern>Include only components matching this pattern. Repeatable.
--deselect <pattern>Exclude components matching this pattern. Repeatable.
--skip-analyzeReuse the most recent extract session instead of re-scanning.
--skip-generateReuse the most recent generate session instead of re-generating.
--skip-applyStop after generate; do not push to Contentful. Makes --space-id / --environment-id / --cma-token optional.
--exclude-invalidAutomatically reject components with validation errors (empty names, collisions).
--printWrite components.json to --out after generation completes.
--viewports <path>JSON file with a viewport array, forwarded to apply push.

--dry-run still works but emits a stderr deprecation notice. Use --print-prompt instead.

Composite mode and composition sources. See Coded components for the full explanation:

FlagPurpose
--atomicImport a flat list of components with no embedded-component hierarchy. This is the default.
--compositeImport the embedded-component hierarchy (opt in). Wins if both --composite and --atomic are passed.
--composition-map <path>Consume a hand-authored parent → children interchange map. Deterministic, and outranks the agent. Implies --composite.
--generate-map <path>Also write a composition-map skeleton from the resolved edges during extraction, ready to hand-edit and feed back via --composition-map. Implies --composite.
--composition-agentResolve the hierarchy with a coding agent when the deterministic sources find no groups. Best effort and cached. Implies --composite.
--composition-agent-mode <mode>parser (the default, where the agent writes a sandboxed parser) or edges (the agent lists relationships directly).
--composition-refreshBypass the composition cache and re-resolve from scratch, forcing the agent to run. Implies --composite.
--prompt <stage=value>Override a stage prompt. value is a file path or literal text, for example --prompt composition=./prompt.md. Repeatable.
--auto-reject-cyclesAutomatically reject the components in a slot dependency cycle and continue, instead of blocking. See Slot dependency cycles.

Any composition source flag implies --composite, so you rarely pass --composite explicitly once you use one. The edge-source precedence is code slots, then map, then agent.

experiences analyze extract

FlagPurpose
--project <path>Path to the project root to scan.
--dir <subpath>Scan a specific subdirectory within the project.
--session <id>Reuse a specific extract session ID.

experiences analyze select-agent

FlagPurpose
--agent <name>Coding agent to use for the scope decision.
--model <name>Model override for the selected agent.
--session <id>Analyze select-agent decisions are stored against this pipeline session.
--select-prompt-path <path>Custom .md skill prompt for the select agent. A banner is shown when active.
--no-cacheBypass the per-component select cache.
--show-rationalePrint the decisions and rationale that a prior select-agent run recorded for this session. Read-only — reads the persisted rationale from the session database without invoking the agent.
--jsonWith --show-rationale, emit machine-readable JSON.
--verboseDisplay detailed agent output.
--print-promptPrint the select prompt to stdout and exit.

experiences analyze select

The standalone interactive TUI for reviewing extracted components.

FlagPurpose
--session <id>Load a specific extract session into the TUI.
--select-allAccept every extracted component without launching the TUI.
--select <pattern>Accept components matching this pattern. Repeatable.
--deselect <pattern>Reject components matching this pattern. Repeatable.

experiences generate components

FlagPurpose
--agent <name>Coding agent to use.
--model <name>Model override for the selected agent.
--tokens <path>Design token file for prop resolution.
--token-map <path>Token-map file for token-to-prop binding.
--generate-prompt-path <path>Custom .md skill prompt for the generate agent. A banner is shown when active; the cache is isolated by prompt hash.
--session <id>Persist generated definitions against this pipeline session.
--no-cacheBypass cached results and regenerate all definitions.
--verboseDisplay detailed agent output.
--print-promptPrint the generate prompt to stdout and exit.

experiences apply preview

FlagPurpose
--space-id <id>Contentful space ID. Required.
--environment-id <id>Contentful environment ID. Required.
--cma-token <token>CMA personal access token. Also read from CONTENTFUL_MANAGEMENT_TOKEN.
--host <url>Override the Contentful API base URL.
--components <path>Path to a components.json (CDF) file to preview from disk instead of the current session.
--tokens <path>Path to a tokens.json (DTCG) file to include in the preview.
--session <id>Load generated components from a specific pipeline session ID.

experiences apply select

FlagPurpose
--space-id <id>Contentful space ID. Required.
--environment-id <id>Contentful environment ID. Required.
--cma-token <token>CMA personal access token. Also read from CONTENTFUL_MANAGEMENT_TOKEN.
--host <url>Override the Contentful API base URL.
--components <path>Path to a components.json (CDF) file to load from disk instead of the current session.
--tokens <path>Path to a tokens.json (DTCG) file.
--session <id>Load generated components from a specific pipeline session ID.
--select-allSelect all entities without launching the TUI.
--select <pattern>Select entities by ID pattern. Repeatable.
--deselect <pattern>Deselect entities by ID pattern. Repeatable.
--allow-deletionsInclude components and design tokens missing from the manifest in removal actions. Disabled by default.
--forceSkip confirmation for breaking changes (field removals, type changes).

experiences apply push

FlagPurpose
--space-id <id>Contentful space ID. Required.
--environment-id <id>Contentful environment ID. Required.
--cma-token <token>CMA personal access token. Also read from CONTENTFUL_MANAGEMENT_TOKEN.
--host <url>Override the Contentful API base URL.
--components <path>Path to a components.json (CDF) file to push from disk instead of the current session.
--tokens <path>Path to a tokens.json (DTCG) file.
--session <id>Load generated components from a specific pipeline session ID.
--allow-deletionsInclude components and design tokens missing from the manifest in removal actions. Disabled by default.
--yesSkip the interactive confirmation prompt.
--verboseShow all entity progress, including skipped and unchanged entities.
--forceSkip confirmation for breaking changes (for CI pipelines).
--dry-runRun the preview step only without pushing.