Commands for agents

Every command takes --project <dir> (default: the current directory) and --json for machine-readable output. Exit codes are the same everywhere:

An unknown command, an unknown flag or a missing argument exits 1, not 3, although help --json lists bad invocations under 3. Some --help texts cite design documents by file name or number (such as 07-auth-and-permissions.md or ADR-0019); those are not in the handbook and you cannot open them. Search the handbook for the topic instead.

What each command needsCopy Anchor Link

“A placeholder is enough” means any value of the right form: DATABASE_URL=postgres://placeholder@localhost/placeholder, and once engine.yaml names it, SIGNING_KEY of at least 32 characters (server.security.signing_key must be at least 32 characters otherwise). The engine never reads a .env file; export the variables.

Which command to reach for:

flowchart TD
  q{"What do you need?"} --> learn["To know a feature"]
  q --> proj["To know this project"]
  q --> chg["To change the project"]
  q --> ver["To prove a change"]
  learn --> docs["The handbook:<br/>llms.txt, then the page"]
  proj --> desc["guide, describe project,<br/>describe type"]
  chg --> verb{"Is there a dev verb?"}
  verb -- yes --> dev["dev ... --apply"]
  verb -- no --> yaml["Edit YAML, then check --fix"]
  ver --> db{"Database?"}
  db -- no --> nodb["check --no-db, seed verify"]
  db -- yes --> full["check, render --json,<br/>a11y audit"]

Learn the engine and the projectCopy Anchor Link

Change the projectCopy Anchor Link

The dev verbsCopy Anchor Link

Each verb edits the configuration, keeping comments, writes the new element’s id and checks the configuration, writing nothing when the configuration itself would be invalid. Two things it does not hold back:

• Templates a new element names. dev route add (with an --index) and dev endpoint add write a valid route or endpoint whose templates do not exist yet, and check fails until you write them.
• A failure after the write. dev route add --scaffold writes routes.yaml, then loads the whole configuration to write the template; with a ${VAR} unset it exits 3 having written the route but not the template, and a second run says nothing to change. Write the template with engine-dmo new template <type>/entry.html.

So run engine-dmo check after every verb. Every verb takes --dry-run (print the diff, write nothing) and --apply (apply the schema plan afterwards when it is not destructive; a destructive plan exits 2 and is left for a person). After each change the verbs regenerate AGENTS.md and the agent skills when the project has them.

With --json, a verb that fails prints an object with command, exit and error.

ScaffoldingCopy Anchor Link

Each takes --site <key> for a site’s own template root and --force to overwrite. Each needs configuration. The scaffolds are starting points: new template <type>/index.html writes an empty body block with no h1, which fails the accessibility checks until you fill it.

IdsCopy Anchor Link

check --fix writes an id for every element that has none, keeping comments, then checks. Run it after any hand edit that adds an element.

VerifyCopy Anchor Link

ContentCopy Anchor Link

An error names the field and its code (nonsense: type page has no field "nonsense" ... (unknown_field)), so you can fix the JSON and run it again.

Two content operations have no command. Scheduling a publish for later is done in the admin, by the content MCP’s publish tool with publish_at, or by a seed document’s schedule:. Unpublishing with a redirect to another address is done through the content MCP; content trash --redirect removes a document and redirects its address.

The content MCPCopy Anchor Link

If your client speaks the Model Context Protocol, engine-dmo mcp --as <staff email> serves the content tools (read, create and update documents, upload media, publish) over standard input and output, acting as that staff user with exactly their permissions. It needs a database and a staff user, and is refused in production. --drafts-only keeps publishing out of reach; --sites, --toolsets and --types narrow it further. engine-dmo mcp tools --json lists the tools and their schemas without serving. See Content MCP.

The dev verbs, check, render and describe are not MCP tools: run them as shell commands.