Syncing with Updates

When you upgrade mxcli, the skills, lint rules and project guidance it ships may have changed. A project keeps them in step with the binary through one command, which the Claude Code bootstrap script runs on every session start:

mxcli init --sync-skills      # or: mxcli init --sync

It is quiet when everything is already current.

What Gets Refreshed

A bundled lint rule is refreshed only while its file is a version mxcli itself shipped. Once you edit it, it is yours: --sync-skills and mxcli init keep it and say so on the first sync by a new mxcli, and it no longer receives mxcli’s updates to the rule. Delete the file to take the current version back.

Moving an edited rule to a new file name works too. A bundled rule is not written while another file in .claude/lint-rules/ defines its rule ID, so the stock copy does not come back beside yours and report the same rule twice.

Prefer the options and overrides in .claude/lint-config.yaml where a rule has them (severity, options, or enabled: false to switch it off): those keep receiving the rule’s fixes.

The mxcli section of CLAUDE.md and AGENTS.md

mxcli init writes its content between two markers. Put project notes outside them — above or below — and every later sync and every re-run of mxcli init keeps them:

<!-- mxcli:begin — generated by mxcli and refreshed by 'mxcli init --sync-skills'. Edit outside these markers; anything between them is replaced. -->
# Mendix Project: MyApp
…
<!-- mxcli:end -->

## Our conventions

Invoices are immutable once sent.

A file written by an mxcli from before the markers cannot be split into mxcli’s text and yours, so the sync leaves it alone and prints a note. Run mxcli init once to adopt the markers: it regenerates the file, so move any notes you had added below the end marker afterwards.

The Version Stamp

mxcli init and every sync record the mxcli that wrote the tooling in .ai-context/mxcli-tooling.json:

{
  "version": "v0.25.0",
  "built": "2026-10-01T09:12:44Z",
  "written": "2026-10-03"
}

It is rewritten only when the version changes, so the daily session-start sync does not dirty the working tree. Commit it with the rest of the tooling.

An older binary warns. Any command that opens the project (-p) with a binary older than the stamp prints, once and on stderr, both versions and how to update. The tooling may use statements, commands or lint-rule fields the older binary does not have — mdl 1; is a parse error before it existed, and a rule reading a newer catalog field fails.

An older binary does not sync. init --sync-skills from an older binary refuses rather than rolling the skills, rules and CLAUDE.md back to what it knows. Update the binary instead. An explicit mxcli init from an older binary still runs, after the same warning.

Versions are compared only when the order is certain: two releases by number (v0.24.0 < v0.25.0), two nightlies by the date in the tag (nightly-20261002-…), a release against a nightly by build date. A dev build (v0.24.0-888-g4ba1495f2, -dirty, or no version) is never reported as older.

Binaries that predate the stamp

A binary can only check a stamp it knows to read. mxcli v0.24.0 and earlier open a project stamped by a newer mxcli without any warning. For them the guard is the bootstrap script, .claude/bootstrap-mxcli.sh, which a newer mxcli init regenerates: before it links the mxcli on PATH into the project it compares that binary’s version with the stamp, and it does not link an older one — it downloads MXCLI_TAG instead. MXCLI_TAG defaults to the release of the mxcli that generated the script (vX.Y.Z), or nightly when that was a nightly or development build. A ./mxcli older than the stamp is replaced the same way, through a temporary file, so a ./mxcli that is a symlink to the PATH binary never has the download written through it. If the download fails, the older ./mxcli is kept with a warning rather than leaving the project without a binary.

On Windows (Git Bash, MSYS2 or Cygwin) the script fetches the mxcli-windows-<arch>.exe asset and installs it, or links the PATH binary, as ./mxcli.exe. Git Bash, PowerShell and cmd can all run it as ./mxcli. A non-executable ./mxcli beside it, such as the Linux build that mxcli new leaves on Windows, is removed.

Re-running mxcli init

mxcli init regenerates everything, including the devcontainer and tool configuration files, and keeps project notes outside the CLAUDE.md / AGENTS.md markers. Use it after an upgrade that changed tool configuration; for skills, rules and guidance alone, --sync-skills is enough.

Build-Time Sync (for mxcli developers)

When building mxcli from source, make build automatically syncs all assets:

make build          # Syncs everything
make sync-skills    # Skills only
make sync-commands  # Commands only
make sync-vsix      # VS Code extension only

Checking Versions

mxcli version                          # the binary
cat .ai-context/mxcli-tooling.json     # the mxcli that wrote the project's tooling