> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://contentful.com/developers/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://contentful.com/_mcp/server.

# Debug logging

> Capture a JSONL trace of the design system CLI for troubleshooting.

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:

```bash
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:

```bash
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.

> Capture a JSONL trace of the design system CLI for troubleshooting.