dev
engine-dmo dev: Local development: the serve, check and apply loop, and the authoring verbs. Every subcommand, argument and flag.
Local development: the serve, check and apply loop, and the authoring verbs.
| Command | What it does |
|---|---|
engine-dmo dev config set | Set one value in a configuration file (search.driver meilisearch), checked like any verb |
engine-dmo dev config unset | Remove one key from a configuration file, checked like any verb |
engine-dmo dev endpoint add | Add a declared endpoint from a recipe (recipe:enquiry, recipe:newsletter) |
engine-dmo dev field add | Add a field to a type, or a custom field to organisation or person, with its id |
engine-dmo dev field remove | Remove a field; its values stay under its id, and the plan says how many documents hold one |
engine-dmo dev field rename | Rename a field: its handle changes, its id and values stay, the old handle stays an alias |
engine-dmo dev field set | Change a field’s label, help or a parameter |
engine-dmo dev group add | Add a group to a type’s editor layout |
engine-dmo dev importer rename | Rename a importer: its key changes in importers.yaml and in every endpoint step naming it, and its id, with what is stored under it, stays |
engine-dmo dev locale add | Declare a locale in locales.yaml with its id, and enable it on a site |
engine-dmo dev network add | Declare a network in networks.yaml with its id, and join sites to it |
engine-dmo dev option add | Add an option, with its id, to a select field, or a style to a link field |
engine-dmo dev portal action add | Declare a portal action on a site, with its id, target, fields, permission and tiers |
engine-dmo dev portal screen add | Declare a portal screen on a site, with its id, path, template, permission, tiers and data; --scaffold writes its template |
engine-dmo dev role add | Declare a partner role in portal/roles.yaml with its id and grants; a built-in key restates that role with the grants given |
engine-dmo dev route add | Route a type on a site, with its id; --scaffold writes its template |
engine-dmo dev site add | Add a site directory with its site.yaml and routes.yaml |
engine-dmo dev site rename | Rename a site: its directory moves, its id and data stay, old admin and public URLs redirect |
engine-dmo dev slot add | Declare a promotion slot on a site, with its id, the types it promotes, its capacity and its rules |
engine-dmo dev source rename | Rename a source: its key changes in sources.yaml and in every endpoint step naming it, and its id, with what is stored under it, stays |
engine-dmo dev status | What engine-dmo dev up last found: the check, the plan, live aliases, the address and the images the sizing check found oversized |
engine-dmo dev tier add | Declare a membership tier in memberships.yaml with its id, ranked last or after another tier |
engine-dmo dev tier rename | Rename a tier: its key changes in memberships.yaml and every rule naming it, its id and memberships stay |
engine-dmo dev type add | A custom type with a title, a slug and a summary |
engine-dmo dev up | Serve with the config watcher: on every change write missing ids, check, plan, apply what is safe and reload |
engine-dmo dev webhook rename | Rename a webhook: its key changes in webhooks.yaml and in every endpoint step naming it, and its id, with what is stored under it, stays |
How the verbs behave
Each authoring verb makes its change in a copy of the configuration, loads that copy the way check does, and writes the files only when the configuration is still valid; otherwise it prints the problems and exits 3 with nothing was written. It writes the ids of the elements it adds, so never write an id by hand. --dry-run prints the diff and writes nothing.
The verbs run without a database and without the deployment’s secrets (see Commands and the environment), in development, in staging only with dev.authoring: true, and never in production.
What the configuration check does not cover, and how to finish the job:
| Verb | What happens | What to do |
|---|---|---|
dev endpoint add | Writes endpoints.yaml and exits 0, saying the recipe’s templates are the site’s to write. check then fails until the response partials and mail templates exist | Write the templates the message names, then run check |
dev route add --scaffold | Writes routes.yaml first, then the entry template, which loads the whole configuration. With DATABASE_URL (or another variable without a default) unset, the route is written and the command exits 3 with no template. Run again, it answers nothing to change and still writes no template | Set the placeholders from Commands and the environment first. If the route is already written, run engine-dmo new template <type>/entry.html |
dev route add --index ... --scaffold | Writes <type>/entry.html only. check then fails: type "walk" has an index route and no walk/index.html | Run engine-dmo new template <type>/index.html. The file it writes is an empty block with no heading; give it an h1 and the list before you render it |
dev field add <core type> ... --after <core field> | On a core type (page, article and the other built-in types) whose config/schema/<type>.yaml already exists, --after names only fields in that file: --after names "slug", which is not a field in schema/page.yaml, exit 3 | Leave out --after (the field goes last), or name a field you added. engine-dmo describe type <type> lists the core fields, marked core |
dev config set rewrites the map it changes and may reorder its keys (setting site.name.cy can put cy before en). The order has no meaning.
engine-dmo dev config set
Set one value in a configuration file (search.driver meilisearch), checked like any verb.
engine-dmo dev config set <file> <path> <value> [flags] | Argument | Required | Repeatable |
|---|---|---|
file | yes | no |
path | yes | no |
value | yes | no |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--apply | bool | after writing, apply the schema plan when it is not destructive | |
--dry-run | bool | print the diff of every file it would change, and write nothing |
--json prints the text output in the JSON envelope. Runs in a project.
engine-dmo dev config unset
Remove one key from a configuration file, checked like any verb.
engine-dmo dev config unset <file> <path> [flags] | Argument | Required | Repeatable |
|---|---|---|
file | yes | no |
path | yes | no |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--apply | bool | after writing, apply the schema plan when it is not destructive | |
--dry-run | bool | print the diff of every file it would change, and write nothing |
--json prints the text output in the JSON envelope. Runs in a project.
engine-dmo dev endpoint add
Add a declared endpoint from a recipe (recipe:enquiry, recipe:newsletter)
engine-dmo dev endpoint add <key> [flags] | Argument | Required | Repeatable |
|---|---|---|
key | yes | no |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--apply | bool | after writing, apply the schema plan when it is not destructive | |
--dry-run | bool | print the diff of every file it would change, and write nothing | |
--from | string | recipe:enquiry | the recipe |
--site | string | the site (default: the default site) | |
--subject | string | for an enquiry, the type it is about, taken from the path |
--json prints the text output in the JSON envelope. Runs in a project.
engine-dmo dev field add
Add a field to a type, or a custom field to organisation or person, with its id.
engine-dmo dev field add <type> <name> [flags] | Argument | Required | Repeatable |
|---|---|---|
type | yes | no |
name | yes | no |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--after | string | place it after this field | |
--apply | bool | after writing, apply the schema plan when it is not destructive | |
--dry-run | bool | print the diff of every file it would change, and write nothing | |
--group | string | add it to this group of the editor | |
--help-text | string | its help text in the source locale | |
--index | bool | projected for listing, filtering and sorting | |
--label | string | its label in the source locale | |
--options | strings | a select’s option values, each given an id | |
--param | string, repeatable | a type parameter as key=value in YAML (max=280, multiline=true); repeatable | |
--required | bool | required at publish | |
--site | string | a field this site alone offers, on a shared type | |
--translate | string | none | locale | language | group | |
--type | string | the field type (engine-dmo describe fieldtypes) |
--json prints the text output in the JSON envelope. Runs in a project.
engine-dmo dev field remove
Remove a field; its values stay under its id, and the plan says how many documents hold one.
engine-dmo dev field remove <type> <name> [flags] | Argument | Required | Repeatable |
|---|---|---|
type | yes | no |
name | yes | no |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--apply | bool | after writing, apply the schema plan when it is not destructive | |
--dry-run | bool | print the diff of every file it would change, and write nothing |
--json prints the text output in the JSON envelope. Runs in a project.
engine-dmo dev field rename
Rename a field: its handle changes, its id and values stay, the old handle stays an alias.
engine-dmo dev field rename <type> <old> <new> [flags] | Argument | Required | Repeatable |
|---|---|---|
type | yes | no |
old | yes | no |
new | yes | no |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--apply | bool | after writing, apply the schema plan when it is not destructive | |
--dry-run | bool | print the diff of every file it would change, and write nothing | |
--no-alias | bool | do not keep the old handle as an alias |
--json prints the text output in the JSON envelope. Runs in a project.
engine-dmo dev field set
Change a field’s label, help or a parameter.
engine-dmo dev field set <type> <name> [flags] | Argument | Required | Repeatable |
|---|---|---|
type | yes | no |
name | yes | no |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--apply | bool | after writing, apply the schema plan when it is not destructive | |
--dry-run | bool | print the diff of every file it would change, and write nothing | |
--help-text | string | its help text in the source locale | |
--label | string | its label in the source locale | |
--param | string, repeatable | set key=value on the field (required=true, max=120); repeatable |
--json prints the text output in the JSON envelope. Runs in a project.
engine-dmo dev group add
Add a group to a type’s editor layout.
engine-dmo dev group add <type> <key> [flags] | Argument | Required | Repeatable |
|---|---|---|
type | yes | no |
key | yes | no |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--apply | bool | after writing, apply the schema plan when it is not destructive | |
--dry-run | bool | print the diff of every file it would change, and write nothing | |
--fields | strings | the fields it holds, in order | |
--label | string | the group’s label in the source locale |
--json prints the text output in the JSON envelope. Runs in a project.
engine-dmo dev importer rename
Rename a importer: its key changes in importers.yaml and in every endpoint step naming it, and its id, with what is stored under it, stays.
engine-dmo dev importer rename <old> <new> [flags] | Argument | Required | Repeatable |
|---|---|---|
old | yes | no |
new | yes | no |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--apply | bool | after writing, apply the schema plan when it is not destructive | |
--dry-run | bool | print the diff of every file it would change, and write nothing | |
--site | string | the site whose importers.yaml it is; omitted, the default site |
--json prints the text output in the JSON envelope. Runs in a project.
engine-dmo dev locale add
Declare a locale in locales.yaml with its id, and enable it on a site.
engine-dmo dev locale add <code> [flags] | Argument | Required | Repeatable |
|---|---|---|
code | yes | no |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--apply | bool | after writing, apply the schema plan when it is not destructive | |
--dry-run | bool | print the diff of every file it would change, and write nothing | |
--fallback | strings | locales it falls back to, in order | |
--label | string | the locale’s name in its own language | |
--site | string | enable it on this site |
--json prints the text output in the JSON envelope. Runs in a project.
engine-dmo dev network add
Declare a network in networks.yaml with its id, and join sites to it.
engine-dmo dev network add <key> [flags] | Argument | Required | Repeatable |
|---|---|---|
key | yes | no |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--apply | bool | after writing, apply the schema plan when it is not destructive | |
--dry-run | bool | print the diff of every file it would change, and write nothing | |
--name | string | the network’s name in the source locale | |
--site | strings | a site to join the network; repeatable |
--json prints the text output in the JSON envelope. Runs in a project.
engine-dmo dev option add
Add an option, with its id, to a select field, or a style to a link field.
engine-dmo dev option add <type> <field> <value> [flags] | Argument | Required | Repeatable |
|---|---|---|
type | yes | no |
field | yes | no |
value | yes | no |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--apply | bool | after writing, apply the schema plan when it is not destructive | |
--class | string | a link style’s class | |
--dry-run | bool | print the diff of every file it would change, and write nothing | |
--label | string | the option’s label in the source locale |
--json prints the text output in the JSON envelope. Runs in a project.
engine-dmo dev portal action add
Declares a portal action in config/sites/<site>/portal.yaml: a form posted to {portal path}/actions/<key>. The key is <subject>.<verb>, the verb one of create, update, remove, add, submit, request, invite. The target is one of --document <type> (with --create for a new document of the active organisation, or the document named by ?id=), --organisation or --person (their custom fields, named custom.<name>). --can is the permission a partner’s role must grant (default action.<key>), and --tiers or --min-tier the tiers whose organisations may use it (default every tier and none).
engine-dmo dev portal action add <subject.verb> [flags] Available in engine-dmo only.
| Argument | Required | Repeatable |
|---|---|---|
subject.verb | yes | no |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--apply | bool | after writing, apply the schema plan when it is not destructive | |
--approval | string | tier (the tier’s member_editable rule, the default) or required | |
--can | string | the partner permission the action needs (default action.<key>) | |
--create | bool | with --document, create a new document of the active organisation | |
--document | string | a document target: the type it writes | |
--dry-run | bool | print the diff of every file it would change, and write nothing | |
--fields | strings | the fields it writes; repeatable or comma separated | |
--label | string | the action’s name in the source locale, where a screen lists it | |
--min-tier | string | the lowest tier that may use it, and every tier ranked above | |
--organisation | bool | write the active organisation’s custom fields | |
--person | bool | write the signed-in person’s custom fields | |
--rate-limit | string | a limit such as 20/hour/person | |
--respond | string | a reference screen to redirect to after a good post | |
--site | string | the site (default: the default site) | |
--tiers | strings | the tiers whose organisations may use it, none included; repeatable or comma separated |
--json prints the text output in the JSON envelope. Runs in a project.
engine-dmo dev portal screen add
Declares a portal screen in config/sites/<site>/portal.yaml: a page under the portal path rendered from a template
under the site's portal template directory, with declared data the engine reads scoped to the partner's organisation.
--path carries {org}, {id} or neither (default /organisations/{org}/<key>); --template defaults to <key>.html.
--data is repeatable: a name, the source and its parameters, such as
--data 'offers=documents type=offer states=draft,published sort=-updatedAt limit=50'
The sources are documents, document, published, report, enquiries, pending, people, membership, organisation, promotions, first_session.
A key that is a reference screen's (dashboard, organisation, report, contact_details, people, membership, contact_team, enquiries, events, promotions, listing_edit, photos, hours) replaces that screen's template
and takes only --template. engine-dmo dev portal screen add <key> [flags] Available in engine-dmo only.
| Argument | Required | Repeatable |
|---|---|---|
key | yes | no |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--apply | bool | after writing, apply the schema plan when it is not destructive | |
--can | string | the partner permission the screen needs (default screen.<key>) | |
--data | string, repeatable | a data source: ‘<name>=<source> [<param>=<value>…]’; repeatable | |
--dry-run | bool | print the diff of every file it would change, and write nothing | |
--min-tier | string | the lowest tier that may open it, and every tier ranked above | |
--nav-group | string | put the screen in the portal navigation under this group (default business with --nav-order) | |
--nav-order | int | 0 | the screen’s place in its navigation group |
--path | string | the path under the portal path, with {org}, {id} or neither (default /organisations/{org}/<key>) | |
--scaffold | bool | write the screen’s template under the site’s first template root, unless the chain already has it | |
--site | string | the site (default: the default site) | |
--template | string | the template under the site’s portal template directory (default <key>.html) | |
--tiers | strings | the tiers whose organisations may open it, none included; repeatable or comma separated | |
--title | string | the screen’s title in the source locale, which the navigation shows |
--json prints the text output in the JSON envelope. Runs in a project.
engine-dmo dev role add
Declares a partner role: what a person may do for an organisation in the portal and the member API. --can takes the permissions it grants (profile.update, organisation.update, listing.update, photos.add, photos.remove, hours.update, event.submit, people.invite, people.manage, promotion.request, billing.pay, enquiries.manage, report.view, enquiries.view, membership.view, pending.view) and patterns such as listing.* or *. A key that is owner, manager, contact or billing restates the built-in role, which keeps the engine’s id; owner always holds every permission.
engine-dmo dev role add <key> [flags] Available in engine-dmo only.
| Argument | Required | Repeatable |
|---|---|---|
key | yes | no |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--apply | bool | after writing, apply the schema plan when it is not destructive | |
--can | strings | a permission or pattern the role grants; repeatable or comma separated | |
--dry-run | bool | print the diff of every file it would change, and write nothing | |
--label | string | the role’s name in the source locale |
--json prints the text output in the JSON envelope. Runs in a project.
engine-dmo dev route add
Route a type on a site, with its id; --scaffold writes its template.
engine-dmo dev route add <type> <uri> [flags] | Argument | Required | Repeatable |
|---|---|---|
type | yes | no |
uri | yes | no |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--apply | bool | after writing, apply the schema plan when it is not destructive | |
--dry-run | bool | print the diff of every file it would change, and write nothing | |
--index | string | the index route’s uri | |
--scaffold | bool | write the type’s template from its fields (engine-dmo new template) | |
--site | string | the site (default: the default site) |
--json prints the text output in the JSON envelope. Runs in a project.
engine-dmo dev site add
Add a site directory with its site.yaml and routes.yaml.
engine-dmo dev site add <key> [flags] | Argument | Required | Repeatable |
|---|---|---|
key | yes | no |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--apply | bool | after writing, apply the schema plan when it is not destructive | |
--domain | strings | a host the site answers; repeatable | |
--dry-run | bool | print the diff of every file it would change, and write nothing | |
--locales | strings | the locales it enables, the first its default | |
--name | string | the site’s name | |
--network | string | the network it joins, declared when new; omitted, the default network |
--json prints the text output in the JSON envelope. Runs in a project.
engine-dmo dev site rename
Rename a site: its directory moves, its id and data stay, old admin and public URLs redirect.
engine-dmo dev site rename <old> <new> [flags] | Argument | Required | Repeatable |
|---|---|---|
old | yes | no |
new | yes | no |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--apply | bool | after writing, apply the schema plan when it is not destructive | |
--dry-run | bool | print the diff of every file it would change, and write nothing |
--json prints the text output in the JSON envelope. Runs in a project.
engine-dmo dev slot add
Declares a slot in config/sites/<site>/promotions.yaml: a place on the site’s pages where a promotion can appear, rendered by promoted(‘<key>’) and labelled by promotionLabel(item). --types names the document types it may promote; --capacity how many are live at once (default 1); --min-days and --max-days bound a promotion’s length; --lead-time is the earliest a request may start after it is made (3d); --tiers or --min-tier say whose organisations may request it (default every tier and none); --price is shown to the partner, with --currency (default the site’s) and --per week, day or placement.
engine-dmo dev slot add <key> [flags] Available in engine-dmo only.
| Argument | Required | Repeatable |
|---|---|---|
key | yes | no |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--apply | bool | after writing, apply the schema plan when it is not destructive | |
--capacity | int | 0 | how many promotions are live in it at once (default 1) |
--currency | string | the price’s currency (default the site’s) | |
--dry-run | bool | print the diff of every file it would change, and write nothing | |
--lead-time | string | the earliest a request may start after it is made, such as 3d | |
--max-days | int | 0 | the longest promotion in days (default no limit) |
--min-days | int | 0 | the shortest promotion in days (default 1) |
--min-tier | string | the lowest tier that may request it, and every tier ranked above | |
--name | string | the slot’s name in the source locale, as staff and partners see it | |
--per | string | what the price is for: week, day or placement (default placement) | |
--price | string | the price shown to the partner, a decimal such as 150.00 | |
--site | string | the site (default: the default site) | |
--tiers | strings | the tiers whose organisations may request it, none included; repeatable or comma separated | |
--types | strings | the document types it may promote; repeatable or comma separated |
--json prints the text output in the JSON envelope. Runs in a project.
engine-dmo dev source rename
Rename a source: its key changes in sources.yaml and in every endpoint step naming it, and its id, with what is stored under it, stays.
engine-dmo dev source rename <old> <new> [flags] | Argument | Required | Repeatable |
|---|---|---|
old | yes | no |
new | yes | no |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--apply | bool | after writing, apply the schema plan when it is not destructive | |
--dry-run | bool | print the diff of every file it would change, and write nothing | |
--site | string | the site whose sources.yaml it is; omitted, the default site |
--json prints the text output in the JSON envelope. Runs in a project.
engine-dmo dev status
What engine-dmo dev up last found: the check, the plan, live aliases, the address and the images the sizing check found oversized.
engine-dmo dev status --json prints the command’s own JSON document. Runs in a project.
engine-dmo dev tier add
Declare a membership tier in memberships.yaml with its id, ranked last or after another tier.
engine-dmo dev tier add <key> [flags] Available in engine-dmo only.
| Argument | Required | Repeatable |
|---|---|---|
key | yes | no |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--after | string | rank it directly above this tier; omitted, it ranks highest | |
--apply | bool | after writing, apply the schema plan when it is not destructive | |
--dry-run | bool | print the diff of every file it would change, and write nothing | |
--label | string | the tier’s name in the source locale |
--json prints the text output in the JSON envelope. Runs in a project.
engine-dmo dev tier rename
Rename a tier: its key changes in memberships.yaml and every rule naming it, its id and memberships stay.
engine-dmo dev tier rename <old> <new> [flags] Available in engine-dmo only.
| Argument | Required | Repeatable |
|---|---|---|
old | yes | no |
new | yes | no |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--apply | bool | after writing, apply the schema plan when it is not destructive | |
--dry-run | bool | print the diff of every file it would change, and write nothing |
--json prints the text output in the JSON envelope. Runs in a project.
engine-dmo dev type add
A custom type with a title, a slug and a summary.
engine-dmo dev type add <key> [flags] | Argument | Required | Repeatable |
|---|---|---|
key | yes | no |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--apply | bool | after writing, apply the schema plan when it is not destructive | |
--dry-run | bool | print the diff of every file it would change, and write nothing | |
--label | string | the type’s name in the source locale | |
--plural | string | its plural | |
--site | string | declare it in this site’s schema directory, so it is that site’s alone | |
--sites | strings | declare it in config/schema/ on these sites only (sites:); each site’s directory may then extend it |
--json prints the text output in the JSON envelope. Runs in a project.
engine-dmo dev up
dev up runs serve --dev and watches config/. On a change it writes any missing ids (engine-dmo check --fix), loads and checks the whole project, computes the schema plan, and applies it if it is not destructive, then reloads the engine in this process. A failed check or a destructive plan leaves the engine on the last good configuration and prints why. engine-dmo dev status reads what it last found.
engine-dmo dev up [flags] | Flag | Type | Default | Meaning |
|---|---|---|---|
--listen | string | override server.listen |
--json prints the text output in the JSON envelope. Runs in a project.
engine-dmo dev webhook rename
Rename a webhook: its key changes in webhooks.yaml and in every endpoint step naming it, and its id, with what is stored under it, stays.
engine-dmo dev webhook rename <old> <new> [flags] | Argument | Required | Repeatable |
|---|---|---|
old | yes | no |
new | yes | no |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--apply | bool | after writing, apply the schema plan when it is not destructive | |
--dry-run | bool | print the diff of every file it would change, and write nothing | |
--site | string | the site whose webhooks.yaml it is; omitted, the default site |
--json prints the text output in the JSON envelope. Runs in a project.
describe
engine-dmo describe: Describe the project, a content type, the field types, a route or a template, with ids, as text or --json. Every subcommand, argument and flag.
docs
engine-dmo docs: The template API of this project, and the skill that points an agent at the handbook. Every subcommand, argument and flag.