CLI
Every engine-dmo and engine-cms command by purpose, the global flags, --json output (data or envelope), --quiet, how a command finds its project, and how to list the whole command tree as JSON.
Both binaries take the same commands, flags and arguments, except the commands of the DMO modules, which only engine-dmo has. This reference uses engine-dmo; for a core command, engine-cms behaves the same.
engine-dmo <command> [subcommand] [arguments] [flags]
engine-dmo <command> --help # one command's flags
engine-dmo help --json # every command, argument and flag, as JSON Some --help and help --json texts cite documents by internal names, such as (07-auth-and-permissions.md), (ADR-0019) or make check. Those documents are not published and those make targets are not yours; this reference and the rest of the handbook describe the same behaviour.
Global flags
Every command takes these:
| Flag | Default | Meaning |
|---|---|---|
--project | . | The project directory. Commands that need a project read config/ under it |
--config | config | The configuration directory, relative to the project |
--json | off | Machine-readable output on standard output (below) |
--quiet | off | Print only errors. A command that prints data (a list, a report, a document) still prints it |
--no-colour | off | No colour. A non-empty NO_COLOR environment variable does the same; colour is only ever used on a terminal |
Output and exit codes
Under --json every command prints exactly one JSON document on standard output, in one of two shapes:
| Shape | Commands | What it is |
|---|---|---|
| Data | Commands whose job is to return something: content get, describe type, migrate status, version, template api and the other lists, reports and documents | The command’s own document |
| Envelope | Commands that act and report what they did: migrate up, schema apply, content publish, user create and the rest | {"command": "...", "exit": 0, "error": "...", "lines": ["..."]}: the text output as lines, the exit code, and the error when there was one |
Each command’s section below says which shape it prints. Errors, warnings and prompts go to standard error. The exit code is always meaningful:
| Code | Meaning |
|---|---|
0 | Success |
1 | Error |
2 | Changes pending, or refused for want of confirmation |
3 | Configuration invalid, or a flag value that cannot be used (an unknown command or flag exits 1) |
4 | Degraded but running |
Exit codes says which commands use 2 and 4, and when.
Commands by purpose
Projects and development
| Command | Purpose |
|---|---|
| init | Start a project: the bare starter, or a copy of a project with --from |
| check | The CI gate: configuration, schema, routes, templates. Exit 3 on invalid configuration |
| dev | dev up (serve with the config watcher) and the authoring verbs that change configuration safely |
| new | Scaffold a type, a template, a component or a block |
| describe | The project, a type, the field types, a route or a template, with ids |
| guide | Working guidance for this project, for a person or an agent |
| render | Render one public page in process, with errors, queries and findings |
| template | The generated template API and template tests |
| build | Run the project’s frontend build, then check |
| assets | The frontend build as the engine resolves it |
| lsp | The template language server for an editor |
| docs | This handbook in the terminal, and served with the project’s template API |
| config | The resolved configuration, its validation, and the JSON Schema of every file |
| seed | Seed sets: validated content with history, assets and analytics |
| plugin | Build the project’s plugins |
| completion | Shell completion scripts |
Deploying and operating
| Command | Purpose |
|---|---|
| serve | Start the server |
| migrate | Engine migrations, as a deploy step |
| schema | Plan and apply configuration against the database |
| health | Liveness and readiness against a running server |
| warm | After a deploy: repair search, queue derivatives, warm the page cache |
| doctor | The support bundle |
| jobs | The job queue |
| schedule | Scheduled tasks |
| telemetry | Test the error reporter and the OTLP endpoint |
| version | Version, bundle, modules, variant and capabilities |
| site | Export a site as a standalone install, or retire it |
| sar | A subject access request bundle for one email address |
| dpia | A data protection impact assessment filled from the configuration |
| audit | Verify the audit log’s hash chain |
Content and data
| Command | Purpose |
|---|---|
| content | Documents: list, get, create, update, publish, trash, restore, export, import |
| media | The media library: import, stats, transforms, warm, prune |
| search | The search index and the query log |
| redirects | The redirect rules table |
| locale | Locales: coverage, drift, adding a locale’s drafts |
| translate | Translation jobs, the glossary and the memory |
| tags | The tag vocabulary |
| export | Static exports of the content API and embed widgets |
| api | The content API’s contract, keys and answers |
| analytics | Rollups, retention, exports and reports |
| webhooks | Outbound webhook deliveries |
| ai | The AI provider, budget, review queue and activity log |
| a11y | Accessibility audit, statement, issues and conformance report |
People, mail and access
| Command | Purpose |
|---|---|
| user | Staff users and groups |
| access | The effective permission matrix |
| Transactional mail: status, test, templates, suppression | |
| newsletter | Newsletter subscribers, campaigns and deliverability |
| lists | Smart lists |
| mcp | The content MCP for a local agent, and a client for a remote one |
DMO bundle only
| Command | Purpose |
|---|---|
| crm | Organisations, memberships, duplicates, invitations, claims, imports, erasure |
| portal | The member portal’s templates |
| broadcast | CRM broadcasts |
| affiliates | Affiliate networks and conversions |
Some subcommands of shared commands are also engine-dmo only, such as analytics report, api member and the dev verbs for tiers, roles, slots and the portal; each is marked on its page.
Commands and the environment
Commands differ in how much of the project they read, and so in which environment variables must be set. A ${VAR} with no default is an error (environment variable VAR is not set, exit 3) in any command that loads the configuration with its secrets, even one that never connects to the database.
| Reads | Commands | Needs |
|---|---|---|
| Nothing of a project | init, docs, version, help, completion, config schema, describe fieldtypes | Nothing |
| The configuration, with secrets left out | check --no-db, describe project, describe type, template api, guide, and the dev verbs without --scaffold or --apply | Every ${VAR} without a default set, except those in a secret path such as database.url and server.security.signing_key |
| The whole configuration, without connecting | config validate, config render, dpia, new, seed verify, seed write, describe template, and dev route add --scaffold | Every ${VAR} without a default set, and each secret valid: server.security.signing_key, when the file names it, must be empty or at least 32 characters |
| The database | check without --no-db, render, describe route, serve, migrate, schema, seed apply, template test, a11y audit, lists, and every command that reads or writes content, users or jobs | A reachable database in database.url, plus the above |
To work without a database, set placeholders in your shell. The commands in the first three rows never connect with them:
export DATABASE_URL=postgres://localhost/placeholder
export SIGNING_KEY="" # only when engine.yaml names ${SIGNING_KEY}; empty means a development key An empty SIGNING_KEY is accepted outside production, where the engine derives a development key; a value of 1 to 31 characters is refused (signing_key must be at least 32 characters). An empty DATABASE_URL is refused (database.url is required), so it needs a placeholder address. The engine does not read .env files. --help on any command needs neither variable.
Reference
Where to find every command and flag, every configuration file and key, the template API for your project, environment variables, exit codes and error codes, and how to get the same from the binary.
a11y
engine-dmo a11y: Accessibility statements, the issues register and the conformance scaffold. Every subcommand, argument and flag.