Craft

CDF Import & Export

CDF (Craft Data Format) is Craft's portable project format. A CDF file is just a .md or .json file that contains metadata that helps us map it to and from your Craft project. A Workspace CDF is a zip of a whole project: the CDF files in real folders that mirror the project's folders, plus a .craft/ directory carrying the project's file type definitions and settings. Because a Workspace CDF is just files in folders, anything that can edit files — a text editor, a coding agent, a script — can work on your project.

What you can do with it

  • Download a complete, editable backup of your project.
  • Edit your world locally with a coding agent such as Claude Code or Codex, then import the changes back.
  • Share a whole project as a single file someone else can import, or send a fork's changes back to the original project.
  • Move worlds in from other tools — Friends & Fables exports Workspace CDFs directly.
  • Import one file, a handful of files, or a hand-built folder of new material — an import doesn't have to be a full workspace.

Exporting your project

Open your project's settings, choose the CDF Import/Export tab, and click Export CDF. Craft downloads the whole project as a zip that unpacks into a normal folder: 

my-world/
  Heroes/
    Aragorn.character.json
  Lore/
    Fall of Gondor.note.md
  .craft/          — file type definitions, project settings, sync state
  AGENTS.md        — teaches a coding agent how to edit the project
  CLAUDE.md

Content files are named Name.<type>.json or Name.<type>.md after their file type. Markdown files are plain markdown with YAML frontmatter; JSON files hold the record's structured fields. The .craft/ folder is the project's metadata — leave it in place, because it's what lets your edits flow back into the same project later. If you'd rather work git-style than through zips, the Export with CLI button on the same tab sets up the Craft CLI instead.

Editing locally with a coding agent

Unzip the download and open the folder in your coding agent — the Claude Code or Codex desktop apps (no terminal needed), or a terminal agent like Claude Code, Codex, opencode, Cursor, or the Gemini CLI. Then simply describe what you want changed. The AGENTS.md in the folder teaches the agent the file format, the schemas, and the editing rules automatically, so there is no prompt to paste.

Run the session locally on your computer (open the folder from your machine), not in a cloud environment — cloud sandboxes can't see your local files.

Unzip the download, then open the unzipped folder as a workspace in the Claude Code desktop app and describe the changes you want. No terminal needed — the AGENTS.md in the folder teaches it the file format and editing rules automatically.

Unzip the download, then move into the folder:

cd ~/Downloads/my-world

Start Claude Code there:

claude

Then simply describe the changes you want. If you don't have the CLI yet, install it first with npm install -g @anthropic-ai/claude-code.

Codex (desktop or CLI), opencode, Cursor, and the Gemini CLI all work the same way: open the unzipped folder in the agent and ask away. They each read the AGENTS.md automatically, so there is no prompt to paste.

The export card's How to edit with Claude Code, Codex, and other coding agents section walks through the exact steps for each agent, including where to type the commands if you've never used a terminal.

Getting your changes back

Two ways, both on the same settings tab:

  • Re-upload the zip — compress the edited folder and drop it on the import panel below the export card.
  • Sync with the Craft CLI — run craft push from inside the folder: no re-zipping, and the folder stays connected for next time. See The Craft CLI.

Imports are preview-first. Craft reads the zip and shows a plan — which files it would create, which it would update, which project settings would change — and nothing is applied until you confirm. You can uncheck any file or setting you don't want. Imports never delete files: a zip is a batch of changes to land, not a mirror of the project, so anything absent from the zip is left alone. Every applied change is recorded in version history, and the panel offers to save a project version first so the state before the import is one revert away. Zips can be up to 50MB.

Single files and partial zips

The import panel accepts more than full exports:

  • A complete Workspace CDF export.
  • A partial zip — any set of Name.<type>.json / .md files; folders and the .craft/ directory are both optional.
  • A single bare .json or .md file, no zip.

Files are matched to the project by the stable id in each file's $craft block, falling back to path and type for files that don't carry one — so a re-imported file updates the file it came from even if it was renamed or moved in the app meanwhile, and unmatched files are created. If a partial zip introduces a brand-new file type, include its definition at .craft/file-types/<slug>.json and the import creates the type and its files together.

Duplicating a file to make a new one?

The $craft id is the file's identity, so a duplicated file collides with the original on import. Delete the copy's $craft block and the import will treat it as a fresh file.

Importing as a new project

To turn a Workspace CDF into a brand-new project, use the Import page — click Import Project in the header of the New Project page. Upload the zip and Craft creates the project: file types first, then folders and files, with every file validated on the way in. If some files are invalid, you get a table of exact errors to fix — or you can retry with the invalid files skipped. Imported projects are always private; you can publish or share them later.

PreviousCommand ReferenceNextContext Rot