The development loop

Working on a project is a short loop: change a file, let the engine check and apply it, look at the page, repeat. This page lists the commands in that loop, what each needs, and how to read what it prints.

Run the site while you workCopy Anchor Link

engine-dmo dev up

flowchart TD
  save["You save a file in config/"] --> ids["Write missing ids"]
  ids --> check{"Project checks?"}
  check -- no --> keep["Keep serving the last good configuration<br/>and print the errors"]
  check -- yes --> plan{"Schema plan destructive?"}
  plan -- yes --> hold["Keep serving; print the plan<br/>for you to approve and apply"]
  plan -- no --> apply["Apply the plan"]
  apply --> reload["Reload the engine"]

Development mode, in both:

• reparses a template on every request, so a template change shows on reload;
• shows the development error page, with the template, line and context of a failure;
• starts each extension’s development server as a child process (the vite extension runs Vite);
• watches the configuration;
• serves Go’s profiler at /_debug/pprof/.

The admin is at /studio, the public sites at their configured domains (localhost answers for the default site).

Change configuration with the dev verbsCopy Anchor Link

You can edit the YAML by hand, but the engine-dmo dev verbs are safer: each edits the files keeping their comments, writes the new element’s id, and checks the configuration it changed. A change that would make the configuration invalid (an unknown field type, an unknown option) is refused with nothing was written and exit 3. With dev up running, the change is applied as soon as the verb writes it.

A verb does not count templates, so it can exit 0 and leave check failing:

• dev route add writes the route even though the type has no entry.html (or no index.html for --index) yet.
• dev endpoint add writes the endpoint; the recipe’s partials and mail templates are yours to write, and it says so.

Run engine-dmo check --no-db after every verb.

engine-dmo dev type add walk --label Walk --plural Walks
engine-dmo dev field add walk distance --type number --label Distance
engine-dmo dev route add walk "/walks/{slug}" --index /walks --scaffold
engine-dmo new template walk/index.html
engine-dmo dev field rename walk distance lengthKm

--scaffold writes the type’s entry.html from its fields. It does not write index.html: a route with an index also needs <type>/index.html, which engine-dmo new template walk/index.html starts for you, and check refuses the route until it exists. The scaffolded index is an empty body block with no heading, so fill it in before you check a page’s accessibility.

Every verb takes --dry-run, which prints the diff of every file it would change and writes nothing, and --apply, which applies the schema plan afterwards when it is not destructive (use it when dev up is not running).

engine-dmo adds dev tier, dev role, dev portal and dev slot for the DMO modules. engine-dmo help --json lists every verb with its arguments and flags. When a project has AGENTS.md or the agent skills, the verbs regenerate them after each change.

Check the projectCopy Anchor Link

engine-dmo check

check is the gate to run before every commit and in CI. It validates every configuration file, the schema, every template and the deployment settings, and prints every problem at once (seed verify checks the seed):

config/sites/main/routes.yaml:2:11: route "page" has no id
    2 |   - type: page
      |           ^^^^
      = run engine-dmo check --fix to write one; ids are written by the tooling, never by hand
      = error code MRD-1006

1 error, 0 warnings. Configuration is not valid.

check prints template findings first, one line each (_shared/base.html:3:1: warning: ...), then every diagnostic in full with its source line. An error can therefore appear twice, once in each form.

Every error carries an error code (MRD-1006 above); Error codes explains each.

engine-dmo config validate checks only the configuration files, and engine-dmo config render prints the configuration as the engine resolved it, every default filled in and secrets redacted.

Plan and apply schema changesCopy Anchor Link

The database holds a copy of your schema: types, fields, locales, sites, routes, roles and grants, each by its id. schema plan compares the files with it; schema apply makes the database match.

engine-dmo schema plan
engine-dmo schema apply

schema plan is read-only and exits 2 when changes are pending, 0 when there are none. Each line is one change:

A change marked [DESTRUCTIVE: ...] loses data or access: a removed field that documents hold values in, or a grant whose removal takes a permission from active users. schema apply runs the whole plan in one transaction and refuses a destructive plan unless it is approved.

Destructive changesCopy Anchor Link

Approve a destructive plan in one of two ways:

• An approval file. The plan prints its digest; write it to config/schema/.destructive-approved (or the path schema.destructive_approval names) and run engine-dmo schema apply. A different plan has a different digest, so the approval covers exactly the plan you reviewed.
• Interactively. engine-dmo schema apply --allow-destructive shows the plan and asks you to confirm; add --yes where no terminal can ask.

A removed field’s values are not deleted: they stay in each document’s revisions, kept under _orphaned with the field’s id, and nothing is dropped silently.

ReplacementsCopy Anchor Link

A ! line means an element in the files has a new id but an old handle. That is almost always a copied block whose id came with it. Put the stored id back in the file to keep the stored element, or, when you really mean a new element, apply with --replace <type>.<field> for each one named.

RefusalsCopy Anchor Link

schema apply refuses a plan that would leave nobody able to manage users or holding the owner role, even with --allow-destructive. A plan line under NOT YET is a change this engine version cannot apply; undo it in the files to apply the rest.

MigrationsCopy Anchor Link

engine-dmo migrate status   # exits 2 if any are pending
engine-dmo migrate up

Migrations create and change the engine’s own tables. They only move forward, and they are separate from your schema: a new engine version brings migrations, your configuration brings schema changes. The server refuses to start while a migration is pending. See Upgrading the engine.

Seed and reset contentCopy Anchor Link

seed verify does not validate values: a select value that is not an option, or a number below its min, passes it and fails only in seed apply. Its errors name the file but not the line, and a problem in a field is reported once per locale.

seed apply refuses a database that already holds documents or media, since seeding would duplicate them: run seed reset --confirm first. Its flags are --set <dir> (another seed set under seed/), --profile <name> (a profile from seed.yaml; the help text’s mention of make check refers to the engine’s own test suite, not your project), --scale small|medium|large (the volume of generated analytics) and --timeout. In production it refuses unless the database is empty and you pass --i-know-what-i-am-doing, and it never creates seed users there.

You can also write content from the command line: engine-dmo content create, content update, content publish and content get take and print JSON. The CLI reference lists them.

Look at what the engine seesCopy Anchor Link

Every command takes --json. “The project files” means the files are read and no variable need be set; “Configuration” means the whole configuration must load, which needs every ${VAR} without a default to be set (a placeholder value is enough); “a database” means one that is migrated and has the schema applied. describe project and describe type show the core fields of a core type (page has only title and slug) and the fields you added.

render and describe route write the engine’s start-up log lines to standard error before their result, and before failing when the database cannot be reached; with --json, standard output holds only the JSON. A path the site does not answer renders with status 404: the home page answers /, and its slug path (/home) is not found.

The usual way to write a template: describe route <path> --json for the context it receives, write it, then render <path> --json to see the result and any errors.

Scaffold filesCopy Anchor Link

engine-dmo new writes starting files you then edit:

--site <key> writes into that site’s template root; --force overwrites.

Editor supportCopy Anchor Link

• Configuration: init maps each configuration file to its JSON Schema for VS Code and Zed. engine-dmo config schema --write rewrites them after an engine upgrade, and engine-dmo config schema --file site prints one kind of file’s schema. --file takes a kind (engine, locales, site, routes, schema, endpoints and the rest) or a real path such as config/sites/main/site.yaml; a bare file name such as site.yaml is refused with the list of kinds.
• Templates: engine-dmo lsp is a language server on standard input and output. It gives check’s diagnostics as you type, completion, hover and go to definition. Configure your editor to start it in the project directory. It refuses a production project.

Read the guide and the handbookCopy Anchor Link

engine-dmo guide                        # this project: rules, sites, types, fields, template roots and filters
engine-dmo guide --out AGENTS.md        # the same, to a file
engine-dmo docs serve                   # this project's template API at http://127.0.0.1:6061

guide is generated from the project’s schema, routes and the engine’s template contract, so it is always current; regenerate it after any change rather than editing it. --skill writes it with skill front matter. docs serve takes --listen and --site (one site’s template API only).

Build the frontendCopy Anchor Link

engine-dmo build

Runs the project’s package.json build script (or --command), then engine-dmo check (--no-check to skip it, --no-db and --strict passed to check).

A typical sessionCopy Anchor Link