mxcli Language Poster
mxcli · the language poster
mxcli
MDL
the language poster
Let AI agents read and change Mendix apps — in a SQL-like language, from the command line.
RELEASE
0.25.0 · nightly recommended
LANGUAGE
mdl 1; — frozen beta
PROJECTS
Mendix 9–11 · MPR v1 & v2
LICENSE
Apache 2.0
SOURCE
github.com/mendixlabs/mxcli
DOCS
www.mxcli.org
ALSO IN MDL
workflows
nanoflows
rules
REST & OData
JSON mappings
business events
external SQL
Java & JS actions
AI agents · 11.9+
scheduled events
task queues
translations
settings
themes
mxcli syntax <topic> · mxcli help <command> · mxcli lint --list-rules — the tool is the reference
Zoom into any panel · ▶ Present for the tour
ALPHA — back up the .mpr; close Studio Pro before writing
01 Agents write MDL. mxcli does the rest.
01 · THE IDEA
Agents write MDL. mxcli does the rest.
MDL is a SQL-like language for the Mendix model: 5–10× denser than model JSON, so one script is one model turn.
mxcli's deterministic layer parses, checks and writes the .mpr — no Studio Pro needed.
AI agent
Claude Code · Cursor · Copilot
Windsurf · OpenCode · …
orders.mdl
mdl 1;
create entity …
create microflow …
create page …
grant …
mxcli
parse (ANTLR4)
check refs + idioms
execute per statement
write canonical BSON
app.mpr
v1 single SQLite file
v2 + mprcontents/
write
exec
BSON
headless — no Studio Pro
deterministic writes
re-exec writes nothing
8 agent tools
Go · single binary
list · describe · search · select
context from the catalog: 81 SQLite tables
mxbuild + runtime
run --local · hot reload ≈1 s
or docker · Portable App
feedback: check errors · lint · test results · page checks · screenshots
02 Start with the bootstrap prompt
02 · GET STARTED
Start with the bootstrap prompt
1
Open an empty repo in Claude Code — web, desktop or iPad
2
Paste the bootstrap prompt from www.mxcli.org
3
The agent installs mxcli, unpacks its skills and hands over to bootstrap-app
the prompt, abridged
This
is
an
empty
repo
.
Provision
it
as
a
Mendix
app
developed
with
mxcli
.
1
.
Make
sure
mxcli
is
available
…
# curl the release
2
.
.
/
mxcli
init
--sync-skills
3
.
Read
.
ai
-context
/
skills
/
bootstrap
-app
/
SKILL
.
md
and
follow
it
end
to
end
.
full text: www.mxcli.org/tools/bootstrap-prompt.html
bootstrap-app then …
interviews you about the app
mxcli new + init --tool claude
writes README & FINDINGS
records the plan in docs/brain
commits, boots, checks HTTP 200
takes the lint + report baseline
prompt stays phone-sized — the steps ship in mxcli
OR BY HAND
curl
-fsSL
-o
mxcli
…
/
releases
/
download
/
nightly
/
mxcli
-linux-amd64
&
&
mxcli
new
MyApp
--version
1
1
.
8
.
0
03 mxcli init
03 · SET UP A PROJECT
mxcli init
mxcli
init
--tool
claude
--tool
cursor
# or --all-tools · add-tool windsurf
files
MyApp
/
├
─
app
.
mpr
├
─
AGENTS
.
md
# universal agent guide
├
─
CLAUDE
.
md
# gates & conventions
├
─
.
claude
/
│
├
─
skills
/
mendix
/
# 74 skills
│
├
─
commands
/
mendix
/
# 10 slash commands
│
└
─
lint
-rules
/
*
.
star
# Starlark rules
├
─
.
ai
-context
/
skills
/
# skills for any tool
└
─
.
devcontainer
/
# mxbuild · JDK 21 · Docker
After an mxcli upgrade: mxcli init --sync-skills. Extra packs: mxcli
skill list | add | upgrade.
8 AGENT TOOLS
Claude Code
CLAUDE.md · .claude/
Cursor
.cursorrules
GitHub Copilot
copilot-instructions.md
Windsurf
.windsurfrules
Continue
.continue/config.json
Aider
.aider.conf.yml
OpenCode
opencode.json
Mistral Vibe
.vibe/
04 The CLI map
04 · COMMANDS
The CLI map
CORE
init
new
exec
check
diff
fmt
syntax
EXPLORE
describe
structure
search
callers
callees
refs
impact
context
QUALITY
lint
report
test
eval
RUN & DEBUG
run
docker
playwright
debug
oql
log
MODEL UPKEEP
rename
layout
fix
marketplace
widget
theme
AGENTS & EDITORS
skill
brain
lsp
mcp
tui
serve
global flags
mxcli
-p
app
.
mpr
-c
"list entities in Sales"
--json
# -p optional with one .mpr here
05 Read before you write
05 · EXPLORE
Read before you write
MDL
mdl
1
;
list
modules
;
list
entities
in
Sales
;
describe
entity
Sales
.
Customer
;
describe
Sales
.
ACT_Order_Submit
;
-- type auto-detected
describe
structure
depth
1
;
search
'validation'
;
CLI
mxcli
-c
"describe structure depth 1"
mxcli
describe
-f
mermaid
Sales
.
Customer
mxcli
context
Sales
.
ACT_Order_Submit
-d
2
OR STAY IN THE REPL
connect
local
'app.mpr'
;
list
pages
;
status
;
exit
list is canonical in mdl 1. show … still
parses, flagged MDL-DEPR002.
DESCRIBE -F MERMAID →
Customer
Name: String
Email: String
IsActive: Bool
Order
Number: AutoNr
Date: DateTime
1 *
Order_Customer
Also -f json and -f elk. mxcli serve and the VS Code
extension render the same views for review.
06 Query the model like a database
06 · CATALOG
Query the model like a database
MDL
refresh
catalog
full
;
select
Name
,
ActivityCount
from
CATALOG
.
MICROFLOWS
where
ActivityCount
>
1
0
order
by
ActivityCount
desc
;
select
SourceName
,
RefKind
,
TargetName
from
CATALOG
.
REFS
where
TargetName
=
'Sales.Customer'
;
list
callers
of
Sales
.
ACT_Order_Submit
transitive
;
list
impact
of
Sales
.
Customer
;
81
CATALOG.* tables & views in a local
SQLite index — list catalog tables;
ENTITIES
ATTRIBUTES
MICROFLOWS
ACTIVITIES
PAGES
WIDGETS
REFS
PERMISSIONS
WORKFLOWS
STRINGS
SOURCE
GRAPH_*
CLI twins: mxcli callers · callees · refs · impact · search · graph-report
LIST CALLERS OF SALES.ACT_ORDER_SUBMIT TRANSITIVE →
ACT_Order_Submit
SUB_Order_Validate
Order_Edit (page)
WF_Approval (workflow)
07 Entities
07 · DOMAIN MODEL
Entities
MDL
create
persistent
entity
Sales
.
Customer
(
Name
:
string
(
1
0
0
)
not
null
,
Email
:
string
(
2
0
0
)
not
null
unique
,
IsActive
:
boolean
default
true
,
Credit
:
decimal
)
index
(
Email
)
;
create
persistent
entity
Sales
.
Photo
extends
System
.
Image
(
Caption
:
string
(
2
0
0
)
)
;
alter
entity
Sales
.
Customer
add
attribute
Phone
:
string
(
5
0
)
;
alter
entity
Sales
.
Customer
rename
attribute
Phone
to
PhoneNumber
;
create or modify rebuilds the element and
drops attributes you leave out. Prefer if
not exists / alter for re-runnable
scripts.
view entities: create view entity … as
select … (10.18+)
Customer
Name
String (100)
Email
String (200)
IsActive
Boolean
Credit
Decimal
index: Email · unique: Email
08 Types & relations
08 · DOMAIN MODEL
Types & relations
MDL
create
association
Sales
.
Order_Customer
from
Sales
.
Order
to
Sales
.
Customer
type
reference
on
delete
cascade
;
create
enumeration
Sales
.
OrderStatus
(
Draft
'Draft'
,
Confirmed
'Confirmed'
,
Shipped
'Shipped'
)
;
alter
enumeration
Sales
.
OrderStatus
add
value
Delivered
caption
'Delivered'
;
ATTRIBUTE TYPES
string(n)
string(unlimited)
integer
long
decimal
boolean
datetime
binary
hashedstring
autonumber
Module.Enum
AUDIT PSEUDO-TYPES
autoowner
autochangedby
autocreateddate
autochangeddate
MODIFIERS
not null
unique
default <v>
calculated by M.MF
ASSOCIATION OPTIONS
type reference | referenceset
owner default | both
storage column | table
on delete cascade | restrict | set null
from = the entity that owns the reference (the FK side).
09 Microflows
09 · LOGIC
Microflows
MDL
create
microflow
Sales
.
ACT_Order_Submit
(
$Order
:
Sales
.
Order
)
returns
boolean
begin
retrieve
$Lines
from
$Order
/
Sales
.
Line_Order
;
declare
$count
integer
=
0
;
loop
$line
in
$Lines
begin
change
$line
(
IsConfirmed
=
true
)
;
set
$count
=
$count
+
1
;
end
loop
;
if
$count
>
0
then
commit
$Order
;
log
info
'Order submitted'
;
end
if
;
return
$count
>
0
;
end
;
ACTIVITIES
retrieve
create
change
commit
delete
rollback
call microflow
call java action
call rest service
show page
close page
show message
validation feedback
log
FIND · FILTER · count
loop
while
case
on error rollback
RULES MXCLI CHECK ENFORCES
; after every statement
retrieve … first = one object
no return inside a loop
no nested list ops (MDL-LISTOP02)
no empty list as a loop source
retrieve
loop $line
change
set
commit
the same microflow in Studio Pro
10 Pages & widgets
10 · UI
Pages & widgets
MDL
create
page
Sales
.
Customer_Edit
(
params
:
(
$Customer
:
Sales
.
Customer
)
,
title
:
'Edit Customer'
,
layout
:
Atlas_Core
.
PopupLayout
)
{
dataview
dvCustomer
(
datasource
:
$Customer
)
{
textbox
txtName
(
label
:
'Name'
,
attribute
:
Name
)
combobox
cbStatus
(
label
:
'Status'
,
attribute
:
Status
)
footer
{
actionbutton
btnSave
(
caption
:
'Save'
,
action
:
save
changes
,
buttonstyle
:
primary
)
actionbutton
btnCancel
(
caption
:
'Cancel'
,
action
:
cancel
changes
)
}
}
}
;
alter
page
Sales
.
Customer_Edit
{
set
(
caption
:
'Save & Close'
)
on
btnSave
;
drop
txtUnused
;
}
;
WIDGETS
dataview
datagrid
gallery
listview
layoutgrid
container
textbox
textarea
datepicker
combobox
checkbox
dynamictext
image
snippetcall
actionbutton
+ pluggable
Edit Customer
×
Name
Jansen B.V.
Status
Confirmed ▾
Cancel
Save
11 Roles, access & navigation
11 · SECURITY
Roles, access & navigation
MDL
create
module
role
Sales
.
Manager
description
'Full access'
;
grant
execute
on
microflow
Sales
.
ACT_Order_Submit
to
Sales
.
Manager
;
grant
view
on
page
Sales
.
Customer_Edit
to
Sales
.
Manager
,
Sales
.
User
;
grant
create
,
delete
,
read
*
,
write
*
on
entity
Sales
.
Customer
to
Sales
.
Manager
;
grant
read
*
on
entity
Sales
.
Order
to
Sales
.
User
where
[
Status
=
'Open'
]
;
create
user
role
Manager
(
ModuleRoles
:
(
Sales
.
Manager
)
)
;
alter
app
security
(
SecurityLevel
:
production
)
;
create
or
modify
navigation
Responsive
home
page
Sales
.
Home_Web
{
menu
item
'Orders'
(
OnClick
:
show
page
Sales
.
Order_Overview
)
}
;
SecurityLevel production makes missing
access a build error.
user role
Manager
module role Sales.Manager
entity
CRUD · XPath rows
microflow
execute
page
view
12 Run, test & debug
12 · RUNTIME
Run, test & debug
shell
mxcli
run
--local
--watch
--detach
# warm loop: mxbuild --serve + runtime
mxcli
run
wait
--ready
&
&
mxcli
run
status
mxcli
test
tests
/
--local
# .test.mdl microflow tests
mxcli
playwright
check
/
p
/
orders
# text verdict per page
mxcli
debug
break
Sales
.
ACT_Order_Submit
# microflow debugger
mxcli
oql
"select Name from Sales.Customer"
mxcli
docker
up
·
reload
# Portable App Distribution path
orders.test.mdl
/
*
*
*
@
test
Multiply
*
@
expect
$result
=
5
0
*
/
$result
=
call
microflow
Sales
.
Multiply
(
A
=
1
0
,
B
=
5
)
;
/
≈1 s
hot reload_model
~2 s
warm test run
:8080
app · :8090 admin
run --hub → https://<name>.mxcli.org
browser preview from a cloud session · Linux builds
13 The gates
13 · QUALITY
The gates
check
syntax + references
~2 s
cheapest first — stop at the first red
.claude/lint-rules/*.star
RULE_ID
=
"CUSTOM001"
CATEGORY
=
"naming"
SEVERITY
=
"warning"
def
check
(
)
:
out
=
[
]
for
e
in
entities
(
)
:
if
not
is_pascal_case
(
e
.
name
)
:
out
.
append
(
violation
(
message
=
e
.
name
+
' not PascalCase'
)
)
return
out
RULE FAMILIES
CONV
SEC
ARCH
QUAL
DESIGN
MPR
lint -f text | json | sarif · --list-rules
exec
apply · twice = no writes
lint
~50 rules
~3 s
report
6 categories · 0–100
docker check
mxbuild / mx check
~25 s
test
microflow tests
~2 s warm
run
playwright check
14 74 skills, routed by description
14 · SKILLS
74 skills, routed by description
Each SKILL.md's description tells the agent when to load it.
LOGIC
write-microflows
write-nanoflows
write-rules
patterns-crud
patterns-data-processing
validation-microflows
cheatsheet-variables
cheatsheet-errors
resolve-forward-references
xpath-constraints
regular-expressions
java-actions
java-dependencies
javascript-actions
DOMAIN MODEL
generate-domain-model
mdl-entities
system-module
write-oql-queries
UI
create-page
alter-page
overview-pages
master-detail-pages
write-layouts
fragments
custom-widgets
create-custom-widget
bulk-widget-updates
atlas-design
theme-styling
migrate-design-prototype
SECURITY & SETTINGS
manage-security
manage-navigation
project-settings
translations
organize-project
INTEGRATION
rest-client
rest-call-from-json
json-structures-and-mappings
odata-data-sharing
database-connections
browse-integrations
catalog-search
mock-rest-apis
connect-rapidminer-graph
download-marketplace-content
WORKFLOWS & AGENTS
write-workflows
agents
scheduled-events-and-queues
business-events
RUN · TEST · DEBUG
run-local
run-app
docker-workflow
runtime-admin-api
analyze-runtime
test-app
test-microflows
verify-with-oql
demo-data
debug-microflows
debug-bson
SKILL PACKS
mxcli skill add
mendix-bulk-oql-dml
mendix-odata-pushdown
mendix-vega-charts
PROCESS & QUALITY
bootstrap-app
choose-edit-mode
check-syntax
live-edit-with-studio-pro
project-brain
graph-analysis
assess-quality
write-lint-rules
upgrade-mendix-version
record-narrated-demo
teamserver-git
assess-migration
migrate-oracle-forms
migrate-k2-nintex
CLAUDE SLASH COMMANDS
/mendix:explore
/mendix:create-entity
/mendix:create-crud
/mendix:check-script
/mendix:diff-script
/mendix:diff-local
/mendix:lint
/mendix:test
/mendix:validate-project
/mendix:refresh-catalog
“add an edit page for Customer”
→ loads create-page, then writes MDL
15 Describe, use, check
15 · CUSTOM WIDGETS
Describe, use, check
1 describe
2 use
3 check
shell
mxcli
widget
describe
\
htmlelement
-p
app
.
mpr
# every .mpk in widgets/
# becomes usable + a skill
mxcli
widget
init
-p
app
.
mpr
Properties, types, defaults, editor
rules, child slots — and a ready-to-run
MDL example.
describe
widget
type
htmlelement
;
MDL
htmlelement
frame
(
tagName
:
'div'
,
tagContentMode
:
'container'
)
{
attribute
a1
(
attributeName
:
'data-testid'
)
tagcontentcontainer
body
{
dynamictext
t
(
Content
:
'Hi'
)
}
}
Name a widget by the last part of its
id; repeated items are blocks, not
values.
MDL-WIDGET25
unknown widget + suggestions
MDL-WIDGET26
unknown container
MDL-WIDGET27
list given as a value
MDL-WIDGET30
child has nowhere to go
mxcli check script.mdl -p app.mpr
Build your own: the create-custom-widget skill scaffolds a React/TypeScript widget and packs the .mpk.
CE0463 after a widget upgrade?
mxcli fix widgets -p app.mpr
resyncs definitions, keeps MPR v2
16 Marketplace modules & widgets
16 · MARKETPLACE
Marketplace modules & widgets
search
versions
install
diff
update
new module or widget
later: a newer version
shell
mxcli
auth
login
# Mendix PAT, once
mxcli
marketplace
search
'excel'
mxcli
marketplace
versions
2
3
5
1
3
--min-mendix
1
0
.
2
4
.
0
mxcli
marketplace
install
2
3
5
1
3
-p
app
.
mpr
mxcli
marketplace
diff
2
3
5
1
3
-p
app
.
mpr
--to
4
.
5
.
0
mxcli
marketplace
update
2
3
5
1
3
-p
app
.
mpr
--to
4
.
5
.
0
\
--save-edits
.
/
local
-edits
content id, not the name
23513 installs Administration
latest ≠ right
newer releases may need a newer Mendix
keeps GUIDs & grants
update refuses over local edits
stays MPR v2
widgets land in widgets/
AFTER AN INSTALL OR UPDATE
mxcli fix widgets
mxcli fix design-properties
update security <Module>
mxcli docker check
17 Logs, debugger & OpenTelemetry
17 · RUNTIME INSIGHT
Logs, debugger & OpenTelemetry
logs
mxcli
log
list
--filter
Conn
mxcli
log
set
\
ConnectionBus_Queries
=
TRACE
levels NONE … TRACE · runtime.log in .mxcli/
debugger
mxcli
debug
enable
mxcli
debug
break
M
.
ACT_Save
\
--activity
'#3'
\
--if
'$Order/Total > 100'
mxcli
debug
paused
mxcli
debug
inspect
$Order
mxcli
debug
step
over
mxcli
debug
disable
pauses real requests — always disable
telemetry
mxcli
run
--local
-p
app
.
mpr
\
--metrics
\
--trace-otlp
\
http
:
/
/
1
2
7
.
0
.
0
.
1
:
4
3
1
8
Prometheus at :8090/prometheus · OpenTelemetry
spans to any OTLP collector
trace · ACT_Order_Submit
ACT_Order_Submit 412 ms
retrieve
call REST 290 ms
HTTP POST
--trace-otlp keeps timestamps + parents
The analyze-runtime skill lets the agent ask “why?”
errors from logs · load from metrics · time from traces · model shape from
CATALOG.* — then fix the MDL and run again
18 Working alongside Studio Pro
18 · COLLABORATION
Working alongside Studio Pro
1
One editor at a time
mxcli refuses to write while
App.mpr.lock exists. Close the
project in Studio Pro, run mxcli,
reopen. (exec --force: stale lock)
2
Branches live on Team Server
Create them in Studio Pro, or
git switch -c b && git push -u
origin b. A local-only branch
crashes Studio Pro.
3
Commits need metadata
Studio Pro reads a git note
(refs/notes/mx_metadata) on
every commit. mxcli git note
writes it for yours.
after an mxcli change
mxcli
fix
hashes
-p
app
.
mpr
# MPR v2 index ok?
git
add
App
.
mpr
mprcontents
&
&
git
commit
-m
'…'
mxcli
git
note
-p
app
.
mpr
--write
# mx_metadata note
git
push
origin
feature
refs
/
notes
/
mx_metadata
Push the notes ref straight away: Studio Pro's background fetch replaces unpushed notes. Merge in Studio
Pro, never git merge/rebase model history.
Or edit live, with it open
mxcli --mcp http://localhost/mcp \
--mcp-dial localhost:7782 -c '…'
Writes go to Studio Pro's model,
unsaved until you save there.
skill: live-edit-with-studio-pro
skill: teamserver-git
Slides
−
+
Fit
Poster