Command-line tool

Command-line tool

mesh is the developer command. It builds a project; it does not run your application’s actions. Everything here is run from the project root, with bunx mesh, after Installation.

bunx mesh <command> [options]

The commands

The data adapter contributes three more, so that @mesh/cli never imports a query library:

An enabled extension may contribute further subcommands. Extensions load only from mesh.config.ts, so mesh --help tells you which ones are active.

Exit codes

What a build error looks like

Every diagnostic names the file, the line and the column, both 1-based, and says what to do:

resources/todo.mx:13:21 error `accept` names "titel", which is not an attribute of todo. Did you mean "title"?

The same shape is used for a tag the vocabulary does not allow, a tag the compiler does not implement yet (which names the milestone that will), a duplicate resource name, a free variable in an expression, and a capability the configured adapter does not declare. Nothing is silently ignored.

The guard

bunx mesh build --check

It runs the whole build, regenerates in memory, writes nothing, and fails if the result differs from what is committed. It catches two mistakes: a hand edit to a generated file, and a resource file changed without rebuilding.

It is exact because the build is deterministic: templates through a pinned formatter, same input, same bytes. In your project, run it in the same script as your tests.

inspect

bunx mesh inspect todo

Prints the model as JSON: every attribute with its type and constraints, every action with what it accepts, every relationship, calculation, aggregate and policy, each with the source position of the tag it came from. It is the first thing to look at when a build error mentions a rule you did not expect, and it is what a bug report should include.

explain

bunx mesh explain todo complete

Prints the plan that action’s generated handler follows. The plan is chosen once, at build time, and the handler then performs it without deciding anything:

todo.complete (update)
  strategy     atomic: one UPDATE, no read first
  changes      done = true                 folded into the statement
  policy       list.ownerId = actor.id     folded into the statement as a filter
  validations  none

explain prints a plan, not SQL. Nothing produces SQL at build time: queries are assembled at run time from the action’s own filter, the caller’s filter and the policies, because which of those apply is only known when the call arrives.

Two lines are worth learning to read:

• strategy is either atomic (one statement, no read first) or read-then-write. An update whose change or validation is opaque, or reads the stored record, is read-then-write and must say require-atomic=false, or the build fails (ADR-0017).
• folded into the statement means the rule costs no extra query. A rule that cannot fold runs in memory on the locked row instead.

Migrations

bunx mesh migrate generate

mesh migrate generate compares the old model with the new one before it asks drizzle-kit for a migration, and refuses a destructive or ambiguous change unless you name it: dropping a column, changing its type, renaming it, making an optional column required.

bunx mesh migrate generate --allow drop:todo.dueOn

It never applies anything. Applying is explicit and separate:

bunx mesh migrate apply

The migrations are plain SQL files in migrations/, and you commit them. drizzle-kit owns the snapshot and the diff; Mesh owns the refusal and the flag.

Next

• Usage — the build-and-check loop in context.
• Configuration — the file every command reads.