Import design system

Debug logging

The experiences CLI can write a structured JSONL trace of every decision — extract, filter, agent call, session state, push result — to a local file. Turn it on when a run misbehaves, then attach the file when filing an issue.

Enable debug logging

Pass --debug on any subcommand:

$experiences import --debug
$experiences generate components --debug --agent claude
$experiences runs --debug

Or set the environment variable, which enables debug logging for every invocation in the current shell:

$export EDSI_DEBUG=1
$experiences import

Force debug off (overriding both EDSI_DEBUG and the persisted debug field in credentials.json) with --no-debug.

Log location

Traces are written to:

~/.contentful/experience-design-system-cli/debug/<timestamp>-<command>.jsonl

Subprocesses spawned during a wizard run join the same log file, so an entire experiences import flow lands in a single file. When debug logging is active, the CLI prints a bright-green start banner naming the log path at the beginning of the command and again at exit.

Redaction

Debug traces are automatically redacted before writing to disk. The logger scrubs:

  • Any field whose key matches token, secret, password, authorization, apikey, credential, bearer, cma, or cmaToken.
  • Any string value that looks like a Contentful management token (CFPAT-…), an OpenAI key (sk-…), a Slack token (xox…), or a Bearer … header.

Long strings are truncated. That said, traces still contain component names, prop names, file paths, and other project-shaped metadata. Review before sharing outside your organization.

Advanced configuration

The debug root defaults to ~/.contentful/experience-design-system-cli/debug/ and can be overridden:

  • EDSI_DEBUG_ROOT — change the base directory.
  • EDSI_DEBUG_LOG — force a specific log file path (also used internally by spawned subprocesses to join the parent’s log).

Troubleshooting

  • No log file appears — Confirm the banner printed. If it didn’t, --debug wasn’t resolved — check for --no-debug, EDSI_DEBUG=0, or a stale debug: false in ~/.config/experiences/credentials.json.
  • Long-running wizard — Pipe --debug output through tail -f on the log file in a second terminal to watch decisions in real time.
  • Filing an issue — Attach the .jsonl file and the exact command you ran; the trace usually pinpoints the failing step without a repro.