CLI Getting Started

The maplibre-yaml CLI provides command-line tools for validating and previewing your YAML map configurations. It helps catch errors early and enables rapid development with hot reload.

Installation

Global Installation

Install the CLI globally to use it anywhere:

npm install -g @maplibre-yaml/cli

Or with pnpm:

pnpm add -g @maplibre-yaml/cli

Using npx

You can use the CLI without installing it:

npx @maplibre-yaml/cli <command>

Short Alias

The CLI provides a shorter mlym alias:

mlym validate config.yaml

Validate Configuration

Validate your YAML configuration files to catch errors before runtime.

Basic Validation

Validate a single file:

maplibre-yaml validate my-map.yaml

Output for valid configuration:

✓ my-map.yaml

✓ 1 file(s) valid

Output for invalid configuration:

✗ my-map.yaml
  error config: Expected object, got undefined

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

Glob Patterns

Validate multiple files using glob patterns:

# Validate all YAML files in a directory
maplibre-yaml validate "configs/**/*.yaml"

# Validate specific patterns
maplibre-yaml validate "maps/*.yaml"

# Multiple patterns
maplibre-yaml validate "src/**/*.map.yaml" "configs/*.yaml"

Output with progress indicator (for >10 files):

Validating [████████████████████] 100% (25/25)
✓ Validated 25 files

✓ 23 file(s) valid
✗ 2 file(s) with issues: 3 error(s)

Output Formats

Choose from multiple output formats:

Human-Readable (default)

maplibre-yaml validate my-map.yaml

JSON for CI/CD

Get structured JSON output:

maplibre-yaml validate my-map.yaml --format json

Output:

{
  "valid": true,
  "files": [
    {
      "file": "my-map.yaml",
      "valid": true,
      "errors": [],
      "warnings": []
    }
  ],
  "summary": {
    "total": 1,
    "valid": 1,
    "invalid": 0,
    "errorCount": 0,
    "warningCount": 0
  }
}

SARIF for GitHub Code Scanning

Generate SARIF format for GitHub Advanced Security:

maplibre-yaml validate my-map.yaml --format sarif

VSCode Problem Matcher

Output format compatible with VSCode’s Problem Matcher:

maplibre-yaml validate my-map.yaml --format vscode

Output:

/path/to/config.yaml:5:10: error: [config.center] Expected array, got string
/path/to/config.yaml:12:3: warning: [layers[0]] Deprecated property

See VSCode Integration for setup instructions.

Watch Mode

Continuously validate files as they change:

maplibre-yaml validate "configs/**/*.yaml" --watch

Features:

• Intelligent Caching: Only re-validates changed files
• Fast: Cached validations complete in less than 1ms
• Real-time Feedback: Shows errors immediately on save

Strict Mode

Treat warnings as errors:

maplibre-yaml validate my-map.yaml --strict

Exit Codes

The validate command uses specific exit codes for automation:

Code	Meaning
0	Valid configuration
1	Validation errors
2	File not found
3	Invalid YAML syntax
4	Unknown error

Performance

The CLI is highly optimized for speed:

• 100 files: Validated in ~80ms
• Single file: Validated in ~1ms
• Watch mode: Cached validations in ~1ms
• Parallel processing: Configurable concurrency (default: 10)

Example CI usage:

.github/workflows/validate.yml

name: Validate Maps
on: [push, pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npx @maplibre-yaml/cli validate "configs/**/*.yaml" --format json

GitHub Code Scanning with SARIF:

.github/workflows/code-scanning.yml

name: Code Scanning
on: [push, pull_request]
jobs:
  analyze:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npx @maplibre-yaml/cli validate "**/*.yaml" --format sarif > results.sarif
      - uses: github/codeql-action/upload-sarif@v2
        with:
          sarif_file: results.sarif

Preview Your Map

Start a local development server with hot reload to preview your map as you edit.

Basic Preview

maplibre-yaml preview my-map.yaml

This will:

• Start a Vite development server on port 3000
• Open your browser automatically
• Watch the YAML file for changes
• Reload the map when you save edits

Custom Port

Use a different port:

maplibre-yaml preview my-map.yaml --port 8080

Don’t Open Browser

Start the server without opening the browser:

maplibre-yaml preview my-map.yaml --no-open

Preview Features

The preview server includes:

• Hot Reload: Automatically refreshes when you edit the YAML file
• Error Overlay: Shows configuration errors with helpful messages
• Status Bar: Displays connection state and file path
• Live Validation: Validates configuration on every change
• MapLibre Integration: Full support for all MapLibre features

Error Handling

If your configuration has errors, the preview will show:

• A dark overlay with the error message
• Red status indicator
• Specific error details (path, line, column)
• No map render (prevents confusion)

Example error display:

Configuration Error
━━━━━━━━━━━━━━━━━
config: Expected object, got undefined

Development Workflow

1. Start the preview server:

   maplibre-yaml preview my-map.yaml

2. Edit your YAML file in your editor

3. Save the file

4. Preview automatically reloads with changes

5. Fix any errors shown in the overlay

6. Repeat!

Getting Help

Command Help

Get help for any command:

maplibre-yaml --help
maplibre-yaml validate --help
maplibre-yaml preview --help

Version

Check the installed version:

maplibre-yaml --version

Next Steps

• Command Reference - Detailed command documentation
• Examples - Sample YAML configurations
• Schema Reference - Full schema documentation