Preface

This documentation covers mxcli, a command-line tool for reading, querying, and modifying Mendix application projects, and MDL (Mendix Definition Language), the SQL-like language it uses. Start with the Vision to understand where this project is headed. The material is organized into ten parts:

• Part I: Tutorial walks you through installation, exploring a project, making your first changes, and integrating with AI assistants.
• Part II: MDL by Example presents complete, self-contained examples – a CRM module, REST integration, data import, master-detail pages, validation, security, and more.
• Part III: Migration covers AI-assisted migration of existing applications to Mendix – assessment, transformation, generation, data migration, and validation.
• Part IV: The MDL Language is a comprehensive guide to MDL syntax – domain models, microflows, pages, security, navigation, workflows, and business events.
• Part V: Project Tools covers code navigation, catalog queries, linting, testing, external SQL, and Docker integration.
• Part VI: IDE Integration describes the VS Code extension, LSP server, and mxcli init project setup.
• Part VII: Go Library documents the Go API for programmatic access to Mendix projects.
• Part VIII: MDL Statement Reference provides detailed syntax and examples for every MDL statement.
• Part IX: Architecture and Internals explains the MPR file format, parser pipeline, and catalog system for contributors.
• Part X: Appendixes includes quick reference tables, reserved words, error messages, and a glossary.

You can read the Tutorial sequentially or jump directly to the section relevant to your task. The Statement Reference (Part VI) is designed for lookup rather than linear reading.

Vision

mxcli and MDL exist to make Mendix development accessible to coding agents, automation pipelines, and developers who prefer text-based tools. The long-term goal is a complete alternative to Mendix Studio Pro that runs headless, integrates with AI workflows, and never requires leaving VS Code.

Coding Agents First

The primary audience for mxcli is not a human typing commands – it is a coding agent (Claude Code, GitHub Copilot, OpenCode, Cursor, Windsurf, or similar) that reads, reasons about, and modifies Mendix projects autonomously. Everything in mxcli is designed with this in mind:

• MDL as machine-readable output. Every DESCRIBE command produces valid MDL that can be fed back as input. Agents can read a microflow, modify it, and write it back without lossy format conversions.
• Skills and context files. mxcli init generates structured skill files that teach agents MDL syntax, common patterns, and project conventions – reducing hallucination and retry loops.
• Headless operation. mxcli is a single static binary with no GUI, no daemon, and no login. It runs in CI pipelines, containers, and sandboxed agent environments without setup friction.

QA Feedback in the Agentic Loop

Agents produce better results when they can evaluate their own output. mxcli provides the tooling to close this feedback loop:

• mxcli check validates MDL syntax and catches anti-patterns before changes are applied.
• mxcli lint runs 40+ rules across the full project, surfacing issues an agent can fix in the same session.
• mxcli docker build and mx check compile and validate the project against the real Mendix runtime, catching structural errors that static analysis misses.
• mxcli test runs microflow tests inside a live Mendix container, giving agents pass/fail signals on functional correctness.

Together, these tools let an agent write MDL, validate it, fix issues, and verify the result – all without human intervention.

VS Code as the Review Surface

While agents do the building, humans need to review and approve the result. The VS Code extension (vscode-mdl) provides the visual tools to do this without leaving the editor:

• Syntax highlighting, diagnostics, and completion for .mdl files.
• Hover and go-to-definition for navigating the Mendix model from code.
• Context menu commands to run, check, and lint MDL directly from the editor.
• Terminal link integration so that entity names, microflow references, and error locations in terminal output are clickable.

The goal is that a developer can review an agent’s changes, run the app, inspect the result, and approve – all within VS Code.

Long-Term Roadmap

The end state is a complete headless development environment for Mendix:

The measure of success is simple: a team should be able to develop, test, review, and deploy a Mendix application without ever opening Studio Pro.

What is mxcli?

mxcli is a command-line tool that enables developers and AI coding assistants to read, understand, and modify Mendix application projects. Mendix projects are stored in binary .mpr files that cannot be read or edited as text. mxcli bridges this gap by providing a text-based interface using MDL (Mendix Definition Language), a SQL-like syntax for querying and manipulating Mendix models.

How It Works

┌─────────────────┐     ┌──────────────┐     ┌─────────────────┐
│   Developer     │     │    mxcli     │     │ Mendix Project  │
│   or AI Agent   │────>│  (MDL REPL)  │────>│   (.mpr file)   │
│                 │ MDL │              │     │                 │
│ "Create a       │     │ Parses MDL   │     │ Creates actual  │
│  Customer       │     │ Validates    │     │ entities,       │
│  entity..."     │     │ Executes     │     │ microflows,     │
└─────────────────┘     └──────────────┘     │ pages, etc.     │
                                             └─────────────────┘

A developer or AI agent writes MDL statements. mxcli parses and validates them, then applies the changes directly to the .mpr project file. The modified project can then be opened in Mendix Studio Pro as usual.

Important: Do not edit a project with mxcli while it is open in Studio Pro. Studio Pro maintains in-memory caches that cannot be updated externally, and concurrent edits will cause errors. Close the project in Studio Pro first, run mxcli, then re-open the project.

Key Capabilities

• Project exploration – list modules, entities, microflows, pages; describe any element in MDL; full-text search across all strings and source definitions.
• Code navigation – find callers, callees, references, and impact analysis for any project element.
• Model modification – create and alter entities, microflows, pages, security rules, navigation, workflows, and more using MDL scripts.
• Catalog queries – SQL-based querying of project metadata (entity counts, microflow complexity, widget usage, cross-references).
• Linting and reports – 40+ built-in lint rules with SARIF output for CI; scored best-practices reports.
• Testing – test microflows using MDL syntax with javadoc-style annotations.
• AI assistant integration – works with Claude Code, GitHub Copilot, OpenCode, Cursor, Continue.dev, Windsurf, and Aider. mxcli init sets up project configuration, skills, and a Dev Container for sandboxed AI development.
• VS Code extension – syntax highlighting, diagnostics, code completion, hover, go-to-definition, and context menu commands for .mdl files.
• External SQL – connect to PostgreSQL, Oracle, or SQL Server; query external databases; import data into a running Mendix application.

Supported Environments

What is MDL?

MDL (Mendix Definition Language) is a text-based, SQL-like language for describing and manipulating Mendix application models. It provides a human-readable representation of Mendix project elements – entities, microflows, pages, security rules, and more – at the same abstraction level as the visual models in Studio Pro.

Why a Text-Based Language?

Mendix projects are stored in a binary format (.mpr files containing BSON documents in SQLite). While Studio Pro provides a visual interface, there is no standard text format for Mendix models. This creates problems for:

• AI assistants that need to read and generate model elements
• Code review of changes to Mendix projects
• Scripting and automation of repetitive modeling tasks
• Documentation of project structure and design patterns

MDL addresses these problems by providing a syntax that is both human-readable and machine-parseable.

Characteristics of MDL

MDL draws on three well-understood languages: SQL for its CREATE/ALTER/DROP/SHOW verbs and set-oriented queries, and Ada and PL/SQL for its readable, block-structured statement bodies. The result is a syntax that is immediately recognisable to anyone who has written database or procedural code.

• SQL-like syntax – uses familiar keywords like CREATE, ALTER, DROP, SHOW, DESCRIBE, GRANT.
• Declarative – you describe what the model should look like, not how to construct it step by step.
• Complete – covers domain models, microflows, pages, security, navigation, workflows, and business events.
• Validated – mxcli can check MDL scripts for syntax errors and reference validity before applying them.

Token Efficiency

When working with AI coding assistants, context window size is a critical constraint. MDL’s compact syntax uses significantly fewer tokens than equivalent JSON model representations:

Fewer tokens means lower API costs, more application context fits in a single prompt, and AI assistants produce more accurate output because there is less noise in their input.

Example: JSON vs MDL

A simple entity definition illustrates the difference.

JSON representation (~180 tokens):

{
  "entity": {
    "name": "Customer",
    "documentation": "Customer master data",
    "attributes": [
      {"name": "Name", "type": {"type": "String", "length": 200}},
      {"name": "Email", "type": {"type": "String", "length": 200}}
    ]
  }
}

MDL representation (~35 tokens):

/** Customer master data */
CREATE PERSISTENT ENTITY Sales.Customer (
    Name: String(200),
    Email: String(200)
);

The MDL version conveys the same information in roughly one-fifth the space, and its structure is immediately recognizable to anyone familiar with SQL DDL.

What MDL Covers

MDL provides statements for the following areas of a Mendix project:

See Part II (The MDL Language) for a complete guide, or Part VI (MDL Statement Reference) for detailed syntax of each statement.

Design Principles

mxcli is not a thin wrapper over the .mpr format. It is a deliberate bet on a particular way of letting coding agents build Mendix applications: the agent writes a compact, human-readable DSL, and mxcli’s deterministic layer turns that DSL into the many low-level mutations, validations, and tool calls a real model change requires. The principles below explain the design choices that follow from that bet, and why they differentiate mxcli from driving Studio Pro’s tools directly.

Token efficiency

An agent authoring against mxcli emits one larger MDL script, not a long back-and-forth of small, chatty tool calls. MDL itself is dense – a module that takes 15,000–25,000 tokens as raw model JSON is 2,000–4,000 tokens as MDL, a 5–10x reduction (see What is MDL?). But the larger win is orchestration overhead: one script is one agent action and one summarized result, so there are fewer model turns, lower API cost, and faster execution than emitting each individual document edit as its own turn. The MCP Backend cost analysis traces this in detail – a ~20-statement script that expands to ~60 low-level tool calls still costs the agent one turn when it runs through mxcli.

Complexity belongs in the deterministic layer

A single MDL statement maps deterministically to whatever it takes to realise it: multiple BSON documents on the file backend, or a fixed choreography of MCP tool calls against a running Studio Pro. create association, for example, expands to reference resolution, the write itself, and a validation pass. The LLM never has to orchestrate that – it states intent in MDL, and mxcli’s deterministic code carries the fan-out, ordering, and read-modify-write bookkeeping. The agent handles the simple task (say what you want); mxcli handles the complex one (make it valid). This keeps the hard, error-prone mechanics in code that is tested and reproducible rather than in a probabilistic model.

Human-readable DSL

MDL is a domain-specific language inspired by SQL, Ada, and PL/SQL – SQL for its CREATE/ALTER/DROP/SHOW verbs and set-oriented queries, Ada and PL/SQL for its readable block structure. That familiar, structured syntax means LLM-generated scripts are easy for a human to review, audit, and author – both in documentation and in skills. A diff of an MDL script reads like a diff of DDL, not an opaque binary or a wall of JSON. Readable code is reviewable code, and reviewable changes are the ones a team can safely let an agent make.

Headless agentic loop

Everything an agent needs to build and test a Mendix application is available without ever opening Studio Pro. mxcli is a single static binary; it reads and writes .mpr files directly, validates with mxcli check and the real Mendix build tools, runs microflow tests in a container, and analyses the model – all from the command line. Studio Pro becomes an optional visual review surface, not a required step in the loop. See the Vision for the full roadmap toward Studio-Pro-free development.

Understanding large applications

mxcli builds a queryable catalog of project metadata and a dependency graph on top of it, both exposed as ordinary SQL tables. An agent explores an unfamiliar app the same way it would explore a database – SELECT over CATALOG.ENTITIES, CATALOG.REFS, or the CATALOG.graph_* views to find god nodes, module coupling, dependency cycles, and dead code. No bespoke traversal API to learn; complex applications become explorable through straightforward queries. See Graph Analysis and Catalog Use Cases.

Precise skills

Because MDL is a concrete syntax, skill files can embed specific, executable examples of exactly the MDL an agent should produce – not vague prose about how Mendix concepts fit together. “Generate this shape of create page for a master-detail view” is a copyable example; the agent adapts one worked case rather than inferring structure from description. Concrete examples in skills yield more reliable, accurate output and fewer retry loops.

Power with safety

Coding agents driving mxcli are powerful – they can generate scripts in bulk, run automated tests, and rewrite large parts of a model. That power requires appropriately scoped privileges. mxcli init provisions a Dev Container that bounds exactly what the agent can see, do, and modify: it runs against the project files and nothing else, with the toolchain pre-installed and the host environment out of reach. Sandboxing is the default recommended way to run an agent, not an afterthought. See Dev Container Setup.

Deterministic verification

mxcli check and mxcli lint let the agent verify its own output against deterministic rules – syntax, references, anti-patterns, security and architecture policies – with no LLM judgement involved. This is an explicit design choice: correctness checks stay in the deterministic layer so the feedback loop is fast, reproducible, and trustworthy. An agent can write MDL, get an objective pass/fail, fix, and re-check in the same session without a human – and without asking a model to grade a model. Deeper gates (mxcli docker check, mxcli test) extend the same principle to the real Mendix build and runtime.

Longer-term: smaller local models

Generating code in a constrained DSL is inherently simpler for an LLM than orchestrating a stateful sequence of tool calls – there is one grammar to satisfy, not an evolving protocol to reason about. That simplicity opens a path to smaller, cheaper, and eventually local models for Mendix authoring. A DSL grammar can be integrated into an LLM via grammar-constrained decoding, so the model can only emit tokens that form valid MDL. The deterministic layer already absorbs the complexity (see above); the DSL boundary is what makes constraining the model’s output tractable in the first place.

The Language Poster

All of mxcli and MDL on one page: the idea, getting started, the CLI map, exploring and querying a project, domain models, microflows, pages, security, running and testing, quality gates, skills, custom widgets, the Marketplace, runtime insight, and working alongside Studio Pro.

Open the interactive poster – zoom into any panel, or step through it as a 19-panel tour.

A full-resolution PNG (5498×3380) is available for printing.

Mendix Concepts for Newcomers

This page explains the core Mendix concepts you’ll encounter when using mxcli. If you’re familiar with web frameworks, relational databases, or backend development, most of these will map to things you already know.

The Big Picture

A Mendix application is a model-driven app. Instead of writing code in files, developers build applications visually in Studio Pro (the Mendix IDE). The entire application model – data structures, logic, UI, security – is stored in a single binary file called an MPR (Mendix Project Resource).

mxcli lets you read and modify that MPR file using text commands, without opening Studio Pro.

Modules

A module is the top-level organizational unit, like a package in Go or a namespace in C#. Each module has its own:

• Domain model (data structures)
• Microflows and nanoflows (logic)
• Pages (UI)
• Enumerations (constant sets)
• Security settings

A typical project has a few custom modules (Sales, Admin, Integration) plus system modules provided by the platform (System, Administration).

LIST MODULES;

Domain Model

The domain model is the data layer of a module. If you know relational databases, the mapping is straightforward:

Entities

An entity defines a data type. There are several kinds:

• Persistent – stored in the database (the default and most common)
• Non-persistent – exists only in memory during a user session, useful for form state or temporary calculations
• View – backed by an OQL query, like a database view

CREATE PERSISTENT ENTITY Sales.Customer (
    Name: String(200) NOT NULL,
    Email: String(200),
    IsActive: Boolean DEFAULT true
);

Associations

An association is a relationship between two entities. Think of it as a foreign key.

• Reference – many-to-one or one-to-one (a foreign key column on the “from” entity)
• ReferenceSet – many-to-many (a join table under the hood)

CREATE ASSOCIATION Sales.Order_Customer
    FROM Sales.Order TO Sales.Customer
    TYPE Reference;

Generalization

Entities can inherit from other entities using generalization (the EXTENDS keyword). The child entity gets all parent attributes. This is commonly used with system entities like System.Image (for file uploads) or System.User (for user accounts).

CREATE PERSISTENT ENTITY Sales.ProductImage EXTENDS System.Image (
    Caption: String(200)
);

Microflows and Nanoflows

Microflows are the server-side logic of a Mendix app. They’re visual flowcharts in Studio Pro, but in MDL they read like imperative code with activities:

• Retrieve data from the database
• Create, Change, Commit, Delete objects
• Call other microflows or external services
• If/Else branching, Loop iteration
• Show Page, Log Message, Validation Feedback

CREATE MICROFLOW Sales.CreateOrder(
    DECLARE $Customer: Sales.Customer
)
RETURN Boolean
BEGIN
    CREATE $Order: Sales.Order (
        OrderDate = [%CurrentDateTime%],
        Status = 'Draft'
    );
    CHANGE $Order (
        Sales.Order_Customer = $Customer
    );
    COMMIT $Order;
    RETURN true;
END;

Nanoflows are the client-side equivalent. They run in the browser (or native mobile app) and are useful for offline-capable logic and low-latency UI interactions. They have the same syntax but fewer available activities (no database transactions, no direct service calls).

Pages

Pages define the user interface. A page has:

• A layout – the outer frame (header, sidebar, footer) shared across pages
• Widgets – the UI components inside the page

Widgets are nested in a tree. Common widget types:

CREATE PAGE Sales.CustomerOverview
(
    Title: 'Customers',
    Layout: Atlas_Core.Atlas_Default
)
{
    DATAGRID dgCustomers (DataSource: DATABASE Sales.Customer) {
        COLUMN (Attribute: Name, Caption: 'Name')
        COLUMN (Attribute: Email, Caption: 'Email')
        COLUMN (Attribute: IsActive, Caption: 'Active')
    }
};

Snippets

A snippet is a reusable page fragment. You define it once and embed it in multiple pages using a SnippetCall. Think of it as a component or partial template.

Security

Mendix uses a role-based access control model:

1. Module roles are defined per module (e.g., Sales.Admin, Sales.User)
2. User roles are defined at the project level and aggregate module roles
3. Access rules control what each module role can do with entities (CREATE, READ, WRITE, DELETE) and which microflows/pages they can access

CREATE MODULE ROLE Sales.Manager;

GRANT CREATE, READ, WRITE ON Sales.Customer TO Sales.Manager;
GRANT EXECUTE ON MICROFLOW Sales.CreateOrder TO Sales.Manager;
GRANT VIEW ON PAGE Sales.CustomerOverview TO Sales.Manager;

Navigation

Navigation profiles define how users move through the app. There are profiles for responsive web, tablet, phone, and native mobile. Each profile has:

• A home page (the landing page after login)
• A menu with items that link to pages or microflows

Workflows

Workflows model long-running processes with human tasks. Think of them as state machines for approval flows, onboarding processes, or multi-step procedures. A workflow has:

• User tasks – steps that require human action
• Decisions – branching based on conditions
• Parallel splits – concurrent paths

Workflows complement microflows: microflows handle immediate logic, workflows handle processes that span hours or days.

How It All Fits Together

Project
├── Module: Sales
│   ├── Domain Model
│   │   ├── Entity: Customer (Name, Email, IsActive)
│   │   ├── Entity: Order (OrderDate, Status)
│   │   └── Association: Order_Customer
│   ├── Microflows
│   │   ├── CreateOrder
│   │   └── ApproveOrder
│   ├── Pages
│   │   ├── CustomerOverview
│   │   └── OrderEdit
│   ├── Enumerations
│   │   └── OrderStatus (Draft, Active, Closed)
│   └── Security
│       ├── Module Role: Manager
│       └── Module Role: Viewer
├── Module: Administration
│   └── ...
└── Navigation
    └── Responsive profile → Home: Sales.CustomerOverview

In mxcli, you can explore this structure with:

DESCRIBE STRUCTURE DEPTH 2;

What’s Next

• Part I: Tutorial – hands-on walkthrough
• Part II: The MDL Language – complete language guide
• Glossary – alphabetical reference of all terms

Document Conventions

This page describes the formatting and notation conventions used throughout this documentation.

Code Examples

MDL examples use sql code fencing because MDL’s syntax is SQL-like and this provides appropriate syntax highlighting:

CREATE PERSISTENT ENTITY MyModule.Customer (
    Name: String(200) NOT NULL
);

Go code examples use go code fencing:

reader, err := modelsdk.Open("/path/to/app.mpr")
defer reader.Close()

Shell commands use bash code fencing:

mxcli -p app.mpr -c "LIST MODULES"

Syntax Notation

When describing the syntax of MDL statements, the following conventions apply:

For example, the notation:

CREATE [PERSISTENT] ENTITY module.name (
    attribute_name: type [NOT NULL] [, ...]
);

means: CREATE and ENTITY are required keywords; PERSISTENT is optional; module.name is a user-provided qualified name; each attribute has a name and type, with an optional NOT NULL constraint; and additional attributes may follow, separated by commas.

Cross-References

References to MDL statements link to their detailed pages in Part VI (MDL Statement Reference) using the format “See CREATE ENTITY” or “See GRANT”. References to conceptual explanations link to the relevant section in Part II (The MDL Language).

Terminology

Mendix-specific terms such as “entity”, “microflow”, “nanoflow”, “module”, and “domain model” follow standard Mendix terminology. See the Glossary for definitions.

5-Minute Quickstart

Get from zero to modifying a Mendix project in 5 minutes. No prior MDL knowledge needed.

1. Install mxcli

Option A: Zero install (Playground)

Open the mxcli Playground in a Codespace – mxcli, a sample project, and example scripts are pre-installed. Skip to step 3.

Option B: Binary download

Release assets are raw binaries named mxcli-<os>-<arch> (nothing to extract). Use the rolling nightly build while mxcli is alpha:

# macOS / Linux
curl -fsSL -o mxcli \
  https://github.com/mendixlabs/mxcli/releases/download/nightly/mxcli-linux-amd64
chmod +x mxcli && sudo mv mxcli /usr/local/bin/

Option C: Build from source (Go + Make)

git clone https://github.com/mendixlabs/mxcli.git && cd mxcli && make build
# binary at ./bin/mxcli  (go install @latest doesn't work — see Installation)

Verify: mxcli --version should print the version number.

See Installation for all options including Dev Containers.

2. Open your project

mxcli -p /path/to/your-app.mpr

You’ll see:

Connected to: your-app.mpr (Mendix 11.6.3)
MDL REPL - Mendix Definition Language
mdl>

Don’t have a Mendix project? Create one with mxcli new test-app --version 11.8.0 — this downloads MxBuild, creates a blank project, and sets up all tooling automatically.

3. Explore what’s there

-- List all modules
LIST MODULES;

-- List entities in a module
LIST ENTITIES IN MyFirstModule;

-- See the full structure at a glance
DESCRIBE STRUCTURE;

4. Create something

-- Create a new entity
CREATE PERSISTENT ENTITY MyFirstModule.Customer (
  Name: String(200) NOT NULL,
  Email: String(200),
  IsActive: Boolean DEFAULT true
);

Expected output:

Created entity: MyFirstModule.Customer

5. Verify it works

-- See what you created
DESCRIBE ENTITY MyFirstModule.Customer;

Output:

@Position(100, 100)
create or modify persistent entity MyFirstModule.Customer (
  Name: String(200) not null,
  Email: String(200),
  IsActive: Boolean default true
);

Open the project in Studio Pro – your entity is there.

6. Create a microflow

CREATE MICROFLOW MyFirstModule.ACT_DeactivateCustomer (
  $Customer: MyFirstModule.Customer
)
BEGIN
  CHANGE $Customer (IsActive = false);
  COMMIT $Customer;
END;

7. Validate

# Check your project for errors (from a separate terminal)
mxcli check -p /path/to/your-app.mpr

No errors? You’re done. Open in Studio Pro and everything is there.

What’s next?

Common issues

“mx command not available” – Install mxbuild for validation:

mxcli setup mxbuild -p your-app.mpr

“CGO not available” – mxcli uses pure Go SQLite. No C compiler needed. If you see CGO errors, ensure you’re using the official pre-built binary or a make build from source.

“refusing to write …: Studio Pro has this project open” – Close the project in Studio Pro before running mxcli write commands, then reopen it. Studio Pro does not reload the model from disk, so its next save would silently discard mxcli’s changes. If Studio Pro is not running, the .mpr.lock was left behind by a crash: delete it, or pass --force to exec.

Setting Up

Before you can start exploring and modifying Mendix projects from the command line, you need three things:

1. mxcli installed on your machine
2. A Mendix project (an .mpr file) to work with
3. A feel for the REPL, the interactive shell where you’ll spend most of your time

This chapter walks you through all three.

Installation methods

There are five ways to get started with mxcli:

• Playground – open the mxcli Playground in a GitHub Codespace. Zero install, runs in your browser with a sample Mendix project, tutorials, and example scripts. Best way to try mxcli for the first time.
• mxcli new (recommended for new projects) – run mxcli new MyApp --version 11.8.0 to create a new Mendix project from scratch with all tooling and Dev Container configured. One command does everything: downloads MxBuild, creates the project, sets up AI tools, and installs the correct mxcli binary.
• Binary download – grab a pre-built binary from GitHub Releases. Quickest path if you want to use mxcli on your own project.
• Build from source – clone the repo and run make build. Useful if you want the latest unreleased changes or plan to contribute.
• Dev Container (recommended for existing projects) – run mxcli init on your Mendix project, open it in VS Code, and reopen in the container. This gives you mxcli, a JDK, Docker-in-Docker, and Claude Code all pre-configured in a sandboxed environment. This is the recommended approach, especially when pairing with AI coding assistants.

The next few pages cover each method, then walk you through opening a project and using the REPL.

Alpha software warning. mxcli can corrupt your Mendix project files. Always work on a copy of your .mpr or use version control (Git) before making changes.

Installation

Pick whichever method suits your situation. If you just want to try mxcli without installing anything, start with the Playground. If you’re planning to use mxcli on your own project with an AI coding assistant, skip to the Dev Container section.

Playground (zero install)

The fastest way to try mxcli. The mxcli Playground is a GitHub repository with a pre-configured Mendix project, example scripts, and tutorials. Open it in a Codespace and start using mxcli immediately – nothing to install on your machine.

The Codespace comes with mxcli, a JDK, Docker-in-Docker, Claude Code, and a sample Mendix 11.x project ready to explore and modify. It includes:

• 5 example scripts – explore, create entities, microflows, pages, and security
• Step-by-step tutorials – from first steps through linting and testing
• AI tool configs – pre-configured for Claude Code, GitHub Copilot, OpenCode, Cursor, Windsurf, Continue.dev, and Aider

Once the Codespace is running:

./mxcli -p App.mpr -c "DESCRIBE STRUCTURE"          # Explore the project
./mxcli exec scripts/01-explore.mdl -p App.mpr   # Run an example script
./mxcli                                           # Start interactive REPL

When you’re ready to work on your own Mendix project, use one of the installation methods below.

Binary download

Pre-built binaries are published for Linux, macOS, and Windows on both amd64 and arm64. Release assets are raw binaries named mxcli-<os>-<arch> (Windows: .exe) — there is nothing to extract.

While mxcli is fast-moving alpha, use the rolling nightly build (new features land there before a tagged release); pin a vX.Y.Z release for reproducibility.

# Linux/macOS — nightly (recommended for now)
curl -fsSL -o mxcli \
  https://github.com/mendixlabs/mxcli/releases/download/nightly/mxcli-linux-amd64
chmod +x mxcli && sudo mv mxcli /usr/local/bin/

# ...or pin a specific release
curl -fsSL -o mxcli \
  https://github.com/mendixlabs/mxcli/releases/download/v0.16.0/mxcli-darwin-arm64
chmod +x mxcli && sudo mv mxcli /usr/local/bin/

Assets: mxcli-linux-amd64, mxcli-linux-arm64, mxcli-darwin-amd64, mxcli-darwin-arm64, mxcli-windows-amd64.exe, mxcli-windows-arm64.exe. On Windows, download the .exe and add its folder to your PATH. You can browse them on the GitHub Releases page.

go install github.com/mendixlabs/mxcli/cmd/mxcli@latest does not work: the ANTLR parser is generated at build time and isn’t committed, so a go install from the module source fails. Use a pre-built binary, or Build from source below (which runs make grammar).

Build from source

Building from source requires Go 1.24 or later and Make. No C compiler is needed – mxcli uses a pure-Go SQLite driver.

git clone https://github.com/mendixlabs/mxcli.git
cd mxcli
make build

The binary lands at ./bin/mxcli. You can copy it to a directory on your PATH or run it directly:

./bin/mxcli --version

New project from scratch

If you don’t have a Mendix project yet, mxcli new creates one with everything configured:

mxcli new MyApp --version 11.8.0

This single command:

1. Downloads MxBuild for the specified Mendix version
2. Creates a blank Mendix project (App.mpr)
3. Sets up AI tooling (.claude/, skills, AGENTS.md)
4. Configures a Dev Container (.devcontainer/)
5. Runs one build, so the action stubs MxBuild regenerates are already settled
6. Puts an mxcli binary in the project — a hard link to the one you ran on Linux, a downloaded Linux build on macOS/Windows (the container needs a Linux ELF)

Open the resulting MyApp/ folder in VS Code and click “Reopen in Container” — you’re ready to go.

Options:

mxcli new MyApp --version 10.24.0 --output-dir ./projects/my-app
mxcli new MyApp --version 11.8.0 --skip-init    # Skip AI tooling setup
mxcli new MyApp --version 11.8.0 --skip-build   # Skip the first build

Dev Container for existing projects

For an existing Mendix project, mxcli init adds AI tooling and a Dev Container configuration.

Here’s how to set it up:

Step 1: Install mxcli using one of the methods above (you need it locally to run init).

Step 2: Run mxcli init on your Mendix project:

mxcli init /path/to/my-mendix-project

This creates a .devcontainer/ folder (along with skill files, agent configs, and other goodies) inside your project directory.

Step 3: Open the project folder in VS Code and click “Reopen in Container” when prompted (or use the Command Palette: Dev Containers: Reopen in Container).

VS Code will build and start the container. This takes a minute or two the first time.

What’s inside the Dev Container

The container comes with everything you need pre-installed:

Once the container is running, mxcli is ready to use – no further setup needed.

Specifying AI tools

By default, mxcli init configures for Claude Code. You can target other tools too:

# Cursor only
mxcli init --tool cursor /path/to/my-mendix-project

# Multiple tools
mxcli init --tool claude --tool cursor /path/to/my-mendix-project

# Everything
mxcli init --all-tools /path/to/my-mendix-project

Run mxcli init --list-tools to see all supported tools.

Verify your installation

Whichever method you used, confirm that mxcli is working:

mxcli --version

You should see version and build information printed to the terminal. If you get a “command not found” error, double-check that the binary is on your PATH.

You’re ready to open a project.

Opening Your First Project

mxcli works with Mendix project files – the .mpr files that Mendix Studio Pro creates. Let’s open one.

Back up first. mxcli is alpha software and can corrupt project files. Before you start, either make a copy of your .mpr file or make sure the project is under version control (Git). This isn’t just a disclaimer – take it seriously.

The -p flag

The most common way to point mxcli at a project is with the -p flag:

mxcli -p /path/to/app.mpr -c "LIST MODULES"

This opens the project in read-only mode, runs the command, and exits. The -p flag works with all mxcli subcommands.

-c takes several statements separated by ;. Like mxcli exec, it stops at the first statement that fails, prints statement 2 of 3: … and how many later statements were not run, and exits non-zero; add --continue-on-error to run every statement and report each failure. An empty -c "" is an error: it never opens the interactive REPL, so a script that generates an empty command list cannot hang waiting on input.

Opening in the REPL

You can also open a project from inside the interactive REPL:

# Start the REPL, then open a project
mxcli

OPEN PROJECT '/path/to/app.mpr';
LIST MODULES;

Or pass -p when launching the REPL so it opens the project immediately:

mxcli -p /path/to/app.mpr

-- Project is already open, start working
LIST MODULES;

When you provide -p, the project stays open for the duration of your REPL session. You don’t need to pass it again for each command.

Read-only vs read-write

By default, mxcli opens projects in read-only mode. This is safe for exploration – you can browse modules, describe entities, search through the project, and run catalog queries without risk.

When you execute a command that modifies the project (like CREATE ENTITY), mxcli automatically upgrades to read-write mode. You’ll see a confirmation message when this happens.

MPR format auto-detection

Mendix projects come in two formats:

• v1: A single .mpr SQLite database file (Mendix versions before 10.18)
• v2: An .mpr metadata file plus an mprcontents/ folder with individual documents (Mendix 10.18 and later)

You don’t need to worry about which format your project uses. mxcli detects the format automatically and handles both transparently. Just point it at the .mpr file either way.

Working in a Dev Container

If you’re using the Dev Container setup from the previous page, your project is already mounted in the container. The typical path is:

mxcli -p app.mpr

The Dev Container sets the working directory to your project root, so relative paths work naturally.

Quick sanity check

Once you have a project open, try listing the modules:

mxcli -p app.mpr -c "LIST MODULES"

You should see a table of module names. If you see your project’s modules listed, everything is working and you’re ready to explore.

Next up: the REPL, where the real fun starts.

The REPL

The mxcli REPL is an interactive shell for working with Mendix projects, much like psql is for PostgreSQL or mysql for MySQL. You type MDL statements, press Enter, and see results immediately.

Starting the REPL

Launch it with or without a project:

# Start with a project already loaded
mxcli -p app.mpr

# Start without a project (you can open one later)
mxcli

You’ll see a prompt where you can start typing MDL:

mxcli>

Running commands

Type any MDL statement and press Enter:

LIST MODULES;

Results are printed as formatted tables directly in the terminal.

Multi-line statements

MDL statements end with a semicolon (;). If you press Enter before typing a semicolon, mxcli knows you’re still writing and waits for more input:

CREATE ENTITY MyModule.Customer (
    Name: String(200) NOT NULL,
    Email: String(200),
    IsActive: Boolean DEFAULT true
);

The REPL shows a continuation prompt (.....>) while you’re in a multi-line statement. The statement executes when you type the closing ; and press Enter.

Getting help

Type HELP to see a list of available commands:

HELP;

This prints a categorized overview of all MDL statements – useful when you can’t remember the exact syntax for something.

Command history

Use the up and down arrow keys to scroll through previous commands, just like in any other shell. This is especially handy when you’re iterating on a query or tweaking a CREATE statement.

Exiting

When you’re done, type either:

EXIT;

or:

QUIT;

You can also press Ctrl+D to exit.

One-off commands with -c

You don’t always need an interactive session. The -c flag lets you run a single command and exit:

mxcli -p app.mpr -c "LIST ENTITIES IN MyModule"

This is great for quick lookups and for scripting. The output is pipe-friendly, so you can chain it with other tools:

# Count entities per module
mxcli -p app.mpr -c "LIST MODULES" | tail -n +2 | while read module; do
    echo "$module: $(mxcli -p app.mpr -c "LIST ENTITIES IN $module" | wc -l) entities"
done

Running script files

For anything beyond a quick one-liner, you can put MDL statements in a .mdl file and execute the whole thing:

mxcli -p app.mpr -c "EXECUTE SCRIPT 'setup.mdl'"

Or from the REPL:

EXECUTE SCRIPT 'setup.mdl';

This is how you’ll typically apply larger changes – write the MDL in a file, check the syntax with mxcli check, then execute it.

The TUI (Terminal UI)

If you prefer a more visual experience, mxcli also offers a graphical terminal interface:

mxcli tui -p app.mpr

The TUI gives you a split-pane layout with a project tree, an MDL editor, and output panels. It’s built on top of the same REPL engine, so all the same commands work. This can be a nice middle ground between the bare REPL and opening Studio Pro.

What’s next

Now that you know how to install mxcli, open a project, and use the REPL, you’re ready to start exploring. The next chapter walks through the commands you’ll use most often: SHOW, DESCRIBE, and SEARCH.

Developing on the Web (Claude Code)

You can build a Mendix app with mxcli entirely in the browser — no local CLI, no Studio Pro, no machine setup. Claude Code on the web runs the agent in a cloud container against a GitHub repository; mxcli provisions the whole toolchain inside that container on first run and commits the result so future sessions come back up on their own. It works from a laptop, and from an iPad or phone.

This page walks the entire workflow:

1. Create a GitHub repository
2. Get a hub key for browser preview (optional)
3. Create a Claude Code environment
4. Start the session with the bootstrap prompt
5. Iterate — the warm loop, preview, and screenshots

New to how Claude Code on the web works (sessions, environments, network policies)? See Anthropic’s guide: https://code.claude.com/docs/en/claude-code-on-the-web.

1. Create a GitHub repository

Create a new, empty repository on GitHub (private is fine). This is where the app will live and where every Claude Code session runs. You don’t need a template or any starter files — the bootstrap prompt starts from a truly empty repo and runs the current mxcli, so there is nothing to keep up to date.

If you already have a Mendix project in a repo, you can skip the bootstrap prompt and use mxcli init instead (step 4 notes how).

2. Get a hub key for browser preview

Optional, but recommended — it’s what lets you actually see the running app in a browser tab from a web session.

A cloud session has no localhost you can open, so mxcli can reverse-tunnel the running app out to the mxcli hub and give you a public preview URL (see External browser preview). The hosted hub at hub.mxcli.org is GitHub-authenticated, so each preview is private to you — which means you need a per-user hub key:

1. Open https://hub.mxcli.org/cli in any browser and sign in with GitHub.
2. Click Create a hub key and copy it.
3. Keep it for step 3 — you’ll set it as MXCLI_HUB_KEY.

The key is durable (no expiry, survives hub restarts); you set it once and it stays valid until you revoke it from the same page. If you’d rather run your own hub, see mxcli tunnel-hub.

You can skip this step and add the key later — without it, the app still builds and runs in the container; you just won’t have a browser preview URL.

3. Create a Claude Code environment

In Claude Code on the web, create an environment pointed at the repository from step 1. The environment is the reusable container definition for your sessions; configure two things on it:

Environment variables

Set the hub key here, on the environment — never in a committed file. It’s a credential, and a gitignored file wouldn’t survive container recycling anyway; environment variables are re-injected into every session, so the environment is the only place it belongs.

Network policy

The bootstrap prompt downloads a few things on first run, so the environment’s network policy must allow outbound HTTPS to:

• github.com / objects.githubusercontent.com — the prebuilt mxcli binary from GitHub Releases.
• Mendix’s CDN — MxBuild and the runtime (mxcli fetches the version your app needs).
• hub.mxcli.org — the browser-preview tunnel (only if you’re using step 2).

A policy that permits general outbound HTTPS covers all of these. If your organization restricts egress, allow-list those hosts. See the network policy docs for where to configure this.

Even faster startup: if you control the environment image, pre-installing mxcli (and pre-caching MxBuild + the runtime) makes step 4 nearly instant and removes the one network-dependent step. This is the most robust setup for a team.

4. Start the session with the bootstrap prompt

Open a session on the environment and paste the bootstrap prompt. It tells the agent to set up the complete toolchain, create the app, wire the AI tooling and Dev Container, start a findings document, boot the app, and commit everything so the next session self-bootstraps.

👉 Copy the bootstrap prompt — it’s a single paste. In short, the agent will:

• ensure mxcli is available (pre-installed, or download the nightly binary);
• mxcli init --sync-skills — unpack the skills embedded in the binary, then follow the bootstrap-app skill, which carries the rest of this list (the paste itself is only those two steps plus “read the skill”);
• interview you about the app, then mxcli new App --version <X.Y.Z> (or mxcli init if an .mpr already exists);
• mxcli init --tool claude — adds a SessionStart hook so future sessions come back up automatically;
• mxcli run --local --setup --ensure-db — cache MxBuild + runtime, start Postgres, create the app database;
• create a FINDINGS.md (see below) and start logging to it;
• commit App.mpr, .devcontainer/, and .claude/ so the steady state is file-driven;
• boot mxcli run --local and verify the app answers HTTP 200.

You can append your own goal to the end of the prompt — e.g. “Then seed a domain model, pages, and microflows for a time-registration app”, or link a design prototype to seed from.

Keep a findings document

The bootstrap prompt asks the agent to create a FINDINGS.md at the repo root and to append to it as it works. Treat it as a lab notebook for the session:

• anything surprising or broken — an mxcli command that errored, a workaround you had to apply, a check that passed but a real mx check later flagged;
• the Mendix / mxcli versions in play and how each finding was verified;
• decisions and dead-ends, so a later session (or a teammate) doesn’t repeat them.

This is high-leverage for two reasons. It gives your next session durable context that survives container reaping, and — because mxcli is fast-moving alpha — a clear findings doc is the single most useful thing you can share back to improve mxcli. If something misbehaves, capture the exact MDL, the command, and the error in FINDINGS.md; that’s often enough for a fix.

5. Iterate

Once the app is up, use the warm local dev loop — a Docker-free, ~1-second edit→test cycle:

mxcli run --local -p App.mpr --watch --screenshot   # hot-reload + a PNG per change

Edit the model with MDL and the running loop hot-applies it:

mxcli exec change.mdl -p App.mpr                     # the loop picks it up and reloads

To see the app in a browser from the web session, add --hub (this is where the key from step 2 pays off):

mxcli run --hub https://hub.mxcli.org -p App.mpr     # prints a shareable preview URL

--hub implies --local, so you get the warm loop and a public preview URL in one command — edit here, hot-apply, refresh the tab.

--hub ships in the Linux build only, and a Claude Code web session is a Linux container, so it works here. It is the native Windows/macOS installs that leave the tunnel out — see Linux builds only.

See mxcli run –local for --watch, --ensure-db, --setup, the screenshot flags, and the full --hub reference.

After idle: sessions self-bootstrap

Cloud containers are reaped when idle, so a resumed session starts from the committed files, not from re-pasting the prompt. Because step 4 ran mxcli init, .claude/settings.json carries a SessionStart hook that runs mxcli run --local --setup --ensure-db on every new session — it re-caches MxBuild + runtime and re-provisions the database, leaving the session ready to run --local. You never re-paste the bootstrap prompt; it’s a one-time seed.

Next steps

• The bootstrap prompt — the exact copy-paste text and the rules that make it robust.
• Local Dev Loop — the warm loop, browser preview, and screenshots in depth.
• Claude Code Integration — how skills, CLAUDE.md, and slash commands shape what the agent does with your project (applies to web and local).

Exploring a Project

Once you have a project open – whether through the REPL, a CLI one-liner, or a script file – the next step is to look around. What modules exist? What entities are defined? What does a particular microflow do?

mxcli provides three families of commands for exploration:

• SHOW commands list elements by type. LIST ENTITIES lists all entities; LIST MICROFLOWS IN Sales narrows the list to one module.
• DESCRIBE commands display the full MDL source for a single element, giving you the complete definition including attributes, associations, logic, and widget trees.
• SEARCH performs full-text search across every string in the project – captions, messages, expressions, documentation, and more.
• DESCRIBE STRUCTURE gives you a compact tree view of the entire project or a single module, at varying levels of detail.

These commands are read-only. They never modify your project. You can run them freely to build a mental model of the application before making any changes.

What you will learn

In this chapter, you will:

1. List modules, entities, microflows, pages, and other elements with SHOW commands
2. Inspect the full definition of any element with DESCRIBE
3. Find elements by keyword with SEARCH
4. Get a bird’s-eye view of project structure with DESCRIBE STRUCTURE

Prerequisites

You should have mxcli installed and know how to open a project. If not, work through the Setting Up chapter first.

The examples in this chapter assume you have a Mendix project open. You can follow along using either the REPL or CLI one-liners:

# REPL (interactive)
mxcli -p /path/to/app.mpr

# CLI one-liner
mxcli -p /path/to/app.mpr -c "LIST ENTITIES"

If you do not have a Mendix project handy, the commands will still make sense – the output format and options are the same regardless of the project content.

LIST MODULES, LIST ENTITIES

The SHOW family of commands lists project elements by type. They are the fastest way to see what a project contains.

Listing modules

Every Mendix project is organized into modules. Start by listing them:

LIST MODULES;

Example output:

MyFirstModule
Administration
Atlas_Core
System

By default, system and marketplace modules (like System and Atlas_Core) are included. The modules appear in the order they are defined in the project.

Listing entities

To see all entities across all modules:

LIST ENTITIES;

Example output:

Administration.Account
MyFirstModule.Customer
MyFirstModule.Order
MyFirstModule.OrderLine

Each entity is shown as a qualified name – the module name and entity name separated by a dot.

Filtering by module

Most SHOW commands accept an IN clause to filter results to a single module:

LIST ENTITIES IN MyFirstModule;

MyFirstModule.Customer
MyFirstModule.Order
MyFirstModule.OrderLine

This is typically what you want when working on a specific module.

Listing microflows

LIST MICROFLOWS;

Administration.ChangeMyPassword
MyFirstModule.ACT_Customer_Save
MyFirstModule.ACT_Order_Process
MyFirstModule.DS_Customer_GetAll

Filter to a module:

LIST MICROFLOWS IN MyFirstModule;

MyFirstModule.ACT_Customer_Save
MyFirstModule.ACT_Order_Process
MyFirstModule.DS_Customer_GetAll

Listing pages

LIST PAGES;

Administration.Account_Overview
Administration.Login
MyFirstModule.Customer_Overview
MyFirstModule.Customer_Edit
MyFirstModule.Order_Detail

Filter to a module:

LIST PAGES IN MyFirstModule;

MyFirstModule.Customer_Overview
MyFirstModule.Customer_Edit
MyFirstModule.Order_Detail

Other SHOW commands

The same pattern works for all major element types:

LIST ENUMERATIONS;
LIST ENUMERATIONS IN MyFirstModule;

LIST ASSOCIATIONS;
LIST ASSOCIATIONS IN MyFirstModule;

LIST WORKFLOWS;
LIST WORKFLOWS IN MyFirstModule;

LIST NANOFLOWS;
LIST NANOFLOWS IN MyFirstModule;

LIST CONSTANTS;
LIST CONSTANTS IN MyFirstModule;

LIST SNIPPETS;
LIST SNIPPETS IN MyFirstModule;

You can also list security-related elements:

LIST MODULE ROLES;
LIST MODULE ROLES IN MyFirstModule;

LIST USER ROLES;

LIST DEMO USERS;

And navigation:

LIST NAVIGATION;

Using SHOW from the command line

Every SHOW command works as a CLI one-liner with -c:

mxcli -p app.mpr -c "LIST ENTITIES"
mxcli -p app.mpr -c "LIST MICROFLOWS IN MyFirstModule"
mxcli -p app.mpr -c "LIST PAGES"

This is useful for quick lookups without entering the REPL, and for piping output to other tools:

# Count entities per module
mxcli -p app.mpr -c "LIST ENTITIES" | cut -d. -f1 | sort | uniq -c

# Find all microflows with "Save" in the name
mxcli -p app.mpr -c "LIST MICROFLOWS" | grep -i save

Summary of SHOW commands

Now that you can list elements, the next step is inspecting individual elements in detail with DESCRIBE and SEARCH.

DESCRIBE, SEARCH

While SHOW commands list elements by name, DESCRIBE gives you the full definition of a single element. SEARCH lets you find elements by keyword when you do not know the exact name.

DESCRIBE ENTITY

To see the complete definition of an entity, including its attributes, types, and constraints:

DESCRIBE ENTITY MyFirstModule.Customer;

Example output:

CREATE PERSISTENT ENTITY MyFirstModule.Customer (
  Name: String(200),
  Email: String(200),
  Phone: String(50),
  DateOfBirth: DateTime,
  IsActive: Boolean DEFAULT false
);

The output is valid MDL – you could copy it, modify it, and execute it as a CREATE OR MODIFY statement. This round-trip capability is one of the key design features of MDL.

DESCRIBE also shows associations and access rules when they exist:

DESCRIBE ENTITY MyFirstModule.Order;

mdl 1;
CREATE PERSISTENT ENTITY MyFirstModule.Order (
  OrderNumber: AutoNumber DEFAULT 1,
  OrderDate: DateTime,
  TotalAmount: Decimal,
  Status: MyFirstModule.OrderStatus
);

CREATE ASSOCIATION MyFirstModule.Order_Customer
  FROM MyFirstModule.Order TO MyFirstModule.Customer;

DESCRIBE MICROFLOW

To see the full logic of a microflow:

DESCRIBE MICROFLOW MyFirstModule.ACT_Customer_Save;

Example output:

CREATE MICROFLOW MyFirstModule.ACT_Customer_Save
  ($Customer: MyFirstModule.Customer)
  RETURNS Boolean
BEGIN
  IF $Customer/Name = empty THEN
    VALIDATION FEEDBACK $Customer/Name MESSAGE 'Name is required';
    RETURN false;
  END IF;

  COMMIT $Customer;
  RETURN true;
END;

This shows the parameters, return type, and the complete flow logic. For complex microflows, this can be quite long – but it gives you the full picture in one command.

DESCRIBE PAGE

Pages are shown as their widget tree:

DESCRIBE PAGE MyFirstModule.Customer_Edit;

Example output:

CREATE PAGE MyFirstModule.Customer_Edit
(
  Params: ( $Customer: MyFirstModule.Customer ),
  Title: 'Edit Customer',
  Layout: Atlas_Core.PopupLayout
)
{
  DATAVIEW dvCustomer (DataSource: $Customer) {
    TEXTBOX txtName (Label: 'Name', Attribute: Name)
    TEXTBOX txtEmail (Label: 'Email', Attribute: Email)
    TEXTBOX txtPhone (Label: 'Phone', Attribute: Phone)

    FOOTER {
      ACTIONBUTTON btnSave (Caption: 'Save', Action: SAVE CHANGES, ButtonStyle: Primary)
      ACTIONBUTTON btnCancel (Caption: 'Cancel', Action: CANCEL CHANGES)
    }
  }
};

DESCRIBE ENUMERATION

DESCRIBE ENUMERATION MyFirstModule.OrderStatus;

CREATE ENUMERATION MyFirstModule.OrderStatus (
  Draft 'Draft',
  Submitted 'Submitted',
  Approved 'Approved',
  Rejected 'Rejected',
  Completed 'Completed'
);

Each value is followed by its caption (the display label shown to end users).

DESCRIBE ASSOCIATION

DESCRIBE ASSOCIATION MyFirstModule.Order_Customer;

DESCRIBE prints only the clauses that differ from the defaults (TYPE Reference, OWNER Default, STORAGE COLUMN, ON DELETE SET NULL), so an association that uses all of them comes back as just its ends:

CREATE ASSOCIATION MyFirstModule.Order_Customer
  FROM MyFirstModule.Order TO MyFirstModule.Customer;

DESCRIBE MODULE

To see the full contents of a module (all entities, microflows, pages, etc.):

DESCRIBE MODULE MyFirstModule;

This is especially useful from the CLI:

mxcli describe -p app.mpr module MyFirstModule

Other DESCRIBE targets

The same pattern works for other element types:

DESCRIBE MODULE MyFirstModule;
DESCRIBE WORKFLOW MyFirstModule.ApprovalFlow;
DESCRIBE NANOFLOW MyFirstModule.NAV_GoToDetail;
DESCRIBE SNIPPET MyFirstModule.CustomerCard;
DESCRIBE CONSTANT MyFirstModule.ApiBaseUrl;
DESCRIBE JSON STRUCTURE MyFirstModule.CustomerResponse;
DESCRIBE IMPORT MAPPING MyFirstModule.IMM_Customer;
DESCRIBE EXPORT MAPPING MyFirstModule.EMM_Customer;
DESCRIBE CONSUMED REST SERVICE MyFirstModule.PetStoreAPI;
DESCRIBE IMAGE COLLECTION MyFirstModule.Icons;
DESCRIBE NAVIGATION;
DESCRIBE SETTINGS;

Full-text search with SEARCH

When you do not know the exact name of an element, use SEARCH to find it by keyword. This searches across all strings in the project – entity names, attribute names, microflow logic, page captions, messages, documentation, and more.

SEARCH 'validation';

Example output:

MyFirstModule.ACT_Customer_Save (Microflow)
  "VALIDATION FEEDBACK $Customer/Name MESSAGE 'Name is required'"

MyFirstModule.ACT_Order_Validate (Microflow)
  "VALIDATION FEEDBACK $Order/OrderDate MESSAGE 'Order date cannot be in the past'"

MyFirstModule.Customer_Edit (Page)
  "Validation errors will appear here"

Search is case-insensitive and matches partial words.

Search from the command line

The CLI provides a dedicated search subcommand with formatting options:

# Search with default output
mxcli search -p app.mpr "validation"

# Show only element names (no context)
mxcli search -p app.mpr "validation" --format names

# JSON output for programmatic use (stdout is only the JSON array;
# progress goes to stderr, and no matches is [])
mxcli search -p app.mpr "validation" --json

The --format names option is useful for piping into other commands:

# Find all microflows mentioning "email" and describe each one
mxcli search -p app.mpr "email" --format names | while read name; do
  mxcli -p app.mpr -c "DESCRIBE MICROFLOW $name"
done

Combining SHOW, DESCRIBE, and SEARCH

A typical exploration workflow looks like this:

1. Start broad with SHOW to see what exists:

   LIST MODULES;
   LIST ENTITIES IN Sales;
   

2. Zoom in with DESCRIBE on interesting elements:

   DESCRIBE ENTITY Sales.Order;
   DESCRIBE MICROFLOW Sales.ACT_Order_Process;
   

3. Search when you need to find something specific:

   SEARCH 'discount';
   

This workflow mirrors how you would explore a project in Mendix Studio Pro – browsing the project explorer, opening documents, and using Find to locate things.

Next, learn how to get a compact overview of the entire project with DESCRIBE STRUCTURE.

DESCRIBE STRUCTURE

The DESCRIBE STRUCTURE command gives you a compact, tree-style overview of a project. It is the fastest way to understand the overall shape of an application – what modules exist, what types of documents they contain, and how large each module is.

Default view

With no arguments, DESCRIBE STRUCTURE displays all user modules at depth 2 – modules with their documents listed by type:

DESCRIBE STRUCTURE;

Example output:

MyFirstModule
  Entities
    Customer (Name, Email, Phone, DateOfBirth, IsActive)
    Order (OrderNumber, OrderDate, TotalAmount, Status)
    OrderLine (Quantity, UnitPrice, LineTotal)
  Microflows
    ACT_Customer_Save ($Customer: Customer) : Boolean
    ACT_Order_Process ($Order: Order) : Boolean
    DS_Customer_GetAll () : List of Customer
  Pages
    Customer_Overview
    Customer_Edit ($Customer: Customer)
    Order_Detail ($Order: Order)
  Enumerations
    OrderStatus (Draft, Submitted, Approved, Rejected, Completed)
Administration
  Entities
    Account (FullName, Email, IsLocalUser, BlockedSince)
  Microflows
    ChangeMyPassword ($OldPassword, $NewPassword) : Boolean
  Pages
    Account_Overview
    Login

This gives you a bird’s-eye view without opening individual elements. Entity signatures show attribute names; microflow signatures show parameters and return types.

Depth levels

The DEPTH option controls how much detail is shown:

DEPTH 1 – Module summary

Shows one line per module with element counts:

DESCRIBE STRUCTURE DEPTH 1;

MyFirstModule       3 entities, 3 microflows, 3 pages, 1 enumeration, 2 associations
Administration      1 entity, 1 microflow, 2 pages

This is useful for getting a quick sense of project size and where the complexity lives.

DEPTH 2 – Elements with signatures (default)

This is the default when you run DESCRIBE STRUCTURE with no depth specified. It shows modules, their documents grouped by type, and compact signatures for each element. See the example under Default view above.

DEPTH 3 – Full detail

Shows typed attributes and named parameters:

DESCRIBE STRUCTURE DEPTH 3;

MyFirstModule
  Entities
    Customer
      Name: String(200)
      Email: String(200)
      Phone: String(50)
      DateOfBirth: DateTime
      IsActive: Boolean DEFAULT false
    Order
      OrderNumber: AutoNumber
      OrderDate: DateTime
      TotalAmount: Decimal
      Status: MyFirstModule.OrderStatus
    OrderLine
      Quantity: Integer
      UnitPrice: Decimal
      LineTotal: Decimal
  Microflows
    ACT_Customer_Save ($Customer: MyFirstModule.Customer) : Boolean
    ACT_Order_Process ($Order: MyFirstModule.Order) : Boolean
    DS_Customer_GetAll () : List of MyFirstModule.Customer
  Pages
    Customer_Overview
    Customer_Edit ($Customer: MyFirstModule.Customer)
    Order_Detail ($Order: MyFirstModule.Order)
  Enumerations
    OrderStatus
      Draft 'Draft'
      Submitted 'Submitted'
      Approved 'Approved'
      Rejected 'Rejected'
      Completed 'Completed'
  Associations
    Order_Customer: Order -> Customer (Reference)
    OrderLine_Order: OrderLine -> Order (Reference)

Depth 3 is verbose but gives you the most complete picture without running individual DESCRIBE commands.

At depths 2 and 3 each page also lists its outermost data widgets, the ones that set up a data context, for example Page MyFirstModule.Customer_Edit [DataView<Customer>]. A data widget nested inside another one is not listed. The widget index is built only by REFRESH CATALOG FULL, so on a default catalog pages print without the list.

Filtering by module

Use IN to show only a single module:

DESCRIBE STRUCTURE IN MyFirstModule;

This produces the same tree format but limited to one module. Combine with DEPTH for control over detail:

DESCRIBE STRUCTURE DEPTH 3 IN MyFirstModule;

Including system modules

By default, system and marketplace modules are hidden. Add ALL to include them:

DESCRIBE STRUCTURE DEPTH 1 ALL;

MyFirstModule       3 entities, 3 microflows, 3 pages, 1 enumeration, 2 associations
Administration      1 entity, 1 microflow, 2 pages
Atlas_Core          0 entities, 0 microflows, 12 pages
System              15 entities, 0 microflows, 0 pages

This is useful when you need to see system entities (like System.Image or System.FileDocument) or check what a marketplace module provides.

Using DESCRIBE STRUCTURE from the command line

# Quick project overview
mxcli -p app.mpr -c "DESCRIBE STRUCTURE DEPTH 1"

# Detailed view of one module
mxcli -p app.mpr -c "DESCRIBE STRUCTURE DEPTH 3 IN Sales"

# Full project including system modules
mxcli -p app.mpr -c "DESCRIBE STRUCTURE ALL"

When to use DESCRIBE STRUCTURE vs SHOW + DESCRIBE

DESCRIBE STRUCTURE is best for orientation – understanding the shape of the project at a glance. For detailed work on specific elements, switch to DESCRIBE.

What is next

Now that you can explore a project, you are ready to start making changes. Continue to Your First Changes to learn how to create entities, microflows, and pages using MDL.

Your First Changes

Now that you can explore a project with SHOW and DESCRIBE, it’s time to make changes. This chapter walks through the three most common modifications: creating an entity, a microflow, and a page.

Before you start

Always work on a copy. mxcli writes directly to your .mpr file. Before making changes, either:

• Copy the .mpr file (and mprcontents/ folder if it exists) to a scratch directory
• Use Git so you can revert with git checkout

# Make a working copy
cp app.mpr app-scratch.mpr
cp -r mprcontents/ mprcontents-scratch/   # only for MPR v2 projects

The workflow

Every modification follows the same pattern:

1. Write MDL – either directly on the command line with -c, or in a .mdl script file
2. Check syntax – run mxcli check to catch errors before touching the project
3. Execute – apply the changes to the .mpr file
4. Validate – use mxcli docker check for a full Studio Pro-level validation
5. Open in Studio Pro – confirm the result visually

# Step 1-2: Write and check syntax
mxcli check setup.mdl

# Step 3: Execute against the project
mxcli exec setup.mdl -p app.mpr

# Step 4: Full validation
mxcli docker check -p app.mpr

# Step 5: Open in Studio Pro and inspect

You can also skip the script file and execute commands directly:

mxcli -p app.mpr -c "CREATE PERSISTENT ENTITY MyModule.Product (Name: String(200) NOT NULL, Price: Decimal);"

What we’ll build

Over the next few pages, you’ll create:

The final page, Validating with mxcli check, covers the full validation workflow in detail.

Quick note on module names

Every MDL statement references a module. In these examples we use MyModule – replace it with whatever module exists in your project. You can check available modules with:

mxcli -p app.mpr -c "LIST MODULES"

Idempotent scripts with OR MODIFY

If you plan to run a script more than once (common during development), use CREATE OR MODIFY instead of plain CREATE. This updates the entity if it already exists instead of failing:

CREATE OR MODIFY PERSISTENT ENTITY MyModule.Product (
    Name: String(200) NOT NULL,
    Price: Decimal,
    IsActive: Boolean DEFAULT true
);

The OR MODIFY variant is available for entities, enumerations, microflows, and pages. You’ll see it used throughout the tutorial.

Creating an Entity

Entities are the foundation of any Mendix application – they define your data model. In this page you’ll create a Product entity with several attributes, verify it, and then link it to another entity with an association.

Create a simple entity

The CREATE PERSISTENT ENTITY statement defines an entity that is stored in the database. Attributes go inside parentheses, separated by commas:

CREATE PERSISTENT ENTITY MyModule.Product (
    Name: String(200) NOT NULL,
    Price: Decimal,
    IsActive: Boolean DEFAULT true
);

Let’s break this down:

Run it from the command line:

mxcli -p app.mpr -c "CREATE PERSISTENT ENTITY MyModule.Product (Name: String(200) NOT NULL, Price: Decimal, IsActive: Boolean DEFAULT true);"

Or save it to a file and execute:

mxcli exec create-product.mdl -p app.mpr

Verify the entity

Use DESCRIBE ENTITY to confirm your entity was created correctly:

mxcli -p app.mpr -c "DESCRIBE ENTITY MyModule.Product"

This prints the full MDL definition of the entity, including all attributes and their types. You should see Name, Price, and IsActive listed.

Add an association

Associations link entities together. To connect Product to an existing Order entity, create a reference association:

CREATE ASSOCIATION MyModule.Order_Product
    FROM MyModule.Order TO MyModule.Product
    TYPE Reference;

This creates a many-to-one relationship: each Order can reference one Product. Use ReferenceSet instead of Reference for many-to-many.

The naming convention Order_Product follows Mendix best practices – the “from” entity name comes first, then the “to” entity.

Association types

Delete behavior

You can specify what happens when the “to” entity is deleted:

CREATE ASSOCIATION MyModule.Order_Product
    FROM MyModule.Order TO MyModule.Product
    TYPE Reference
    ON DELETE RESTRICT;

Options: PREVENT (block deletion if referenced), CASCADE (delete the associated objects too), or leave it out for the default behavior — delete the object and null out the references.

Using OR MODIFY for idempotent scripts

If you want to run the same script repeatedly without errors, use CREATE OR MODIFY:

CREATE OR MODIFY PERSISTENT ENTITY MyModule.Product (
    Name: String(200) NOT NULL,
    Price: Decimal,
    IsActive: Boolean DEFAULT true,
    Description: String(unlimited)
);

If the entity already exists, this updates it to match the new definition. If it doesn’t exist, it creates it. This is especially useful during iterative development.

More attribute types

Here’s a fuller example showing the attribute types you’ll use most often:

CREATE PERSISTENT ENTITY MyModule.Product (
    Name: String(200) NOT NULL,
    Description: String(unlimited),
    Price: Decimal,
    Quantity: Integer,
    Weight: Long,
    IsActive: Boolean DEFAULT true,
    ReleaseDate: DateTime,
    Status: MyModule.ProductStatus
);

The last attribute references an enumeration (MyModule.ProductStatus). You’d create that separately:

CREATE ENUMERATION MyModule.ProductStatus (
    Active 'Active',
    Discontinued 'Discontinued',
    OutOfStock 'Out of Stock'
);

Extending a system entity

To create an entity that inherits from a system entity (like System.Image for file storage), use EXTENDS. Note that EXTENDS must come before the opening parenthesis:

-- Correct: EXTENDS before (
CREATE PERSISTENT ENTITY MyModule.ProductPhoto EXTENDS System.Image (
    PhotoCaption: String(200)
);

-- Wrong: EXTENDS after ( -- this will cause a parse error
CREATE PERSISTENT ENTITY MyModule.ProductPhoto (
    PhotoCaption: String(200)
) EXTENDS System.Image;

Common mistakes

String needs an explicit length. String alone is not valid – you must specify the maximum length:

-- Wrong
Name: String

-- Correct
Name: String(200)

-- For unlimited length
Description: String(unlimited)

EXTENDS must come before the parenthesis. See the example above. This is a common source of parse errors.

Module must exist. The module in the qualified name (e.g., MyModule in MyModule.Product) must already exist in the project. Check with LIST MODULES.

Creating a Microflow

Microflows are the server-side logic of a Mendix application. They’re comparable to functions or methods in traditional programming. In this page you’ll create a microflow that accepts parameters, creates an object, commits it to the database, and returns it.

Create a simple microflow

This microflow takes a name and price, creates a Product object, commits it, and returns it:

CREATE MICROFLOW MyModule.CreateProduct(
    DECLARE $Name: String,
    DECLARE $Price: Decimal
)
RETURN MyModule.Product
BEGIN
    CREATE $Product: MyModule.Product (
        Name = $Name,
        Price = $Price,
        IsActive = true
    );
    COMMIT $Product;
    RETURN $Product;
END;

Let’s walk through each part:

Save this to a file (e.g., create-product-mf.mdl) and execute:

mxcli check create-product-mf.mdl
mxcli exec create-product-mf.mdl -p app.mpr

Verify the microflow

Use DESCRIBE MICROFLOW to see the generated MDL:

mxcli -p app.mpr -c "DESCRIBE MICROFLOW MyModule.CreateProduct"

This shows the full microflow definition, including parameters, activities, and the return type.

Understanding variables

All variables in MDL start with $. There are two contexts where you declare them:

Parameters (in the signature):

CREATE MICROFLOW MyModule.DoSomething(
    DECLARE $Customer: MyModule.Customer,
    DECLARE $Count: Integer
)

Local variables (inside BEGIN…END):

BEGIN
    DECLARE $Total: Integer = 0;
    DECLARE $Message: String = 'Processing...';
    DECLARE $Items: List of MyModule.Item = empty;
END;

For entity parameters, do not assign a default value – just declare the type:

-- Correct: entity parameter with no default
DECLARE $Customer: MyModule.Customer

-- Wrong: entity parameter with = empty
DECLARE $Customer: MyModule.Customer = empty

Retrieving objects

Use RETRIEVE to fetch objects from the database:

CREATE MICROFLOW MyModule.GetActiveProducts()
RETURN List of MyModule.Product
BEGIN
    RETRIEVE $Products: List of MyModule.Product
        FROM MyModule.Product
        WHERE IsActive = true;
    RETURN $Products;
END;

To retrieve a single object, add LIMIT 1:

RETRIEVE $Product: MyModule.Product
    FROM MyModule.Product
    WHERE Name = $SearchName
    LIMIT 1;

Conditional logic

Use IF ... THEN ... ELSE ... END IF for branching:

CREATE MICROFLOW MyModule.UpdateProductStatus(
    DECLARE $Product: MyModule.Product
)
RETURN Boolean
BEGIN
    IF $Product/Price > 0 THEN
        CHANGE $Product (IsActive = true);
        COMMIT $Product;
        RETURN true;
    ELSE
        LOG WARNING 'Product has no price set';
        RETURN false;
    END IF;
END;

Looping over a list

Use LOOP ... IN ... BEGIN ... END LOOP to iterate:

CREATE MICROFLOW MyModule.DeactivateProducts(
    DECLARE $Products: List of MyModule.Product
)
RETURN Boolean
BEGIN
    LOOP $Product IN $Products
    BEGIN
        CHANGE $Product (IsActive = false);
        COMMIT $Product;
    END LOOP;
    RETURN true;
END;

Note: the list $Products is a parameter. Never create an empty list variable and then loop over it – accept the list as a parameter instead.

Error handling

Add ON ERROR to handle failures on individual activities:

COMMIT $Product ON ERROR CONTINUE;

Options are CONTINUE (ignore the error and proceed), ROLLBACK (roll back the transaction and continue), or an inline error handler block:

COMMIT $Product ON ERROR BEGIN
    LOG ERROR 'Failed to commit product';
    RETURN false;
END ERROR;

Organizing with folders

Place microflows in folders using the FOLDER keyword:

CREATE MICROFLOW MyModule.CreateProduct(
    DECLARE $Name: String,
    DECLARE $Price: Decimal
)
RETURN MyModule.Product
FOLDER 'ACT'
BEGIN
    CREATE $Product: MyModule.Product (
        Name = $Name,
        Price = $Price,
        IsActive = true
    );
    COMMIT $Product;
    RETURN $Product;
END;

This places the microflow in the ACT folder within the module, following the common Mendix convention of grouping microflows by type (ACT for actions, VAL for validations, SUB for sub-microflows).

Common mistakes

Every flow path must end with RETURN. If your microflow has IF/ELSE branches, each branch needs its own RETURN statement (or the return can come after END IF if both branches converge).

COMMIT is required to persist changes. CREATE and CHANGE only modify the object in memory. Without COMMIT, changes are lost when the microflow ends.

Entity parameters don’t use = empty. Declare them with just the type. Assigning = empty is for list variables inside the microflow body, not for parameters.

Creating a Page

Pages are the user interface of a Mendix application. In this page you’ll create an overview page that lists products in a data grid, and then an edit page with a form for modifying a single product.

Prerequisites

Before creating a page, you need two things:

1. An entity – the page needs data to display. We’ll use the MyModule.Product entity from the previous steps.
2. A layout – every page is placed inside a layout that provides the overall page structure (header, sidebar, content area). The layout must already exist in your project.

To see what layouts are available:

mxcli -p app.mpr -c "LIST PAGES IN Atlas_Core"

Most Mendix projects based on Atlas UI have layouts like Atlas_Core.Atlas_Default (full page), Atlas_Core.PopupLayout (dialog), and others.

Create an overview page

An overview page typically shows a data grid that lists all objects of an entity:

CREATE PAGE MyModule.ProductOverview
(
    Title: 'Products',
    Layout: Atlas_Core.Atlas_Default
)
{
    DATAGRID dgProducts (DataSource: DATABASE MyModule.Product) {
        COLUMN (Attribute: Name, Caption: 'Name')
        COLUMN (Attribute: Price, Caption: 'Price')
        COLUMN (Attribute: IsActive, Caption: 'Active')
    }
};

Let’s break this down:

Execute it:

mxcli -p app.mpr -c "CREATE PAGE MyModule.ProductOverview (Title: 'Products', Layout: Atlas_Core.Atlas_Default) { DATAGRID dgProducts (DataSource: DATABASE MyModule.Product) { COLUMN colName (Attribute: Name, Caption: 'Name') COLUMN colPrice (Attribute: Price, Caption: 'Price') COLUMN colActive (Attribute: IsActive, Caption: 'Active') } }"

Or save to a file and run:

mxcli check create-pages.mdl
mxcli exec create-pages.mdl -p app.mpr

Verify the page

mxcli -p app.mpr -c "DESCRIBE PAGE MyModule.ProductOverview"

This prints the full page definition with all widgets and their properties.

Create an edit page

Edit pages use a DataView to display and edit a single object. The object is passed as a page parameter:

CREATE PAGE MyModule.Product_Edit
(
    Params: ( $Product: MyModule.Product ),
    Title: 'Edit Product',
    Layout: Atlas_Core.PopupLayout
)
{
    DATAVIEW dvProduct (DataSource: $Product) {
        TEXTBOX txtName (Label: 'Name', Attribute: Name)
        TEXTBOX txtPrice (Label: 'Price', Attribute: Price)
        CHECKBOX cbActive (Label: 'Active', Attribute: IsActive)

        FOOTER {
            ACTIONBUTTON btnSave (Caption: 'Save', Action: SAVE CHANGES, ButtonStyle: Primary)
            ACTIONBUTTON btnCancel (Caption: 'Cancel', Action: CANCEL CHANGES)
        }
    }
};

Key differences from the overview page:

Notice the two different page syntaxes: the overview page uses the compact syntax (LAYOUT and TITLE as keywords before parentheses), while the edit page uses the property syntax (properties inside a (Key: value) block followed by a { widget tree } block). Both are valid – use whichever fits better.

Widget reference

Here are the most commonly used widgets:

Input widgets

TEXTBOX txtName (Label: 'Name', Attribute: Name)
TEXTAREA txtDesc (Label: 'Description', Attribute: Description)
CHECKBOX cbActive (Label: 'Active', Attribute: IsActive)
DATEPICKER dpCreated (Label: 'Created', Attribute: CreatedDate)
COMBOBOX cbStatus (Label: 'Status', Attribute: Status)
RADIOBUTTONS rbType (Label: 'Type', Attribute: ProductType)

Display widgets

DYNAMICTEXT dynName (Attribute: Name)

Action buttons

ACTIONBUTTON btnSave (Caption: 'Save', Action: SAVE CHANGES, ButtonStyle: Primary)
ACTIONBUTTON btnCancel (Caption: 'Cancel', Action: CANCEL CHANGES)
ACTIONBUTTON btnDelete (Caption: 'Delete', Action: DELETE, ButtonStyle: Danger)
ACTIONBUTTON btnProcess (Caption: 'Process', Action: CALL MICROFLOW MyModule.ACT_ProcessProduct(Product = $Product))

Layout widgets

CONTAINER cntWrapper (Class: 'card') {
    -- child widgets go here
}

LAYOUTGRID lgMain {
    ROW r1 {
        COLUMN c1 (Weight: 6) { ... }
        COLUMN c2 (Weight: 6) { ... }
    }
}

Embedding a snippet

To reuse a page fragment, call a snippet:

SNIPPETCALL scProductCard (Snippet: MyModule.ProductCard)

The snippet must already exist in the project.

Common mistakes

Layout must exist in the project. If you specify a layout that doesn’t exist, the page will fail validation. Check available layouts with LIST PAGES and look for documents of type Layout.

Widget names must be unique within a page. Every widget needs a name (e.g., txtName, btnSave), and these must not collide within the same page.

DataView needs a data source. A DataView must know where its data comes from – either a page parameter (DataSource: $Product), a microflow, or a nested context.

Validating with mxcli check

You’ve created entities, microflows, and pages. Before opening your project in Studio Pro, you should validate that everything is correct. mxcli provides three levels of validation, each catching different kinds of problems.

Level 1: Syntax check (no project needed)

The fastest check. It parses your MDL script and reports syntax errors without touching any .mpr file:

mxcli check script.mdl --no-project

Without --no-project, a plain mxcli check script.mdl run from a directory holding exactly one .mpr auto-detects it (it prints Using project: ...) and goes on to Level 2 against it. --no-project gives the syntax-only check wherever you run it.

This catches:

• Typos in keywords (CRETE instead of CREATE)
• Missing semicolons or parentheses
• Invalid attribute type syntax (String without a length)
• Anti-patterns like empty list variables used as loop sources
• Nested loops that should use RETRIEVE for lookups

You don’t even need a project file for this. It’s a pure syntax and structure check, so it runs instantly.

Checking inline commands

You can also check a single statement:

mxcli check -c "CREATE PERSISTENT ENTITY MyModule.Product (Name: String(200));"

Level 2: Syntax + reference validation

Add -p and --references to also verify that names in your script resolve to real elements in the project:

mxcli check script.mdl -p app.mpr --references

This catches everything Level 1 catches, plus:

• References to entities that don’t exist (MyModule.NonExistent)
• References to attributes that don’t exist on an entity
• Microflow calls to non-existent microflows
• Page layouts that don’t exist in the project
• Association endpoints pointing to missing entities
• A plain create whose name already exists in the project
• A statement the project’s Mendix version cannot store (MDL-VERSION01, e.g. create view entity below 10.21) — the same version gates exec refuses with

This is the check you should run before executing a script. It’s fast (reads the project but doesn’t modify it) and catches most mistakes.

mxcli exec runs the same semantic checks before it writes anything, and refuses a script with an error. It prints errors and warnings in full but only counts the info notes (2 info notes not shown — run mxcli check script.mdl to see them), so a re-run stays readable; check prints every note, and exec --verbose does too.

References inside an excluded document (@excluded, or a page or snippet that stays excluded because its stored namesake is) are reported as Reference warnings rather than errors, because Mendix does not validate excluded documents. A missing data-source flow is a warning too, but only when every binding inside that container is qualified (Module.Entity.Attribute) — describe page writes them that way there. The widgets bind against the entity the flow returns, so with the flow missing a bare binding cannot be resolved and the check fails, naming the widget. A missing entity still fails the check.

Name conflicts with the project

A plain create of something the project already has is reported here rather than left to exec:

statement 4: association already exists in project: Sales.Order_Customer — use CREATE OR MODIFY to update it

This matters because exec stops at the first such statement, having already written the ones before it — so a script that only fails at execution time leaves the project half-modified. --references reports every conflict in the script up front, before anything is written.

Three spellings say “it is fine if this already exists”, and none of them is reported as a conflict:

create module M; is also never reported: it is a no-op when the module exists, which is why it can safely open every script.

Level 3: Full project validation with mx check

After executing your script, validate the entire project using the Mendix toolchain:

mxcli setup mxbuild -p app.mpr   # once per Mendix version
mxcli docker check -p app.mpr

This runs Mendix’s own mx check tool on a temporary copy of the project. It performs the same validation that Studio Pro does when you open a project, catching issues that mxcli’s parser cannot detect:

• BSON serialization errors (malformed internal data)
• Security configuration problems (missing access rules, CE0066 errors)
• Widget definition mismatches (CE0463 errors), each labelled either a stale widget definition, which mxcli fix widgets clears, or one that persists after update-widgets
• Missing required properties on widgets
• Broken cross-references between documents

docker check does not download MxBuild, and does not use Docker: the docker in its name groups it with docker build. It runs the mx of an MxBuild already on the machine, as a local process, and stops with mx not found when there is none. mxcli setup mxbuild -p app.mpr downloads the project’s version once and caches it under ~/.mxcli/mxbuild/; mxcli new and mxcli docker build download it too.

With a local Mendix installation

If you have mx installed locally (e.g., from a Mendix installation), the check finds it on PATH or in the Studio Pro installation, and setup mxbuild is not needed. To choose a specific one:

mxcli docker check -p app.mpr --mxbuild-path /path/to/mendix

The recommended workflow

Here’s the workflow you should follow for every change:

Write MDL --> Check syntax --> Execute --> Docker check --> Open in Studio Pro

In practice:

# 1. Write your MDL in a script file
cat > changes.mdl << 'EOF'
CREATE OR MODIFY PERSISTENT ENTITY MyModule.Product (
    Name: String(200) NOT NULL,
    Price: Decimal,
    IsActive: Boolean DEFAULT true
);

CREATE OR MODIFY MICROFLOW MyModule.CreateProduct(
    DECLARE $Name: String,
    DECLARE $Price: Decimal
)
RETURN MyModule.Product
BEGIN
    CREATE $Product: MyModule.Product (
        Name = $Name,
        Price = $Price,
        IsActive = true
    );
    COMMIT $Product;
    RETURN $Product;
END;
EOF

# 2. Check syntax (fast, no project used)
mxcli check changes.mdl --no-project

# 3. Check references (needs project, still fast)
mxcli check changes.mdl -p app.mpr --references

# 4. Execute against the project
mxcli exec changes.mdl -p app.mpr

# 5. Full validation
mxcli docker check -p app.mpr

# 6. Open in Studio Pro and verify visually

Previewing changes with diff

Before executing, you can preview what a script would change:

mxcli diff -p app.mpr changes.mdl

This runs the script with exec’s own code on a scratch copy of the project and shows every document exec would create, modify or remove, each as its describe before and after. It does not modify the project.

What mxcli check catches automatically

Beyond basic syntax, mxcli check includes built-in anti-pattern detection:

Linting for deeper analysis

For a broader set of checks across the entire project (not just a single script), use the linter:

mxcli lint -p app.mpr

This runs 19 built-in rules plus 31 Starlark rules covering security, architecture, quality, and naming conventions. See mxcli lint --list-rules for the full list.

For CI/CD integration, output in SARIF format:

mxcli lint -p app.mpr --format sarif > results.sarif

Working with AI Assistants

mxcli is built from the ground up to work with AI coding assistants. The mxcli init command sets up your Mendix project with skills, configuration files, and a dev container so that AI tools can read and modify your project using MDL.

Why AI + MDL?

Mendix projects are stored in binary .mpr files. AI assistants cannot read or edit binary files directly. mxcli solves this by providing MDL – a text-based, SQL-like language that describes Mendix model elements. An AI assistant uses mxcli commands to explore the project, writes MDL scripts to make changes, validates them, and executes them against the .mpr file.

The result: you describe what you want in natural language, and the AI builds it in your Mendix project.

The token efficiency advantage

When working with AI APIs, context window size is a critical constraint. MDL’s compact syntax provides a significant advantage over JSON model representations:

Fewer tokens means lower API costs, more of your application fits in a single prompt, and the AI produces better results because there is less noise in the context.

Supported AI tools

mxcli supports six AI coding assistants out of the box, plus a universal format that works with any tool:

# List all supported tools
mxcli init --list-tools

How it works at a glance

The workflow is the same regardless of which AI tool you use:

1. Initialize – mxcli init creates config files, skills, and a dev container
2. Open in dev container – sandboxes the AI so it only accesses your project
3. Start the AI assistant – Claude Code, GitHub Copilot, Cursor, etc.
4. Ask for changes in natural language – “Create a Customer entity with name and email”
5. The AI explores – it runs SHOW, DESCRIBE, and SEARCH commands via mxcli
6. The AI writes MDL – guided by the skill files installed in your project
7. The AI validates – mxcli check catches syntax errors before anything is applied
8. The AI executes – the MDL script is run against your .mpr file
9. You review in Studio Pro – open the project and verify the result

The next pages cover each tool in detail, starting with Claude Code.

Claude Code Integration

Claude Code is the primary AI integration for mxcli. It gets the deepest support: a dedicated configuration directory, project-level context in CLAUDE.md, skill files that teach Claude MDL patterns, and slash commands for common operations.

Initializing a project

Claude Code is the default tool, so you don’t need to specify a flag:

mxcli init /path/to/my-mendix-project

This is equivalent to:

mxcli init --tool claude /path/to/my-mendix-project

What gets created

After running mxcli init, your project directory gains several new entries:

my-mendix-project/
├── CLAUDE.md                    # Project context for Claude Code
├── AGENTS.md                    # Universal AI assistant guide
├── .claude/
│   ├── settings.json            # Claude Code settings
│   ├── commands/                # Slash commands (/create-entity, etc.)
│   └── lint-rules/              # Starlark lint rules
├── .ai-context/
│   ├── skills/                  # MDL pattern guides (shared by all tools)
│   └── examples/                # Example MDL scripts
├── .devcontainer/
│   ├── devcontainer.json        # Dev container configuration
│   └── Dockerfile               # Container image with mxcli, JDK, Docker
├── mxcli                        # CLI binary (copied into project)
└── app.mpr                      # Your Mendix project (already existed)

CLAUDE.md

The CLAUDE.md file gives Claude Code project-level context. It describes what mxcli is, lists the available MDL commands, and tells Claude to read the skill files before writing MDL. This file is automatically read by Claude Code when it starts.

Skills

The .claude/skills/ directory (and .ai-context/skills/ for the universal copy) holds one directory per skill, each with a SKILL.md. For example, write-microflows/SKILL.md explains microflow syntax, common mistakes, and a validation checklist. Claude Code discovers them from .claude/skills/ automatically and reads the relevant one before generating MDL, which dramatically improves output quality.

Commands

The .claude/commands/ directory contains slash commands that you can invoke from within Claude Code. These provide shortcuts for common operations.

Setting up the dev container

The dev container is the recommended way to work with Claude Code. It sandboxes the AI so it can only access your project files, and it comes pre-configured with everything you need.

What’s installed in the container

Opening the dev container

1. Open your project folder in VS Code
2. VS Code detects the .devcontainer/ directory and shows a notification
3. Click “Reopen in Container” (or use the command palette: Dev Containers: Reopen in Container)
4. Wait for the container to build (first time takes a few minutes)
5. Once inside the container, open a terminal

Starting Claude Code

With the dev container running, open a terminal in VS Code and start Claude:

claude

Claude Code now has access to your project files, the mxcli binary, and all the skill files. You can start asking it to do things.

How Claude works with your project

Claude follows a consistent pattern when you ask it to modify your Mendix project:

1. Explore

Claude uses mxcli commands to understand your project before making changes:

-- What modules exist?
LIST MODULES;

-- What entities are in this module?
LIST ENTITIES IN Sales;

-- What does this entity look like?
DESCRIBE ENTITY Sales.Customer;

-- What microflows exist?
LIST MICROFLOWS IN Sales;

-- Search for something specific
SEARCH 'validation';

2. Read the relevant skill

Before writing MDL, Claude reads the appropriate skill file. If you ask for a microflow, it reads write-microflows.md. If you ask for a page, it reads create-page.md. The skills contain syntax references, examples, and validation checklists.

3. Write MDL

Claude generates an MDL script based on what it learned from the project and the skill files:

/** Customer master data */
@Position(100, 100)
CREATE PERSISTENT ENTITY Sales.Customer (
    Name: String(200) NOT NULL,
    Email: String(200) NOT NULL,
    Phone: String(50),
    IsActive: Boolean DEFAULT true
);

4. Validate

Claude checks the script for syntax errors and reference issues:

./mxcli check script.mdl
./mxcli check script.mdl -p app.mpr --references

5. Execute

If validation passes, Claude runs the script against your project:

./mxcli -p app.mpr -c "EXECUTE SCRIPT 'script.mdl'"

6. Verify

Claude can run a full project check using the Mendix build tools:

./mxcli docker check -p app.mpr

Example interaction

Here is a typical conversation with Claude Code:

You: Create a Customer entity in the Sales module with name, email, and phone. Then create an overview page that shows all customers in a data grid.

Claude (explores the project):

./mxcli -p app.mpr -c "LIST MODULES"
./mxcli -p app.mpr -c "LIST ENTITIES IN Sales"
./mxcli -p app.mpr -c "LIST PAGES IN Sales"

Claude (reads skills, writes MDL, validates, and executes):

mdl 1;
/** Customer contact information */
@Position(100, 100)
CREATE PERSISTENT ENTITY Sales.Customer (
    Name: String(200) NOT NULL,
    Email: String(200) NOT NULL,
    Phone: String(50),
    IsActive: Boolean DEFAULT true,
    CreatedAt: DateTime DEFAULT '[%CurrentDateTime%]'
);

/** Customer overview page with data grid */
CREATE PAGE Sales.Customer_Overview
(
  Title: 'Customers',
  Layout: Atlas_Core.Atlas_Default
)
{
  LAYOUTGRID mainGrid {
    ROW {
      COLUMN (DesktopWidth: 12) {
        DATAGRID dgCustomers (
          DataSource: DATABASE FROM Sales.Customer SORT BY Name ASC
        ) {
          COLUMN (Attribute: Name, Caption: 'Name')
          COLUMN (Attribute: Email, Caption: 'Email')
          COLUMN (Attribute: Phone, Caption: 'Phone')
          COLUMN (Attribute: IsActive, Caption: 'Active')
        }
      }
    }
  }
};

Claude validates the script, executes it, and reports back. You can then open the project in Studio Pro to review the result.

Tips for working with Claude Code

• Be specific about module names. Say “Create a Customer entity in the Sales module” rather than just “Create a Customer entity.”
• Mention existing elements. If you want an association to an existing entity, name it: “Link Order to the existing Sales.Customer entity.”
• Let Claude explore first. If you’re asking for changes to an existing project, Claude will run SHOW and DESCRIBE commands to understand what’s already there. This leads to better results than trying to describe the current state yourself.
• Review in Studio Pro. After Claude makes changes, open the project in Studio Pro to verify everything looks right visually.
• Use mxcli docker check to catch issues that mxcli check alone might miss. The Mendix build tools perform deeper validation.

Next steps

If you use other AI tools alongside Claude Code, see Other AI tools (GitHub Copilot, OpenCode, Cursor, Continue.dev, Windsurf). To understand how skills work in detail, see Skills and CLAUDE.md.

OpenCode Integration

OpenCode is a fully supported AI integration for mxcli. It gets deep support: a dedicated configuration directory, project-level context in AGENTS.md, skill files that teach the AI MDL patterns, slash commands for common operations, and Starlark lint rules.

Initializing a project

Use the --tool opencode flag:

mxcli init --tool opencode /path/to/my-mendix-project

To set up both OpenCode and Claude Code together:

mxcli init --tool opencode --tool claude /path/to/my-mendix-project

What gets created

After running mxcli init --tool opencode, your project directory gains:

my-mendix-project/
├── AGENTS.md                    # Universal AI assistant guide (OpenCode reads this)
├── opencode.json                # OpenCode configuration file
├── .opencode/
│   ├── commands/                # Slash commands (/create-entity, etc.)
│   └── skills/                  # MDL pattern guides (OpenCode skill format)
│       ├── write-microflows/
│       │   └── SKILL.md
│       ├── create-page/
│       │   └── SKILL.md
│       └── ...
├── .claude/
│   └── lint-rules/              # Starlark lint rules (shared with mxcli lint)
├── .ai-context/
│   ├── skills/                  # Shared skill files (universal copy)
│   └── examples/                # Example MDL scripts
├── .devcontainer/
│   ├── devcontainer.json        # Dev container configuration
│   └── Dockerfile               # Container image with mxcli, JDK, Docker
├── mxcli                        # CLI binary (copied into project)
└── app.mpr                      # Your Mendix project (already existed)

opencode.json

The opencode.json file is OpenCode’s primary configuration. Its instructions are AGENTS.md alone:

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "AGENTS.md"
  ]
}

The skills are not listed there. OpenCode inlines every instruction file’s whole body into the system prompt, so listing the skill trees put about 2.7 MB of skill text in front of every session. OpenCode discovers the skills in .opencode/skills/ itself and loads a skill’s body only when its description matches the task.

Skills

Skills live in .opencode/skills/<name>/SKILL.md and use YAML frontmatter that OpenCode understands. The description is the skill’s own, with its “Use when…” clause, since that is what OpenCode matches a task against:

---
name: write-microflows
description: 'Microflow syntax reference in MDL — … Use before writing any CREATE MICROFLOW …'
compatibility: opencode
---

# Writing Microflows
...

Each skill covers a specific area: microflow syntax, page patterns, security setup, and so on. OpenCode reads the relevant skill before generating MDL, which significantly improves output quality.

Commands

The .opencode/commands/ directory contains slash commands available inside OpenCode. These mirror the Claude Code commands: /create-entity, /create-microflow, /create-page, /lint, and others.

Lint rules

Lint rules live in .claude/lint-rules/ regardless of which tool is selected — this is where mxcli lint looks for custom Starlark rules. OpenCode init writes the rules there so mxcli lint works the same way for both tool choices.

Setting up the dev container

The dev container setup is identical to the Claude Code workflow. Open your project folder in VS Code, click “Reopen in Container” when prompted, and wait for the container to build.

What’s installed in the container

Starting OpenCode

With the dev container running, open a terminal in VS Code and start OpenCode:

opencode

OpenCode now has access to your project files, the mxcli binary, the skill files in .opencode/skills/, and the commands in .opencode/commands/.

How OpenCode works with your project

The workflow mirrors Claude Code exactly:

1. Explore

OpenCode uses mxcli commands to understand the project before making changes:

-- What modules exist?
LIST MODULES;

-- What entities are in this module?
LIST ENTITIES IN Sales;

-- What does this entity look like?
DESCRIBE ENTITY Sales.Customer;

-- What microflows exist?
LIST MICROFLOWS IN Sales;

-- Search for something specific
SEARCH 'validation';

2. Read the relevant skill

Before writing MDL, OpenCode reads the appropriate skill file from .opencode/skills/. If you ask for a microflow, it reads the write-microflows skill. If you ask for a page, it reads create-page.

3. Write MDL

OpenCode generates an MDL script based on the project context and skill guidance:

/** Customer master data */
@Position(100, 100)
CREATE PERSISTENT ENTITY Sales.Customer (
    Name: String(200) NOT NULL,
    Email: String(200) NOT NULL,
    Phone: String(50),
    IsActive: Boolean DEFAULT true
);

4. Validate

./mxcli check script.mdl
./mxcli check script.mdl -p app.mpr --references

5. Execute

./mxcli -p app.mpr -c "EXECUTE SCRIPT 'script.mdl'"

6. Verify

./mxcli docker check -p app.mpr

Adding OpenCode to an existing project

If you already ran mxcli init for another tool and want to add OpenCode support:

mxcli add-tool opencode

This creates .opencode/, opencode.json, and the lint rules without touching any existing configuration.

Tips for working with OpenCode

• Be specific about module names. Say “Create a Customer entity in the Sales module” rather than just “Create a Customer entity.”
• Mention existing elements. If you want an association to an existing entity, name it: “Link Order to the existing Sales.Customer entity.”
• Let the AI explore first. OpenCode will run SHOW and DESCRIBE commands to understand what’s already in the project. This leads to better results.
• Review in Studio Pro. After changes are applied, open the project in Studio Pro to verify the result visually.
• Use mxcli docker check to catch issues that mxcli check alone might miss.

Next steps

To understand what the skill files contain and how they guide AI behavior, see Skills and CLAUDE.md. For other supported tools, see Other AI tools (Cursor, Continue.dev, Windsurf, OpenCode).

Other AI tools

Claude Code is the default integration, but mxcli also supports OpenCode, Cursor, Continue.dev, Windsurf, Aider, and Mistral Vibe. Each tool gets its own configuration file that teaches the AI about MDL syntax and mxcli commands.

Initializing for a specific tool

Use the --tool flag to specify which AI tool you use:

# OpenCode
mxcli init --tool opencode /path/to/my-mendix-project

# Cursor
mxcli init --tool cursor /path/to/my-mendix-project

# Continue.dev
mxcli init --tool continue /path/to/my-mendix-project

# Windsurf
mxcli init --tool windsurf /path/to/my-mendix-project

# Aider
mxcli init --tool aider /path/to/my-mendix-project

# Mistral Vibe
mxcli init --tool vibe /path/to/my-mendix-project

Setting up multiple tools

You can configure several tools at once. This is useful if different team members use different editors, or if you want to try several tools on the same project:

# Multiple tools
mxcli init --tool claude --tool cursor /path/to/my-mendix-project

# All supported tools at once
mxcli init --all-tools /path/to/my-mendix-project

Adding a tool to an existing project

If you already ran mxcli init and want to add support for another tool without re-initializing:

mxcli add-tool cursor
mxcli add-tool windsurf

This creates the tool-specific config file without touching the existing setup.

What each tool gets

Every tool gets the universal files that are always created:

On top of the universal files, each tool gets its own configuration:

Tool details

OpenCode

OpenCode receives full integration on par with Claude Code: dedicated skills in .opencode/skills/, slash commands in .opencode/commands/, and Starlark lint rules in .claude/lint-rules/. See the dedicated OpenCode Integration page for the complete walkthrough.

mxcli init --tool opencode /path/to/project

GitHub Copilot

GitHub Copilot has dedicated support via --tool copilot, which generates .github/copilot-instructions.md — Copilot’s project-level instructions file that’s automatically loaded in VS Code.

mxcli init --tool copilot /path/to/project

The generated file is compact (Copilot has a smaller instruction context window than Claude Code) and points to AGENTS.md and .ai-context/skills/ for full reference material. It includes the critical ./mxcli (not mxcli) rule, quick command examples, and MDL syntax reminders.

For many organizations, Copilot is the default AI assistant as part of their Microsoft/GitHub enterprise agreement. To use: open the project in VS Code with the GitHub Copilot extension, open Copilot Chat (Ctrl+Shift+I), and ask for Mendix changes. Copilot will reference .github/copilot-instructions.md, AGENTS.md, and the skill files for MDL syntax guidance.

Cursor

Cursor reads its instructions from .cursorrules in the project root. The file mxcli generates contains a compact MDL syntax reference and a list of mxcli commands the AI can use. Cursor’s Composer and Chat features will reference this file automatically.

mxcli init --tool cursor /path/to/project

Created files:

• .cursorrules – MDL syntax, command reference, and conventions
• AGENTS.md – universal guide (Cursor also reads this)
• .ai-context/skills/ – shared skill files

To use: open the project in Cursor, then use Composer (Ctrl+I) or Chat (Ctrl+L) to ask for Mendix changes.

Continue.dev

Continue.dev uses a JSON configuration file with custom commands. The generated config tells Continue about mxcli and provides slash commands for common MDL operations.

mxcli init --tool continue /path/to/project

Created files:

• .continue/config.json – custom commands, slash command definitions
• AGENTS.md and .ai-context/skills/ – universal files

To use: open the project in VS Code with the Continue extension, then use the Continue sidebar to ask for changes.

Windsurf

Windsurf reads .windsurfrules from the project root. The generated file contains MDL rules and mxcli command documentation tailored for Codeium’s AI.

mxcli init --tool windsurf /path/to/project

Created files:

• .windsurfrules – MDL rules and command reference
• AGENTS.md and .ai-context/skills/ – universal files

To use: open the project in Windsurf, then use Cascade to ask for Mendix changes.

Aider

Aider is a terminal-based AI pair programming tool. The generated YAML config tells Aider about the project structure and available commands.

mxcli init --tool aider /path/to/project

Created files:

• .aider.conf.yml – Aider configuration
• AGENTS.md and .ai-context/skills/ – universal files

To use: run aider in the project directory from the terminal.

Mistral Vibe

Mistral Vibe is a terminal-based AI coding agent by Mistral AI. It uses .vibe/config.toml for configuration, .vibe/prompts/ for system prompts, and .vibe/skills/ for SKILL.md-based skills.

mxcli init --tool vibe /path/to/project

Created files:

• .vibe/config.toml – project configuration with system prompt reference
• .vibe/prompts/mendix-mdl.md – system prompt with project context and mxcli commands
• .vibe/skills/write-microflows/SKILL.md – microflow syntax and rules
• .vibe/skills/create-page/SKILL.md – page/widget syntax
• .vibe/skills/check-syntax/SKILL.md – validation workflow
• .vibe/skills/explore-project/SKILL.md – project query commands
• AGENTS.md and .ai-context/skills/ – universal files

To use: run vibe in the project directory from the terminal. Vibe auto-discovers skills in .vibe/skills/ and loads the system prompt from .vibe/prompts/.

The universal format: AGENTS.md

Regardless of which tool you pick, mxcli always creates AGENTS.md and the .ai-context/ directory. These use a universal format that most AI tools understand:

• AGENTS.md is a comprehensive guide placed in the project root. It describes mxcli, lists MDL commands, and explains the development workflow. Many AI tools (GitHub Copilot, OpenAI Codex, and others) automatically read markdown files in the project root.
• .ai-context/skills/ contains the same skill files that Claude Code gets, but in the shared location. Any tool that can read project files can reference these.

This means even if your AI tool is not in the supported list, it can still benefit from mxcli init. The AGENTS.md file and skill directory provide enough context for any AI assistant to work with MDL.

Listing supported tools

To see all tools mxcli knows about:

mxcli init --list-tools

Next steps

To understand what the skill files contain and how they guide AI behavior, see Skills and CLAUDE.md.

Skills and CLAUDE.md

Skills teach AI assistants how to write correct MDL. Each skill covers a specific topic – creating pages, writing microflows, managing security – and contains syntax references, examples, and validation checklists. When an AI assistant needs to generate MDL, it reads the relevant skill first, which dramatically improves output quality.

The format

Skills follow the Agent Skills standard: each one is a directory holding a SKILL.md, whose YAML frontmatter says what it covers and when to use it.

.ai-context/skills/
└── write-microflows/
    └── SKILL.md

---
name: write-microflows
description: Microflow syntax reference in MDL -- every activity type, control flow,
  expressions, and the mistakes that fail `mxcli check`. Use before writing any
  CREATE MICROFLOW, and when debugging a microflow syntax error.
---

# Mendix Microflow Skill
...

The description is what makes a skill findable. A tool that reads skills loads every description up front – a line or two each – and pulls in the full body only when one is actually needed. So the assistant knows the whole set exists without any of them costing context until used, and without a hand-maintained index that can fall out of step.

Where skills live

mxcli init installs the same set in two places:

The .claude/skills/ copy exists because that is the only directory Claude Code scans, one level deep. Both copies are refreshed from the mxcli binary on every session by mxcli init --sync-skills, so they cannot drift apart.

If you are upgrading a project created by an older mxcli, the flat <name>.md files it used to write are retired automatically on the next refresh. Skill files you added yourself are left alone.

Available skills

mxcli init installs the following skill files:

What a skill file contains

A typical skill file has four sections:

1. Syntax reference

The core MDL syntax for the topic, with all available options and keywords:

-- From write-microflows.md:
CREATE MICROFLOW Module.Name(
    $param: Module.Entity
) RETURNS Boolean AS $result
BEGIN
    -- activities here
END;

2. Examples

Complete, working MDL examples that the AI can use as templates:

-- From create-page.md:
CREATE PAGE Sales.Customer_Overview
(
  Title: 'Customers',
  Layout: Atlas_Core.Atlas_Default
)
{
  DATAGRID dgCustomers (
    DataSource: DATABASE FROM Sales.Customer SORT BY Name ASC
  ) {
    COLUMN (Attribute: Name, Caption: 'Name')
  }
};

3. Common mistakes

A list of errors the AI should avoid. For example, write-microflows.md warns against creating empty list variables as loop sources, and create-page.md documents required widget properties that are easy to forget.

4. Validation checklist

Steps the AI should follow after writing MDL to confirm correctness:

# Syntax check only (--no-project: do not auto-detect an .mpr in this directory)
./mxcli check script.mdl --no-project

# Syntax + reference validation
./mxcli check script.mdl -p app.mpr --references

CLAUDE.md

The CLAUDE.md file is specific to Claude Code. It sits in the project root and is automatically read by Claude when it starts. It provides:

• Project overview – what the project is, which modules exist, and what mxcli is
• Available commands – a summary of mxcli commands Claude can use
• Rules – instructions like “always read the relevant skill file before writing MDL” and “always validate with mxcli check before executing”
• Conventions – project-specific naming conventions, module structure, etc.

Think of CLAUDE.md as the “system prompt” for Claude Code in the context of your project. It sets the tone and establishes guardrails.

AGENTS.md

AGENTS.md serves the same purpose as CLAUDE.md but in a universal format. It is always created by mxcli init, regardless of which tool you selected. AI tools that don’t have their own config format (or that read markdown files from the project root) will pick up AGENTS.md automatically.

Adding custom skills

You can create your own skills to teach the AI about your project’s patterns and conventions. Add a directory with a SKILL.md to .ai-context/skills/ (and .claude/skills/ if you use Claude Code):

.ai-context/skills/
├── write-microflows/SKILL.md         # Built-in (installed by mxcli init)
├── create-page/SKILL.md              # Built-in
├── our-naming-conventions/SKILL.md   # Custom: your team's naming rules
├── order-processing-pattern/SKILL.md # Custom: how orders work in your app
└── api-integration-guide/SKILL.md    # Custom: how to call external APIs

mxcli init --sync-skills only rewrites the skills mxcli itself ships, so your own directories survive every upgrade. It also refreshes the bundled lint rules and the mxcli section of CLAUDE.md — see Syncing with Updates.

A custom skill is a markdown document with two lines of frontmatter. Write the body the way you would explain something to a new team member, and write the description so an assistant can tell from it alone whether this is the skill for the job:

---
name: order-processing-pattern
description: How orders are processed in this application -- validation rules,
  status enumeration, logging node and confirmation email. Use when writing or
  changing any microflow that touches an Order.
---

# Order Processing Pattern

When creating microflows that process orders in our application, follow these rules:

1. Always validate the order has at least one OrderLine
2. Use the Sales.OrderStatus enumeration for status tracking
3. Log to the 'OrderProcessing' node at INFO level
4. Send a confirmation email via Sales.SendNotification

## Example

\```sql
CREATE MICROFLOW Sales.ACT_Order_Submit($order: Sales.Order)
RETURNS Boolean AS $success
BEGIN
    -- validation, processing, notification...
END;
\```

The AI will read your custom skills alongside the built-in ones, learning your project’s specific patterns.

How the AI uses skills

The workflow is straightforward:

1. You ask for a change: “Create a page that shows all orders”
2. The AI determines which skill is relevant (in this case, create-page.md and overview-pages.md)
3. The AI reads the skill files
4. The AI writes MDL following the syntax and patterns in the skill
5. The AI validates with mxcli check
6. The AI executes the script

Skills act as a guardrail. Without them, AI assistants tend to guess at MDL syntax and get details wrong. With skills, the AI has a precise reference to follow, and the output is correct far more often.

Next steps

Now that you understand how skills guide AI behavior, see The MDL + AI Workflow for the complete recommended workflow from project initialization to review in Studio Pro.

The MDL + AI Workflow

This page walks through the complete recommended workflow for using mxcli with an AI assistant, from project setup to reviewing the result in Studio Pro.

The ten-step workflow

Step 1: Initialize the project

Start by running mxcli init on your Mendix project:

mxcli init /path/to/my-mendix-project

This creates the configuration files, skill documents, and dev container setup. If you use a tool other than Claude Code, specify it with --tool:

mxcli init --tool cursor /path/to/my-mendix-project

Step 2: Open in a dev container

Open the project folder in VS Code (or Cursor). VS Code will detect the .devcontainer/ directory and prompt you to reopen in a container. Click “Reopen in Container”.

The dev container provides a sandboxed environment where the AI assistant can only access your project files. It comes with mxcli, JDK, Docker, and your AI tool pre-installed.

Step 3: Start your AI assistant

Once inside the dev container, open a terminal and start your AI tool:

# Claude Code
claude

# Or use Cursor's Composer, Continue.dev's sidebar, etc.

Step 4: Describe what you want

Tell the AI what you need in plain language. Be specific about module names and mention existing elements:

“Create a Product entity in the Sales module with name, price, and description. Add an association to the existing Sales.Category entity.”

Better prompts lead to better results. A few tips:

• Name the module explicitly: “in the Sales module”
• Reference existing elements: “linked to the existing Customer entity”
• Describe the behavior, not the implementation: “a microflow that validates the email format” rather than “an IF statement that checks for @ and .”

Step 5: The AI explores your project

Before making changes, the AI uses mxcli to understand the current state of your project:

-- See what modules exist
LIST MODULES;

-- Check what's already in the Sales module
DESCRIBE STRUCTURE IN Sales;

-- Look at an existing entity for context
DESCRIBE ENTITY Sales.Category;

-- Search for related elements
SEARCH 'product';

This exploration step is important. The AI needs to know what entities, associations, and microflows already exist so it can write MDL that fits with your project.

Step 6: The AI writes MDL

Guided by the skill files and its exploration, the AI writes an MDL script:

mdl 1;
/** Product catalog item */
@Position(300, 100)
CREATE PERSISTENT ENTITY Sales.Product (
    Name: String(200) NOT NULL,
    Description: String(0),
    Price: Decimal NOT NULL DEFAULT 0,
    IsActive: Boolean DEFAULT true
);

/** Link products to categories */
CREATE ASSOCIATION Sales.Product_Category
    FROM Sales.Product
    TO Sales.Category
    TYPE Reference
    OWNER Default;

Step 7: The AI validates

Before executing, the AI checks for errors:

# Check syntax
./mxcli check script.mdl

# Check syntax and verify that referenced elements exist
./mxcli check script.mdl -p app.mpr --references

If there are errors, the AI fixes them and re-validates. This cycle happens automatically – you don’t need to intervene.

Step 8: The AI executes

Once validation passes, the AI runs the script against your project:

./mxcli -p app.mpr -c "EXECUTE SCRIPT 'script.mdl'"

The changes are written directly to your .mpr file.

Step 9: Deep validation

For thorough validation, the AI can run the Mendix build tools:

./mxcli docker check -p app.mpr

This uses MxBuild (the same engine Studio Pro uses) to check the project for consistency errors, missing references, and other issues that mxcli check alone might miss.

Step 10: Review in Studio Pro

Open your project in Mendix Studio Pro to review the changes visually. Check that:

• Entities appear correctly in the domain model
• Pages render as expected
• Microflow logic looks right in the visual editor
• Security settings are correct

A complete example session

Here is what a full session looks like when you ask Claude Code to build a customer management feature:

You: “Create a customer management feature in the CRM module. I need a Customer entity with name, email, phone, and status. Create an overview page with a data grid and a popup edit form. Add a microflow that validates the email before saving.”

Claude Code:

1. Runs LIST MODULES and LIST ENTITIES IN CRM to understand the project
2. Reads generate-domain-model.md, overview-pages.md, and write-microflows.md skills
3. Writes a script with the entity, enumeration, pages, and microflow
4. Validates with mxcli check
5. Executes the script
6. Runs mxcli docker check to verify
7. Reports back with a summary of what was created

The entire interaction takes a few minutes. The equivalent work in Studio Pro would take considerably longer.

Tips for best results

Be specific about what exists

If you’re working with an existing project, mention the elements that are already there:

“Add a ShippingAddress field to the existing CRM.Customer entity and update the CRM.Customer_Edit page to include it.”

Let the AI explore

Don’t try to describe your entire project upfront. The AI is good at exploring. A prompt like “look at the Sales module and add a discount field to orders” is enough – the AI will figure out the entity name, existing fields, and page structure on its own.

Iterate

You don’t have to get everything right in one prompt. Start with the entity, review it, then ask for pages, then microflows. Small, focused requests tend to produce better results than one massive prompt.

Use mxcli docker check for final validation

mxcli check validates MDL syntax and references, but it doesn’t catch everything. The Mendix build tools (mxcli docker check) perform the same validation that Studio Pro does. Use it as a final gate before considering the work done.

Version control

Always work on a copy of your project or use version control. mxcli writes directly to your .mpr file. If something goes wrong, you want to be able to revert. For MPR v2 projects (Mendix 10.18+), the individual document files in mprcontents/ work well with Git.

Add custom skills for your project

If your project has specific patterns or conventions, write them down as skill files. For example, if every entity needs an audit trail (CreatedBy, CreatedAt, ChangedBy, ChangedAt), create a skill that documents this convention. The AI will follow it consistently.

MDL by Example

This part presents complete, self-contained MDL examples that show how the language comes together for real use cases. Each example is ready to run against a Mendix project.

Where Part III covers MDL syntax one statement at a time, these examples show full features built end to end – domain model, business logic, pages, and security working together.

Examples

CRM Module

A complete customer management feature: domain model, validation, CRUD pages, and security – all in one script.

Domain Model

mdl 1;
-- Enumerations first (referenced by entities)
CREATE ENUMERATION CRM.CustomerStatus (
  Active 'Active',
  Inactive 'Inactive',
  Suspended 'Suspended'
);

CREATE ENUMERATION CRM.ContactType (
  Email 'Email',
  Phone 'Phone',
  Visit 'Visit'
);

-- Entities with per-attribute documentation
/** Customer master data */
@Position(100, 100)
CREATE PERSISTENT ENTITY CRM.Customer (
  /** Auto-generated unique identifier */
  CustomerId: AutoNumber NOT NULL UNIQUE DEFAULT 1,
  /** Full legal name */
  Name: String(200) NOT NULL ERROR MESSAGE 'Customer name is required',
  /** Primary contact email */
  Email: String(200) UNIQUE ERROR MESSAGE 'Email already exists',
  /** Phone number in international format */
  Phone: String(50),
  /** Current account balance */
  Balance: Decimal DEFAULT 0,
  /** Whether the account is active */
  IsActive: Boolean DEFAULT TRUE,
  /** Current lifecycle status */
  Status: Enumeration(CRM.CustomerStatus) DEFAULT 'Active',
  /** Free-form notes about this customer */
  Notes: String(unlimited)
)
INDEX (Name)
INDEX (Email);

/** Record of a customer interaction */
@Position(400, 100)
CREATE PERSISTENT ENTITY CRM.ContactLog (
  /** Date and time of the interaction */
  ContactDate: DateTime NOT NULL,
  /** Type of interaction */
  ContactType: Enumeration(CRM.ContactType) DEFAULT 'Email',
  /** Summary of what was discussed */
  Summary: String(2000) NOT NULL ERROR MESSAGE 'Summary is required',
  /** Follow-up needed? */
  FollowUpRequired: Boolean DEFAULT FALSE
);

-- Associations
CREATE ASSOCIATION CRM.ContactLog_Customer
  FROM CRM.ContactLog TO CRM.Customer
  TYPE Reference OWNER Default;

Validation Microflow

The two-microflow pattern: a validation microflow returns field-level feedback, and an action microflow calls it before saving.

mdl 1;
CREATE MICROFLOW CRM.VAL_Customer ($Customer: CRM.Customer)
RETURNS Boolean AS $IsValid
BEGIN
  DECLARE $IsValid Boolean = true;

  IF trim($Customer/Name) = '' THEN
    SET $IsValid = false;
    VALIDATION FEEDBACK $Customer/Name MESSAGE 'Name cannot be empty';
  END IF;

  IF $Customer/Email != empty AND not(contains($Customer/Email, '@')) THEN
    SET $IsValid = false;
    VALIDATION FEEDBACK $Customer/Email MESSAGE 'Enter a valid email address';
  END IF;

  IF $Customer/Balance < 0 THEN
    SET $IsValid = false;
    VALIDATION FEEDBACK $Customer/Balance MESSAGE 'Balance cannot be negative';
  END IF;

  RETURN $IsValid;
END;

CREATE MICROFLOW CRM.ACT_Customer_Save ($Customer: CRM.Customer)
RETURNS Boolean AS $IsValid
BEGIN
  $IsValid = CALL MICROFLOW CRM.VAL_Customer(Customer = $Customer);

  IF $IsValid THEN
    COMMIT $Customer;
    CLOSE PAGE;
  END IF;

  RETURN $IsValid;
END;

Pages

mdl 1;
-- NewEdit page with validation (first: the overview opens it)
CREATE PAGE CRM.Customer_NewEdit (
  Params: ( $Customer: CRM.Customer ),
  Title: 'Customer',
  Layout: Atlas_Core.PopupLayout
) {
  LAYOUTGRID mainGrid {
    ROW {
      COLUMN (DesktopWidth: AutoFill) {
        DATAVIEW dataView1 (DataSource: $Customer) {
          TEXTBOX txtName (Label: 'Name', Attribute: Name)
          TEXTBOX txtEmail (Label: 'Email', Attribute: Email)
          TEXTBOX txtPhone (Label: 'Phone', Attribute: Phone)
          TEXTAREA txtNotes (Label: 'Notes', Attribute: Notes)
          FOOTER {
            ACTIONBUTTON btnSave (
              Caption: 'Save',
              Action: CALL MICROFLOW CRM.ACT_Customer_Save,
              ButtonStyle: Success
            )
            ACTIONBUTTON btnCancel (Caption: 'Cancel', Action: CANCEL CHANGES)
          }
        }
      }
    }
  }
};

-- Overview page with data grid
CREATE PAGE CRM.Customer_Overview (
  Title: 'Customers',
  Layout: Atlas_Core.Atlas_Default
) {
  DATAGRID dgCustomers (DataSource: DATABASE CRM.Customer, Selection: Single) {
    COLUMN (Attribute: Name, Caption: 'Name') { TEXTFILTER fName }
    COLUMN (Attribute: Email, Caption: 'Email') { TEXTFILTER fEmail }
    COLUMN (Attribute: Phone, Caption: 'Phone')
    COLUMN (Attribute: Status, Caption: 'Status')
    COLUMN (Attribute: IsActive, Caption: 'Active')
    CONTROLBAR {
      ACTIONBUTTON btnNew (Caption: 'New', Action: CREATE OBJECT CRM.Customer THEN SHOW PAGE CRM.Customer_NewEdit, ButtonStyle: Primary)
    }
  }
};

Security

mdl 1;
-- Module roles
CREATE MODULE ROLE CRM.User;
CREATE MODULE ROLE CRM.Admin DESCRIPTION 'Full customer management access';

-- Entity access
GRANT CREATE, DELETE, READ *, WRITE * ON ENTITY CRM.Customer TO CRM.Admin;
GRANT CREATE, READ *, WRITE * ON ENTITY CRM.Customer TO CRM.User
  WHERE [IsActive = true];

GRANT CREATE, DELETE, READ *, WRITE * ON ENTITY CRM.ContactLog TO CRM.Admin;
GRANT CREATE, READ *, WRITE * ON ENTITY CRM.ContactLog TO CRM.User;

-- Document access
GRANT EXECUTE ON MICROFLOW CRM.ACT_Customer_Save TO CRM.User;
GRANT VIEW ON PAGE CRM.Customer_Overview TO CRM.User;
GRANT VIEW ON PAGE CRM.Customer_NewEdit TO CRM.User;

-- User roles
CREATE OR MODIFY USER ROLE CRMUser ( ModuleRoles: (System.User, CRM.User) );
CREATE OR MODIFY USER ROLE CRMAdmin ( ModuleRoles: (System.User, CRM.Admin) );

-- Demo users for testing
CREATE OR MODIFY DEMO USER 'crm_user' ( Password: 'CrmPassword1!', UserRoles: (CRMUser) );
CREATE OR MODIFY DEMO USER 'crm_admin' ( Password: 'CrmPassword1!', UserRoles: (CRMAdmin) );
ALTER APP SECURITY ( EnableDemoUsers: TRUE );

REST Integration

Calling external APIs from microflows – GET, POST, authentication, and error handling.

Simple GET

CREATE MICROFLOW Integration.FetchWebpage ()
RETURNS String AS $Content
BEGIN
  $Content = CALL REST SERVICE GET 'https://example.com/api/status' (
    Headers: ('Accept': 'application/json'),
    Timeout: 30,
  ) RETURNS String;
  RETURN $Content;
END;

GET with URL Parameters

CREATE MICROFLOW Integration.SearchProducts (
  $Query: String,
  $Page: Integer
)
RETURNS String AS $Response
BEGIN
  $Response = CALL REST SERVICE GET 'https://api.example.com/search?q={1}&page={2}' WITH (
    {1} = urlEncode($Query),
    {2} = toString($Page)
  ) (
    Headers: ('Accept': 'application/json'),
    Timeout: 60,
  ) RETURNS String;
  RETURN $Response;
END;

POST with JSON Body

CREATE MICROFLOW Integration.CreateCustomer (
  $Name: String,
  $Email: String
)
RETURNS String AS $Response
BEGIN
  $Response = CALL REST SERVICE POST 'https://api.example.com/customers' (
    Headers: ('Content-Type': 'application/json'),
    Body: TEMPLATE '{{"name": "{1}", "email": "{2}"}' WITH (
      {1} = $Name,
      {2} = $Email
    ),
    Timeout: 30,
  ) RETURNS String;
  RETURN $Response;
END;

POST a Body Built Elsewhere

When the body is already in a variable (or any other expression), write the expression. It sends the expression’s value: mxcli stores it as the template '{1}' with the expression as its parameter, which is what Studio Pro stores, and DESCRIBE prints it in that form. A URL written as an expression (@Integration.BaseUrl + '/orders') is stored the same way.

CREATE MICROFLOW Integration.SendOrder (
  $Order: Integration.Order
)
RETURNS String AS $Response
BEGIN
  DECLARE $Payload String = '{"number": "' + $Order/Number + '"}';
  $Response = CALL REST SERVICE POST @Integration.BaseUrl + '/orders' (
    Headers: ('Content-Type': 'application/json'),
    Body: $Payload,
    Timeout: 30,
  ) RETURNS String;
  RETURN $Response;
END;

Body: TEMPLATE '$Payload' is different: a template is text, so that sends the eight characters $Payload. An expression followed by WITH (…) has no {n} placeholders to fill and is refused as MDL-REST05.

POST a Binary Body (File Upload)

Mendix models a binary request body on the REST CALL activity, not on a consumed REST client document. The expression is the file document’s Contents member, and the content type goes on a header.

CREATE MICROFLOW Integration.UploadDocument (
  $Doc: Integration.UploadedFile
)
RETURNS Boolean AS $Ok
BEGIN
  DECLARE $Ok Boolean = false;
  $Response = CALL REST SERVICE POST 'https://api.example.com/documents' (
    Headers: ('ContentType': 'application/pdf'),
    Body: BINARY $Doc/Contents,
    Timeout: 300,
  ) RETURNS response;
  SET $Ok = $Response/StatusCode = 200;
  RETURN $Ok;
END;

RETURNS response binds a System.HttpResponse, so the microflow’s own return type must match what you do with it — returning $Response from a RETURNS String microflow is CE0117 at the end event.

$Doc must be a specialization of System.FileDocument.

A consumed REST client document has no binary body — its three body types (Rest$JsonBody, Rest$StringBody, Rest$ImplicitMappingBody) are all textual — so Body: file from $Doc in a CREATE CONSUMED REST SERVICE operation is refused as MDL-REST02. Downloading is unaffected: Response: file as $Doc works.

Basic Authentication

CREATE MICROFLOW Integration.FetchSecureData (
  $Username: String,
  $Password: String
)
RETURNS String AS $Response
BEGIN
  $Response = CALL REST SERVICE GET 'https://api.example.com/secure/data' (
    Headers: ('Accept': 'application/json'),
    Authentication: BASIC (Username: $Username, Password: $Password),
    Timeout: 30,
  ) RETURNS String;
  RETURN $Response;
END;

Error Handling

Use ON ERROR WITHOUT ROLLBACK to catch failures and return a fallback instead of rolling back the transaction:

CREATE MICROFLOW Integration.SafeAPICall (
  $Url: String
)
RETURNS Boolean AS $Success
BEGIN
  DECLARE $Success Boolean = false;

  $Response = CALL REST SERVICE GET $Url (
    Headers: ('Accept': 'application/json'),
    Timeout: 30,
  ) RETURNS String
    ON ERROR WITHOUT ROLLBACK BEGIN
      LOG ERROR NODE 'Integration' 'API call failed: ' + $Url;
      RETURN false;
    END ERROR;

  SET $Success = true;
  RETURN $Success;
END;

JSON Structure + Import Mapping

Map a JSON response to Mendix entities using a JSON structure and import mapping.

mdl 1;
-- Step 1: Define the JSON structure
CREATE JSON STRUCTURE Integration.JSON_Pet
  SAMPLE '{"id": 1, "name": "Fido", "status": "available"}';

-- Step 2: Create a non-persistent entity to hold the data
CREATE NON-PERSISTENT ENTITY Integration.PetResponse (
  PetId: Integer,
  Name: String,
  Status: String
);

-- Step 3: Create the import mapping
CREATE IMPORT MAPPING Integration.IMM_Pet
  WITH JSON STRUCTURE Integration.JSON_Pet
{
  CREATE Integration.PetResponse {
    PetId = id,
    Name = name,
    Status = status
  }
};

-- Step 4: Use in a microflow with IMPORT FROM MAPPING
-- $PetResponse = IMPORT FROM MAPPING Integration.IMM_Pet($JsonContent);

Export Mapping (Entity → JSON)

Serialize entities back to JSON using an export mapping.

CREATE EXPORT MAPPING Integration.EMM_Pet
  WITH JSON STRUCTURE Integration.JSON_Pet
{
  Integration.PetResponse {
    id = PetId,
    name = Name,
    status = Status
  }
};

-- Use in a microflow with EXPORT TO MAPPING
-- $JsonOutput = EXPORT TO MAPPING Integration.EMM_Pet($PetResponse);

Nested Mappings with Associations

Map nested JSON objects to multiple entities linked by associations.

CREATE IMPORT MAPPING Integration.IMM_Order
  WITH JSON STRUCTURE Integration.JSON_Order
{
  CREATE Integration.OrderResponse {
    OrderId = orderId KEY,
    CREATE Integration.OrderResponse_CustomerInfo/Integration.CustomerInfo = customer {
      Email = email,
      Name = name
    },
    CREATE Integration.OrderResponse_OrderItem/Integration.OrderItem = items {
      Sku = sku,
      Quantity = quantity,
      Price = price
    }
  }
};

Consuming a REST API

From an OpenAPI Spec (Recommended)

If the API has an OpenAPI 3.x spec (JSON or YAML), generate the REST client in one command. A Swagger 2.0 spec is refused; convert it to OpenAPI 3 first (for example npx swagger2openapi swagger.json -o openapi.json) and import the converted file.

mdl 1;
-- From a local file (relative to the .mpr file)
CREATE OR MODIFY CONSUMED REST SERVICE CapitalModule.CapitalAPI (
  OpenAPI: 'specs/capital.json'
);

-- From a URL
CREATE OR MODIFY CONSUMED REST SERVICE PetStoreModule.PetStoreAPI (
  OpenAPI: 'https://petstore3.swagger.io/api/v3/openapi.json'
);

Operations, path/query parameters, request bodies, response types, resource groups (from tags), and Basic auth are all derived automatically from the spec.

JSON responses are imported as Response: JSON (a string). The import does not yet create entities for them: to get objects, create non-persistent entities and give the operation a Response: MAPPING Module.Entity { … }, as shown under Manual Definition below.

Preview without writing:

DESCRIBE CONTRACT OPERATION FROM OPENAPI 'specs/capital.json';

Manual Definition

Define a reusable REST client with typed operations using CREATE CONSUMED REST SERVICE. Each operation declares its method, path, optional parameters, headers, body, and response mapping.

-- Define a client for the orders API
CREATE CONSUMED REST SERVICE Integration.OrdersApi (
  BaseUrl: 'https://api.example.com/v1',
  Authentication: NONE
)
{
  OPERATION GetOrder (
    Method: GET,
    Path: '/orders/{id}',
    Parameters: ($id: String),
    Headers: ('Accept': 'application/json'),
    Timeout: 30,
    Response: JSON AS $Result
  )

  OPERATION CreateOrder (
    Method: POST,
    Path: '/orders',
    Headers: ('Content-Type': 'application/json'),
    Body: MAPPING Integration.OrderRequest {
      customerId = CustomerId,
      totalAmount = TotalAmount,
      notes = Notes,
    },
    Response: MAPPING Integration.OrderResponse {
      Id = id,
      Status = status,
      CreatedAt = createdAt,
    }
  )
};

A header value is a template, like the path: {Token} is the operation parameter Token, which the operation must declare (Parameters: ($Token: String), else CE7056). An authorization header is Headers: ('Authorization': 'Bearer {Token}'). The expression spelling 'Bearer ' + $Token is deprecated (MDL-DEPR711) and mxcli fmt --upgrade rewrites it; it used to store only Bearer .

Use CREATE OR MODIFY CONSUMED REST SERVICE to replace an existing client’s definition without dropping it first. It declares the whole operation list: an operation it does not list is removed, and the output names it. The statement below keeps GetOrder and removes CreateOrder:

CREATE OR MODIFY CONSUMED REST SERVICE Integration.OrdersApi (
  BaseUrl: 'https://api.example.com/v2',
  Authentication: BASIC (Username: 'apiuser', Password: 'secret')
)
{
  OPERATION GetOrder (
    Method: GET,
    Path: '/orders/{id}',
    Parameters: ($id: String),
    Headers: ('Accept': 'application/json'),
    Timeout: 60,
    Response: JSON AS $Result
  )
};

To add, change or remove one operation and leave the rest as stored — including operations made in Studio Pro, whose settings MDL cannot always express — use ALTER CONSUMED REST SERVICE. MODIFY OPERATION writes only the keys it lists:

ALTER CONSUMED REST SERVICE Integration.OrdersApi
  ADD OPERATION CancelOrder (
    Method: POST,
    Path: '/orders/{id}/cancel',
    Parameters: ($id: String),
    Response: NONE
  ),
  MODIFY OPERATION GetOrder (Timeout: 60),
  DROP OPERATION LegacyOrder,
  SET (BaseUrl: 'https://api.example.com/v2');

Body types: JSON FROM $var, TEMPLATE '...', MAPPING Entity { jsonField = Attr, ... } Response types: JSON, STRING, FILE, STATUS (each optionally AS $var — the variable is not stored; the call site binds it), NONE, MAPPING Entity { Attr = jsonField, ... } Authentication: NONE, BASIC (Username: '...', Password: '...')

Publishing a REST API

Create a published REST service with CRUD operations backed by microflows.

/** Order management API for the shop front end. */
CREATE PUBLISHED REST SERVICE Module.OrderAPI (
  Path: 'rest/orders/v1',
  Version: '1.0.0',
  ServiceName: 'Order API'
)
{
  RESOURCE 'orders' {
    GET '' MICROFLOW Module.PRS_GetAllOrders;
    GET '{id}' MICROFLOW Module.PRS_GetOrderById;
    POST '' MICROFLOW Module.PRS_CreateOrder;
    PUT '{id}' MICROFLOW Module.PRS_UpdateOrder;
    DELETE '{id}' MICROFLOW Module.PRS_DeleteOrder;
  }
};

Documentation: the /** … */ doc comment above CREATE is the service’s documentation — what lint QUAL002 asks for. On CREATE OR MODIFY no comment keeps the stored text and /** */ clears it. The OpenAPI description consumers read (PublicDocumentation) has no MDL spelling and is kept as stored.

Operation paths: Use empty string '' for the root, '{paramName}' for path parameters. Do NOT start or end with /. Path parameters must match a microflow parameter name exactly (case-sensitive) — '{id}' binds the microflow’s $id, whatever its type.

Operation parameters come from the microflow, the way Studio Pro derives them. Create the microflow before the service:

Each gets the microflow parameter’s type. A header parameter, a renamed parameter or a description set in Studio Pro has no MDL spelling: describe notes it in a comment, and CREATE OR MODIFY / ALTER on that project keep it.

Mappings and commit: a body that is not a file document needs an import mapping, and a microflow returning an object or a list needs an export mapping:

mdl 1;
CREATE OR MODIFY PUBLISHED REST SERVICE Module.OrderAPI (
  Path: 'rest/orders/v1',
  Version: '1.0.0',
  ServiceName: 'Order API'
)
{
  RESOURCE 'orders' {
    -- COMMIT: Yes (the default without the clause) | YesWithoutEvents | No
    POST '' MICROFLOW Module.PRS_CreateOrder
      IMPORT MAPPING Module.IMM_Order EXPORT MAPPING Module.EMM_Order
      COMMIT YesWithoutEvents;
  }
};

Authentication

Authentication sets how a caller authenticates — Studio Pro’s Requires authentication and its methods:

mdl 1;
CREATE OR MODIFY PUBLISHED REST SERVICE Module.OrderAPI (
  Path: 'rest/orders/v1',
  Version: '1.0.0',
  ServiceName: 'Order API',
  Authentication: (basic, session, microflow Module.PRS_Authenticate)
)
{
  RESOURCE 'orders' {
    GET '' MICROFLOW Module.PRS_GetAllOrders;
  }
};
GRANT ACCESS ON PUBLISHED REST SERVICE Module.OrderAPI TO Module.User;

ALTER PUBLISHED REST SERVICE Module.OrderAPI SET (Authentication: (session));
ALTER PUBLISHED REST SERVICE Module.OrderAPI SET (Authentication: none);

• The methods are stored in the order written, as Studio Pro stores them in the order they were ticked; describe prints the stored order.
• Left out, CREATE OR MODIFY and ALTER keep the service’s stored setting. A new service without it requires no authentication. describe does not print none.
• The authentication microflow returns System.User — empty means “not authenticated”. An object parameter can only be a System.HttpRequest or a System.HttpResponse, matched by type; any other parameter is an authentication parameter of the service (below). exec and check --references refuse anything else as MDL-REST04 (Mendix: CE0334, CE0336).
• With authentication on, the service needs at least one allowed module role (GRANT ACCESS …), or mx check reports CE0338. Custom authentication also needs app security on (CE6600). Roles without authentication are accepted.

Authentication parameters

A custom-authentication microflow can read values of the request as its own parameters — a token in a header, a tenant in the query string. Each one is bound in an optional list after the microflow (Studio Pro: the service’s Parameters, Mendix 7.17+):

mdl 1;
CREATE OR MODIFY MICROFLOW Module.PRS_Authenticate (
  $HttpRequest: System.HttpRequest, $Token: String, $Tenant: Integer, $Lang: String
)
RETURNS System.User AS $User
BEGIN
  RETRIEVE $User FROM System.User WHERE [Name = $Token] FIRST;
  RETURN $User;
END;

CREATE OR MODIFY PUBLISHED REST SERVICE Module.OrderAPI (
  Path: 'rest/orders/v1',
  Version: '1.0.0',
  ServiceName: 'Order API',
  Authentication: (
    basic,
    microflow Module.PRS_Authenticate (
      $Token: header 'X-Api-Token',
      $Tenant: query,
      $Lang: query 'lang' description 'UI language, defaults to en'
    )
  )
)
{
  RESOURCE 'orders' {
    GET '' MICROFLOW Module.PRS_GetAllOrders;
  }
};

• The data type is never written: it is the microflow parameter’s.
• A parameter not listed is a query parameter under its own name, so a microflow with $Token: String works with microflow Module.PRS_Authenticate alone. System.HttpRequest / System.HttpResponse are never listed. Without the service parameter Mendix reports CE0336 (“The microflow parameter (‘Token’) is not present in the custom authentication parameter list”).
• MDL-REST04 refuses an entry naming a parameter the microflow does not have, a request or response parameter, a kind other than query / header, and a parameter listed twice.
• The list follows the microflow: listed entries in the order written, then the unlisted ones in the microflow’s order. Methods without microflow clear it. Left out with the rest of Authentication, the stored parameters are kept.
• describe prints the list only when the stored parameters are not what microflow M.F alone would write — a header, a renamed or described parameter, or another order.

Multiple Resources

CREATE PUBLISHED REST SERVICE Module.CrmAPI (
  Path: 'rest/crm/v1',
  Version: '1.0.0',
  ServiceName: 'CRM API'
)
{
  RESOURCE 'orders' {
    GET '' MICROFLOW Module.PRS_GetOrders;
  }
  RESOURCE 'customers' {
    GET '' MICROFLOW Module.PRS_GetCustomers;
  }
  RESOURCE 'orders/{orderId}/items' {
    GET '' MICROFLOW Module.PRS_GetOrderItems;
  }
};

Update or Remove

-- Replace with new version
CREATE OR REPLACE PUBLISHED REST SERVICE Module.OrderAPI (
  Path: 'rest/orders/v2',
  Version: '2.0.0',
  ServiceName: 'Order API v2'
) { ... };

-- Remove entirely
DROP PUBLISHED REST SERVICE Module.OrderAPI;

Data Transformers (JSLT)

Data Transformers apply transformation steps (JSLT or XSLT) to JSON or XML payloads. Useful for reshaping API responses before import mapping, or normalising data from third-party sources. Requires Mendix 11.9+.

mdl 1;
-- Create a transformer that extracts key fields from a weather API response.
-- The SOURCE JSON defines a sample payload used for schema inference and testing.
CREATE DATA TRANSFORMER Integration.WeatherTransform
SOURCE JSON '{
  "latitude": 51.9,
  "longitude": 4.5,
  "timezone": "Europe/Amsterdam",
  "current": {
    "time": "2024-01-15T14:00",
    "temperature_2m": 12.8,
    "wind_speed_10m": 18.3,
    "weather_code": 3
  }
}'
{
  JSLT $$
{
  "lat":        .latitude,
  "lon":        .longitude,
  "timezone":   .timezone,
  "temp":       .current.temperature_2m,
  "wind_speed": .current.wind_speed_10m,
  "code":       .current.weather_code
}
  $$;
};

-- List all data transformers in the Integration module
LIST DATA TRANSFORMERS IN Integration;

-- Inspect a transformer (outputs a re-executable CREATE statement)
DESCRIBE DATA TRANSFORMER Integration.WeatherTransform;

-- Remove a transformer
DROP DATA TRANSFORMER Integration.WeatherTransform;

Notes:

• Steps execute in order; the output of each step feeds the next.
• JSLT '...' for short single-line expressions; JSLT $$ ... $$ for multi-line.
• XSLT $$ ... $$ is also supported for XML-to-XML transformations.
• Requires Mendix 11.9+. Use LIST FEATURES to confirm support before using.

Data Import Pipeline

Connect to an external database, explore its schema, import data into Mendix, and generate database connectors – all from the mxcli REPL.

Connect and Explore

-- Connect to the legacy database
SQL CONNECT postgres 'host=legacy-db port=5432 dbname=crm user=readonly' AS legacy;

-- Discover the schema
SQL legacy SHOW TABLES;
SQL legacy DESCRIBE customers;
SQL legacy DESCRIBE orders;

-- Preview the data
SQL legacy SELECT * FROM customers LIMIT 10;

Import Data

The IMPORT FROM statement reads from the external database and inserts into the Mendix application’s PostgreSQL database with proper Mendix ID generation:

-- Import customers
IMPORT FROM legacy
  QUERY 'SELECT name, email, phone, active FROM customers'
  INTO CRM.Customer
  MAP (name AS Name, email AS Email, phone AS Phone, active AS IsActive)
  BATCH 500;

-- Import orders with association linking
-- The LINK clause looks up Customer by Email and creates the association
IMPORT FROM legacy
  QUERY 'SELECT order_number, order_date, total, customer_email FROM orders'
  INTO Sales.Order
  MAP (order_number AS OrderNumber, order_date AS OrderDate, total AS TotalAmount)
  LINK (customer_email TO Sales.Order_Customer ON Email)
  BATCH 500;

Generate Database Connectors

For ongoing integration (querying the external database from microflows at runtime), generate Database Connector entities and queries:

-- Auto-generate non-persistent entities and query microflows
SQL legacy GENERATE CONNECTOR INTO Integration
  TABLES (customers, orders, products);

This generates:

• Constants for JDBC connection string, username, and password
• Non-persistent entities with mapped attributes (SQL types to Mendix types)
• A DATABASE CONNECTION definition with query microflows

The output is valid MDL that can be reviewed before execution. Add the EXEC flag to execute immediately:

SQL legacy GENERATE CONNECTOR INTO Integration
  TABLES (customers, orders)
  EXEC;

Execute Queries from Microflows

Once a database connection is defined, microflows can execute queries at runtime:

mdl 1;
-- Non-persistent entity for query results
CREATE NON-PERSISTENT ENTITY Integration.Customer (
  /** Customer name from external system */
  Name: String(200),
  /** Email address */
  Email: String(200),
  /** Account balance */
  Balance: Decimal
);

-- Database connection with parameterized query
CREATE DATABASE CONNECTION Integration.LegacyDatabase (
  Type: 'PostgreSQL',
  ConnectionString: @Integration.LegacyDatabase_DBSource,
  Username: @Integration.LegacyDatabase_DBUsername,
  Password: @Integration.LegacyDatabase_DBPassword
) {
  QUERY SearchCustomers (
    Sql: 'SELECT name, email, balance FROM customers WHERE name ILIKE {search}',
    Parameters: ( search: String DEFAULT '%' ),
    Returns: Integration.Customer,
    Map: (Name = name, Email = email, Balance = balance)
  )
};

-- Microflow that executes the query
CREATE MICROFLOW Integration.SearchLegacyCustomers ($SearchTerm: String)
RETURNS List of Integration.Customer AS $Results
BEGIN
  $Results = EXECUTE DATABASE QUERY Integration.LegacyDatabase.SearchCustomers
    (search = '%' + $SearchTerm + '%');
  RETURN $Results;
END;

Master-Detail Page

A single page with a list on the left and a detail form on the right. Selecting an item in the list updates the form via the SELECTION data source binding – no microflow needed.

CREATE PAGE CRM.Customer_MasterDetail (
  Title: 'Customers',
  Layout: Atlas_Core.Atlas_Default
) {
  LAYOUTGRID mainGrid {
    ROW {
      -- Master list (left panel)
      COLUMN (DesktopWidth: 4) {
        DYNAMICTEXT heading (Content: 'Customers', RenderMode: H3)
        GALLERY customerList (DataSource: DATABASE CRM.Customer, Selection: Single) {
          TEMPLATE {
            DYNAMICTEXT name (
              Content: '{1}',
              ContentParams: ({1} = Name),
              RenderMode: H4
            )
            DYNAMICTEXT email (
              Content: '{1}',
              ContentParams: ({1} = Email)
            )
          }
        }
      }

      -- Detail form (right panel, bound to gallery selection)
      COLUMN (DesktopWidth: 8) {
        DYNAMICTEXT detailHeading (Content: 'Details', RenderMode: H3)
        DATAVIEW customerDetail (DataSource: SELECTION customerList) {
          TEXTBOX txtName (Label: 'Name', Attribute: Name)
          TEXTBOX txtEmail (Label: 'Email', Attribute: Email)
          TEXTBOX txtPhone (Label: 'Phone', Attribute: Phone)
          TEXTAREA txtNotes (Label: 'Notes', Attribute: Notes)
          FOOTER {
            ACTIONBUTTON btnSave (
              Caption: 'Save',
              Action: SAVE CHANGES,
              ButtonStyle: Success
            )
            ACTIONBUTTON btnCancel (Caption: 'Cancel', Action: CANCEL CHANGES)
          }
        }
      }
    }
  }
};

The key pattern is DataSource: SELECTION customerList – the data view automatically displays whichever item is selected in the gallery. No event handlers, no microflow calls, no state management.

Modifying Existing Pages

ALTER PAGE modifies widgets in place without recreating the entire page. This is useful for incremental changes, maintenance, and agent-driven iteration.

Change a Button

ALTER PAGE CRM.Customer_Edit {
  SET (Caption: 'Save & Close', ButtonStyle: Success) ON btnSave
};

Add a Field After an Existing One

ALTER PAGE CRM.Customer_Edit {
  INSERT AFTER txtEmail {
    TEXTBOX txtPhone (Label: 'Phone', Attribute: Phone)
  }
};

Add a Widget Into a Container

Use INSERT INTO to append a widget as a container’s last child — the only way to fill an empty container.

ALTER PAGE CRM.Customer_Overview {
  INSERT INTO ctnToolbar {
    ACTIONBUTTON btnNew (Caption: 'New Customer', Action: NOTHING, ButtonStyle: Primary)
  }
};

Remove Widgets

ALTER PAGE CRM.Customer_Edit {
  DROP txtLegacyField, lblOldNote
};

Replace an Entire Footer

ALTER PAGE CRM.Customer_Edit {
  REPLACE dvMain.footer WITH {
    FOOTER {
      ACTIONBUTTON btnSave (Caption: 'Save', Action: SAVE CHANGES, ButtonStyle: Success)
      ACTIONBUTTON btnDelete (Caption: 'Delete', Action: DELETE, ButtonStyle: Danger)
      ACTIONBUTTON btnCancel (Caption: 'Cancel', Action: CANCEL CHANGES)
    }
  }
};

Multiple Changes at Once

ALTER PAGE CRM.Customer_Edit {
  SET (Title: 'Edit Customer Details');
  SET (Label: 'Email Address') ON txtEmail;
  INSERT AFTER txtPhone {
    TEXTBOX txtWebsite (Label: 'Website', Attribute: Website)
  };
  DROP lblInternalRef
};

Add a Page Variable

ALTER PAGE CRM.ProductOverview {
  ADD Variables $showStockColumn: Boolean = if (3 < 4) then true else false
};

Add a Page Parameter

Add a parameter to an existing page without rewriting it. The page has a URL, so the new parameter gets a segment in the same statement:

ALTER PAGE CRM.Customer_Edit {
  SET (Url: 'customer-edit/{Customer}/{Order}');
  ADD Parameters $Order: CRM.Order
};

Switch Page Layout

Change a page’s layout without losing any widgets:

-- Switch from TopBar to Default layout (auto-maps by placeholder name)
ALTER PAGE CRM.Customer_Edit {
  SET Layout = Atlas_Core.Atlas_Default
};

When the new layout has different placeholder names, use MAP:

ALTER PAGE CRM.Customer_Edit {
  SET Layout = Atlas_Core.Atlas_SideBar MAP (Main AS Content, Extra AS Sidebar)
};

Modify DataGrid Columns

Target columns using dotted notation gridName.columnName:

mdl 1;
-- Add a column
ALTER PAGE CRM.Customer_List {
  INSERT AFTER dgCustomers.Email {
    COLUMN Phone (Attribute: Phone, Caption: 'Phone')
  }
};

-- Remove a column
ALTER PAGE CRM.Customer_List {
  DROP dgCustomers.OldNotes
};

-- Rename a column header
ALTER PAGE CRM.Customer_List {
  SET (Caption: 'E-mail Address') ON dgCustomers.Email
};

Use DESCRIBE PAGE CRM.Customer_List to discover column names.

Works on Snippets Too

ALTER SNIPPET CRM.NavigationMenu {
  SET (Caption: 'Dashboard') ON btnHome;
  INSERT AFTER btnHome {
    ACTIONBUTTON btnReports (
      Caption: 'Reports',
      Action: SHOW PAGE CRM.Reports_Overview
    )
  }
};

Validation Pattern

Mendix uses a two-microflow pattern for form validation: a validation microflow checks fields and returns feedback, and an action microflow calls it before saving.

The Validation Microflow

VALIDATION FEEDBACK attaches error messages to specific fields. The form highlights the field and displays the message.

CREATE MICROFLOW Sales.VAL_Order ($Order: Sales.Order)
RETURNS Boolean AS $IsValid
BEGIN
  DECLARE $IsValid Boolean = true;

  -- Required field
  IF $Order/OrderNumber = empty OR trim($Order/OrderNumber) = '' THEN
    SET $IsValid = false;
    VALIDATION FEEDBACK $Order/OrderNumber MESSAGE 'Order number is required';
  END IF;

  -- Date must be in the future
  IF $Order/DeliveryDate != empty AND $Order/DeliveryDate < [%CurrentDateTime%] THEN
    SET $IsValid = false;
    VALIDATION FEEDBACK $Order/DeliveryDate MESSAGE 'Delivery date must be in the future';
  END IF;

  -- Numeric range
  IF $Order/Quantity <= 0 THEN
    SET $IsValid = false;
    VALIDATION FEEDBACK $Order/Quantity MESSAGE 'Quantity must be greater than zero';
  END IF;

  IF $Order/Quantity > 10000 THEN
    SET $IsValid = false;
    VALIDATION FEEDBACK $Order/Quantity MESSAGE 'Maximum quantity is 10,000';
  END IF;

  -- Cross-field validation
  IF $Order/DiscountPercent > 0 AND $Order/ApprovedBy = empty THEN
    SET $IsValid = false;
    VALIDATION FEEDBACK $Order/ApprovedBy MESSAGE 'Discounted orders require approval';
  END IF;

  RETURN $IsValid;
END;

The Action Microflow

The action microflow calls validation, and only saves if it passes:

CREATE MICROFLOW Sales.ACT_Order_Save ($Order: Sales.Order)
RETURNS Boolean AS $IsValid
BEGIN
  $IsValid = CALL MICROFLOW Sales.VAL_Order(param = $Order);

  IF $IsValid THEN
    COMMIT $Order;
    CLOSE PAGE;
  END IF;

  RETURN $IsValid;
END;

Wiring It Up

The page’s Save button calls the action microflow (not the validation microflow directly):

CREATE PAGE Sales.Order_Edit (
  Params: ( $Order: Sales.Order ),
  Title: 'Order',
  Layout: Atlas_Core.PopupLayout
) {
  LAYOUTGRID mainGrid {
    ROW {
      COLUMN (DesktopWidth: AutoFill) {
        DATAVIEW dv (DataSource: $Order) {
          TEXTBOX txtOrderNumber (Label: 'Order Number', Attribute: OrderNumber)
          DATEPICKER dpDelivery (Label: 'Delivery Date', Attribute: DeliveryDate)
          TEXTBOX txtQuantity (Label: 'Quantity', Attribute: Quantity)
          TEXTBOX txtDiscount (Label: 'Discount %', Attribute: DiscountPercent)
          FOOTER {
            ACTIONBUTTON btnSave (
              Caption: 'Save',
              Action: CALL MICROFLOW Sales.ACT_Order_Save,
              ButtonStyle: Success
            )
            ACTIONBUTTON btnCancel (Caption: 'Cancel', Action: CANCEL CHANGES)
          }
        }
      }
    }
  }
};

Role-Based Security

A complete security setup: module roles, entity access with XPath row-level constraints, document access, user roles, and demo users.

Module Roles

Module roles define what actions are available within a module:

mdl 1;
CREATE MODULE ROLE Sales.Viewer DESCRIPTION 'Read-only access to sales data';
CREATE MODULE ROLE Sales.User DESCRIPTION 'Can create and edit orders';
CREATE MODULE ROLE Sales.Admin DESCRIPTION 'Full access including delete';

Entity Access

GRANT controls which CRUD operations a role can perform. XPath constraints in WHERE filter which rows are visible:

mdl 1;
-- Admin: full access to all customers
GRANT CREATE, DELETE, READ *, WRITE * ON ENTITY Sales.Customer TO Sales.Admin;

-- User: can create and edit, but only active customers
GRANT CREATE, READ *, WRITE * ON ENTITY Sales.Customer TO Sales.User
  WHERE [IsActive = true];

-- Viewer: read-only, active customers only
GRANT READ * ON ENTITY Sales.Customer TO Sales.Viewer
  WHERE [IsActive = true];

-- Orders: users can only see their own (via owner token)
GRANT CREATE, READ *, WRITE * ON ENTITY Sales.Order TO Sales.User
  WHERE [System.owner = '[%CurrentUser%]'];

-- Admin sees all orders
GRANT CREATE, DELETE, READ *, WRITE * ON ENTITY Sales.Order TO Sales.Admin;

Microflow and Page Access

mdl 1;
-- Microflow access
GRANT EXECUTE ON MICROFLOW Sales.ACT_Order_Save TO Sales.User;
GRANT EXECUTE ON MICROFLOW Sales.ACT_Order_Delete TO Sales.Admin;

-- Page access
GRANT VIEW ON PAGE Sales.Customer_Overview TO Sales.Viewer;
GRANT VIEW ON PAGE Sales.Customer_Overview TO Sales.User;
GRANT VIEW ON PAGE Sales.Order_Edit TO Sales.User;
GRANT VIEW ON PAGE Sales.Admin_Dashboard TO Sales.Admin;

User Roles

User roles combine module roles from different modules into a single assignable role:

mdl 1;
CREATE OR MODIFY USER ROLE SalesViewer ( ModuleRoles: (System.User, Sales.Viewer) );
CREATE OR MODIFY USER ROLE SalesRep ( ModuleRoles: (System.User, Sales.User) );
CREATE OR MODIFY USER ROLE SalesManager ( ModuleRoles: (System.User, Sales.Admin), ManageAllRoles: true );

Demo Users

Demo users are created for testing and development:

mdl 1;
CREATE OR MODIFY DEMO USER 'viewer' ( Password: 'Password1!', UserRoles: (SalesViewer) );
CREATE OR MODIFY DEMO USER 'sales_rep' ( Password: 'Password1!', UserRoles: (SalesRep) );
CREATE OR MODIFY DEMO USER 'manager' ( Password: 'Password1!', UserRoles: (SalesManager) );

-- Enable demo users in project security
ALTER APP SECURITY ( EnableDemoUsers: TRUE );

Additive Grants

GRANT merges with existing access — it never removes permissions:

-- Viewer already has READ (Name, Email)
GRANT READ (Phone) ON ENTITY Sales.Customer TO Sales.Viewer;
-- Result: READ (Name, Email, Phone)

Revoking Access

mdl 1;
-- Remove all access for a role
REVOKE ALL ON ENTITY Sales.Customer FROM Sales.Viewer;

-- Partial revoke: remove read on a specific attribute
REVOKE READ (Phone) ON ENTITY Sales.Customer FROM Sales.User;

-- Partial revoke: downgrade write to read-only
REVOKE WRITE (Email) ON ENTITY Sales.Customer FROM Sales.User;

-- Remove microflow access
REVOKE EXECUTE ON MICROFLOW Sales.ACT_Order_Delete FROM Sales.User;

View Entities

View entities are backed by an OQL query. They appear in the domain model but have no database table (and no database view either) – their rows are computed from other entities via aggregation and joins, evaluated by the runtime per query. “Read-only” is a common but imprecise shorthand: a view row has no storage and commit does not write it back, yet it is editable in memory (it behaves like a non-persistent object), so a form can bind to one and write changes back through the source entity. See View Entity for the full model and the CE6770 type-match gotcha.

Sales Summary by Category

mdl 1;
-- Source entities
CREATE PERSISTENT ENTITY Reports.ProductCategory (
  /** Category display name */
  CategoryName: String(200) NOT NULL
);

CREATE PERSISTENT ENTITY Reports.SaleTransaction (
  /** Transaction amount */
  Amount: Decimal NOT NULL,
  /** Date of the sale */
  SaleDate: DateTime NOT NULL
);

CREATE ASSOCIATION Reports.SaleTransaction_ProductCategory
  FROM Reports.ProductCategory TO Reports.SaleTransaction
  TYPE Reference OWNER Default;

-- View entity: aggregates sales by category
CREATE VIEW ENTITY Reports.SalesTotalByCategory (
  CategoryName: String(200),
  TotalAmount: Decimal,
  TransactionCount: Integer
) AS (
  SELECT
    c.CategoryName AS CategoryName,
    sum(s.Amount) AS TotalAmount,
    count(s.ID) AS TransactionCount
  FROM Reports.SaleTransaction AS s
  INNER JOIN s/Reports.SaleTransaction_ProductCategory/Reports.ProductCategory AS c
  GROUP BY c.CategoryName
);

Querying a View Entity in a Microflow

View entities can be retrieved like any other entity, including with WHERE filters:

CREATE MICROFLOW Reports.GetSalesTotalForCategory (
  $Category: Reports.ProductCategory
)
RETURNS Decimal AS $TotalAmount
BEGIN
  DECLARE $TotalAmount Decimal = 0;

  RETRIEVE $Summary FROM Reports.SalesTotalByCategory
    WHERE CategoryName = $Category/CategoryName
    FIRST;

  IF $Summary != empty THEN
    SET $TotalAmount = $Summary/TotalAmount;
  END IF;

  RETURN $TotalAmount;
END;

Displaying in a Page

View entities work with data grids and list views like persistent entities:

CREATE PAGE Reports.SalesByCategory_Overview (
  Title: 'Sales by Category',
  Layout: Atlas_Core.Atlas_Default
) {
  DATAGRID dgSales (DataSource: DATABASE Reports.SalesTotalByCategory) {
    COLUMN (Attribute: CategoryName, Caption: 'Category')
    COLUMN (Attribute: TotalAmount, Caption: 'Total Sales')
    COLUMN (Attribute: TransactionCount, Caption: 'Transactions')
  }
};

Migration Guide

mxcli and MDL enable AI-assisted migration of existing applications to the Mendix platform. An AI coding agent (Claude Code, GitHub Copilot, OpenCode, Cursor, Windsurf) investigates the source application, maps its elements to Mendix concepts, generates MDL scripts, and validates the result – all from the command line.

This part covers the five-phase migration workflow and the skills that support each phase.

Why mxcli for Migration?

Traditional migrations require deep Mendix expertise and manual work in Studio Pro. With mxcli:

• AI agents do the heavy lifting – the agent reads source code, proposes a transformation plan, and generates MDL scripts
• Skills provide guardrails – platform-specific migration skills guide the agent with correct mappings, naming conventions, and patterns
• Validation is automated – mxcli check, lint, docker check, and test catch errors before anyone opens Studio Pro
• The process is repeatable – MDL scripts can be version-controlled, reviewed, and re-run

The Five Phases

  Phase 1           Phase 2           Phase 3           Phase 4         Phase 5
 ┌──────────┐    ┌───────────┐   ┌──────────────┐   ┌──────────┐   ┌──────────┐
 │  Assess  │--> │  Propose  │-->│   Generate   │-->│   Test   │-->│  Finish  │
 │  Source  │    │ Transform │   │  Mendix App  │   │  & Lint  │   │ in Studio│
 └──────────┘    └───────────┘   └──────────────┘   └──────────┘   │   Pro    │
                                                                   └──────────┘

Phase 1: Assessment

The first step is a thorough investigation of the source application. The AI agent examines the codebase and produces a structured migration inventory.

The assess-migration Skill

The assess-migration skill provides a 6-step investigation framework that works with any technology stack – Java, .NET, Python, Node.js, PHP, Ruby, or any other platform. It guides the agent through:

1. Technology stack – build files, frameworks, runtime versions
2. Data model – ORM entities, database schema, relationships
3. Business logic – service classes, stored procedures, validation rules
4. User interface – pages, templates, navigation structure
5. Integrations – REST/SOAP clients, message queues, file feeds
6. Security – authentication, authorization, role definitions

What to Extract

Platform-Specific Skills

For common source platforms, dedicated skills provide deeper guidance with precise element mappings:

Assessment Output

The assessment produces a structured report with:

• Executive summary – technology stack, application size, complexity rating
• Categorized inventory – counts and details for each category
• Mendix mapping – how each source element maps to Mendix concepts
• Migration risks – complex stored procedures, custom UI components, real-time integrations
• Recommended phases – suggested order of migration work

Example: Starting an Assessment

Point the AI agent at the source codebase and ask it to assess for migration:

Assess the application in /path/to/source for migration to Mendix.
Use the assess-migration skill.

The agent will investigate build files, ORM models, service classes, UI templates, security configuration, and API clients. The resulting assessment report becomes the input for Phase 2.

Phase 2: Transformation Plan

With the assessment complete, the agent creates a detailed transformation plan that maps every source element to its Mendix equivalent.

Module Structure

Plan the Mendix module structure. A common pattern is to consolidate many small source modules into fewer Mendix modules:

Source Application           Mendix
─────────────────           ─────────
CRM_Core, CRM_UI    ──▶    CRM
Cases_Core, Cases_UI ──▶    Cases
Auth_Core, Auth_SSO  ──▶    Administration
Shared_Utils         ──▶    Commons

Transformation Mapping

For each element in the assessment, the agent documents the target Mendix implementation:

Prioritization

Order the migration work to maximize early value and minimize dependency issues:

1. Enumerations – no dependencies, used by entities
2. Domain model – entities, attributes, associations
3. Security – module roles, user roles, access rules
4. Core business logic – validation microflows, calculation microflows
5. Pages – overview pages, edit forms, dashboards
6. Integrations – REST clients, OData services, file handling
7. Navigation – menu structure, home pages
8. Advanced features – scheduled events, workflows, business events

This order ensures that each layer can reference the elements created before it.

Phase 3: Generation

With the transformation plan in hand, the agent generates the Mendix application using MDL scripts. Skills guide the agent toward correct, idiomatic MDL.

Key Skills

Generation Workflow

# 1. Create a new Mendix project in Studio Pro (or use an existing one)
# 2. Execute MDL scripts in dependency order
mxcli exec domain-model.mdl -p app.mpr
mxcli exec microflows.mdl -p app.mpr
mxcli exec pages.mdl -p app.mpr
mxcli exec security.mdl -p app.mpr

# Or work interactively in the REPL
mxcli -p app.mpr

Example: Domain Model

mdl 1;
-- Enumerations first (referenced by entities)
CREATE ENUMERATION Sales.OrderStatus (
  Draft 'Draft',
  Pending 'Pending',
  Confirmed 'Confirmed',
  Shipped 'Shipped',
  Delivered 'Delivered',
  Cancelled 'Cancelled'
);

-- Entities
/** Customer master data */
@Position(100, 100)
CREATE PERSISTENT ENTITY CRM.Customer (
  Name: String(200) NOT NULL ERROR MESSAGE 'Customer name is required',
  Email: String(200) UNIQUE ERROR MESSAGE 'Email already exists',
  Phone: String(50),
  IsActive: Boolean DEFAULT TRUE
)
INDEX (Name)
INDEX (Email);

/** Sales order */
@Position(300, 100)
CREATE PERSISTENT ENTITY Sales.Order (
  OrderNumber: String(50) NOT NULL UNIQUE,
  OrderDate: DateTime NOT NULL,
  TotalAmount: Decimal DEFAULT 0,
  Status: Enumeration(Sales.OrderStatus) DEFAULT 'Draft'
)
INDEX (OrderNumber)
INDEX (OrderDate DESC);

-- Associations
CREATE ASSOCIATION Sales.Order_Customer
  FROM Sales.Order TO CRM.Customer
  TYPE Reference OWNER Default;

Example: Microflow

CREATE MICROFLOW Sales.ACT_Order_CalculateTotal
BEGIN
  DECLARE $Order Sales.Order;
  RETRIEVE $Lines FROM Sales.OrderLine
    WHERE [Sales.OrderLine_Order = $Order];
  DECLARE $Total Decimal = 0;
  LOOP $Line IN $Lines
  BEGIN
    SET $Total = $Total + $Line/Price * $Line/Quantity;
  END;
  CHANGE $Order (TotalAmount = $Total);
  COMMIT $Order;
END;
/

Example: Page

CREATE PAGE CRM.Customer_Overview (
  Title: 'Customers',
  Layout: Atlas_Core.Atlas_Default
) {
  DATAGRID dgCustomers (DataSource: DATABASE CRM.Customer, Selection: Single) {
    COLUMN (Attribute: Name, Caption: 'Name') { TEXTFILTER fName }
    COLUMN (Attribute: Email, Caption: 'Email') { TEXTFILTER fEmail }
    COLUMN (Attribute: Phone, Caption: 'Phone')
    COLUMN (Attribute: IsActive, Caption: 'Active')
    CONTROLBAR {
      ACTIONBUTTON btnNew (Caption: 'New', Action: SHOW PAGE CRM.Customer_NewEdit, ButtonStyle: Primary)
    }
  }
};

Validation Between Steps

Validate after each script to catch errors early:

# Syntax check (fast, no project used)
mxcli check domain-model.mdl --no-project

# Reference validation (checks entity/microflow names exist)
mxcli check pages.mdl -p app.mpr --references

Data Migration

mxcli can connect directly to external databases to explore schemas, import data, and generate database connector code. This is useful for migrating reference data, seeding test data, or setting up ongoing integrations with legacy systems.

Key Skills

Connect to the Source Database

mxcli supports PostgreSQL, Oracle, and SQL Server:

-- Connect to the legacy database
SQL CONNECT postgres 'host=legacy-db port=5432 dbname=crm user=readonly password=...' AS legacy;

-- Explore the schema
SQL legacy SHOW TABLES;
SQL legacy DESCRIBE customers;

Import Data

The IMPORT FROM statement reads from the source database and inserts into the Mendix application’s PostgreSQL database:

-- Import customers
IMPORT FROM legacy
  QUERY 'SELECT name, email, phone, active FROM customers'
  INTO CRM.Customer
  MAP (name AS Name, email AS Email, phone AS Phone, active AS IsActive)
  BATCH 500;

-- Import with association linking
IMPORT FROM legacy
  QUERY 'SELECT order_number, order_date, total, customer_email FROM orders'
  INTO Sales.Order
  MAP (order_number AS OrderNumber, order_date AS OrderDate, total AS TotalAmount)
  LINK (customer_email TO Sales.Order_Customer ON Email)
  BATCH 500;

The import pipeline handles:

• Mendix ID generation – creates valid 64-bit object IDs
• Batch insertion – respects PostgreSQL parameter limits
• Association linking – looks up related entities by attribute value
• Optimistic locking – sets MxObjectVersion if the entity uses it

Generate Database Connectors

For ongoing integration (not one-time import), generate Database Connector entities and microflows:

-- Auto-generate non-persistent entities and query microflows
SQL legacy GENERATE CONNECTOR INTO Integration
  TABLES (customers, orders, products);

This creates:

• Non-persistent entities with mapped attributes
• Constants for connection strings (JDBC URL, username, password)
• DATABASE CONNECTION definitions with query microflows

Credential Management

Database credentials should never be hardcoded. mxcli supports:

• Environment variables – set MXCLI_SQL_<ALIAS>_DSN
• YAML config file – ~/.mxcli/sql.yaml with per-alias DSN entries
• Credential isolation – credentials are never exposed to the AI agent or logged

Phase 4: Validation and Handoff

mxcli provides a multi-level validation pipeline. The agent uses these tools to self-correct before a human ever looks at the result.

Validation Steps

# 1. Syntax check (fast, no project used)
mxcli check script.mdl --no-project

# 2. Reference validation (checks entity/microflow names exist)
mxcli check script.mdl -p app.mpr --references

# 3. Lint the full project (19 built-in + 31 Starlark rules)
mxcli lint -p app.mpr

# 4. Quality report (scored 0-100 per category)
mxcli report -p app.mpr --format markdown

# 5. Mendix compiler check (requires Docker)
mxcli docker check -p app.mpr

# 6. Build and run (requires Docker)
mxcli docker run -p app.mpr

Lint Categories

The linter covers 6 categories:

Quality Reports

The assess-quality skill guides the agent to run mxcli report and interpret the scores. A migration is ready for handoff when:

• No critical lint issues (SEC, QUAL categories)
• Quality score above 70 across all categories
• mxcli docker check passes with no errors
• All tests pass

Automated Testing

Write .test.mdl files to validate migrated business logic:

-- tests/order_tests.test.mdl
-- @test: Order total is calculated correctly

$Customer = CREATE CRM.Customer (Name = 'Test');
COMMIT $Customer;

$Order = CREATE Sales.Order (OrderNumber = 'ORD-001', OrderDate = now());
CHANGE $Order (Sales.Order_Customer = $Customer);
COMMIT $Order;

$Line = CREATE Sales.OrderLine (Price = 10.00, Quantity = 3);
CHANGE $Line (Sales.OrderLine_Order = $Order);
COMMIT $Line;

CALL MICROFLOW Sales.ACT_Order_CalculateTotal (Order = $Order);

-- @assert: $Order/TotalAmount = 30.00

# Run tests (Docker, or --local for mxcli's own runtime)
mxcli test tests/ -p app.mpr

Handoff to Studio Pro

The final step transitions to Mendix Studio Pro for visual refinement:

Handoff Checklist

# Final validation before opening in Studio Pro
mxcli docker check -p app.mpr          # No compiler errors
mxcli lint -p app.mpr                  # No critical lint issues
mxcli report -p app.mpr               # Review quality scores
mxcli test tests/ -p app.mpr          # All tests pass
mxcli -p app.mpr -c "DESCRIBE STRUCTURE DEPTH 2"  # Review structure

Iterative Workflow

The mxcli/Studio Pro workflow is iterative – you can switch between them:

  mxcli/MDL                    Studio Pro
 ┌──────────┐               ┌──────────────┐
 │ Generate  │──── open ───▶│ Visual edit   │
 │ entities, │               │ styling,     │
 │ microflows│◀── save ─────│ test, deploy  │
 │ pages     │               │              │
 └──────────┘               └──────────────┘

Changes made in either tool are persisted in the .mpr file. Always close mxcli before opening in Studio Pro, and vice versa.

MDL Basics

MDL (Mendix Definition Language) is a SQL-like language for reading and modifying Mendix application projects. It provides a text-based alternative to the visual editors in Mendix Studio Pro.

What MDL Looks Like

MDL uses familiar SQL-style syntax with Mendix-specific extensions. Here is a simple example that creates an entity with attributes:

CREATE PERSISTENT ENTITY Sales.Customer (
  CustomerId: AutoNumber NOT NULL UNIQUE DEFAULT 1,
  Name: String(200) NOT NULL,
  Email: String(200) UNIQUE,
  IsActive: Boolean DEFAULT TRUE
)
INDEX (Name);

Statement Termination

Every statement ends with a semicolon (;):

mdl 1;
CREATE MODULE OrderManagement;

CREATE PERSISTENT ENTITY Sales.Order (
  OrderId: AutoNumber NOT NULL UNIQUE DEFAULT 1,
  OrderDate: DateTime NOT NULL,
)
INDEX (OrderDate DESC);

A missing ; is an error, and so is the Oracle SQL*Plus-style / on its own line. At the REPL and in mxcli -c "…" the end of the input ends the last statement, so a single command such as list entities needs no terminator there.

Trailing Commas

A trailing comma is allowed in every bracketed list — attributes, enumeration values, parameters, property lists, { … } blocks — under every language version. () is the only way to write an empty list: (,) and (a,,) are errors.

Keyword Case

Keywords are case-insensitive, and lowercase is canonical: describe writes them in lowercase and mxcli fmt normalizes them to it. Names are not keywords, even when they are spelled like one — a module member User, an attribute Title or a property key Folder: keeps its case, and so does a CamelCase value such as ButtonStyle: Success or a type name such as String(200). Expressions, XPath, OQL and SQL are stored as written, so fmt leaves their text alone.

One Spelling per Keyword

Each keyword has one spelling, and a page action uses the words a microflow uses: show page, save changes, cancel changes, close page, create object, delete, open link, sign out, complete task, open user task, open workflow, call microflow M.F, call nanoflow M.F, call workflow M.WF. A validation message is error message '…' (after not null, unique, required, in a validation rule and after on delete restrict); a delete behaviour is the SQL referential action, on delete cascade / restrict / set null; a reference set’s type is ReferenceSet; a REST call that returns nothing says returns nothing.

One Verb per Job

list enumerates, describe shows one thing, and an alter adds and drops its children:

• describe page M.P, describe app security, describe security matrix [in M], describe structure …, describe context of X;
• list navigation, list navigation menu [profile], list settings (they print tables, so they are listings);
• alter user role R drop module roles (…), alter settings language drop '…', alter settings workflows drop group '…';
• alter entity E add|rename|modify|drop attribute …;
• call rest service get '…' …, describe widget type combobox, create fragment F as { … }.

show entity X and show association X are not mdl 1: describe entity X prints the definition as MDL, and list entities in M / list associations in M print the summary columns. show version, show status, show connections and show catalog status report the session, not the model: they are session commands (R7), typed at the REPL.

Activity Settings

A microflow or nanoflow activity says what it does in words, and lists its settings in one property list (ADR-0013):

• Words carry the action and its data flow: the verb, the result variable ($x =), the main operand (the method and URL, the called document, the object), returns … and on error ….
• One ( Key: value, … ) list after the main operand carries what a Studio Pro user sets in the activity’s properties dialog: headers, authentication, timeout, request body. : sets a setting, = binds a value, trailing commas are allowed, and an unknown key is an error.

$Html = call rest service get 'https://example.com' (
  Headers: ('Accept': 'text/html'),
  Timeout: 300,
) returns String;

The keys are named as the matching document property is (Headers, Authentication, Timeout, as on a consumed REST service). An activity with one or two settings that read naturally as words keeps its clauses — log info node 'App' 'text', show message 'Saved' type Information.

Document Type Names

Document types are named as Studio Pro names them: consumed rest service(s), consumed odata service(s), published odata service(s), task queue(s), alter app security …, alter settings runtime …, list image collections / list icon collections / list message definition collections, ai model(s) (the agent editor’s model document), and create json structure M.J sample '…'.

The older spellings of all three sections still parse in a script file with the same meaning, warn with an MDL-DEPR* code, and mxcli fmt --upgrade rewrites them; Language Versions and Migration lists every one.

consumed web service, published web service and xml schema are reserved: MDL does not support these Studio Pro documents yet, and a statement that names one is refused with an error saying so.

business event service and database connection keep their names: a Mendix 10+ business event service document holds both the published and the subscribed operations, and database connection is the Database Connector’s own name for the document.

Language Version Header

A script starts with a header that names the MDL language version it is written in:

mdl 1;

create persistent entity Sales.Customer (
  Name: String(200)
);

• mdl 1 is the language this manual documents. It was frozen at beta: a script headed mdl 1; means the same under every later mxcli release.
• The header is the first statement. It may be repeated later with the same version — descriptions concatenated into one file each start with it — but a header naming another version is an error, and so is a version this mxcli does not know.
• describe writes mdl 1; at the top of every description, so a description runs as it is, and mxcli fmt --upgrade adds it to an older script.
• At the REPL and in mxcli -c "…", input without a header is read as mdl 1.
• A script file without a header is the older language, mdl 0, and keeps its meaning (constructs that mean something else under mdl 1 warn). How it differs, and how to upgrade it, is on Language Versions and Migration.
• It is independent of the Mendix version your project targets.

What mdl 1 makes strict:

• Every statement ends with ;, and a / terminator line is an error.
• '' is the only string escape; a backslash is an ordinary character, so 'C:\temp' is that path.
• A text template (log, show message, validation feedback) written as one literal is the template text even when it spans lines, which is how a template holds a line break.
• In a REST client, published REST service, business event service, model, knowledge base, consumed MCP service or agent, an unknown property key is an error that names the key it most likely meant, and so is a value its key does not take (Response: json from $X).
• A while loop is while <condition> begin … end while;; leaving out begin, or the while after end, is an error.
• show entity X / show association X is an error: describe entity X prints the definition, list entities in M the summary columns.
• A session command — connect, disconnect, use, set format = …, status, show version, show status, show connections, show catalog status, check, build, lint, debug, execute script, execute runtime, help, introspect api — is an error in a script. Type it at the REPL, or use the command-line flag (mxcli exec script.mdl -p app.mpr --json).
• DynamicClasses, DynamicCellClass and an OData client’s credential or header value take the expression bare; a quoted value is a Mendix string.

The manual, the skills, mxcli syntax and the example scripts are written in the canonical form, and CI holds them to it: make check-conformance parses every MDL block in them as mdl 1 and fails on a deprecated spelling (mxcli check --deprecations=error does the same for a script of your own; add --v1=error to also fail on what a headerless script must change before it can carry mdl 1;). The design is in ADR-0011; mxcli syntax language-header has the details.

Re-runnable Creates: or modify and if not exists

A plain create fails when the element already exists. Two guards make a script re-runnable, and they mean different things:

if not exists goes after the kind’s keywords and before the name, on every create that names one element — create microflow if not exists M.MF () …, create module if not exists M;, create user role if not exists Clerk (M.User);, create configuration if not exists 'Default' (…);. It is not accepted on annotation, index (use alter entity … add index if not exists), validation rule, navigation, translations or external entities, which have no single named element to test. Writing create or modify … if not exists is refused as MDL085: the two guards contradict each other. describe never emits if not exists.

Case Insensitivity

All MDL keywords are case-insensitive. The following are equivalent:

CREATE PERSISTENT ENTITY Sales.Customer ( ... );
create persistent entity Sales.Customer ( ... );
Create Persistent Entity Sales.Customer ( ... );

Identifiers (module names, entity names, attribute names) are case-sensitive and must match the Mendix model exactly.

Statement Categories

MDL statements fall into several categories:

Further Reading

• Lexical Structure – keywords, literals, and tokens
• Qualified Names – how elements are referenced
• Comments – comment syntax
• Script Files – running MDL from files

Lexical Structure

This page describes the tokens that make up the MDL language: keywords, literals, and identifiers.

Keywords

MDL keywords are case-insensitive. The following are reserved keywords:

ACCESS, ACTIONS, ADD, AFTER, ALL, ALTER, AND, ANNOTATION, AS, ASC,
ASCENDING, ASSOCIATION, AUTONUMBER, BATCH, BEFORE, BEGIN, BINARY,
BOOLEAN, BOTH, BUSINESS, BY, CALL, CANCEL, CAPTION, CASCADE,
CATALOG, CHANGE, CHILD, CLOSE, COLUMN, COMBOBOX, COMMIT, CONNECT,
CONFIGURATION, CONNECTOR, CONSTANT, CONSTRAINT, CONTAINER, CREATE,
CRUD, DATAGRID, DATAVIEW, DATE, DATETIME, DECLARE, DEFAULT, DELETE,
DELETE_BEHAVIOR, DELETE_BUT_KEEP_REFERENCES, DELETE_AND_REFERENCES, DEMO,
DEPTH, DESC, DESCENDING, DESCRIBE, DIFF, DISCONNECT, DROP, ELSE,
EMPTY, END, ENTITY, ENUMERATION, ERROR, EVENT, EVENTS, EXECUTE,
EXEC, EXIT, EXPORT, EXTENDS, EXTERNAL, FALSE, FOLDER, FOOTER,
FOR, FORMAT, FROM, FULL, GALLERY, GENERATE, GRANT, HEADER, HELP,
HOME, IF, IMPORT, IN, INDEX, INFO, INSERT, INTEGER, INTO, JAVA,
KEEP_REFERENCES, LABEL, LANGUAGE, LAYOUT, LAYOUTGRID, LEVEL, LIMIT,
LINK, LIST, LISTVIEW, LOCAL, LOG, LOGIN, LONG, LOOP, MANAGE, MAP,
MATRIX, MENU, MESSAGE, MICROFLOW, MICROFLOWS, MODEL, MODIFY, MODULE,
MODULES, MOVE, NANOFLOW, NANOFLOWS, NAVIGATION, NODE, NON_PERSISTENT,
NOT, NULL, OF, ON, OR, ORACLE, OVERVIEW, OWNER, PAGE, PAGES, PARENT,
PASSWORD, PERSISTENT, POSITION, POSTGRES, PRODUCTION, PROJECT,
PROTOTYPE, QUERY, QUIT, REFERENCE, REFERENCESET, REFRESH, REMOVE,
REPLACE, REPORT, RESPONSIVE, RETRIEVE, RETURN, REVOKE, ROLE, ROLES,
ROLLBACK, ROW, SAVE, SCRIPT, SEARCH, SECURITY, SELECTION, SET, SHOW,
SNIPPET, SNIPPETS, SQL, SQLSERVER, STATUS, STRING, STRUCTURE,
TABLES, TEXTBOX, TEXTAREA, THEN, TO, TRUE, TYPE, UNIQUE, UPDATE,
USER, VALIDATION, VALUE, VIEW, VIEWS, VISIBLE, WARNING, WHERE, WIDGET,
WIDGETS, WITH, WORKFLOWS, WRITE

Most keywords work unquoted as identifiers (entity names, attribute names). Only structural keywords like CREATE, DELETE, BEGIN, END, RETURN, ENTITY, and MODULE require quoting when used as identifiers.

Quoting escapes parser keywords only — not platform-reserved member names. Quoting an identifier tells the MDL parser to treat it as a name rather than a token, so "create", "status", and "type" parse fine as attribute names. But some names are reserved by the Mendix platform, and Studio Pro rejects them even when quoted (the quotes are stripped, and the bare name is still invalid): Type (CE7247), the audit attributes CreatedDate / ChangedDate / Owner / ChangedBy, plus ID, GUID, CurrentUser, and the Java keyword list. mxcli check --references flags these as MDL021 (CE7247) / MDL020. Rename them (e.g. Type → ResourceType); use the AutoCreatedDate / AutoChangedDate / AutoOwner / AutoChangedBy pseudo-types for the audit fields.

Literals

String Literals

String literals use single quotes:

'single quoted string'
'it''s here'            -- doubled single quote to escape

The only escape sequence is '' (two single quotes) to represent a literal single quote, as in a Mendix expression. Under mdl 1; a backslash is an ordinary character: 'C:\temp' is that path.

A string in a microflow or nanoflow expression is read by the same rule as any other string, and the expression stores its value the way Studio Pro does: an apostrophe doubled, a backslash and a line break as themselves. 'C:\temp' stores 'C:\temp', whether the builder renders the expression or stores it as written.

A string in an XPath constraint follows the same rule, wherever the XPath is written: a retrieve’s where, an entity access rule, a page datasource, a workflow user task’s targeting xpath, and a navigation sync constraint. So do the Mendix expressions a statement stores as written beside them — a retrieve’s limit and offset, a database query’s dynamic expression. describe writes each back as stored.

A line break is written into the literal itself: a string may span lines, and the break is part of its value. This is also how a text template — the message of log, show message or validation feedback — holds a line break; under mdl 1; a template written as one literal is the template text whether or not it spans lines:

mdl 1;
create microflow Shop.LogCleanup ($Count: Integer)
begin
  log info node 'Shop' 'Deleted {1} records.
Run again tomorrow.' with ({1} = toString($Count));
end;

describe writes every string this way — a caption, an annotation, a widget property, a string in an expression: '' is its only escape and a stored line break is a line break in the literal.

With with ({n} = …) parameters the literal is the template text too. Strings in a script without the header follow the older rules on Language Versions and Migration.

Numeric Literals

42          -- Integer
3.14        -- Decimal
-100        -- Negative integer
1.5e10      -- Scientific notation

Boolean Literals

TRUE
FALSE

Quoted Identifiers

When an identifier collides with a reserved keyword, use double quotes (ANSI SQL style) or backticks (MySQL style):

"ComboBox"."CategoryTreeVE"
`Order`.`Status`
"ComboBox".CategoryTreeVE    -- mixed quoting is allowed

See Qualified Names for more on identifier syntax and the Module.Name notation.

Qualified Names

MDL uses dot-separated qualified names to reference elements within a Mendix project. This naming convention ensures elements are unambiguous across modules.

Simple Identifiers

Valid identifier characters:

• Letters: A-Z, a-z
• Digits: 0-9 (not as first character)
• Underscore: _

MyEntity
my_attribute
Attribute123

Qualified Name Format

The general format is Module.Element or Module.Entity.Attribute:

MyModule.Customer           -- Entity in module
MyModule.OrderStatus        -- Enumeration in module
MyModule.Customer.Name      -- Attribute in entity

Two-Part Names

Most elements use a two-part name: Module.ElementName.

Sales.Customer              -- entity
Sales.OrderStatus           -- enumeration
Sales.ACT_CreateOrder       -- microflow
Sales.Customer_Edit         -- page
Sales.Order_Customer        -- association

Three-Part Names

Attribute references use three parts: Module.Entity.Attribute.

Sales.Customer.Name         -- attribute on entity
Sales.Order.TotalAmount     -- attribute on entity

Quoting Rules

When a name segment is a reserved keyword, wrap it in double quotes or backticks:

"ComboBox"."CategoryTreeVE"
`Order`.`Status`

Mixed quoting is allowed – you only need to quote the segments that conflict:

"ComboBox".CategoryTreeVE
Sales."Order"

Identifiers that contain only letters, digits, and underscores (and do not start with a digit) never need quoting.

Usage in Statements

Qualified names appear throughout MDL:

-- Entity creation
CREATE PERSISTENT ENTITY Sales.Customer ( ... );

-- Association referencing two entities
CREATE ASSOCIATION Sales.Order_Customer
  FROM Sales.Customer
  TO Sales.Order
  TYPE Reference;

-- Enumeration reference in an attribute type
Status: Enumeration(Sales.OrderStatus) DEFAULT 'Active'

-- Microflow call
$Result = CALL MICROFLOW Sales.ACT_ProcessOrder (Order = $Order);

See Also

• Lexical Structure – keywords and quoting
• Entities – entity qualified names
• Associations – association naming conventions

Comments and Documentation

MDL supports three comment styles for annotating scripts and attaching documentation to model elements.

Single-Line Comments

Use -- (SQL style) or // (C style) for single-line comments:

-- This is a single-line comment
LIST MODULES;

// This is also a single-line comment
LIST ENTITIES IN Sales

Everything after the comment marker to the end of the line is ignored.

Multi-Line Comments

Use /* ... */ for comments that span multiple lines:

/* This comment spans
   multiple lines and is useful
   for longer explanations */
CREATE PERSISTENT ENTITY Sales.Customer (
  Name: String(200) NOT NULL
);

Documentation Comments

Use /** ... */ to attach documentation to model elements. Documentation comments are stored in the Mendix model and appear in Studio Pro:

/** Customer entity stores master customer data.
 *  Used by the Sales and Support modules.
 */
@Position(100, 200)
CREATE PERSISTENT ENTITY Sales.Customer (
  /** Unique customer identifier, auto-generated */
  CustomerId: AutoNumber NOT NULL UNIQUE DEFAULT 1,

  /** Full legal name of the customer */
  Name: String(200) NOT NULL,

  /** Primary contact email address */
  Email: String(200) UNIQUE
);

Documentation comments can be placed before:

• Entity definitions (becomes entity documentation)
• Attribute definitions (becomes attribute documentation)
• Enumeration definitions (becomes enumeration documentation)
• Association definitions (becomes association documentation)

Not before an enumeration value or an index: Mendix stores no documentation on a value and no name on an index, so check warns that the text is not kept (MDL-ENUMDOC01, MDL-IDX01). Use an ordinary -- comment for a note there.

Updating Documentation

You can also set documentation on existing entities with ALTER ENTITY:

ALTER ENTITY Sales.Customer
  SET DOCUMENTATION 'Customer master data for the Sales module';

Script Files

MDL statements can be saved in .mdl files and executed as scripts. This is the primary way to automate Mendix model changes.

File Format

• Extension: .mdl
• Encoding: UTF-8
• Language header: a script starts with mdl 1;, the MDL language version it is written in (mxcli fmt --upgrade --header adds it to an older script)
• Statement termination: every statement ends with a semicolon (;)

A typical script file:

mdl 1;
-- setup_domain_model.mdl
-- Creates the Sales domain model

CREATE ENUMERATION Sales.OrderStatus (
  Draft 'Draft',
  Pending 'Pending',
  Confirmed 'Confirmed',
  Shipped 'Shipped'
);

CREATE PERSISTENT ENTITY Sales.Customer (
  Name: String(200) NOT NULL,
  Email: String(200) UNIQUE
);

CREATE PERSISTENT ENTITY Sales.Order (
  OrderDate: DateTime NOT NULL,
  Status: Enumeration(Sales.OrderStatus) DEFAULT 'Draft'
);

CREATE ASSOCIATION Sales.Order_Customer
  FROM Sales.Customer
  TO Sales.Order
  TYPE Reference;

Execution Modes

mxcli supports several ways to execute MDL. All modes open a single connection to the project — there is no per-command overhead.

Script File

Use mxcli exec to run a .mdl file:

mxcli exec setup_domain_model.mdl -p /path/to/app.mpr

Inline Commands (-c)

Pass one or more semicolon-separated commands with the -c flag:

# Single command
mxcli -p app.mpr -c "LIST ENTITIES"

# Multiple commands in one connection
mxcli -p app.mpr -c "DESCRIBE ENTITY Sales.Customer; DESCRIBE ENTITY Sales.Order; LIST MICROFLOWS IN Sales"

This is the fastest way for AI agents to batch multiple queries — all commands share a single connection.

Stdin Piping

When stdin is a pipe (not a terminal), mxcli reads commands from it in quiet mode (no banner, no prompts):

# Pipe from echo
echo "LIST ENTITIES; LIST MICROFLOWS" | mxcli -p app.mpr

# Pipe from file
mxcli -p app.mpr < commands.mdl

# Pipe from heredoc
mxcli -p app.mpr <<'EOF'
DESCRIBE ENTITY Sales.Customer;
DESCRIBE ENTITY Sales.Order;
LIST MICROFLOWS IN Sales;
EOF

From the REPL

Use EXECUTE SCRIPT inside an interactive session:

CONNECT LOCAL '/path/to/app.mpr';
EXECUTE SCRIPT './scripts/setup_domain_model.mdl';

Syntax Checking

You can validate a script without connecting to a project:

# Syntax only (--no-project: do not auto-detect an .mpr in this directory)
mxcli check script.mdl --no-project

# Syntax + reference validation (requires project)
mxcli check script.mdl -p app.mpr --references

Syntax checking catches parse errors, unknown keywords, and common anti-patterns before execution.

Comments in Scripts

Scripts support the same comment syntax as interactive MDL:

-- Single-line comment
/* Multi-line comment */
/** Documentation comment (attached to next element) */

Language Versions and Migration

An MDL script is written in one language version, declared by its first statement:

mdl 1;

create persistent entity Shop.Customer (
  Name: String(200)
);

A script file with no header is mdl 0, the alpha language. The rest of this manual documents mdl 1; this page is the one place that documents what mdl 0 means differently, and how to move a script from one to the other.

Two rules make the move safe (ADR-0011):

• A script never changes meaning because a newer mxcli runs it. A change of meaning, or a new rejection, applies only under the header that introduces it. Without the header the old meaning is kept, and the construct warns with an MDL-V1-* code.
• A deprecated spelling is a respelling. It means exactly what its new form means, warns with an MDL-DEPR* code, and mxcli fmt --upgrade rewrites it. It is refused only from the version named in its entry.

Every warning that carries one of these codes ends with a pointer such as (mxcli help MDL-V1-LIMIT1). That command prints the code’s entry: the old form, the new form, whether fmt --upgrade rewrites it, and the version that refuses it. mxcli syntax <topic> --deprecated lists the old spellings of one topic.

mdl 1 is frozen

mdl 1 was frozen at beta. It is a contract: a later change of meaning needs a new version, mdl 2, and a script headed mdl 1; means the same under every later mxcli release. What that changes in practice:

Before the freeze mdl 1; warned “preview: may still change” (MDL-LANG01); that warning is gone. A header after the first statement must name the same version as the first: mdl 0; after mdl 1; is an error, and so is mdl 1; part-way through a script that started without one.

What a script without the header means

Each construct below is refused under mdl 1; and accepted without the header, where it keeps its old meaning and warns with the code shown.

Strings without the header

A script without the header (mdl 0) still reads a backslash before n, r, t, \ or ' as an escape — 'C:\temp' holds a tab — and check warns MDL-V1-ESCAPE for each literal whose value changes under mdl 1. Write the backslash-free form ('it''s') to mean the same under both.

In a microflow or nanoflow expression, without the header 'C:\\temp' stores 'C:\temp' and 'it\'s' stores 'it''s': the stored expression is the same value, spelled as Studio Pro spells it.

describe --mdl 0 keeps the mdl 0 escapes (\n, \\): in a flow’s expression and an XPath constraint it writes a stored backslash as \\, so the description reads back as the stored value under mdl 0. mxcli fmt --upgrade rewrites an mdl 0 script’s escaped strings to the mdl 1 form. An expression whose string holds an escaped line break is written as the expression Mendix stores for it, since an expression that spans lines is stored exactly as written.

Without the header a template literal that spans lines and has no parameters is an expression instead — the template is {1} and the literal its parameter — and check warns MDL-V1-TEMPLATE. With with ({n} = …) parameters it is the template text under both versions.

How to migrate a script

1. Commit the script first, so the upgrade is one reviewable diff.

2. Upgrade it with the project it runs against, and let the upgrade add the header. Never type mdl 1; by hand: the upgrade adds it only after rewriting every construct whose meaning the header would change, and refuses when one has no rewrite.

   mxcli fmt --upgrade -w -p app.mpr script.mdl
   

   The header is the default since the freeze; --header still says so explicitly, and --header=false upgrades the spellings alone.

   The project (-p) answers what the script alone cannot: whether find(…) over a flow’s result is the string function or the list operation, which bare commit statements the stored flows run without events, and which create or modify statements exec would refuse under the header. The project is only read.

3. Read what it reports on stderr. A deprecated spelling with no mechanical rewrite is left in place and listed as “not upgraded”; a header-gated construct with no rewrite blocks the header, and the file keeps its version. Fix those by hand (mxcli help <code> says how) and upgrade again.

4. Check it against the project, the way exec will read it:

   mxcli check script.mdl -p app.mpr --references
   

   check -p reports everything exec would refuse under the header, computed by the same code exec uses, so a refusal shows up here and not halfway through a run.

   To gate a script that is meant to be ready for the header — in CI, say — pass --deprecations=error --v1=error: the first fails on a deprecated spelling (MDL-DEPRnnn), the second on an MDL-V1-* warning, which only a headerless script reports. Either alone lets the other through.

5. Run it twice. The first exec applies the script; the second must write nothing, and report every document unchanged. A second run that writes is a script that does not say what the project holds — the upgrade’s job is to make it say so — and is worth reporting.

   mxcli exec script.mdl -p app.mpr
   mxcli exec script.mdl -p app.mpr   # expect: nothing written
   

Test files (.test.mdl, .test.md) are upgraded the same way: the statements in their blocks are rewritten, and doc comments (@test, @expect, …), separators and prose are kept byte for byte. The header goes on the first line of a .test.mdl file and on the first line inside each mdl-test block of a .test.md file; --header=false declines it, as for a script. The runner and check read it, so a test body means under the header what it means in a script (see Test Formats).

One dialect per file. Upgrade a headerless file before editing it; do not add mdl 1 statements to an mdl 0 file.

What the upgrade does, in order

mxcli fmt --upgrade changes nothing but the constructs below; comments, layout and keyword case survive, and the result is re-parsed before it is written.

1. Deprecated spellings become their new form (the MDL-DEPR* table). This step runs with or without the header.
2. Bare commits are pinned (with -p, with or without the header). A bare commit $X; means with events, Studio Pro’s default; mxcli releases before that change stored it without. In a create or modify flow whose stored commit has no events, the upgrade writes commit $X without events; so that re-running the script keeps what is stored. Without -p the script is left as written and fmt prints a note (MDL067) per flow.
3. Header-gated constructs are rewritten to the spelling that keeps their mdl 0 meaning under the header (not with --header=false): the missing ; is added, / lines are deleted, a backslash escape becomes the character it stood for, retrieve … limit 1 (an object under mdl 0) becomes retrieve … first, a reassignment gets set, and a list operation becomes one statement per activity. One change is version-neutral and is rewritten without the header too (the table says which).
4. The header is added — unless a construct in step 3 has no rewrite, or, with -p, exec would refuse a statement under the header (a create or modify of a stored flow whose change cannot be spliced in, MDL-V1-REBUILD). The file then keeps its version and the rest of the upgrade still applies; --force-header adds the header anyway.

The rewrites and refusals in detail

mxcli fmt --upgrade rewrites every deprecated spelling (the MDL-DEPRnnn warnings) to its canonical form — create or replace becomes create or modify, list entities becomes list entities, on error { … } becomes on error begin … end error — and changes nothing else: comments, layout and keyword case are kept. A deprecated use with no mechanical rewrite is reported and left in place.

mxcli fmt --upgrade script.mdl                  # print the upgraded script
mxcli fmt --upgrade -w script.mdl               # upgrade in place, adding `mdl 1;`
mxcli fmt --upgrade --header=false -w script.mdl  # the spellings alone, no header

The header is added after rewriting every construct whose meaning it would change, so the script keeps doing what it did:

A construct with no mechanical rewrite is reported with the reason, and fmt refuses to add the header rather than change the script’s meaning: an unknown or mis-shaped property (MDL-V1-PROP, MDL-V1-PROPVALUE), create or replace view entity (MDL-V1-REPLACE01), a session command in a script (MDL-V1-SESSION: move it to the command line or the REPL), a nested list operation such as count(filter(…)), find/contains on a variable whose type the script does not state (when the variable holds a microflow or nanoflow call’s result, the called flow’s return type decides: a flow the script creates earlier is read from the script, and any other from the project given with -p app.mpr, so fmt --upgrade -p app.mpr rewrites it), and an escaped line break (\n) inside an expression. An escaped line break in a text template’s literal is rewritten: the break is written into the literal, which under mdl 1 is still the template text. Running fmt --upgrade on its own output changes nothing.

-p app.mpr also settles a bare commit $X; in a create or modify microflow|nanoflow, with or without the header. Since mendixlabs/mxcli#895 a bare commit means with events, Studio Pro’s default; an older mxcli stored the same statement without events. Where the stored flow commits the variable without events, fmt --upgrade -p app.mpr writes commit $X without events;, so re-running the script keeps what is stored instead of turning the event handlers on (or, inside a loop under mdl 1, being refused). A new flow, a new commit, or a stored commit with events is left as written; where the stored flow commits the variable both ways, the statement is left and reported. Without -p, fmt prints a note (MDL067) for each flow with a bare commit.

-p app.mpr also tells the upgrade which statements exec would refuse once the header is there. Under mdl 1 a create or modify microflow|nanoflow of a stored flow is applied as a patch, and a change the patch cannot make (inside a loop body anything but an activity replaced by one of the same kind, an error handler, a redrawn connector, a return added, a statement inserted without @position that needs room past a node the script places) is refused with nothing written; without the header the same statement rebuilds the whole flow (MDL-V1-REBUILD). No rewrite keeps that meaning, so fmt names each such statement and leaves the header off that file, applying the rest of the upgrade. Change those flows with alter, or drop and create them, and upgrade again; --force-header adds the header regardless. mxcli check script.mdl -p app.mpr reports the same statements (an MDL-V1-REBUILD error under mdl 1, the warning without the header), computed by the same code as exec and diff.

Behaviour changes to know about

Besides the generated tables, a few changes alter what an existing script writes. Most apply under both versions, because the old behaviour was a silent wrong write rather than a meaning a script could rely on (ADR-0011 allows fixing those everywhere); the others are gated like any MDL-V1-* change. They are listed because a script that ran before may write something different now. Where the old output can still be asked for, the entry says how.

Reference

The tables below are generated from the registries in the code (visitor.LanguageChanges, executor.LanguageChanges and mdl/deprecation) by make gen-migration-reference; CI fails when they are stale. A version above the newest one this mxcli knows (mdl 2 today) is the version that will refuse the spelling; until then it only warns.

Changes of meaning (MDL-V1-*)

25 constructs mean something different under the mdl 1; header. Without the header each keeps the meaning in the second column and warns with its code.

Deprecated spellings (MDL-DEPR*)

88 old spellings mean exactly what their new form means. They warn with their code under every version before the one in the last column, which refuses them.

Data Types

MDL has a type system that maps to the Mendix metamodel attribute types. Every attribute in an entity definition has a type that determines how values are stored and validated.

Type Categories

Quick Example

CREATE PERSISTENT ENTITY Demo.AllTypes (
  ItemNumber: AutoNumber NOT NULL UNIQUE DEFAULT 1,
  Code: String(10) NOT NULL UNIQUE,
  Name: String(200) NOT NULL,
  Description: String(unlimited),
  Counter: Integer DEFAULT 0,
  BigNumber: Long,
  Amount: Decimal DEFAULT 0.00,
  IsActive: Boolean DEFAULT TRUE,
  CreatedAt: DateTime,
  BirthDate: DateTime,
  Attachment: Binary,
  Status: Enumeration(Demo.Status) DEFAULT 'Active'
);

No Implicit Conversions

MDL does not perform implicit type conversions. Types must match exactly when assigning defaults or modifying attributes.

Compatible type changes (when using CREATE OR MODIFY):

• String(100) to String(200) – increasing length
• Integer to Long – widening numeric type

Incompatible type changes:

• String to Integer
• Boolean to String
• Any type to AutoNumber (if data exists)

Further Reading

• Primitive Types – detailed reference for each type
• Constraints – NOT NULL, UNIQUE, DEFAULT
• Type Mapping – MDL to Mendix to database mapping
• Enumerations – enumeration type definitions

Primitive Types

This page documents each primitive type available for entity attributes in MDL.

String

Variable-length text data.

String              -- Default length (200)
String(n)           -- Specific length (1 to unlimited)
String(unlimited)   -- No length limit

Examples:

Name: String(200)
Description: String(unlimited)
Code: String(10)

Default value format:

Name: String(200) DEFAULT 'Unknown'
Code: String(10) DEFAULT ''

Integer

32-bit signed integer.

Integer

Range: -2,147,483,648 to 2,147,483,647

Quantity: Integer
Age: Integer DEFAULT 0
Priority: Integer NOT NULL DEFAULT 1

Long

64-bit signed integer.

Long

Range: -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807

FileSize: Long
TotalCount: Long DEFAULT 0

Decimal

High-precision decimal number with up to 20 digits total.

Decimal

Price: Decimal
Amount: Decimal DEFAULT 0
TaxRate: Decimal DEFAULT 0.21

Boolean

True/false value. Boolean attributes must have a DEFAULT value (enforced by Mendix Studio Pro).

Boolean DEFAULT TRUE
Boolean DEFAULT FALSE

IsActive: Boolean DEFAULT TRUE
Enabled: Boolean DEFAULT TRUE
Deleted: Boolean DEFAULT FALSE

DateTime

Date and time stored as a UTC timestamp.

DateTime

CreatedAt: DateTime
ModifiedAt: DateTime
ScheduledFor: DateTime

A DateTime is localized (shown in the user’s time zone) by default. For a calendar date that must not shift with the time zone, such as a birth date, add NOT LOCALIZED — see Constraints:

BirthDate: DateTime NOT LOCALIZED

DateTime values include both date and time components. To show only the date, format it on the widget; there is no Date type.

No Date, Float or Currency

Mendix has no date-only attribute type: a date is a DateTime, and showing only its date part is a formatting choice on the widget. Float and Currency were removed in Mendix 7 in favour of Decimal. MDL refuses float and currency with the type to write instead — earlier versions accepted them and silently stored a String.

date was always stored as a DateTime, so in a script without the mdl 1; header it is a deprecated spelling of DateTime: it builds a DateTime and warns MDL-DEPR160, and mxcli fmt --upgrade rewrites it to DateTime. Under mdl 1; it is an error.

AutoNumber

Auto-incrementing integer, typically used for human-readable identifiers. The DEFAULT value specifies the starting number.

AutoNumber

OrderId: AutoNumber NOT NULL UNIQUE DEFAULT 1
CustomerId: AutoNumber

AutoNumber attributes automatically receive the next value on object creation. They are typically combined with NOT NULL and UNIQUE constraints.

Binary

Binary data for files, images, and other non-text content.

Binary

ProfileImage: Binary
Document: Binary
Thumbnail: Binary

File metadata (name, size, MIME type) is stored separately by Mendix. Maximum size is configurable per attribute.

HashedString

Securely hashed string, used for password storage. Values are one-way hashed and cannot be retrieved – comparison is done by hashing the input and comparing hashes.

HashedString

Password: HashedString

Enumeration Reference

References an enumeration type defined with CREATE ENUMERATION. See Enumerations for details.

Enumeration(<Module.EnumerationName>)

Status: Enumeration(Sales.OrderStatus)
Priority: Enumeration(Core.Priority) DEFAULT Core.Priority.Normal
Type: Enumeration(MyModule.ItemType) NOT NULL

Default value format:

-- Fully qualified (preferred)
DEFAULT Module.EnumName.ValueName

-- Legacy string literal form
DEFAULT 'ValueName'

See Also

• Data Types – type system overview
• Constraints – NOT NULL, UNIQUE, DEFAULT
• Type Mapping – MDL to Mendix to database mapping

Constraints

Constraints restrict the values an attribute can hold. They are specified after the type in an attribute definition.

Syntax

<name>: <type> [NOT NULL [ERROR '<message>']] [UNIQUE [ERROR '<message>']] [DEFAULT <value>]

Constraints must appear in this order:

1. NOT NULL (optionally with ERROR)
2. UNIQUE (optionally with ERROR)
3. DEFAULT

NOT NULL

Marks the attribute as required. The value cannot be empty.

Name: String(200) NOT NULL

With a custom error message displayed to the user:

Name: String(200) NOT NULL ERROR MESSAGE 'Name is required'

UNIQUE

Enforces that the value must be unique across all objects of the entity.

Email: String(200) UNIQUE

With a custom error message:

Email: String(200) UNIQUE ERROR MESSAGE 'Email already exists'

DEFAULT

Sets the initial value when a new object is created.

Count: Integer DEFAULT 0
IsActive: Boolean DEFAULT TRUE
Status: Enumeration(Sales.OrderStatus) DEFAULT 'Draft'
Name: String(200) DEFAULT 'Unknown'

Default value syntax varies by type:

Omitting the DEFAULT clause means no default value is set:

OptionalField: String(200)

LOCALIZED / NOT LOCALIZED (DateTime only)

Studio Pro’s Localize setting on a DateTime attribute (LocalizeDate in the model). A localized DateTime is converted to the user’s time zone when it is shown or entered; a non-localized one is not, which is what a calendar date such as a birth date needs — otherwise it can show as the day before for a user west of UTC.

OrderDate: DateTime,                -- localized (Mendix's default)
BirthDate: DateTime NOT LOCALIZED,  -- not localized

• LOCALIZED states the default explicitly. It is mostly useful on ALTER ENTITY … MODIFY ATTRIBUTE to switch a non-localized attribute back, the way NULLABLE clears NOT NULL.
• On a new attribute, no clause means localized.
• On a rewrite — CREATE OR MODIFY ENTITY or MODIFY ATTRIBUTE — no clause keeps the value already stored (a Studio Pro-authored non-localized attribute stays non-localized); a stated clause wins. When the keep is a stored not localized, the statement prints a Note: naming the attribute and the DateTime localized spelling that changes it.
• On a view entity the value follows the OQL source attribute and needs no clause; a stated one overrides it, and a mismatch with the source is CE6770.
• On any type other than DateTime the clause is an error: there is nowhere to store it.
• DESCRIBE ENTITY prints not localized (right after the type) when the attribute is not localized, and nothing otherwise, so its output round-trips.

The deprecated Date type (MDL-DEPR160) is a localized DateTime. For a date-only value write DateTime NOT LOCALIZED.

Combining Constraints

All three constraints can be used together:

Email: String(200) NOT NULL ERROR MESSAGE 'Email is required'
                   UNIQUE ERROR MESSAGE 'Email already exists'
                   DEFAULT ''

More examples:

CREATE PERSISTENT ENTITY Sales.Product (
  -- Required only
  Name: String(200) NOT NULL,

  -- Required with custom error
  SKU: String(50) NOT NULL ERROR MESSAGE 'SKU is required for all products',

  -- Unique only
  Barcode: String(50) UNIQUE,

  -- Required and unique with custom errors
  ProductCode: String(20) NOT NULL ERROR MESSAGE 'Product code required'
                          UNIQUE ERROR MESSAGE 'Product code must be unique',

  -- Default only
  Quantity: Integer DEFAULT 0,

  -- No constraints
  Description: String(unlimited)
);

Validation Rule Mapping

Under the hood, constraints map to Mendix validation rules:

LOCALIZED / NOT LOCALIZED is not a validation rule: it is the LocalizeDate property of the attribute’s DomainModels$DateTimeAttributeType.

See Also

• Primitive Types – type reference
• Attributes – full attribute definition syntax
• ALTER ENTITY – modifying constraints on existing entities

Enumerations

Enumerations define a fixed set of named values. They are used as attribute types to restrict a field to a specific list of options.

CREATE ENUMERATION

[/** <documentation> */]
CREATE ENUMERATION <Module>.<Name> (
  <value-name> '<caption>' [, ...]
)

Each value has an identifier (used in code) and a caption (displayed in the UI):

/** Order status enumeration */
CREATE ENUMERATION Sales.OrderStatus (
  Draft 'Draft',
  Pending 'Pending Approval',
  Approved 'Approved',
  Shipped 'Shipped',
  Delivered 'Delivered',
  Cancelled 'Cancelled'
);

Using Enumerations in Attributes

Reference an enumeration type in an attribute definition with Enumeration(Module.Name):

CREATE PERSISTENT ENTITY Sales.Order (
  Status: Enumeration(Sales.OrderStatus) DEFAULT 'Draft',
  Priority: Enumeration(Core.Priority) NOT NULL
);

The default value is the name of the enumeration value (not the caption). The fully qualified form is preferred:

-- Fully qualified (preferred)
Status: Enumeration(Sales.OrderStatus) DEFAULT Sales.OrderStatus.Draft

-- Legacy string literal form
Status: Enumeration(Sales.OrderStatus) DEFAULT 'Draft'

ALTER ENUMERATION

Add, rename, re-caption, or remove values on an existing enumeration:

mdl 1;
-- Add a new value (the CAPTION keyword is required for ALTER, unlike CREATE)
ALTER ENUMERATION Sales.OrderStatus
  ADD VALUE OnHold CAPTION 'On Hold';

-- Rename a value's identifier (the name used in code)
ALTER ENUMERATION Sales.OrderStatus
  RENAME VALUE Draft TO Pending;

-- Change an existing value's display caption in place (the name is unchanged)
ALTER ENUMERATION Sales.OrderStatus
  MODIFY VALUE OnHold CAPTION 'Temporarily On Hold';

-- Remove a value
ALTER ENUMERATION Sales.OrderStatus
  DROP VALUE Draft;

MODIFY VALUE … CAPTION edits the caption without dropping the value, so it works even while the enumeration is referenced by an entity attribute — unlike drop + recreate, which is blocked by the reference. Several actions can be combined in one statement (e.g. RENAME VALUE Draft TO Pending MODIFY VALUE Pending CAPTION 'Pending Review').

DROP ENUMERATION

Remove an enumeration entirely:

DROP ENUMERATION Sales.OrderStatus;

Dropping an enumeration that is still referenced by entity attributes will cause errors in Studio Pro.

See Also

• Primitive Types – all attribute types including enumeration references
• Data Types – type system overview
• Entities – using enumerations in entity definitions

Type Mapping

This page shows how MDL types correspond to Mendix internal types (BSON storage) and the Go SDK types used by modelsdk-go.

MDL to Backend Type Mapping

Note that Date and DateTime both map to the same underlying BSON type. The distinction is handled at the UI layer.

Default Value Mapping

Default values are stored in BSON as StoredValue structures:

All default values are serialized as strings in the BSON storage, regardless of the attribute type.

See Also

• Primitive Types – MDL type syntax and usage
• Data Types – type system overview

Domain Model

The domain model is the data layer of a Mendix application. It defines the entities (data tables), their attributes (columns), relationships between entities (associations), and inheritance hierarchies (generalizations).

Core Concepts

Module Scope

Every domain model element belongs to a module. Elements are always referenced by their qualified name in Module.Element format:

Sales.Customer           -- entity
Sales.OrderStatus        -- enumeration
Sales.Order_Customer     -- association

Complete Example

This example creates a small Sales domain model with related entities, an enumeration, and an association:

mdl 1;
-- Enumeration for order statuses
CREATE ENUMERATION Sales.OrderStatus (
  Draft 'Draft',
  Pending 'Pending',
  Confirmed 'Confirmed',
  Shipped 'Shipped',
  Delivered 'Delivered',
  Cancelled 'Cancelled'
);

-- Customer entity
/** Customer master data */
@Position(100, 100)
CREATE PERSISTENT ENTITY Sales.Customer (
  CustomerId: AutoNumber NOT NULL UNIQUE DEFAULT 1,
  Name: String(200) NOT NULL ERROR MESSAGE 'Customer name is required',
  Email: String(200) UNIQUE ERROR MESSAGE 'Email already registered',
  Phone: String(50),
  IsActive: Boolean DEFAULT TRUE,
  CreatedAt: DateTime
)
INDEX (Name)
INDEX (Email);

-- Order entity
/** Sales order */
@Position(300, 100)
CREATE PERSISTENT ENTITY Sales.Order (
  OrderId: AutoNumber NOT NULL UNIQUE DEFAULT 1,
  OrderNumber: String(50) NOT NULL UNIQUE,
  OrderDate: DateTime NOT NULL,
  TotalAmount: Decimal DEFAULT 0,
  Status: Enumeration(Sales.OrderStatus) DEFAULT 'Draft',
  Notes: String(unlimited)
)
INDEX (OrderNumber)
INDEX (OrderDate DESC);

-- Association: Order belongs to Customer
CREATE ASSOCIATION Sales.Order_Customer
  FROM Sales.Customer
  TO Sales.Order
  TYPE Reference
  OWNER Default
  ON DELETE SET NULL;

Further Reading

• Entities – entity types and CREATE ENTITY syntax
• Attributes – attribute definitions and validation
• Associations – relationships between entities
• Generalization – entity inheritance
• Indexes – index creation
• Enumerations – enumeration types
• ALTER ENTITY – modifying existing entities

Entities

Entities are the primary data structures in a Mendix domain model. Each entity corresponds to a database table (for persistent entities) or an in-memory object (for non-persistent entities).

Entity Types

CREATE ENTITY

[/** <documentation> */]
[@Position(<x>, <y>)]
CREATE [OR MODIFY] <entity-type> ENTITY <Module>.<Name> (
  <attribute-definitions>
)
[INDEX (<column-list>)]
[ON BEFORE|AFTER CREATE|COMMIT|DELETE|ROLLBACK CALL <Module>.<Microflow> [RAISE ERROR]]
[;|/]

Persistent Entity

The most common type. Data is stored in the application database:

/** Customer master data */
@Position(100, 200)
CREATE PERSISTENT ENTITY Sales.Customer (
  /** Auto-incrementing unique identifier */
  CustomerId: AutoNumber NOT NULL UNIQUE DEFAULT 1,
  /** Full legal name of the customer */
  Name: String(200) NOT NULL ERROR MESSAGE 'Name is required',
  /** Primary contact email address */
  Email: String(200) UNIQUE ERROR MESSAGE 'Email must be unique',
  /** Current account balance */
  Balance: Decimal DEFAULT 0,
  /** Whether the account is active */
  IsActive: Boolean DEFAULT TRUE,
  /** Timestamp of account creation */
  CreatedDate: AutoCreatedDate,
  /** Current lifecycle status */
  Status: Enumeration(Sales.CustomerStatus) DEFAULT 'Active'
)
INDEX (Name)
INDEX (Email);

Non-Persistent Entity

Used for helper objects, filter parameters, and UI state that does not need database storage:

CREATE NON-PERSISTENT ENTITY Sales.CustomerFilter (
  SearchName: String(200),
  MinBalance: Decimal,
  MaxBalance: Decimal
);

View Entity

Defined by an OQL query:

CREATE VIEW ENTITY Reports.CustomerSummary (
  CustomerName: String,
  TotalOrders: Integer,
  TotalAmount: Decimal
) AS
  SELECT
    c.Name AS CustomerName,
    COUNT(o.OrderId) AS TotalOrders,
    SUM(o.Amount) AS TotalAmount
  FROM Sales.Customer c
  LEFT JOIN Sales.Order o ON o.Customer = c
  GROUP BY c.Name;

“Read-only” is a common shorthand for view entities, but it conflates three separate things — and only two of them are true:

• No storage. A view entity has no database table, and it is not a database view either — after deploy, Postgres has no view object for it. The runtime translates the OQL and issues it per query.
• No write-back on commit. Committing a view-entity object does nothing; to persist a change you write through the source entity (retrieve it, change it, commit it).
• Not immutable. A view row is editable in memory — it behaves like a non-persistent object, so a form can bind to it and change its attributes. This makes a view entity a legitimate backing for an editable screen (populate the form with one pushed-down query, write back through the source in the save flow), not only a read-only report.

Gotcha: each declared attribute type must match its source column exactly. A String(60) attribute over a String(100) source column fails the build with CE6770 "View Entity is out of sync with the OQL Query." — widen the attribute to match. (mxbuild genuinely type-checks the OQL, so a clean build is real evidence, not just a syntax pass.)

CREATE OR MODIFY

Creates the entity if it does not exist, or updates it if it does. New attributes are added; existing attributes are preserved:

CREATE OR MODIFY PERSISTENT ENTITY Sales.Customer (
  CustomerId: AutoNumber NOT NULL UNIQUE DEFAULT 1,
  Name: String(200) NOT NULL,
  Email: String(200),
  Phone: String(50)  -- new attribute added on modify
);

System Attributes (Auditing)

Persistent entities can track who created/modified objects and when. Declare them as regular attributes using pseudo-types (like AutoNumber):

CREATE PERSISTENT ENTITY Sales.Order (
  OrderNumber: AutoNumber DEFAULT 1,
  TotalAmount: Decimal,
  Owner: AutoOwner,
  ChangedBy: AutoChangedBy,
  CreatedDate: AutoCreatedDate,
  ChangedDate: AutoChangedDate
);

Toggle on existing entities with ALTER ENTITY:

mdl 1;
ALTER ENTITY Sales.Order ADD ATTRIBUTE Owner: AutoOwner;
ALTER ENTITY Sales.Order DROP ATTRIBUTE ChangedDate;

Annotations

@Position

Controls where the entity appears in the domain model diagram:

@Position(100, 200)
CREATE PERSISTENT ENTITY Sales.Customer ( ... );

Documentation

A /** ... */ comment before the entity or before an individual attribute becomes its documentation in Studio Pro:

/** Customer master data.
 *  Stores both active and inactive customers.
 */
@Position(100, 200)
CREATE PERSISTENT ENTITY Sales.Customer (
  /** Auto-incrementing unique identifier */
  CustomerId: AutoNumber NOT NULL UNIQUE DEFAULT 1,

  /** Full legal name of the customer */
  Name: String(200) NOT NULL ERROR MESSAGE 'Name is required',

  /** Primary contact email address */
  Email: String(200) UNIQUE ERROR MESSAGE 'Email must be unique',

  /** Current account balance in the base currency */
  Balance: Decimal DEFAULT 0,

  /** Whether the customer account is active */
  IsActive: Boolean DEFAULT TRUE,

  /** Timestamp of account creation */
  CreatedDate: AutoCreatedDate,

  /** Current lifecycle status */
  Status: Enumeration(Sales.CustomerStatus) DEFAULT 'Active'
)
INDEX (Name)
INDEX (Email);

Attribute-level documentation appears in Studio Pro when hovering over the attribute in the domain model.

Entity Event Handlers

Persistent entities can have microflow event handlers that run before or after Create, Commit, Delete, or Rollback operations. The optional RAISE ERROR clause makes the handler act as a validation microflow — if it returns false, the operation is aborted.

CREATE PERSISTENT ENTITY Sales.Order (
  Total: Decimal,
  Status: String(50)
)
ON BEFORE COMMIT CALL Sales.ACT_ValidateOrder RAISE ERROR
ON AFTER CREATE CALL Sales.ACT_InitDefaults;

Event handlers can also be added or removed via ALTER ENTITY:

mdl 1;
-- Add a handler to an existing entity
ALTER ENTITY Sales.Order
  ADD EVENT HANDLER ON BEFORE DELETE CALL Sales.ACT_CheckCanDelete RAISE ERROR;

-- Remove a handler (CALL names which, when the event has several)
ALTER ENTITY Sales.Order
  DROP EVENT HANDLER ON BEFORE COMMIT CALL Sales.ACT_ValidateOrder;

Moments: BEFORE, AFTER Events: CREATE, COMMIT, DELETE, ROLLBACK

Each (Moment, Event) combination supports one handler per entity. The microflow must exist in the project (validated at execution time).

DROP ENTITY

Removes an entity from the domain model:

DROP ENTITY Sales.Customer;

See Also

• Attributes – attribute definitions within entities
• Indexes – adding indexes to entities
• Generalization – entity inheritance with EXTENDS
• ALTER ENTITY – modifying existing entities
• Associations – relationships between entities

Attributes and Validation Rules

Attributes define the fields on an entity. Each attribute has a name, a type, and optional constraints.

Attribute Syntax

[/** <documentation> */]
<name>: <type> [NOT NULL [ERROR '<message>']] [UNIQUE [ERROR '<message>']] [DEFAULT <value>]

Attribute Ordering

Attributes are listed in order, separated by commas. The last attribute has no trailing comma:

CREATE PERSISTENT ENTITY Module.Entity (
  FirstAttr: String(200),      -- comma after
  SecondAttr: Integer,         -- comma after
  LastAttr: Boolean DEFAULT FALSE  -- no comma
);

Validation Rules

Validation rules are expressed as attribute constraints. When validation fails, Mendix displays the error message (if provided) or a default message.