Skip to content
ezu

CLI reference

Install with cargo install ezu-cli. Every command below also accepts --verbose for per-node evaluator logs.

ezu

Section titled “ezu”
Render Ezu Style documents to PNG


Usage: ezu [OPTIONS] <COMMAND>


Commands:
  tile       Render a single z/x/y tile to PNG
  bbox       Render the tile mosaic covering a lon/lat bounding box at a fixed zoom
  tiles      Bulk-render an XYZ tile pyramid into `<out>/<z>/<x>/<y>.png`
  check      Validate an Ezu Style document without rendering — exits non-zero on parse / graph / asset errors. Suitable for CI + pre-commit hooks
  graph      Emit a Mermaid `graph LR` diagram of the style's node dependencies
  legend     Emit the style's declared legend as JSON, for a host to lay out beside the map
  translate  Translate a map-engine style (MapLibre GL) into an ezu recipe
  serve      Start the live editor + tile server at `http://127.0.0.1:8080`
  schema     Print the Ezu Style JSON Schema, gathered from the registered ops
  help       Print this message or the help of the given subcommand(s)


Options:
  -v, --verbose  Emit per-node debug logs from the graph evaluator (op name, cache hit/miss, output shape, eval duration). Overrides `RUST_LOG` for this run
  -h, --help     Print help

ezu tile

Section titled “ezu tile”
Render a single z/x/y tile to PNG


Usage: ezu tile [OPTIONS] --style <STYLE> --tile <TILE>


Options:
      --style <STYLE>
          Ezu Style JSON document — local path or http(s):// URL
  -v, --verbose
          Emit per-node debug logs from the graph evaluator (op name, cache hit/miss, output shape, eval duration). Overrides `RUST_LOG` for this run
      --assets-dir <ASSETS_DIR>
          Base directory for resolving asset `src` paths. Defaults to the style file's parent directory (or the current directory when `--style` is a URL)
      --pmtiles <PMTILES>
          PMTiles archive — local path or http(s):// URL
      --mvt <MVT>
          Templated MVT tile source containing `{z}`, `{x}`, `{y}` placeholders. Accepts an http(s):// URL or a local path template (e.g. `/tiles/{z}/{x}/{y}.pbf`)
      --overzoom-levels <OVERZOOM_LEVELS>
          When a requested tile is missing, fall back to a parent tile up to this many zoom levels up and re-project its geometry onto the requested tile (MVT "overzoom"). `0` disables [default: 4]
      --param <NAME=VALUE>
          Override a document parameter, as `name=value` (repeatable). Values are validated against the style's `params` declarations: numbers respect `min`/`max`, colors are `#rrggbb[aa]`, bools are `true`/`false`
      --tile <TILE>
          Tile coordinate as `Z/X/Y`
      --out <OUT>
          Output path. Format is sniffed from the extension (`.png` / `.webp`); use `--format` to override [default: out.png]
      --format <FORMAT>
          Output format. Defaults to whatever `--out`'s extension implies [possible values: png, webp]
  -h, --help
          Print help

ezu bbox

Section titled “ezu bbox”
Render the tile mosaic covering a lon/lat bounding box at a fixed zoom


Usage: ezu bbox [OPTIONS] --style <STYLE> --bbox <BBOX> --zoom <ZOOM>


Options:
      --style <STYLE>
          Ezu Style JSON document — local path or http(s):// URL
  -v, --verbose
          Emit per-node debug logs from the graph evaluator (op name, cache hit/miss, output shape, eval duration). Overrides `RUST_LOG` for this run
      --assets-dir <ASSETS_DIR>
          Base directory for resolving asset `src` paths. Defaults to the style file's parent directory (or the current directory when `--style` is a URL)
      --pmtiles <PMTILES>
          PMTiles archive — local path or http(s):// URL
      --mvt <MVT>
          Templated MVT tile source containing `{z}`, `{x}`, `{y}` placeholders. Accepts an http(s):// URL or a local path template (e.g. `/tiles/{z}/{x}/{y}.pbf`)
      --overzoom-levels <OVERZOOM_LEVELS>
          When a requested tile is missing, fall back to a parent tile up to this many zoom levels up and re-project its geometry onto the requested tile (MVT "overzoom"). `0` disables [default: 4]
      --param <NAME=VALUE>
          Override a document parameter, as `name=value` (repeatable). Values are validated against the style's `params` declarations: numbers respect `min`/`max`, colors are `#rrggbb[aa]`, bools are `true`/`false`
      --bbox <BBOX>
          Bounding box `min_lng,min_lat,max_lng,max_lat` (WGS84)
      --zoom <ZOOM>
          Zoom level
      --out <OUT>
          Output path. Format is sniffed from the extension (`.png` / `.webp`); use `--format` to override [default: out.png]
      --format <FORMAT>
          Output format. Defaults to whatever `--out`'s extension implies [possible values: png, webp]
  -h, --help
          Print help

ezu tiles

Section titled “ezu tiles”
Bulk-render an XYZ tile pyramid into `<out>/<z>/<x>/<y>.png`


Usage: ezu tiles [OPTIONS] --style <STYLE> --min-zoom <MIN_ZOOM> --max-zoom <MAX_ZOOM>


Options:
      --style <STYLE>
          Ezu Style JSON document — local path or http(s):// URL
  -v, --verbose
          Emit per-node debug logs from the graph evaluator (op name, cache hit/miss, output shape, eval duration). Overrides `RUST_LOG` for this run
      --assets-dir <ASSETS_DIR>
          Base directory for resolving asset `src` paths. Defaults to the style file's parent directory (or the current directory when `--style` is a URL)
      --pmtiles <PMTILES>
          PMTiles archive — local path or http(s):// URL
      --mvt <MVT>
          Templated MVT tile source containing `{z}`, `{x}`, `{y}` placeholders. Accepts an http(s):// URL or a local path template (e.g. `/tiles/{z}/{x}/{y}.pbf`)
      --overzoom-levels <OVERZOOM_LEVELS>
          When a requested tile is missing, fall back to a parent tile up to this many zoom levels up and re-project its geometry onto the requested tile (MVT "overzoom"). `0` disables [default: 4]
      --param <NAME=VALUE>
          Override a document parameter, as `name=value` (repeatable). Values are validated against the style's `params` declarations: numbers respect `min`/`max`, colors are `#rrggbb[aa]`, bools are `true`/`false`
      --bbox <BBOX>
          Bounding box `min_lng,min_lat,max_lng,max_lat` (WGS84). When omitted, every tile at each zoom is generated — at z=14 that is 268M tiles, so a bbox is strongly recommended
      --min-zoom <MIN_ZOOM>
          Minimum zoom level (inclusive)
      --max-zoom <MAX_ZOOM>
          Maximum zoom level (inclusive)
      --out <OUT>
          Output directory; tiles are written as `<out>/<z>/<x>/<y>.<ext>` (extension picked by `--format`) [default: tiles]
      --format <FORMAT>
          Output format. Defaults to PNG [default: png] [possible values: png, webp]
      --concurrency <CONCURRENCY>
          Number of tiles rendered in parallel. Defaults to the number of logical CPU cores
  -h, --help
          Print help

ezu check

Section titled “ezu check”
Validate an Ezu Style document without rendering — exits non-zero on parse / graph / asset errors. Suitable for CI + pre-commit hooks


Usage: ezu check [OPTIONS] <STYLE>


Arguments:
  <STYLE>  Ezu Style JSON document — local path or http(s):// URL


Options:
      --assets-dir <ASSETS_DIR>  Base directory for resolving relative asset `src` paths. Defaults to the style file's parent directory (or the current directory when `--style` is a URL)
  -v, --verbose                  Emit per-node debug logs from the graph evaluator (op name, cache hit/miss, output shape, eval duration). Overrides `RUST_LOG` for this run
      --no-fetch                 Skip fetching URL assets and reading local asset files — only run parse + `build_graph`. Faster and works offline; misses errors like an unreachable brush URL or a missing image file
      --json                     Write the report to stdout as JSON instead of log lines: name, version, counts, padding, attribution, and the style's params schema. Logs move to stderr so the stream stays parseable
  -h, --help                     Print help

ezu graph

Section titled “ezu graph”
Emit a Mermaid `graph LR` diagram of the style's node dependencies


Usage: ezu graph [OPTIONS] <STYLE>


Arguments:
  <STYLE>  Ezu Style JSON document — local path or http(s):// URL


Options:
      --out <OUT>  Output file. Writes to stdout when omitted
  -v, --verbose    Emit per-node debug logs from the graph evaluator (op name, cache hit/miss, output shape, eval duration). Overrides `RUST_LOG` for this run
  -h, --help       Print help

ezu legend

Section titled “ezu legend”
Emit the style's declared legend as JSON, for a host to lay out beside the map


Usage: ezu legend [OPTIONS] <STYLE>


Arguments:
  <STYLE>  Ezu Style JSON document — local path or http(s):// URL


Options:
  -v, --verbose                    Emit per-node debug logs from the graph evaluator (op name, cache hit/miss, output shape, eval duration). Overrides `RUST_LOG` for this run
      --zoom <ZOOM>                Keep only the entries that apply at this zoom. Also the zoom the swatches are drawn at, since a symbol may change with scale
      --out <OUT>                  Output file. Writes to stdout when omitted
      --pretty                     Pretty-print the emitted JSON
      --swatch-dir <SWATCH_DIR>    Draw each entry's symbol into this directory as a PNG, and add its path to that entry in the emitted JSON
      --swatch-size <SWATCH_SIZE>  Swatch size as `WIDTHxHEIGHT` (or one number for a square) [default: 48x32]
      --assets-dir <ASSETS_DIR>    Base directory for resolving relative asset `src` paths, for swatches whose symbol needs a brush, font or sprite
  -h, --help                       Print help

ezu translate

Section titled “ezu translate”
Translate a map-engine style (MapLibre GL) into an ezu recipe


Usage: ezu translate [OPTIONS] <STYLE>


Arguments:
  <STYLE>  Source map-engine style (MapLibre GL JSON) — local path or http(s):// URL


Options:
      --out <OUT>              Output file for the ezu recipe. Writes to stdout when omitted
  -v, --verbose                Emit per-node debug logs from the graph evaluator (op name, cache hit/miss, output shape, eval duration). Overrides `RUST_LOG` for this run
      --tile-size <TILE_SIZE>  Emitted `tile-size` (MapLibre uses 512) [default: 512]
      --pad <PAD>              Emitted `pad` — the margin for geometry painted wider than its own extent (a thick stroke) before the crop. Filter reach (blur, warp, mosaic, label extent) is sized by the renderer from the graph, so this is only about paint width, which an expression can decide per feature. The default covers a typical basemap's line widths [default: 16]
      --keep-hidden            Keep `visibility: none` layers in the recipe, gated off behind a `switch` (instead of dropping them)
      --font <NAME=SOURCE>     Map a MapLibre fontstack entry to a font source, as `NAME=SOURCE` (repeatable). SOURCE is an installed-font reference (`system:Helvetica`, optionally `?weight=700&style=italic`) or a font-file URL (`http(s)://…`, `file:…`, `data:…`) — e.g. `--font "Noto Sans Regular=system:Noto Sans"` or `--font "Noto Sans Regular=https://example.com/NotoSans-Regular.ttf"`. Optional: unmapped `text-font` stacks fall back to the style's `glyphs` endpoint (SDF glyph ranges); a mapping wins where present and renders from the real font
      --pretty                 Pretty-print the emitted JSON
  -h, --help                   Print help

ezu serve

Section titled “ezu serve”
Start the live editor + tile server at `http://127.0.0.1:8080`


Usage: ezu serve [OPTIONS] [STYLE]


Arguments:
  [STYLE]  Initial Ezu Style document — local path or http(s):// URL. Accepts either a positional argument (`ezu serve foo.json`) or `--style`. Positional wins when both are given


Options:
      --pmtiles <PMTILES>
          PMTiles archive — local path or http(s):// URL [env: EZU_PMTILES_URL=]
  -v, --verbose
          Emit per-node debug logs from the graph evaluator (op name, cache hit/miss, output shape, eval duration). Overrides `RUST_LOG` for this run
      --mvt <MVT>
          Templated MVT tile source (URL or path) containing `{z}`, `{x}`, `{y}` placeholders; or a `.json` TileJSON document [env: EZU_MVT_URL=]
      --style <STYLE_FLAG>
          Same as the positional `STYLE` argument; kept for back-compat and so `EZU_STYLE` still works [env: EZU_STYLE=] [default: crates/ezu/examples/styles/watercolor.json]
      --assets-dir <ASSETS_DIR>
          Base directory for resolving asset `src` paths (brushes, images). Defaults to the style file's parent directory (or the current directory when the style is a URL) [env: EZU_ASSETS=]
      --bind <BIND>
          Bind address [env: EZU_BIND=] [default: 127.0.0.1:8080]
      --overzoom-levels <OVERZOOM_LEVELS>
          When a requested tile is missing, fall back to a parent tile up to this many zoom levels up and re-project its geometry onto the requested tile (MVT "overzoom"). `0` disables [default: 4]
  -h, --help
          Print help

ezu schema

Section titled “ezu schema”
Print the Ezu Style JSON Schema, gathered from the registered ops


Usage: ezu schema [OPTIONS]


Options:
      --out <OUT>  Write to this path instead of stdout
  -v, --verbose    Emit per-node debug logs from the graph evaluator (op name, cache hit/miss, output shape, eval duration). Overrides `RUST_LOG` for this run
  -h, --help       Print help

Map renders on this site are made fromOpenStreetMap data viaProtomaps (© OpenStreetMap contributors), elevation from Re:Earth Terrain,Mapterhorn andEGM2008 (NGA), and aerial imagery from GSI Japan(© 国土地理院). The painterly styles use CC0 brushes byDavid Revoy.