Download, Install and Update Marketplace Content

This skill covers the full lifecycle of Mendix Marketplace content (modules and widgets) from the command line: discover → download → install → check for local edits → update. These are CLI commands, not MDL statements.

When to Use This Skill

• User wants to add a marketplace module or widget to a project
• User wants to upgrade a module that is already installed
• User asks whether a marketplace module has been edited locally, or what an upgrade would overwrite
• User asks to download a specific .mpk (e.g. for CI, or to import in Studio Pro)
• User asks which versions of a marketplace item are compatible with their Mendix version
• User reports CE0463 or CE6087 right after installing or updating a module

Prerequisites: Authenticate

Marketplace access needs a Mendix Personal Access Token (PAT), created at https://user-settings.mendix.com/ (Developer Settings → Personal Access Tokens).

mxcli auth login                 # interactive prompt for the PAT
mxcli auth login --token <PAT>   # non-interactive (CI)
export MENDIX_PAT=<PAT>          # or via environment
mxcli auth status                # verify it validates

Credentials are stored at ~/.mxcli/auth.json (mode 0600).

Module installs also need the mxbuild toolchain for the project's Mendix version: mxcli setup mxbuild -p app.mpr.

Step 1 — Discover

mxcli marketplace search "database connector"   # find content by name/publisher
mxcli marketplace info 2888                      # details for a content id
mxcli marketplace versions 2888                  # available versions
mxcli marketplace versions 2888 --min-mendix 10.24.0   # compatible versions only

The numeric content id (from search/info) is what every other command takes.

Search caching. The Content API has no server-side search, so the first search fetches the whole catalog (tens of seconds) and caches it under ~/.mxcli/ for 24h; later searches are instant. If the first search seems slow, it is scanning the catalog — let it finish. Pass --refresh to bypass the cache (e.g. for a brand-new module). If search returns nothing, the content may be private or listed under a different name — look it up by id with info <id> (ids come from the marketplace URL .../link/component/<id>).

The listing name is not the module name. Content 23513 is listed as "Administration module" and installs a module called Administration; "Data Widgets" installs DataWidgets. Never match a module to its marketplace listing by name — the commands below identify it by the marketplace version UUID the project records per module.

Content ids that come up often:

Content	Id	Installs module
Administration	23513	Administration
Community Commons	170	CommunityCommons
Data Widgets	116540	DataWidgets
Atlas Core	117187	Atlas_Core (theme module)
Atlas Web Content	117183	Atlas_Web_Content (theme module)

Step 2 — Download a .mpk to disk (optional)

mxcli marketplace download 2888                              # latest, CDN filename
mxcli marketplace download 2888 --version 7.0.2 -o dbc.mpk   # specific version + path

Use this when you only want the file (to commit to mx-modules/, or to import in Studio Pro yourself). download needs no project; install does.

Step 3 — Install into a project

mxcli marketplace install <content-id> -p app.mpr [--version X.Y.Z]

install is type-aware:

Content type	Behaviour
Widget	Copied into widgets/ (overwrites on update).
Module (new)	Copied in with mxcli's own writer — every unit, plus everything else the package ships (widgets/, themesource/, javasource/, ...). Preserves the project's storage format, and works for theme modules.
Module (already present)	Reported, not modified. Use marketplace update (step 5).
Theme / Starter App / Sample	Downloaded with import instructions (import via Studio Pro).

Measured: CommunityCommons 11.5.1 into a vanilla 11.12.1 app — 128 units and 126 bundled files, mprcontents/ grew from 369 to 497 .mxunit files, mx check reports 0 errors.

Do not use mx module-import

mx module-import rewrites an MPR v2 project as v1: one import turned a 69 KB .mpr plus 341 .mxunit files into a single 14 MB SQLite blob with no mprcontents/ (measured on 11.12.1 and again on 11.13.0). The conversion is one-way — mx convert targets Mendix versions, not storage formats — and it takes mxcli diff-local, per-document git diffs and mergeability with it. mx module-import also refuses theme modules outright ("Importing theme module is not supported").

install therefore copies the units itself. --allow-format-change selects the legacy module-import path; without it, that path refuses to run on a v2 project rather than converting silently.

The latest version is usually NOT the one to install

New releases are published against the newest Studio Pro patch within days of it shipping, and install with no --version resolves to the latest. On any project that is not on the very newest patch, the default is therefore routinely the one version that cannot be installed. Measured 2026-08-12 on an 11.12.1 project: the latest release of all six agent-stack modules required 11.12.2, published five days earlier.

install and update refuse it up front and name the version to use instead:

Agent Commons 4.2.0 requires Mendix 11.12.2, and the project is 11.12.1
  hint: install --version 4.1.0 (the newest release built for 11.12.1 or older)

Run mxcli marketplace versions <id> first and read the MIN MENDIX column, or just act on the refusal.

Dependencies are not resolved

install installs exactly the content you name, and its dependencies are neither fetched nor named. Read the check errors after each install — they identify what is missing by qualified name (CommunityCommons.RandomHash, MCPClient.ConsumedMCPService), which tells you the module to add next.

The error count is not monotonic: adding a module can raise it before it falls, because a module brings its own unmet dependencies with it. Measured on a vanilla 11.12.1 app while installing the agent-editor stack: 0 → 15 → 0 → 18 → 1 → 22 → 1 → 1. A rising count is progress, not a regression.

Dependencies include widget content, not only modules — ConversationalUI needs the Markdown viewer (230248) and Events (224259) widget packages, which surface as CE0462 "Could not find widget ... in the 'widgets' directory".

Module packages bundle their own widgets — install order used to matter

A module's .mpk carries a copy of every widget its pages use, pinned to whatever its author had at release time, and different modules pin different versions of the same widget. Measured on the published packages: Atlas_Web_Content 4.3.0 ships five Data Widgets at 3.4.0 that DataWidgets 3.11.3 ships at 3.11.3.

install and update never roll a widget back: a bundled copy older than the one in the project is kept out and reported.

  Kept 5 newer widget(s) the package would have rolled back:
    widgets/com.mendix.widget.web.Datagrid.mpk — kept 3.11.3, package ships 3.4.0
    ...

Before this, updating modules in one order and then another silently downgraded widgets, and nothing surfaced it — an older widget is not a mx check error, so the app just ran old widget code. If you are on an older mxcli, check the versions by hand:

for f in widgets/*.mpk; do
  printf "%-50s %s\n" "$(basename $f)" \
    "$(unzip -p "$f" package.xml | grep -oP '<clientModule[^>]*version="\K[^"]+')"
done

Read <clientModule version>, not the <package version> on the root element — that one is the manifest schema and is 1.0 for every widget ever published.

A package that ships a widget twice (as a .mpk and as an unpacked tree — FeedbackModule 5.0.0 does) installs only the .mpk; the unpacked twin is skipped and reported.

When the installed version has been unpublished

update and diff download the installed version to establish the "has anyone edited this?" baseline, so both fail when that version is gone from the marketplace. A blank 11.13 app ships NanoflowCommons 6.0.0 and the 6.x line now starts at 6.1.1, so the module most in need of updating is exactly the one whose baseline cannot be built.

version "6.0.0" not found; run 'mxcli marketplace versions <id>' to list available versions
  The installed version is the baseline for "has anyone edited this?", so it has to be
  downloadable. It is not, and --force does not help: there is nothing to compare against.
  hint: re-run with --no-baseline to update without that check (local edits are lost silently)

--force does not help — it overrides a finding, and here there is no finding. --no-baseline accepts that the question cannot be answered and updates anyway. Commit first: local edits to that module go without being named.

Step 4 — Repair the model after the install (required, headless)

mxcli fix widgets -p app.mpr             # clears CE0463
mxcli fix design-properties -p app.mpr   # clears CE6087
mxcli docker check -p app.mpr            # confirm

A headless install leaves two things for Mendix's own tools to finish, and neither is an mxcli defect:

• CE0463 "the definition of this widget has changed" — the project's stored widget instances are older than the widget packages now sitting beside them. This is not the CE0463 that .claude/skills/diagnose-ce0463.md is about.
• CE6087 "design properties have been renamed in your theme" — a module references design properties an older Atlas spelled differently. Project-level: the location in the check output is empty, so the message alone does not say which module caused it.

A third, CE0066 "Entity access is out of date", is not left to you. The install and the update copy the incoming module's units in verbatim, so a package whose access rules do not cover every member of their entities used to land that error with nothing said about it (mendixlabs/mxcli#1085). Both now reconcile the module's rules for themselves and report the count; nothing is written when the rules already match. When the line does appear, the module's domain model now differs from the package, so marketplace diff reads it as a local edit — the same consequence Studio Pro's Update security button has. Repair it by hand, on a project updated by an older mxcli, with:

mxcli -p app.mpr -c "update security UserCommons"

Measured end to end on a vanilla 11.12.1 app carrying the agent-editor stack: mx check reported 203 errors (202 × CE0463 + 1 × CE6087) and 0 after the two commands, with the project still MPR v2 — 1,868 .mxunit files, a 249,856-byte index, before and after.

Never run the bare mx commands on an MPR v2 project

mx update-widgets and mx rename-design-properties each do the repair and rewrite the project into the single-file v1 format. Measured on 11.12.1: update-widgets took 369 .mxunit files to 0 and a 69,632-byte index to 14,405,632 bytes; rename-design-properties took 1,865 files to 0 and a 249,856-byte index to 39,895,040 bytes, while renaming 149 design properties across 41 documents. The conversion is one-way.

mxcli fix … runs the same tool, reads its result back out, restores the v2 storage, and writes the changed units into it. It reports the storage count before and after for exactly that reason — a collapse shows up there as a zero. Re-running is free: the second run reports 0 units changed (ADR-0008 elision), so the .mpr is left byte-identical.

An MPR v1 project is passed straight through, since these tools write v1 natively.

Related commands, and when each is right

Command	Persists?	Use
mxcli fix widgets	yes	the fix — after any headless install
mxcli fix design-properties	yes	the fix — after any headless install
mxcli docker check	no	runs the widget resync under a snapshot so the check is not tripped by CE0463; the stored model stays stale
mxcli widget sync	yes, partial	reconciles widget schemas in mxcli's own code; clears 7 of 40 on the reference fixture

Step 5 — Before updating: has the module been edited?

Studio Pro's Marketplace Update replaces the module and discards local edits without asking. marketplace diff answers the question that decides whether that is safe:

mxcli marketplace diff 23513 -p app.mpr                # what have I changed?
mxcli marketplace diff 23513 -p app.mpr --to 4.5.0     # ...and what would an upgrade touch?
mxcli marketplace diff 23513 -p app.mpr --json         # for a CI gate

Administration — installed 4.3.2 (Mendix 11.12.1)

  Locally modified (1 of 21 elements):
    changed   ENTITY Account

  Upgrading to 4.5.0 would touch 5 element(s), 1 of which you have modified:
    CONFLICT  ENTITY Account

Tell the user the first one is slow. Answering needs a reference project — a blank app with the published module imported — and --to needs two. Measured on Administration at 11.12.1: ~47s the first time, ~9s afterwards, once ~/.mxcli/marketplace-refs/ holds the blank app and the built references. Run diff before update rather than instead of it: the update reuses the base reference the diff just built, so the pair costs little more than the diff.

Set MXCLI_NO_REF_CACHE=1 if a result looks stale and you want to rule the cache out — it rebuilds everything without deleting the evidence.

It downloads the installed version's .mpk, imports it into a throwaway reference project built at the project's own Mendix version (a mismatch is refused, not warned about — Mendix's own conversions would otherwise read as your edits), and compares DESCRIBE output on both sides.

A "modified" verdict now means the difference is real. Some element types DESCRIBE renders imperfectly — a snippet whose body comes out { }, a building block under "Building blocks are read-only; they cannot be created via MDL" — and two imperfect renderings can differ for reasons that have nothing to do with you. Those are reported unknown, never changed, and --save-edits refuses to write them: replaying create or modify snippet X (Folder: 'Web') { } would empty the snippet.

Read verified, not just locallyModified. An element that cannot be described is reported as unknown, never as unchanged, and verified: false means "no modifications found" is not a conclusion:

  No local modifications found, but 46 of 89 elements could not be read —
  this is not a clean bill of health.

Flags: -p/--project (required), --to <version>, --module <name> (when the project records no marketplace version for it, i.e. a hand-imported copy), --json, --profile.

Step 6 — Update an installed module

# Refuses if you have edited the module, naming what it would discard
mxcli marketplace update 23513 -p app.mpr --to 4.5.0

# Park those edits as re-executable MDL, then update over them
mxcli marketplace update 23513 -p app.mpr --to 4.5.0 --save-edits ./local-edits
mxcli marketplace update 23513 -p app.mpr --to 4.5.0 --force
mxcli exec ./local-edits/entity-Account.mdl -p app.mpr

Administration updated 4.3.2 → 4.5.0
  28 units copied, 9 element identities preserved, 2 role grant(s) restored.

Flags: -p/--project, --to <version> (required), --module <name>, --save-edits <dir>, --force, --profile.

What it preserves, and why it matters

• Element identity (GUID). The runtime keys entities and attributes on the model's GUID — mendixsystem$entity.id holds it verbatim. A module whose documents are replaced without carrying the old GUIDs is a different module to the database, and its tables are dropped on the next deploy. $ID renumbering is irrelevant here; GUID is everything. This is why deleting a module and re-importing it is never a valid update.
• Role grants. A user role's grant of a module role lives in the project's security document, not the module, so removing the module takes the grants with it and putting it back does not return them.
• Everything else the package ships. Widget binaries under widgets/, styling and design-property declarations under themesource/, and so on — only project.mpr and package.xml are manifest rather than payload. DataWidgets 3.11.3 replaces 49 such files; skipping them leaves the app running old widget code and reporting CE6083 for design properties the module itself declares.

Limits — state these to the user before running it

• Local edits are not preserved. update refuses when it finds any; --save-edits writes them out first; --force proceeds. Saved files are the element's resulting state, not a diff, so replaying restores additions and changes but not removals, and an element that could not be described has nothing to save (it is reported, not skipped).
• No rollback. Work on a copy, or have the project committed to version control first.
• No dependency resolution (same as install).
• update does not run mx check itself — do step 4 afterwards.

Afterwards

mxcli fix widgets -p app.mpr             # step 4 applies to updates too
mxcli fix design-properties -p app.mpr
mxcli docker check -p app.mpr            # expect 0 errors
mxcli diff-local -p app.mpr              # review what landed, per document

Measured after the repair: Administration 4.3.2 → 4.5.0 (28 units, 9 identities, 2 grants) and DataWidgets 3.5.0 → 3.11.3 (49 files) both reach 0 errors.

Worked example: the agent-editor stack on a vanilla app

Run end-to-end on 2026-08-12 against a fresh mxcli new … --version 11.12.1 app. The modules in .claude/skills/mendix/agents must all be present before any create agent statement will build, and two of the dependencies are neither listed there nor modules.

Step	Content	Id	--version	Units	Errors after check
0	(vanilla app)	—	—	370 files	0
1	GenAI Commons	239448	7.1.1	214	15 — needs CommunityCommons
2	Community Commons	170	latest	128	0
3	Mendix Cloud GenAI Connector	239449	7.1.0	223	18 — needs Encryption
4	Encryption	1011	latest	61	1 — CE6087
5	Agent Commons	240371	4.1.0	385	22 — needs MCPClient + ConversationalUI
6	MCP Client	244893	4.1.0	82	—
7	Conversational UI	239450	7.1.0	345	22 — CE0462, missing widgets
8	Markdown viewer (widget)	230248	latest	—	—
9	Events (widget)	224259	latest	—	1 — CE6087
10	Agent Editor	257918	2.1.0	58	1 — CE6087

mxcli new MyAgentApp --version 11.12.1 && cd MyAgentApp
mxcli marketplace install 239448 --version 7.1.1 -p MyAgentApp.mpr
mxcli docker check -p MyAgentApp.mpr        # read the errors; they name what is missing
# ...repeat per row...

Then authoring works — create constant + create model + create agent executed and added 3 units, with show features in agent_documents reporting all four document types available on 11.12.1.

Four things this run established, none of them obvious from the command list:

1. Install AgentEditorCommons last — it depends transitively on the rest.
2. --version is mandatory in practice. Every agent-stack module's latest release required 11.12.2 against an 11.12.1 project.
3. Two dependencies are widgets, and two more are modules the agent skill does not list (CommunityCommons, and the widget packages). Let the check errors drive it.
4. The install leaves the model needing repair, and step 4 is not optional. A plain mx check on the finished project reported 203 errors (202 × CE0463, 1 × CE6087); mxcli fix widgets (62 units) and mxcli fix design-properties (42 units) took it to 0. The project stays MPR v2 throughout: 1,868 .mxunit files, a 249,856-byte index.

The ids are a convenience, not an authority: confirm with search/info rather than trusting them from memory, and note that the listing name never matches the module name.

Notes

• install/update/diff require -p <app.mpr>; download does not.
• All of them require mxcli auth login first; an expired or missing PAT gives an auth error with a login hint.
• Marketplace CDN TLS handshakes time out occasionally. Retry once before reporting a failure.

Platform authentication (mxcli auth login/logout/status/list) with PAT scheme for marketplace-api

Platform authentication (mxcli auth login/logout/status/list) with PAT scheme for marketplace-api.mendix.com, marketplace.mendix.com, and catalog.mendix.com; credentials stored at ~/.mxcli/auth.json (mode 0600), MENDIX_PAT env override

Marketplace download/install (mxcli marketplace download/install) — the content API now exposes a per-version downloadUrl (303→public CDN); install is type-aware (widget→widgets/, new module→mx module-import); existing-module updates are reported, not applied (entity-ID/local-edit safety — see PROPOSAL_marketplace_modules

Marketplace download/install (mxcli marketplace download/install) — the content API now exposes a per-version downloadUrl (303→public CDN); install is type-aware (widget→widgets/, new module→mx module-import); existing-module updates are reported, not applied (entity-ID/local-edit safety — see PROPOSAL_marketplace_modules.md)

Marketplace drift detection (mxcli marketplace diff <content-id> -p app.mpr [--to VERSION] [--json])

reports which elements of an installed marketplace module have been edited locally — the question Studio Pro's Marketplace update never asks before replacing the module. The version's .mpk is downloaded and imported into a throwaway reference project built at the consuming project's Mendix version (a mismatch is refused, not warned about: Mendix's own conversions would read as user edits), then every element is described on both sides and the DESCRIBE output compared — not BSON, in which an untouched module differs from its own package in ~15,000 paths. --to adds what an upgrade would touch and which of those collide with local edits. Honesty rule: an element that cannot be described is reported unknown, never unchanged, and verified:false in the JSON means "no modifications found" is not a conclusion. Module + version are identified from the module's AppStoreGuid, which is the marketplace version UUID — matching on the version number is ambiguous (a blank project has Atlas_Web_Content 4.1.0 and Administration's content also published a 4.1.0). Measured on real content: Administration 4.3.2 in a blank 11.12.1 app → 21/21 unchanged; one added attribute → exactly ENTITY Account; --to 4.3.2 (the installed version) touches nothing, which is the control for --to 4.5.0's five. Package: cmd/mxcli/marketplace/. See docs/11-proposals/PROPOSAL_marketplace_module_upgrade.md

Not Yet Implemented: