The CLI (mlym)

The maplibre-yaml CLI is a command-line tool for map documents. It creates a project, checks your YAML for mistakes, previews a map while you edit it, and exports a map to a plain MapLibre style.json. You use it on your computer and in CI; a map on a web page doesn’t need it.

You need Node.js 20.9 or later (check with node --version). Every command on this page runs through npx maplibre-yaml@latest, which downloads the CLI, so there is nothing to install. The @latest makes npx fetch the newest release instead of reusing an older copy it downloaded before. Once installed, the same program is also called mlym (below).

1. Create a project

npx maplibre-yaml@latest init my-map
cd my-map
npx serve .

init writes two files into my-map/: index.html, a page that loads maplibre-yaml from a CDN, and map.yaml, a street basemap with one point on New York. npx serve . serves the folder (npx asks once to download serve). Open the address it prints, usually http://localhost:3000, and click the blue point to open its popup.

Opening index.html by double-clicking it doesn’t work: the browser blocks a file:// page from loading map.yaml.

--template story creates a story map instead, and --template astro an Astro site ready for GitHub Pages; see init.

2. Check it for mistakes

Break map.yaml on purpose: change center: [-74.006, 40.7128] to center: -74.006, 40.7128, then run:

npx maplibre-yaml@latest validate map.yaml

✗ map.yaml
  error config.center: center needs square brackets: center: [-74.006, 40.7128]
    at line 15, column 11

✗ 1 file(s) with issues: 1 error(s)

Put the brackets back and run it again: it prints ✓ map.yaml. Besides errors, validate reports warnings, for something that is valid but probably not what you meant (a layer naming a source that isn’t declared), and notes, which explain how a valid value is read. Only errors make a file invalid, except in CI, where warnings count as errors too.

3. Preview while you edit

npx maplibre-yaml@latest preview map.yaml

This opens a browser tab at http://localhost:3000 with the map alone on the page. Each time you save map.yaml the map reloads, and a mistake shows as an overlay with the field and the message. Stop the server with Ctrl+C.

preview shows the YAML document, not your index.html. To see the map in your own page, serve the folder as in step 1.

4. Export it to style.json

npx maplibre-yaml@latest emit map.yaml --out dist/

 WARN  layers.marker.interactive: interactive — Interactions (popups, hover, highlight) are runtime behavior with no style.json form; the emitted style renders the layer without them. attachInteractions() restores them over an exported style.

 WARN  controls: controls — Controls are DOM chrome; the emitted style renders the map with MapLibre's default control set only.

✔ Wrote style to …/my-map/dist/style.json

dist/style.json is a standard MapLibre style: the basemap and your point in one file, which renders with plain maplibre-gl and no maplibre-yaml on the page. Each warning names a part of the document that a style can’t hold, here the popup and the zoom buttons. Export to style.json shows what to do with the file.

Install the CLI instead

npx maplibre-yaml@latest works everywhere. To pin the CLI’s version in a project, or to use the shorter name, install it:

# In a project: run it as `npx mlym …` or as `mlym …` in package.json scripts
npm install --save-dev @maplibre-yaml/cli

# Globally: `mlym …` works in any folder
npm install -g @maplibre-yaml/cli

The short name, `mlym`

mlym and maplibre-yaml are two names for the same installed program. mlym exists only after an install: npx mlym on its own fails with a 404, because no npm package has that name. (maplibre-yaml is a small package that runs @maplibre-yaml/cli, which is why npx maplibre-yaml@latest works without an install.)

If something goes wrong

“maplibre-yaml needs Node.js 20.9 or newer”: update Node.js; the current LTS release works.
npx mlym fails with a 404: use npx maplibre-yaml@latest, or install the CLI first (above).
A glob matches nothing: quote it, "maps/**/*.yaml", so the CLI sees the pattern rather than your shell’s expansion of it.

More in CLI commands › Troubleshooting.

Next steps

CLI commands: every option, the output formats, exit codes, the project settings file, and CI.
Editor setup: checks as you type, and validate on save in VS Code.
Your first map, explained: what each part of map.yaml does.

Moved sections

Output formats

JSON, SARIF and VS Code output: CLI commands › Output formats.