Seeding and importing

There are four ways to put content into a project without typing it into the admin:

All of them write values in the stored shapes each field type’s page describes. For moving a whole existing site from another CMS, see Migration.

Seed setsCopy Anchor Link

A seed set is a directory, seed/ by default, that describes content by key:

A project may hold several sets, as seed/<name>/, chosen with --set <name>.

seed.yamlCopy Anchor Link

name: starter
description: The home page and three walks.
locales: [en-GB, cy-GB]
analytics:
  months: 13
  daily_views: 6
  seed: 42
profiles:
  core: [page/*, walk/cherwell-valley]

A documentCopy Anchor Link

documents/<type>/<key>.yaml. The folder is the type and the file name the key, unless the file says type: or key:.

# seed/documents/walk/cherwell-valley.yaml
site: main
locales:
  en-GB:
    title: The Cherwell valley walk
    slug: cherwell-valley-walk
    summary: Eight miles along the river and the canal, with a pub at the halfway point.
    difficulty: moderate
    distanceKm: 12.8
    startPoint: { lat: 52.0629, lon: -1.3398, precision: street }
    heroImage: { asset: valley-view }
    nearbyListings:
      - { id: hook-norton-brewery-tours, type: listing }
    stages:
      - _key: s1
        title: Banbury to Kings Sutton
        directions:
          - _type: block
            _key: s1p1
            style: normal
            markDefs: []
            children:
              - { _type: span, _key: s1p1s0, text: "Leave the town by the towpath.", marks: [] }
  cy-GB:
    title: Taith dyffryn Cherwell
    slug: taith-dyffryn-cherwell
    summary: Wyth milltir ar hyd yr afon a'r gamlas.
    stages:
      - _key: s1
        title: Banbury i Kings Sutton
publish: [en-GB, cy-GB]
tags: [walks.riverside]
history:
  - locale: en-GB
    note: First draft
    fields:
      title: Cherwell walk
      summary: A riverside walk.

Dates and times in schedule, unpublish_at and date-valued fields may be absolute (2026-03-01, 2026-03-01T09:30) or relative to the day of applying (+21d, -6m, +3d 09:00), so a demonstration stays current.

A document of a singleton type fills in its site’s singleton rather than creating a second one.

The home page named by home: { type: page, slug: home } keeps the slug home in every locale: give the Welsh block slug: home, not a translated slug, or /cy/ answers 404 (Slugs and the home page).

References by keyCopy Anchor Link

A seed never contains a database id (the UUID a record receives when it is created). Records name each other by seed key, in the shapes the fields store. Configuration ids are not database ids and are allowed: a form field is seeded with its endpoint’s id from endpoints.yaml, contactForm: end_srhmvkf6j3.

Apply creates records in dependency order and replaces each key with the id the record received. Two documents that name each other are both created, then completed.

AssetsCopy Anchor Link

Each asset is a file and a YAML file of the same name beside it under assets/, at any depth. Files may be .jpg, .jpeg, .png, .webp, .gif, .pdf, .svg or .gpx. They go through the same upload pipeline as an editor’s upload.

# seed/assets/valley-view.yaml
title: The Cherwell valley from Crouch Hill
alt: { en-GB: Fields and hedgerows falling to the river under a wide sky, cy-GB: Caeau a gwrychoedd yn disgyn i'r afon }
caption: { en-GB: Looking south from Crouch Hill }
credit: Photograph by A. Walker
focal: { x: 0.5, y: 0.4 }
tags: [walks.riverside]
rights:
  holder: A. Walker
  licence: CC BY 4.0
  until: +2y

Other recordsCopy Anchor Link

Modules add their own directories in engine-dmo (claims, promotions, affiliates and others); see each module’s page under DMO.

Organisations and peopleCopy Anchor Link

organisations/<key>.yaml is a business, and people/<key>.yaml someone in the CRM in their own right. The file name is the key a document names with its top-level organisation: <key>, unless the file says key:. Both go through the CRM store, so a seeded record is validated as a saved one is. An unknown key in these files is ignored, not refused, so check the result with seed apply’s summary (1 organisations, 2 people, 1 memberships).

# seed/organisations/old-bridge-inn.yaml
name: The Old Bridge Inn
legal_name: Old Bridge Inn Ltd
status: active
email: stay@oldbridgeinn.example
website: https://oldbridgeinn.example
phone: { raw: "01600 712345", region: GB }
address:
  country: GB
  line1: 4 Wye Bridge Street
  locality: Monmouth
  postal_code: NP25 3DY
tags: [stay.hotel]
contacts:
  - name: Sam Owner
    email: sam@oldbridgeinn.example
    role: General manager
    partner_role: owner
    is_primary: true
    started_on: -2y
  - person: pat-morgan
    role: Bookkeeper
memberships:
  - site: main
    tier: standard
    joined_on: -2y
    renews_on: +30d
    amount: "120.00"
    currency: GBP
    history:
      - { tier: gold, amount: "240.00", reason: Upgraded at the spring trade fair }
invitations:
  - email: alex@oldbridgeinn.example
    name: Alex Colleague
    role: Duty manager
    partner_role: contact
    site: main
    by: sam@oldbridgeinn.example

# seed/people/pat-morgan.yaml
name: Pat Morgan
email: pat@example.org
marketing_consent: -1y
tags: [press]

An organisation:

A contact is a person linked to the organisation. Each needs person or name.

A membership is one organisation’s tier on one site. It needs the memberships module and tiers in config/memberships.yaml.

An invitation is someone asked to join the portal, sent through the portal itself, after the documents.

A person:

Dates may be absolute or relative to the day of applying, as for documents. seed verify checks that a person and a document’s organisation name a record in the set, that each date reads and that each site exists; it does not check tier or partner_role, which only seed apply does.

CommandsCopy Anchor Link

seed verify and seed write never connect, but they load the configuration first, and every ${VAR} in engine.yaml without a default must then be set. With no database, set DATABASE_URL to any value. Once engine.yaml reads signing_key: ${SIGNING_KEY}, set SIGNING_KEY too, to a development value of at least 32 characters (server.security.signing_key must be at least 32 characters otherwise), and likewise any other secret such as an SMTP password. The engine does not read a .env file; export the variables in the shell or the CI job:

export DATABASE_URL=postgres://unused SIGNING_KEY=$(openssl rand -hex 32)
engine-dmo seed verify

What seed verify does not checkCopy Anchor Link

seed verify checks names, not values. A select value that is not an option (difficulty: trivial) or a number below the field’s min passes it with Matches the schema. Values are checked when seed apply saves and publishes the document, through the field’s validation:

• A document with publish: stops the apply at the first value that fails, naming the field: publish en refused: difficulty: "trivial" is not one of the options.
• A document without publish: is stored as a draft, and a value that would fail publishing is kept without an error. It shows up only when an editor or content update --publish publishes it.

seed verify reports a problem by file, with no line or column, and reports an unknown field once for each locale block it appears in. Its summary counts documents, assets and users, not navigation sets, though it checks them; seed apply reports the navigation it wrote (navigation: 1 sets, 3 items).

seed apply is not an upsert. It refuses when the database already holds documents or assets (the database already holds N documents and M assets; run engine-dmo seed reset first), and in production it refuses unless the database is empty and --i-know-what-i-am-doing is given.

A value that fails validation stops the apply with the field named, but what was written before it stays: the records applied earlier, and the failing document itself as a draft. The next seed apply then refuses because the database is not empty. Fix the file, then run engine-dmo seed reset --confirm and engine-dmo seed apply again.

Apply works in this order, each step naming the records of the steps before it by the ids they received. In engine-dmo the modules’ own directories (claims, promotions and the rest) are applied after the step they depend on.

flowchart LR
  v["vocabulary"] --> a["assets"] --> u["users"] --> p["people and<br/>organisations<br/>(engine-dmo)"] --> d["documents<br/>history, publish,<br/>pending, schedule"] --> n["navigation"] --> t["invitations,<br/>then trash"] --> g["generated<br/>analytics"]

Example output:

seeded starter: 4 documents, 6 revisions, 4 published, 1 assets, 1 users, 1840 analytics events

Generated documentsCopy Anchor Link

engine-dmo seed generate --type walk --count 200 --near 52.06,-1.34 --publish

Writes documents of a type whose values pass each field’s validation, from built-in word lists and placeholder images. --seed makes the run repeatable over the same database; --locale and --site choose where; --near places generated points around a latitude and longitude where a field has no bounds. A relation field needs documents or tags to point at, so generate the targets first.

seed/generate.yaml describes generated seed files as recipes with placeholders ({pick LIST}, {int A B}, {point PLACE}, {relation RECIPE}, {pt NAME N} and more), written into ordinary seed files by seed write. engine-dmo seed write --help lists every placeholder.

Creating and updating from the command lineCopy Anchor Link

engine-dmo content create --type walk --locale en-GB --data '{
  "title": "Bloxham loop",
  "slug": "bloxham-loop",
  "summary": "A short circuit from the village green.",
  "difficulty": "easy",
  "startPoint": { "lat": 52.02, "lon": -1.37 }
}'

engine-dmo content update <document id> --locale cy-GB --data '{ "title": "Cylch Bloxham" }' --publish

Both validate as the admin’s save does and refuse on an error. --publish then runs the publish checks for that locale. Relations and links name documents and assets by their database ids here. engine-dmo content get <id> shows a document’s working and published values by field name, and content list finds ids. All need a database.

Export and import between environmentsCopy Anchor Link

engine-dmo content export --type walk --site main --out walks.json
engine-dmo content import --file walks.json --site main --dry-run
engine-dmo content import --file walks.json --site main --match slug

An export writes a type’s documents on a site (or a selection with --id or --ids-from), with every locale’s working values (or those named with --locale), as JSON or, with --format csv, a CSV with one row per document and locale for reading in a spreadsheet. Only JSON can be imported. Exports are audited.

The JSON file:

{
  "format": "meridian.content.v1",
  "site": "main",
  "type": "walk",
  "exported_at": "2026-11-02T09:00:00Z",
  "documents": [
    {
      "id": "1b9f...",
      "type": "walk",
      "variant": "",
      "locales": {
        "en-GB": { "status": "published", "values": { "title": "Bloxham loop", "slug": "bloxham-loop" } }
      }
    }
  ]
}