FAQ

This guide answers common questions about the design system import CLI, grouped by what you are trying to do. To set up and run your first import, see Getting started.

The questions are grouped into these topics:

1. Installation. Fixing a failed install, uninstalling or starting fresh, and checking that your environment is ready.
   • What do I do when I run into the EEXIST error?
   • How do I uninstall the CLI or start fresh?
   • How do I check that my environment is ready?
2. Coding agents. Which agents the CLI supports and how to choose one.
   • Do I have to use Claude?
3. Pushing to Contentful. Whether you can push your saved files later.
   • Can I push my saved files later?
4. Debug logs and saved files. Where the CLI writes its logs and how to change them.
   • Where is the debug log?

Installation

These questions cover installing the CLI, removing it, and checking that your machine is ready to run it.

What do I do when I run into the EEXIST error?

The EEXIST: file already exists error means npm could not install the CLI because a file with the same name is already where npm wants to put the experiences command. An earlier install or link of the CLI usually left it there. You see it when you run npm install -g @contentful/experience-design-system-cli.

Remove the earlier install, then install again:

npm uninstall -g @contentful/experience-design-system-cli
npm install -g @contentful/experience-design-system-cli

If the error comes back, tell npm to replace the file:

npm install -g @contentful/experience-design-system-cli --force

Then run experiences --version to confirm the install worked.

How do I uninstall the CLI or start fresh?

To uninstall the CLI, run:

npm uninstall -g @contentful/experience-design-system-cli

To start fresh, you can also remove what the CLI saved on your computer. Deleting these files doesn’t change anything in Contentful.

• Settings and credentials. These are in the ~/.contentful/experience-design-system-cli folder in your home folder. If you delete it, you enter your space ID, environment ID, CMA token, and agent again in Settings the next time you open the CLI.
• Import output. Each import saves files such as components.json and tokens.json in a .contentful folder, in your project or in your Root Project Directory. Delete that folder if you no longer need the saved files.

How do I check that my environment is ready?

You need the following:

• Node.js 24 or later. Run node --version.
• A coding agent that is installed and signed in. Run the agent’s own command, such as claude --version, codex --version, opencode --version, cursor-agent --version, or copilot --version. Then make sure you’re signed in by using the agent’s own sign-in flow.

You can also check your agents inside the CLI. Open Settings > Configuration > Agents. For each agent, the screen shows whether the CLI can find the command, and its version. For Claude Code, it also shows whether you’re signed in. For the other agents, the screen shows “installed, login unknown”. To confirm that one of them is signed in, press the right arrow to open it and run a test.

For install links and step-by-step setup, see the prerequisites in Getting started.

Coding agents

These questions cover which coding agents the CLI works with and how to choose one.

Do I have to use Claude?

No. The CLI supports the following coding agents: Claude Code, Codex, OpenCode, Cursor, and GitHub Copilot.

To choose the agent the import uses, open Settings from the CLI home screen, go to Configuration, then Agents, move to an agent, and press Enter to make it the default. For more about the Settings menu, see the Command reference.

Pushing to Contentful

These questions cover what happens to your files after the CLI saves them.

Can I push my saved files later?

No. There is currently no supported way to push a saved components.json later.

The import saves components.json to your computer before it pushes. The CLI has no command that pushes an existing file, and every import generates new files from your code rather than reusing saved ones. To get your components into Contentful, run the import again and complete it with valid credentials. The CLI requires valid credentials to continue, so there is no way to skip them.

Debug logs and saved files

These questions cover what the CLI writes to your computer while it runs.

Where is the debug log?

Debug logging is on by default. To check it or change it, open Settings from the CLI home screen, then Debug Mode. You can turn logging off and choose how long the CLI keeps logs: 7, 14, or 30 days. The default is 30.

The CLI writes a Markdown log for each screen of your import. Each log records what you chose, what the step produced, and whether it succeeded. The CLI replaces your CMA token in the logs with a note that one is set.

Logs are in this folder:

<root>/.contentful/<MM-DD-YYYY>-session-<n>/debug/

<root> is the Root Project Directory from Settings > Configuration > Project. If you haven’t set one, it’s the project you’re importing. Each time you start the CLI, it creates a new session-<n> folder for that day. The same session folder also holds a dsi-import-<n> folder for each import, with the files that import saved, including components.json.

When Debug Mode is off, the CLI writes no logs, and the import saves its files to <project>/.contentful/.

The Help screen on the CLI home screen shows these locations for your settings.

Next steps

• Getting started — Install the CLI, configure it, and run your first import.
• Import flow — Learn what each step of the import does.
• Command reference — Learn how to start the CLI, and understand the Settings menu.