# Migrating to Galerne

> How imports and exports between Galerne and other CMSs work, the CLI and tool options, the report, re-runs and sync, and what each direction loses.

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

| CMS | Import reads | Export writes |
|---|---|---|
| [Sanity](/docs/migrate-sanity.md) | The dataset export API, the query API for public datasets, or a `.tar.gz` / `.ndjson` file | A dataset folder and `.tar.gz` for `sanity dataset import`, plus schema types |
| [Contentful](/docs/migrate-contentful.md) | The JSON file of `contentful space export` | A file for `contentful space import`, with assets |
| [Storyblok](/docs/migrate-storyblok.md) | The delivery API (and the Management API for components), or a bundle file | Stories, components and assets as JSON |
| [WordPress](/docs/migrate-wordpress.md) | A WXR file from Tools, Export | A WXR file for the WordPress importer, with attachments |
| [Payload](/docs/migrate-payload.md) | The REST API, or a bundle file; Lexical and Slate rich text | Data, collection configs and a seed script |
| [Markdown](/docs/migrate-markdown.md) | A folder of `.md` and `.mdx` files with front matter | A folder of Markdown files with front matter |
| Galerne | An export folder (`galerne-export/1`) | The same, on every plan: see [export format](/docs/export.md) |

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…
```

| Flag | What 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-run` | Read and convert, print the report, write nothing |
| `--since <time>` | Only content changed since this ISO time |
| `--all-media` | Also import files no document uses |
| other flags | Options 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](/docs/tools.md) 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](/docs/export.md) page describes the lines and the report.
