docs menu

Migrating to Galerne

Galerne reads content from Sanity, Contentful, Storyblok, WordPress, Payload and folders of Markdown or MDX, and writes Galerne content back out in each of those formats. Imports keep your ids, so references and links survive, and they land on a branch that you review before it reaches main.

Sources#

CMSImport readsExport writes
SanityThe dataset export API, the query API for public datasets, or a .tar.gz / .ndjson fileA dataset folder and .tar.gz for sanity dataset import, plus schema types
ContentfulThe JSON file of contentful space exportA file for contentful space import, with assets
StoryblokThe delivery API (and the Management API for components), or a bundle fileStories, components and assets as JSON
WordPressA WXR file from Tools, ExportA WXR file for the WordPress importer, with attachments
PayloadThe REST API, or a bundle file; Lexical and Slate rich textData, collection configs and a seed script
MarkdownA folder of .md and .mdx files with front matterA folder of Markdown files with front matter
GalerneAn export folder (galerne-export/1)The same, on every plan: see export format

Exports write files in the other CMS's format. You load them with that CMS's own import tools; Galerne never writes into another CMS's API.

Strapi, Hygraph, Prismic and Directus are not built yet. Meanwhile, export them as Markdown files and use the Markdown source.

Import with the CLI#

The importers ship in a separate package:

bash
npm i -g @galerne/cli @galerne/migrate
galerne import --from sanity --project-id abc123 --dataset production --token sk… --dry-run
galerne import --from sanity --project-id abc123 --dataset production --token sk…
FlagWhat it does
--from <cms>sanity, contentful, storyblok, wordpress, payload or markdown
--branch <name>Target branch. Default import/<cms>-<yyyy-mm-dd>, created when missing
--dry-runRead and convert, print the report, write nothing
--since <time>Only content changed since this ISO time
--all-mediaAlso import files no document uses
other flagsOptions of the source, in kebab case: --project-id abc becomes projectId. Prefix with source- when a name clashes with a global flag: --source-token sets the source's token

Each guide lists the options of its source. Credentials are used for the run and never stored. The CLI writes to Galerne through the API, with your token. It exits with code 1 when a document fails.

What an import does#

  1. Read and convert. Documents, drafts, translations and assets come in the Galerne shape: rich text as Galerne rich text, references as { "_ref": "<id>" }, images with alt text, hotspot and crop.
  2. Infer the schema. A content model is built from what was found and merged with your deployed schema, which wins where they differ. The report includes the result as galerne.config.ts text for you to review and commit.
  3. Write to a branch. The schema change is deployed, then documents go to the branch in batches. Media used by documents are downloaded four at a time; files already in Galerne are skipped, and the same bytes under another id are reused.
  4. Report. You get the report below.
  5. Review and promote. Open the branch in the studio, run the checks, fix what they report, and promote.

Deploying the schema change needs the schema right (admins). On the Free plan, an import that would go over the document limit is refused before it writes.

The report#

json
{
  "cms": "sanity", "branch": "import/sanity-2026-10-17", "dryRun": false,
  "schema": { "configText": "import { defineConfig } …", "changes": [], "deployed": true, "languages": ["en", "fr"] },
  "types": { "post": { "created": 120, "updated": 0, "unchanged": 0, "failed": 0, "published": 118, "drafts": 4 } },
  "docs": { "total": 412, "created": 410, "updated": 0, "unchanged": 0, "failed": 2, "published": 398, "drafts": 14 },
  "references": { "total": 860, "missing": [{ "from": "post-12", "path": "author", "to": "person-9" }] },
  "assets": { "total": 96, "uploaded": 95, "existing": 0, "failed": 1, "bytes": 81234567, "missing": [] },
  "translations": { "docs": 40, "localizedFields": 3 },
  "problems": [{ "level": "warning", "message": "inline object \"footnote\" dropped", "id": "post-3", "path": "body" }],
  "skipped": [{ "id": "versions.r1.post-4", "reason": "publish the release first" }],
  "renamed": [{ "from": "post:7", "to": "post-7-1a2b3c4d" }],
  "changes": 412,
  "cursor": "2026-10-16T18:02:11Z"
}
  • Ids are kept. Ids Galerne cannot store (it allows letters, digits, ., _ and -, up to 128 characters, starting with a letter or digit) get a stable new id with a short hash, listed under renamed, and references to them are rewritten.
  • Problems list everything that did not convert exactly. Each guide says what to expect.
  • Blocks inside rich text, such as a call to action or an embedded entry, become embeds: the import adds a block type for each one, with fields inferred from the values, and lists it in the rich text field's embeds. Exports turn embeds back into the target CMS's own blocks. Content imported before embeds existed holds them as code blocks with language embed:<type>; exports and Galerne imports read those too.

Re-runs and sync#

Imports are idempotent. Running the same import again compares every document with what is stored and writes only what changed; changes is 0 when nothing did. --since limits a run to content changed after a time, and cursor in the report is the time to pass next.

To keep editors working in the old CMS while you rebuild the site, run the import on the same branch again and again. sync() in @galerne/migrate does this in code: every minute by default, it imports what changed since the last pass. Sync does not notice deletions: a document deleted in the old CMS stays in Galerne until you delete it.

Agents and the API#

The import_from and export_to tools do the same over MCP and HTTP (POST /p/<project>/v1/import/from, POST /p/<project>/v1/export/to), so an agent can run a migration and ask for review.

  • import_from takes cms, options, branch, dryRun and allMedia. Options give a URL or the data inline: local paths are refused, and fetches reach public addresses only, up to 200 MB and 60 seconds. For Markdown, pass files: [{ path, content }].
  • export_to takes cms, branch (default main), options and includeMedia. It returns the files inline, with media as URLs, or as base64 with includeMedia up to 20 MB. Use galerne export --to for larger exports.

The MCP tools page lists their inputs.

Export to another CMS#

bash
galerne export --to wordpress --out ./wp-export --site-url https://example.com

--out defaults to <cms>-export-<project>. The folder holds the files and a README.md with the command that loads them into the other CMS. The report lists what the target format cannot hold; each guide has the list.

Move content without an importer#

For a CMS with no importer, write NDJSON import lines yourself and send them to POST /v1/import. A short script is enough:

ts
import { readFileSync } from 'node:fs'

// posts.json: an array exported from your current CMS
const posts = JSON.parse(readFileSync('posts.json', 'utf8'))
const lines = posts.map((post) =>
  JSON.stringify({
    kind: 'doc',
    id: post.id,
    type: 'post',
    values: { title: post.title, slug: post.slug, body: post.markdown, publishedAt: post.date },
    publish: true,
  }),
)

const response = await fetch('https://api.galerne.cloud/p/acme/v1/import?branch=import/blog', {
  method: 'POST',
  headers: { authorization: `Bearer ${process.env.GALERNE_TOKEN}`, 'content-type': 'application/x-ndjson' },
  body: lines.join('\n'),
})
console.log(await response.json())

Rich text can be Markdown. Deploy the matching schema first, and upload media with POST /v1/media and the x-galerne-media-id header to keep their ids. The export format page describes the lines and the report.