CLI Reference#

This reference is generated from the version 2 vl-convert executable used to build the documentation. Global options can appear before or after the command. Command-specific options must follow it:

vl-convert [GLOBAL OPTIONS] <COMMAND> [COMMAND OPTIONS]

Every conversion command accepts --input - and --output - for standard input and output, and uses those streams when the option is omitted. See Standard Input and Output.

Top-Level Help#

Convert Vega-Lite, Vega, and SVG files, or run the HTTP server

Usage: vl-convert [OPTIONS] <COMMAND>

Commands:
  vl2vg        Convert a Vega-Lite specification to a Vega specification
  vl2svg       Convert a Vega-Lite specification to an SVG image
  vl2png       Convert a Vega-Lite specification to a PNG image
  vl2jpeg      Convert a Vega-Lite specification to a JPEG image
  vl2pdf       Convert a Vega-Lite specification to a PDF document
  vl2url       Convert a Vega-Lite specification to a URL that opens the chart in the Vega editor
  vl2html      Convert a Vega-Lite specification to an HTML file
  vl2fonts     Return font metadata for a rendered Vega-Lite specification
  vl2sg        Convert a Vega-Lite specification to a Vega scenegraph
  vg2svg       Convert a Vega specification to an SVG image
  vg2png       Convert a Vega specification to a PNG image
  vg2jpeg      Convert a Vega specification to a JPEG image
  vg2pdf       Convert a Vega specification to a PDF document
  vg2url       Convert a Vega specification to a URL that opens the chart in the Vega editor
  vg2html      Convert a Vega specification to an HTML file
  vg2fonts     Return font metadata for a rendered Vega specification
  vg2sg        Convert a Vega specification to a Vega scenegraph
  bundle-js    Produce the JavaScript bundle used by Vega Embed integrations
  svg2png      Convert an SVG image to a PNG image
  svg2jpeg     Convert an SVG image to a JPEG image
  svg2pdf      Convert an SVG image to a PDF document
  ls-themes    List available themes
  cat-theme    Print the config JSON for a theme
  config-path  Print the default vlc-config file path
  serve        Run the HTTP conversion server
  help         Print this message or the help of the given subcommand(s)

Options:
      --vlc-config <disabled|PATH>
          Converter config: a path to a JSONC config file, or the reserved value `disabled` to skip config-file loading. Relative paths resolve from the current working directory. When omitted, the platform default config path is loaded if it exists
          
          [env: VLC_CONFIG=]

      --base-url <default|disabled|URL|PATH>
          Base URL for resolving relative data and image paths. Reserved values: `default` (use vega-datasets CDN), `disabled` (relative paths error). Otherwise either a URL with scheme (`https://...`, `file://...`) or an absolute filesystem path. Relative paths are rejected
          
          [env: VLC_BASE_URL=]

      --allowed-base-urls <none|net|all|URL_PREFIX>
          Allowed base URLs for data and images. Reserved single-value shortcuts: `none` (block all), `net` (HTTP/HTTPS only, no filesystem), `all` (allow everything incl. filesystem). Otherwise a `;`-separated list of CSP-style patterns: `"https:"` (scheme), `"https://example.com/"` (prefix), `"/data/"` (absolute filesystem path). Long allowlists belong in `--vlc-config` JSONC
          
          [env: VLC_ALLOWED_BASE_URLS=]

      --google-font <GOOGLE_FONT>
          Register a font from Google Fonts. Use "Family" for all variants, or "Family:400,700italic" for specific weight/style combinations. May be specified multiple times; `;` separates entries when passed via `VLC_GOOGLE_FONT`
          
          [env: VLC_GOOGLE_FONT=]

      --google-font-variant-threshold <N>
          Maximum number of Google Font variants one conversion may load, counting configured, requested, and automatically discovered families. The conversion fails once the cap is reached; a single family may carry the total past it. `0` disables the cap
          
          [env: VLC_GOOGLE_FONT_VARIANT_THRESHOLD=]

      --auto-google-fonts[=<BOOL>]
          Automatically download missing fonts from Google Fonts (default: false)
          
          [env: VLC_AUTO_GOOGLE_FONTS=]

      --embed-local-fonts[=<BOOL>]
          Embed locally installed fonts as base64 @font-face in HTML and SVG output (default: false)
          
          [env: VLC_EMBED_LOCAL_FONTS=]

      --subset-fonts[=<BOOL>]
          Subset embedded fonts to only the characters used (default: true). Pass `=false` to embed full font files
          
          [env: VLC_SUBSET_FONTS=]

      --missing-fonts <MISSING_FONTS>
          Missing-font behavior: fallback silently, warn, or error
          
          [env: VLC_MISSING_FONTS=]
          [possible values: fallback, warn, error]

      --max-v8-heap-size-mb <MAX_V8_HEAP_SIZE_MB>
          Maximum V8 heap size per worker in megabytes, at least 64 [default: 0 = no limit]
          
          [env: VLC_MAX_V8_HEAP_SIZE_MB=]

      --max-v8-execution-time-secs <MAX_V8_EXECUTION_TIME_SECS>
          Maximum V8 execution time in seconds [default: 0 = no limit]
          
          [env: VLC_MAX_V8_EXECUTION_TIME_SECS=]

      --gc-after-conversion[=<BOOL>]
          Run V8 garbage collection after each conversion to release memory (default: false)
          
          [env: VLC_GC_AFTER_CONVERSION=]

      --vega-plugin <path|URL>
          Vega plugin: file path (`.js`/`.mjs`) or URL (`https://...`). The plugin must be a single ESM module that exports a default function accepting a vega object. Multi-file plugins should be pre-bundled with esbuild or Rollup. URL plugins auto-allow their domain for imports. May be specified multiple times; plugins execute in order. Put inline ESM plugins in `--vlc-config`
          
          [env: VLC_VEGA_PLUGIN=]

      --plugin-import-domains <PLUGIN_IMPORT_DOMAINS>
          Domains allowed for HTTP imports in plugins, `;`-separated. Examples: `'*'` (any), `'esm.sh'`, `'*.jsdelivr.net'`. May be specified multiple times
          
          [env: VLC_PLUGIN_IMPORT_DOMAINS=]

      --font-dir <PATH>
          Additional directory to search for fonts. Repeat the flag to register multiple directories (`--font-dir /a --font-dir /b`). The combined list is registered when the process starts
          
          [env: VLC_FONT_DIR=]

      --google-fonts-cache-size-mb <MB>
          Capacity of the on-disk Google Fonts cache, in megabytes. `0` uses the default capacity of 512 MB
          
          [env: VLC_GOOGLE_FONTS_CACHE_SIZE_MB=]

      --default-theme <THEME|null>
          Default Vega-Lite theme applied when a request omits `theme`. Pass the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_THEME=]

      --default-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_FORMAT_LOCALE=]

      --default-time-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-time-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_TIME_FORMAT_LOCALE=]

      --themes <JSON|FILE.json|FILE.jsonc|null>
          Custom named themes as an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a map loaded from the `--vlc-config` file
          
          [env: VLC_THEMES=]

      --log-level <LOG_LEVEL>
          Log level for Vega/Vega-Lite messages
          
          [env: VLC_LOG_LEVEL=]
          [default: warn]
          [possible values: error, warn, info, debug]

      --log-format <LOG_FORMAT>
          Log output format. `text` is human-readable; `json` emits one structured line per event for log aggregators

          Possible values:
          - text: Human-readable text logs
          - json: Flat structured JSON logs
          
          [env: VLC_LOG_FORMAT=]
          [default: text]

      --log-filter <DIRECTIVE>
          Raw `tracing-subscriber::EnvFilter` directive (e.g. `"vl_convert=debug,tower_http=info"`). When set, this wins over `--log-level`. When unset, a directive is synthesized from `--log-level`
          
          [env: VLC_LOG_FILTER=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Vega-Lite Commands#

vl2vg#

Convert a Vega-Lite specification to a Vega specification

Usage: vl-convert vl2vg [OPTIONS]

Options:
  -i, --input <INPUT>
          Path to input Vega-Lite file. Reads from stdin if omitted or set to "-"

      --vlc-config <disabled|PATH>
          Converter config: a path to a JSONC config file, or the reserved value `disabled` to skip config-file loading. Relative paths resolve from the current working directory. When omitted, the platform default config path is loaded if it exists
          
          [env: VLC_CONFIG=]

      --base-url <default|disabled|URL|PATH>
          Base URL for resolving relative data and image paths. Reserved values: `default` (use vega-datasets CDN), `disabled` (relative paths error). Otherwise either a URL with scheme (`https://...`, `file://...`) or an absolute filesystem path. Relative paths are rejected
          
          [env: VLC_BASE_URL=]

  -o, --output <OUTPUT>
          Path to output Vega file to be created. Writes to stdout if omitted or set to "-"

      --allowed-base-urls <none|net|all|URL_PREFIX>
          Allowed base URLs for data and images. Reserved single-value shortcuts: `none` (block all), `net` (HTTP/HTTPS only, no filesystem), `all` (allow everything incl. filesystem). Otherwise a `;`-separated list of CSP-style patterns: `"https:"` (scheme), `"https://example.com/"` (prefix), `"/data/"` (absolute filesystem path). Long allowlists belong in `--vlc-config` JSONC
          
          [env: VLC_ALLOWED_BASE_URLS=]

  -v, --vl-version <VL_VERSION>
          Vega-Lite version. One of 5.8, 5.14, 5.15, 5.16, 5.17, 5.20, 5.21, 6.1, 6.4
          
          [default: 6.4]

      --google-font <GOOGLE_FONT>
          Register a font from Google Fonts. Use "Family" for all variants, or "Family:400,700italic" for specific weight/style combinations. May be specified multiple times; `;` separates entries when passed via `VLC_GOOGLE_FONT`
          
          [env: VLC_GOOGLE_FONT=]

  -t, --theme <THEME>
          Named theme provided by the vega-themes package (e.g. "dark")

  -c, --config <CONFIG>
          Path to Vega-Lite config file

      --google-font-variant-threshold <N>
          Maximum number of Google Font variants one conversion may load, counting configured, requested, and automatically discovered families. The conversion fails once the cap is reached; a single family may carry the total past it. `0` disables the cap
          
          [env: VLC_GOOGLE_FONT_VARIANT_THRESHOLD=]

      --auto-google-fonts[=<BOOL>]
          Automatically download missing fonts from Google Fonts (default: false)
          
          [env: VLC_AUTO_GOOGLE_FONTS=]

  -p, --pretty
          Pretty-print JSON in output file

      --embed-local-fonts[=<BOOL>]
          Embed locally installed fonts as base64 @font-face in HTML and SVG output (default: false)
          
          [env: VLC_EMBED_LOCAL_FONTS=]

      --width <WIDTH>
          Override the chart width

      --height <HEIGHT>
          Override the chart height

      --subset-fonts[=<BOOL>]
          Subset embedded fonts to only the characters used (default: true). Pass `=false` to embed full font files
          
          [env: VLC_SUBSET_FONTS=]

      --background <BACKGROUND>
          Override the chart background

      --missing-fonts <MISSING_FONTS>
          Missing-font behavior: fallback silently, warn, or error
          
          [env: VLC_MISSING_FONTS=]
          [possible values: fallback, warn, error]

      --max-v8-heap-size-mb <MAX_V8_HEAP_SIZE_MB>
          Maximum V8 heap size per worker in megabytes, at least 64 [default: 0 = no limit]
          
          [env: VLC_MAX_V8_HEAP_SIZE_MB=]

      --max-v8-execution-time-secs <MAX_V8_EXECUTION_TIME_SECS>
          Maximum V8 execution time in seconds [default: 0 = no limit]
          
          [env: VLC_MAX_V8_EXECUTION_TIME_SECS=]

      --gc-after-conversion[=<BOOL>]
          Run V8 garbage collection after each conversion to release memory (default: false)
          
          [env: VLC_GC_AFTER_CONVERSION=]

      --vega-plugin <path|URL>
          Vega plugin: file path (`.js`/`.mjs`) or URL (`https://...`). The plugin must be a single ESM module that exports a default function accepting a vega object. Multi-file plugins should be pre-bundled with esbuild or Rollup. URL plugins auto-allow their domain for imports. May be specified multiple times; plugins execute in order. Put inline ESM plugins in `--vlc-config`
          
          [env: VLC_VEGA_PLUGIN=]

      --plugin-import-domains <PLUGIN_IMPORT_DOMAINS>
          Domains allowed for HTTP imports in plugins, `;`-separated. Examples: `'*'` (any), `'esm.sh'`, `'*.jsdelivr.net'`. May be specified multiple times
          
          [env: VLC_PLUGIN_IMPORT_DOMAINS=]

      --font-dir <PATH>
          Additional directory to search for fonts. Repeat the flag to register multiple directories (`--font-dir /a --font-dir /b`). The combined list is registered when the process starts
          
          [env: VLC_FONT_DIR=]

      --google-fonts-cache-size-mb <MB>
          Capacity of the on-disk Google Fonts cache, in megabytes. `0` uses the default capacity of 512 MB
          
          [env: VLC_GOOGLE_FONTS_CACHE_SIZE_MB=]

      --default-theme <THEME|null>
          Default Vega-Lite theme applied when a request omits `theme`. Pass the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_THEME=]

      --default-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_FORMAT_LOCALE=]

      --default-time-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-time-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_TIME_FORMAT_LOCALE=]

      --themes <JSON|FILE.json|FILE.jsonc|null>
          Custom named themes as an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a map loaded from the `--vlc-config` file
          
          [env: VLC_THEMES=]

      --log-level <LOG_LEVEL>
          Log level for Vega/Vega-Lite messages
          
          [env: VLC_LOG_LEVEL=]
          [default: warn]
          [possible values: error, warn, info, debug]

      --log-format <LOG_FORMAT>
          Log output format. `text` is human-readable; `json` emits one structured line per event for log aggregators

          Possible values:
          - text: Human-readable text logs
          - json: Flat structured JSON logs
          
          [env: VLC_LOG_FORMAT=]
          [default: text]

      --log-filter <DIRECTIVE>
          Raw `tracing-subscriber::EnvFilter` directive (e.g. `"vl_convert=debug,tower_http=info"`). When set, this wins over `--log-level`. When unset, a directive is synthesized from `--log-level`
          
          [env: VLC_LOG_FILTER=]

  -h, --help
          Print help (see a summary with '-h')

vl2svg#

Convert a Vega-Lite specification to an SVG image

Usage: vl-convert vl2svg [OPTIONS]

Options:
  -i, --input <INPUT>
          Path to input Vega-Lite file. Reads from stdin if omitted or set to "-"

      --vlc-config <disabled|PATH>
          Converter config: a path to a JSONC config file, or the reserved value `disabled` to skip config-file loading. Relative paths resolve from the current working directory. When omitted, the platform default config path is loaded if it exists
          
          [env: VLC_CONFIG=]

      --base-url <default|disabled|URL|PATH>
          Base URL for resolving relative data and image paths. Reserved values: `default` (use vega-datasets CDN), `disabled` (relative paths error). Otherwise either a URL with scheme (`https://...`, `file://...`) or an absolute filesystem path. Relative paths are rejected
          
          [env: VLC_BASE_URL=]

  -o, --output <OUTPUT>
          Path to output SVG file to be created. Writes to stdout if omitted or set to "-"

      --allowed-base-urls <none|net|all|URL_PREFIX>
          Allowed base URLs for data and images. Reserved single-value shortcuts: `none` (block all), `net` (HTTP/HTTPS only, no filesystem), `all` (allow everything incl. filesystem). Otherwise a `;`-separated list of CSP-style patterns: `"https:"` (scheme), `"https://example.com/"` (prefix), `"/data/"` (absolute filesystem path). Long allowlists belong in `--vlc-config` JSONC
          
          [env: VLC_ALLOWED_BASE_URLS=]

  -v, --vl-version <VL_VERSION>
          Vega-Lite version. One of 5.8, 5.14, 5.15, 5.16, 5.17, 5.20, 5.21, 6.1, 6.4
          
          [default: 6.4]

      --google-font <GOOGLE_FONT>
          Register a font from Google Fonts. Use "Family" for all variants, or "Family:400,700italic" for specific weight/style combinations. May be specified multiple times; `;` separates entries when passed via `VLC_GOOGLE_FONT`
          
          [env: VLC_GOOGLE_FONT=]

      --theme <THEME>
          Named theme provided by the vega-themes package (e.g. "dark")

  -c, --config <CONFIG>
          Path to Vega-Lite config file

      --google-font-variant-threshold <N>
          Maximum number of Google Font variants one conversion may load, counting configured, requested, and automatically discovered families. The conversion fails once the cap is reached; a single family may carry the total past it. `0` disables the cap
          
          [env: VLC_GOOGLE_FONT_VARIANT_THRESHOLD=]

      --auto-google-fonts[=<BOOL>]
          Automatically download missing fonts from Google Fonts (default: false)
          
          [env: VLC_AUTO_GOOGLE_FONTS=]

      --format-locale <FORMAT_LOCALE>
          d3-format locale name, inline JSON, or .json/.jsonc file

      --embed-local-fonts[=<BOOL>]
          Embed locally installed fonts as base64 @font-face in HTML and SVG output (default: false)
          
          [env: VLC_EMBED_LOCAL_FONTS=]

      --time-format-locale <TIME_FORMAT_LOCALE>
          d3-time-format locale name, inline JSON, or .json/.jsonc file

      --bundle
          Bundle fonts and images into a self-contained SVG

      --subset-fonts[=<BOOL>]
          Subset embedded fonts to only the characters used (default: true). Pass `=false` to embed full font files
          
          [env: VLC_SUBSET_FONTS=]

      --missing-fonts <MISSING_FONTS>
          Missing-font behavior: fallback silently, warn, or error
          
          [env: VLC_MISSING_FONTS=]
          [possible values: fallback, warn, error]

      --width <WIDTH>
          Override the chart width

      --height <HEIGHT>
          Override the chart height

      --max-v8-heap-size-mb <MAX_V8_HEAP_SIZE_MB>
          Maximum V8 heap size per worker in megabytes, at least 64 [default: 0 = no limit]
          
          [env: VLC_MAX_V8_HEAP_SIZE_MB=]

      --background <BACKGROUND>
          Override the chart background

      --max-v8-execution-time-secs <MAX_V8_EXECUTION_TIME_SECS>
          Maximum V8 execution time in seconds [default: 0 = no limit]
          
          [env: VLC_MAX_V8_EXECUTION_TIME_SECS=]

      --gc-after-conversion[=<BOOL>]
          Run V8 garbage collection after each conversion to release memory (default: false)
          
          [env: VLC_GC_AFTER_CONVERSION=]

      --vega-plugin <path|URL>
          Vega plugin: file path (`.js`/`.mjs`) or URL (`https://...`). The plugin must be a single ESM module that exports a default function accepting a vega object. Multi-file plugins should be pre-bundled with esbuild or Rollup. URL plugins auto-allow their domain for imports. May be specified multiple times; plugins execute in order. Put inline ESM plugins in `--vlc-config`
          
          [env: VLC_VEGA_PLUGIN=]

      --plugin-import-domains <PLUGIN_IMPORT_DOMAINS>
          Domains allowed for HTTP imports in plugins, `;`-separated. Examples: `'*'` (any), `'esm.sh'`, `'*.jsdelivr.net'`. May be specified multiple times
          
          [env: VLC_PLUGIN_IMPORT_DOMAINS=]

      --font-dir <PATH>
          Additional directory to search for fonts. Repeat the flag to register multiple directories (`--font-dir /a --font-dir /b`). The combined list is registered when the process starts
          
          [env: VLC_FONT_DIR=]

      --google-fonts-cache-size-mb <MB>
          Capacity of the on-disk Google Fonts cache, in megabytes. `0` uses the default capacity of 512 MB
          
          [env: VLC_GOOGLE_FONTS_CACHE_SIZE_MB=]

      --default-theme <THEME|null>
          Default Vega-Lite theme applied when a request omits `theme`. Pass the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_THEME=]

      --default-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_FORMAT_LOCALE=]

      --default-time-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-time-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_TIME_FORMAT_LOCALE=]

      --themes <JSON|FILE.json|FILE.jsonc|null>
          Custom named themes as an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a map loaded from the `--vlc-config` file
          
          [env: VLC_THEMES=]

      --log-level <LOG_LEVEL>
          Log level for Vega/Vega-Lite messages
          
          [env: VLC_LOG_LEVEL=]
          [default: warn]
          [possible values: error, warn, info, debug]

      --log-format <LOG_FORMAT>
          Log output format. `text` is human-readable; `json` emits one structured line per event for log aggregators

          Possible values:
          - text: Human-readable text logs
          - json: Flat structured JSON logs
          
          [env: VLC_LOG_FORMAT=]
          [default: text]

      --log-filter <DIRECTIVE>
          Raw `tracing-subscriber::EnvFilter` directive (e.g. `"vl_convert=debug,tower_http=info"`). When set, this wins over `--log-level`. When unset, a directive is synthesized from `--log-level`
          
          [env: VLC_LOG_FILTER=]

  -h, --help
          Print help (see a summary with '-h')

vl2png#

Convert a Vega-Lite specification to a PNG image

Usage: vl-convert vl2png [OPTIONS]

Options:
  -i, --input <INPUT>
          Path to input Vega-Lite file. Reads from stdin if omitted or set to "-"

      --vlc-config <disabled|PATH>
          Converter config: a path to a JSONC config file, or the reserved value `disabled` to skip config-file loading. Relative paths resolve from the current working directory. When omitted, the platform default config path is loaded if it exists
          
          [env: VLC_CONFIG=]

      --base-url <default|disabled|URL|PATH>
          Base URL for resolving relative data and image paths. Reserved values: `default` (use vega-datasets CDN), `disabled` (relative paths error). Otherwise either a URL with scheme (`https://...`, `file://...`) or an absolute filesystem path. Relative paths are rejected
          
          [env: VLC_BASE_URL=]

  -o, --output <OUTPUT>
          Path to output PNG file to be created. Writes to stdout if omitted or set to "-"

      --allowed-base-urls <none|net|all|URL_PREFIX>
          Allowed base URLs for data and images. Reserved single-value shortcuts: `none` (block all), `net` (HTTP/HTTPS only, no filesystem), `all` (allow everything incl. filesystem). Otherwise a `;`-separated list of CSP-style patterns: `"https:"` (scheme), `"https://example.com/"` (prefix), `"/data/"` (absolute filesystem path). Long allowlists belong in `--vlc-config` JSONC
          
          [env: VLC_ALLOWED_BASE_URLS=]

  -v, --vl-version <VL_VERSION>
          Vega-Lite version. One of 5.8, 5.14, 5.15, 5.16, 5.17, 5.20, 5.21, 6.1, 6.4
          
          [default: 6.4]

      --google-font <GOOGLE_FONT>
          Register a font from Google Fonts. Use "Family" for all variants, or "Family:400,700italic" for specific weight/style combinations. May be specified multiple times; `;` separates entries when passed via `VLC_GOOGLE_FONT`
          
          [env: VLC_GOOGLE_FONT=]

      --theme <THEME>
          Named theme provided by the vega-themes package (e.g. "dark")

  -c, --config <CONFIG>
          Path to Vega-Lite config file

      --google-font-variant-threshold <N>
          Maximum number of Google Font variants one conversion may load, counting configured, requested, and automatically discovered families. The conversion fails once the cap is reached; a single family may carry the total past it. `0` disables the cap
          
          [env: VLC_GOOGLE_FONT_VARIANT_THRESHOLD=]

      --auto-google-fonts[=<BOOL>]
          Automatically download missing fonts from Google Fonts (default: false)
          
          [env: VLC_AUTO_GOOGLE_FONTS=]

      --scale <SCALE>
          Image scale factor
          
          [default: 1.0]

      --embed-local-fonts[=<BOOL>]
          Embed locally installed fonts as base64 @font-face in HTML and SVG output (default: false)
          
          [env: VLC_EMBED_LOCAL_FONTS=]

  -p, --ppi <PPI>
          Pixels per inch
          
          [default: 72.0]

      --format-locale <FORMAT_LOCALE>
          d3-format locale name, inline JSON, or .json/.jsonc file

      --subset-fonts[=<BOOL>]
          Subset embedded fonts to only the characters used (default: true). Pass `=false` to embed full font files
          
          [env: VLC_SUBSET_FONTS=]

      --missing-fonts <MISSING_FONTS>
          Missing-font behavior: fallback silently, warn, or error
          
          [env: VLC_MISSING_FONTS=]
          [possible values: fallback, warn, error]

      --time-format-locale <TIME_FORMAT_LOCALE>
          d3-time-format locale name, inline JSON, or .json/.jsonc file

      --max-v8-heap-size-mb <MAX_V8_HEAP_SIZE_MB>
          Maximum V8 heap size per worker in megabytes, at least 64 [default: 0 = no limit]
          
          [env: VLC_MAX_V8_HEAP_SIZE_MB=]

      --width <WIDTH>
          Override the chart width

      --height <HEIGHT>
          Override the chart height

      --max-v8-execution-time-secs <MAX_V8_EXECUTION_TIME_SECS>
          Maximum V8 execution time in seconds [default: 0 = no limit]
          
          [env: VLC_MAX_V8_EXECUTION_TIME_SECS=]

      --background <BACKGROUND>
          Override the chart background

      --gc-after-conversion[=<BOOL>]
          Run V8 garbage collection after each conversion to release memory (default: false)
          
          [env: VLC_GC_AFTER_CONVERSION=]

      --vega-plugin <path|URL>
          Vega plugin: file path (`.js`/`.mjs`) or URL (`https://...`). The plugin must be a single ESM module that exports a default function accepting a vega object. Multi-file plugins should be pre-bundled with esbuild or Rollup. URL plugins auto-allow their domain for imports. May be specified multiple times; plugins execute in order. Put inline ESM plugins in `--vlc-config`
          
          [env: VLC_VEGA_PLUGIN=]

      --plugin-import-domains <PLUGIN_IMPORT_DOMAINS>
          Domains allowed for HTTP imports in plugins, `;`-separated. Examples: `'*'` (any), `'esm.sh'`, `'*.jsdelivr.net'`. May be specified multiple times
          
          [env: VLC_PLUGIN_IMPORT_DOMAINS=]

      --font-dir <PATH>
          Additional directory to search for fonts. Repeat the flag to register multiple directories (`--font-dir /a --font-dir /b`). The combined list is registered when the process starts
          
          [env: VLC_FONT_DIR=]

      --google-fonts-cache-size-mb <MB>
          Capacity of the on-disk Google Fonts cache, in megabytes. `0` uses the default capacity of 512 MB
          
          [env: VLC_GOOGLE_FONTS_CACHE_SIZE_MB=]

      --default-theme <THEME|null>
          Default Vega-Lite theme applied when a request omits `theme`. Pass the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_THEME=]

      --default-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_FORMAT_LOCALE=]

      --default-time-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-time-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_TIME_FORMAT_LOCALE=]

      --themes <JSON|FILE.json|FILE.jsonc|null>
          Custom named themes as an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a map loaded from the `--vlc-config` file
          
          [env: VLC_THEMES=]

      --log-level <LOG_LEVEL>
          Log level for Vega/Vega-Lite messages
          
          [env: VLC_LOG_LEVEL=]
          [default: warn]
          [possible values: error, warn, info, debug]

      --log-format <LOG_FORMAT>
          Log output format. `text` is human-readable; `json` emits one structured line per event for log aggregators

          Possible values:
          - text: Human-readable text logs
          - json: Flat structured JSON logs
          
          [env: VLC_LOG_FORMAT=]
          [default: text]

      --log-filter <DIRECTIVE>
          Raw `tracing-subscriber::EnvFilter` directive (e.g. `"vl_convert=debug,tower_http=info"`). When set, this wins over `--log-level`. When unset, a directive is synthesized from `--log-level`
          
          [env: VLC_LOG_FILTER=]

  -h, --help
          Print help (see a summary with '-h')

vl2jpeg#

Convert a Vega-Lite specification to a JPEG image

Usage: vl-convert vl2jpeg [OPTIONS]

Options:
  -i, --input <INPUT>
          Path to input Vega-Lite file. Reads from stdin if omitted or set to "-"

      --vlc-config <disabled|PATH>
          Converter config: a path to a JSONC config file, or the reserved value `disabled` to skip config-file loading. Relative paths resolve from the current working directory. When omitted, the platform default config path is loaded if it exists
          
          [env: VLC_CONFIG=]

      --base-url <default|disabled|URL|PATH>
          Base URL for resolving relative data and image paths. Reserved values: `default` (use vega-datasets CDN), `disabled` (relative paths error). Otherwise either a URL with scheme (`https://...`, `file://...`) or an absolute filesystem path. Relative paths are rejected
          
          [env: VLC_BASE_URL=]

  -o, --output <OUTPUT>
          Path to output JPEG file to be created. Writes to stdout if omitted or set to "-"

      --allowed-base-urls <none|net|all|URL_PREFIX>
          Allowed base URLs for data and images. Reserved single-value shortcuts: `none` (block all), `net` (HTTP/HTTPS only, no filesystem), `all` (allow everything incl. filesystem). Otherwise a `;`-separated list of CSP-style patterns: `"https:"` (scheme), `"https://example.com/"` (prefix), `"/data/"` (absolute filesystem path). Long allowlists belong in `--vlc-config` JSONC
          
          [env: VLC_ALLOWED_BASE_URLS=]

  -v, --vl-version <VL_VERSION>
          Vega-Lite version. One of 5.8, 5.14, 5.15, 5.16, 5.17, 5.20, 5.21, 6.1, 6.4
          
          [default: 6.4]

      --google-font <GOOGLE_FONT>
          Register a font from Google Fonts. Use "Family" for all variants, or "Family:400,700italic" for specific weight/style combinations. May be specified multiple times; `;` separates entries when passed via `VLC_GOOGLE_FONT`
          
          [env: VLC_GOOGLE_FONT=]

      --theme <THEME>
          Named theme provided by the vega-themes package (e.g. "dark")

  -c, --config <CONFIG>
          Path to Vega-Lite config file

      --google-font-variant-threshold <N>
          Maximum number of Google Font variants one conversion may load, counting configured, requested, and automatically discovered families. The conversion fails once the cap is reached; a single family may carry the total past it. `0` disables the cap
          
          [env: VLC_GOOGLE_FONT_VARIANT_THRESHOLD=]

      --auto-google-fonts[=<BOOL>]
          Automatically download missing fonts from Google Fonts (default: false)
          
          [env: VLC_AUTO_GOOGLE_FONTS=]

      --scale <SCALE>
          Image scale factor
          
          [default: 1.0]

      --embed-local-fonts[=<BOOL>]
          Embed locally installed fonts as base64 @font-face in HTML and SVG output (default: false)
          
          [env: VLC_EMBED_LOCAL_FONTS=]

  -q, --quality <QUALITY>
          JPEG quality between 0 (worst) and 100 (best)
          
          [default: 90]

      --format-locale <FORMAT_LOCALE>
          d3-format locale name, inline JSON, or .json/.jsonc file

      --subset-fonts[=<BOOL>]
          Subset embedded fonts to only the characters used (default: true). Pass `=false` to embed full font files
          
          [env: VLC_SUBSET_FONTS=]

      --missing-fonts <MISSING_FONTS>
          Missing-font behavior: fallback silently, warn, or error
          
          [env: VLC_MISSING_FONTS=]
          [possible values: fallback, warn, error]

      --time-format-locale <TIME_FORMAT_LOCALE>
          d3-time-format locale name, inline JSON, or .json/.jsonc file

      --max-v8-heap-size-mb <MAX_V8_HEAP_SIZE_MB>
          Maximum V8 heap size per worker in megabytes, at least 64 [default: 0 = no limit]
          
          [env: VLC_MAX_V8_HEAP_SIZE_MB=]

      --width <WIDTH>
          Override the chart width

      --height <HEIGHT>
          Override the chart height

      --max-v8-execution-time-secs <MAX_V8_EXECUTION_TIME_SECS>
          Maximum V8 execution time in seconds [default: 0 = no limit]
          
          [env: VLC_MAX_V8_EXECUTION_TIME_SECS=]

      --background <BACKGROUND>
          Override the chart background

      --gc-after-conversion[=<BOOL>]
          Run V8 garbage collection after each conversion to release memory (default: false)
          
          [env: VLC_GC_AFTER_CONVERSION=]

      --vega-plugin <path|URL>
          Vega plugin: file path (`.js`/`.mjs`) or URL (`https://...`). The plugin must be a single ESM module that exports a default function accepting a vega object. Multi-file plugins should be pre-bundled with esbuild or Rollup. URL plugins auto-allow their domain for imports. May be specified multiple times; plugins execute in order. Put inline ESM plugins in `--vlc-config`
          
          [env: VLC_VEGA_PLUGIN=]

      --plugin-import-domains <PLUGIN_IMPORT_DOMAINS>
          Domains allowed for HTTP imports in plugins, `;`-separated. Examples: `'*'` (any), `'esm.sh'`, `'*.jsdelivr.net'`. May be specified multiple times
          
          [env: VLC_PLUGIN_IMPORT_DOMAINS=]

      --font-dir <PATH>
          Additional directory to search for fonts. Repeat the flag to register multiple directories (`--font-dir /a --font-dir /b`). The combined list is registered when the process starts
          
          [env: VLC_FONT_DIR=]

      --google-fonts-cache-size-mb <MB>
          Capacity of the on-disk Google Fonts cache, in megabytes. `0` uses the default capacity of 512 MB
          
          [env: VLC_GOOGLE_FONTS_CACHE_SIZE_MB=]

      --default-theme <THEME|null>
          Default Vega-Lite theme applied when a request omits `theme`. Pass the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_THEME=]

      --default-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_FORMAT_LOCALE=]

      --default-time-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-time-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_TIME_FORMAT_LOCALE=]

      --themes <JSON|FILE.json|FILE.jsonc|null>
          Custom named themes as an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a map loaded from the `--vlc-config` file
          
          [env: VLC_THEMES=]

      --log-level <LOG_LEVEL>
          Log level for Vega/Vega-Lite messages
          
          [env: VLC_LOG_LEVEL=]
          [default: warn]
          [possible values: error, warn, info, debug]

      --log-format <LOG_FORMAT>
          Log output format. `text` is human-readable; `json` emits one structured line per event for log aggregators

          Possible values:
          - text: Human-readable text logs
          - json: Flat structured JSON logs
          
          [env: VLC_LOG_FORMAT=]
          [default: text]

      --log-filter <DIRECTIVE>
          Raw `tracing-subscriber::EnvFilter` directive (e.g. `"vl_convert=debug,tower_http=info"`). When set, this wins over `--log-level`. When unset, a directive is synthesized from `--log-level`
          
          [env: VLC_LOG_FILTER=]

  -h, --help
          Print help (see a summary with '-h')

vl2pdf#

Convert a Vega-Lite specification to a PDF document

Usage: vl-convert vl2pdf [OPTIONS]

Options:
  -i, --input <INPUT>
          Path to input Vega-Lite file. Reads from stdin if omitted or set to "-"

      --vlc-config <disabled|PATH>
          Converter config: a path to a JSONC config file, or the reserved value `disabled` to skip config-file loading. Relative paths resolve from the current working directory. When omitted, the platform default config path is loaded if it exists
          
          [env: VLC_CONFIG=]

      --base-url <default|disabled|URL|PATH>
          Base URL for resolving relative data and image paths. Reserved values: `default` (use vega-datasets CDN), `disabled` (relative paths error). Otherwise either a URL with scheme (`https://...`, `file://...`) or an absolute filesystem path. Relative paths are rejected
          
          [env: VLC_BASE_URL=]

  -o, --output <OUTPUT>
          Path to output PDF file to be created. Writes to stdout if omitted or set to "-"

      --allowed-base-urls <none|net|all|URL_PREFIX>
          Allowed base URLs for data and images. Reserved single-value shortcuts: `none` (block all), `net` (HTTP/HTTPS only, no filesystem), `all` (allow everything incl. filesystem). Otherwise a `;`-separated list of CSP-style patterns: `"https:"` (scheme), `"https://example.com/"` (prefix), `"/data/"` (absolute filesystem path). Long allowlists belong in `--vlc-config` JSONC
          
          [env: VLC_ALLOWED_BASE_URLS=]

  -v, --vl-version <VL_VERSION>
          Vega-Lite version. One of 5.8, 5.14, 5.15, 5.16, 5.17, 5.20, 5.21, 6.1, 6.4
          
          [default: 6.4]

      --google-font <GOOGLE_FONT>
          Register a font from Google Fonts. Use "Family" for all variants, or "Family:400,700italic" for specific weight/style combinations. May be specified multiple times; `;` separates entries when passed via `VLC_GOOGLE_FONT`
          
          [env: VLC_GOOGLE_FONT=]

      --theme <THEME>
          Named theme provided by the vega-themes package (e.g. "dark")

  -c, --config <CONFIG>
          Path to Vega-Lite config file

      --google-font-variant-threshold <N>
          Maximum number of Google Font variants one conversion may load, counting configured, requested, and automatically discovered families. The conversion fails once the cap is reached; a single family may carry the total past it. `0` disables the cap
          
          [env: VLC_GOOGLE_FONT_VARIANT_THRESHOLD=]

      --auto-google-fonts[=<BOOL>]
          Automatically download missing fonts from Google Fonts (default: false)
          
          [env: VLC_AUTO_GOOGLE_FONTS=]

      --format-locale <FORMAT_LOCALE>
          d3-format locale name, inline JSON, or .json/.jsonc file

      --embed-local-fonts[=<BOOL>]
          Embed locally installed fonts as base64 @font-face in HTML and SVG output (default: false)
          
          [env: VLC_EMBED_LOCAL_FONTS=]

      --time-format-locale <TIME_FORMAT_LOCALE>
          d3-time-format locale name, inline JSON, or .json/.jsonc file

      --subset-fonts[=<BOOL>]
          Subset embedded fonts to only the characters used (default: true). Pass `=false` to embed full font files
          
          [env: VLC_SUBSET_FONTS=]

      --width <WIDTH>
          Override the chart width

      --height <HEIGHT>
          Override the chart height

      --missing-fonts <MISSING_FONTS>
          Missing-font behavior: fallback silently, warn, or error
          
          [env: VLC_MISSING_FONTS=]
          [possible values: fallback, warn, error]

      --background <BACKGROUND>
          Override the chart background

      --max-v8-heap-size-mb <MAX_V8_HEAP_SIZE_MB>
          Maximum V8 heap size per worker in megabytes, at least 64 [default: 0 = no limit]
          
          [env: VLC_MAX_V8_HEAP_SIZE_MB=]

      --max-v8-execution-time-secs <MAX_V8_EXECUTION_TIME_SECS>
          Maximum V8 execution time in seconds [default: 0 = no limit]
          
          [env: VLC_MAX_V8_EXECUTION_TIME_SECS=]

      --gc-after-conversion[=<BOOL>]
          Run V8 garbage collection after each conversion to release memory (default: false)
          
          [env: VLC_GC_AFTER_CONVERSION=]

      --vega-plugin <path|URL>
          Vega plugin: file path (`.js`/`.mjs`) or URL (`https://...`). The plugin must be a single ESM module that exports a default function accepting a vega object. Multi-file plugins should be pre-bundled with esbuild or Rollup. URL plugins auto-allow their domain for imports. May be specified multiple times; plugins execute in order. Put inline ESM plugins in `--vlc-config`
          
          [env: VLC_VEGA_PLUGIN=]

      --plugin-import-domains <PLUGIN_IMPORT_DOMAINS>
          Domains allowed for HTTP imports in plugins, `;`-separated. Examples: `'*'` (any), `'esm.sh'`, `'*.jsdelivr.net'`. May be specified multiple times
          
          [env: VLC_PLUGIN_IMPORT_DOMAINS=]

      --font-dir <PATH>
          Additional directory to search for fonts. Repeat the flag to register multiple directories (`--font-dir /a --font-dir /b`). The combined list is registered when the process starts
          
          [env: VLC_FONT_DIR=]

      --google-fonts-cache-size-mb <MB>
          Capacity of the on-disk Google Fonts cache, in megabytes. `0` uses the default capacity of 512 MB
          
          [env: VLC_GOOGLE_FONTS_CACHE_SIZE_MB=]

      --default-theme <THEME|null>
          Default Vega-Lite theme applied when a request omits `theme`. Pass the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_THEME=]

      --default-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_FORMAT_LOCALE=]

      --default-time-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-time-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_TIME_FORMAT_LOCALE=]

      --themes <JSON|FILE.json|FILE.jsonc|null>
          Custom named themes as an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a map loaded from the `--vlc-config` file
          
          [env: VLC_THEMES=]

      --log-level <LOG_LEVEL>
          Log level for Vega/Vega-Lite messages
          
          [env: VLC_LOG_LEVEL=]
          [default: warn]
          [possible values: error, warn, info, debug]

      --log-format <LOG_FORMAT>
          Log output format. `text` is human-readable; `json` emits one structured line per event for log aggregators

          Possible values:
          - text: Human-readable text logs
          - json: Flat structured JSON logs
          
          [env: VLC_LOG_FORMAT=]
          [default: text]

      --log-filter <DIRECTIVE>
          Raw `tracing-subscriber::EnvFilter` directive (e.g. `"vl_convert=debug,tower_http=info"`). When set, this wins over `--log-level`. When unset, a directive is synthesized from `--log-level`
          
          [env: VLC_LOG_FILTER=]

  -h, --help
          Print help (see a summary with '-h')

vl2url#

Convert a Vega-Lite specification to a URL that opens the chart in the Vega editor

Usage: vl-convert vl2url [OPTIONS]

Options:
  -i, --input <INPUT>
          Path to input Vega-Lite file. Reads from stdin if omitted or set to "-"

      --vlc-config <disabled|PATH>
          Converter config: a path to a JSONC config file, or the reserved value `disabled` to skip config-file loading. Relative paths resolve from the current working directory. When omitted, the platform default config path is loaded if it exists
          
          [env: VLC_CONFIG=]

      --base-url <default|disabled|URL|PATH>
          Base URL for resolving relative data and image paths. Reserved values: `default` (use vega-datasets CDN), `disabled` (relative paths error). Otherwise either a URL with scheme (`https://...`, `file://...`) or an absolute filesystem path. Relative paths are rejected
          
          [env: VLC_BASE_URL=]

  -o, --output <OUTPUT>
          Path to output file. Writes to stdout if omitted or set to "-"

      --allowed-base-urls <none|net|all|URL_PREFIX>
          Allowed base URLs for data and images. Reserved single-value shortcuts: `none` (block all), `net` (HTTP/HTTPS only, no filesystem), `all` (allow everything incl. filesystem). Otherwise a `;`-separated list of CSP-style patterns: `"https:"` (scheme), `"https://example.com/"` (prefix), `"/data/"` (absolute filesystem path). Long allowlists belong in `--vlc-config` JSONC
          
          [env: VLC_ALLOWED_BASE_URLS=]

      --fullscreen
          Open chart in fullscreen mode

      --google-font <GOOGLE_FONT>
          Register a font from Google Fonts. Use "Family" for all variants, or "Family:400,700italic" for specific weight/style combinations. May be specified multiple times; `;` separates entries when passed via `VLC_GOOGLE_FONT`
          
          [env: VLC_GOOGLE_FONT=]

      --google-font-variant-threshold <N>
          Maximum number of Google Font variants one conversion may load, counting configured, requested, and automatically discovered families. The conversion fails once the cap is reached; a single family may carry the total past it. `0` disables the cap
          
          [env: VLC_GOOGLE_FONT_VARIANT_THRESHOLD=]

      --auto-google-fonts[=<BOOL>]
          Automatically download missing fonts from Google Fonts (default: false)
          
          [env: VLC_AUTO_GOOGLE_FONTS=]

      --embed-local-fonts[=<BOOL>]
          Embed locally installed fonts as base64 @font-face in HTML and SVG output (default: false)
          
          [env: VLC_EMBED_LOCAL_FONTS=]

      --subset-fonts[=<BOOL>]
          Subset embedded fonts to only the characters used (default: true). Pass `=false` to embed full font files
          
          [env: VLC_SUBSET_FONTS=]

      --missing-fonts <MISSING_FONTS>
          Missing-font behavior: fallback silently, warn, or error
          
          [env: VLC_MISSING_FONTS=]
          [possible values: fallback, warn, error]

      --max-v8-heap-size-mb <MAX_V8_HEAP_SIZE_MB>
          Maximum V8 heap size per worker in megabytes, at least 64 [default: 0 = no limit]
          
          [env: VLC_MAX_V8_HEAP_SIZE_MB=]

      --max-v8-execution-time-secs <MAX_V8_EXECUTION_TIME_SECS>
          Maximum V8 execution time in seconds [default: 0 = no limit]
          
          [env: VLC_MAX_V8_EXECUTION_TIME_SECS=]

      --gc-after-conversion[=<BOOL>]
          Run V8 garbage collection after each conversion to release memory (default: false)
          
          [env: VLC_GC_AFTER_CONVERSION=]

      --vega-plugin <path|URL>
          Vega plugin: file path (`.js`/`.mjs`) or URL (`https://...`). The plugin must be a single ESM module that exports a default function accepting a vega object. Multi-file plugins should be pre-bundled with esbuild or Rollup. URL plugins auto-allow their domain for imports. May be specified multiple times; plugins execute in order. Put inline ESM plugins in `--vlc-config`
          
          [env: VLC_VEGA_PLUGIN=]

      --plugin-import-domains <PLUGIN_IMPORT_DOMAINS>
          Domains allowed for HTTP imports in plugins, `;`-separated. Examples: `'*'` (any), `'esm.sh'`, `'*.jsdelivr.net'`. May be specified multiple times
          
          [env: VLC_PLUGIN_IMPORT_DOMAINS=]

      --font-dir <PATH>
          Additional directory to search for fonts. Repeat the flag to register multiple directories (`--font-dir /a --font-dir /b`). The combined list is registered when the process starts
          
          [env: VLC_FONT_DIR=]

      --google-fonts-cache-size-mb <MB>
          Capacity of the on-disk Google Fonts cache, in megabytes. `0` uses the default capacity of 512 MB
          
          [env: VLC_GOOGLE_FONTS_CACHE_SIZE_MB=]

      --default-theme <THEME|null>
          Default Vega-Lite theme applied when a request omits `theme`. Pass the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_THEME=]

      --default-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_FORMAT_LOCALE=]

      --default-time-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-time-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_TIME_FORMAT_LOCALE=]

      --themes <JSON|FILE.json|FILE.jsonc|null>
          Custom named themes as an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a map loaded from the `--vlc-config` file
          
          [env: VLC_THEMES=]

      --log-level <LOG_LEVEL>
          Log level for Vega/Vega-Lite messages
          
          [env: VLC_LOG_LEVEL=]
          [default: warn]
          [possible values: error, warn, info, debug]

      --log-format <LOG_FORMAT>
          Log output format. `text` is human-readable; `json` emits one structured line per event for log aggregators

          Possible values:
          - text: Human-readable text logs
          - json: Flat structured JSON logs
          
          [env: VLC_LOG_FORMAT=]
          [default: text]

      --log-filter <DIRECTIVE>
          Raw `tracing-subscriber::EnvFilter` directive (e.g. `"vl_convert=debug,tower_http=info"`). When set, this wins over `--log-level`. When unset, a directive is synthesized from `--log-level`
          
          [env: VLC_LOG_FILTER=]

  -h, --help
          Print help (see a summary with '-h')

vl2html#

Convert a Vega-Lite specification to an HTML file

Usage: vl-convert vl2html [OPTIONS]

Options:
  -i, --input <INPUT>
          Path to input Vega-Lite file. Reads from stdin if omitted or set to "-"

      --vlc-config <disabled|PATH>
          Converter config: a path to a JSONC config file, or the reserved value `disabled` to skip config-file loading. Relative paths resolve from the current working directory. When omitted, the platform default config path is loaded if it exists
          
          [env: VLC_CONFIG=]

      --base-url <default|disabled|URL|PATH>
          Base URL for resolving relative data and image paths. Reserved values: `default` (use vega-datasets CDN), `disabled` (relative paths error). Otherwise either a URL with scheme (`https://...`, `file://...`) or an absolute filesystem path. Relative paths are rejected
          
          [env: VLC_BASE_URL=]

  -o, --output <OUTPUT>
          Path to output HTML file to be created. Writes to stdout if omitted or set to "-"

      --allowed-base-urls <none|net|all|URL_PREFIX>
          Allowed base URLs for data and images. Reserved single-value shortcuts: `none` (block all), `net` (HTTP/HTTPS only, no filesystem), `all` (allow everything incl. filesystem). Otherwise a `;`-separated list of CSP-style patterns: `"https:"` (scheme), `"https://example.com/"` (prefix), `"/data/"` (absolute filesystem path). Long allowlists belong in `--vlc-config` JSONC
          
          [env: VLC_ALLOWED_BASE_URLS=]

  -v, --vl-version <VL_VERSION>
          Vega-Lite version. One of 5.8, 5.14, 5.15, 5.16, 5.17, 5.20, 5.21, 6.1, 6.4
          
          [default: 6.4]

      --google-font <GOOGLE_FONT>
          Register a font from Google Fonts. Use "Family" for all variants, or "Family:400,700italic" for specific weight/style combinations. May be specified multiple times; `;` separates entries when passed via `VLC_GOOGLE_FONT`
          
          [env: VLC_GOOGLE_FONT=]

      --theme <THEME>
          Named theme provided by the vega-themes package (e.g. "dark")

  -c, --config <CONFIG>
          Path to Vega-Lite config file

      --google-font-variant-threshold <N>
          Maximum number of Google Font variants one conversion may load, counting configured, requested, and automatically discovered families. The conversion fails once the cap is reached; a single family may carry the total past it. `0` disables the cap
          
          [env: VLC_GOOGLE_FONT_VARIANT_THRESHOLD=]

      --auto-google-fonts[=<BOOL>]
          Automatically download missing fonts from Google Fonts (default: false)
          
          [env: VLC_AUTO_GOOGLE_FONTS=]

  -b, --bundle
          Whether to bundle JavaScript dependencies in the HTML file instead of loading them from a CDN

      --embed-local-fonts[=<BOOL>]
          Embed locally installed fonts as base64 @font-face in HTML and SVG output (default: false)
          
          [env: VLC_EMBED_LOCAL_FONTS=]

      --format-locale <FORMAT_LOCALE>
          d3-format locale name, inline JSON, or .json/.jsonc file

      --subset-fonts[=<BOOL>]
          Subset embedded fonts to only the characters used (default: true). Pass `=false` to embed full font files
          
          [env: VLC_SUBSET_FONTS=]

      --time-format-locale <TIME_FORMAT_LOCALE>
          d3-time-format locale name, inline JSON, or .json/.jsonc file

      --missing-fonts <MISSING_FONTS>
          Missing-font behavior: fallback silently, warn, or error
          
          [env: VLC_MISSING_FONTS=]
          [possible values: fallback, warn, error]

      --renderer <RENDERER>
          Vega renderer. One of 'svg' (default), 'canvas', or 'hybrid'

      --max-v8-heap-size-mb <MAX_V8_HEAP_SIZE_MB>
          Maximum V8 heap size per worker in megabytes, at least 64 [default: 0 = no limit]
          
          [env: VLC_MAX_V8_HEAP_SIZE_MB=]

      --width <WIDTH>
          Override the chart width

      --height <HEIGHT>
          Override the chart height

      --max-v8-execution-time-secs <MAX_V8_EXECUTION_TIME_SECS>
          Maximum V8 execution time in seconds [default: 0 = no limit]
          
          [env: VLC_MAX_V8_EXECUTION_TIME_SECS=]

      --background <BACKGROUND>
          Override the chart background

      --gc-after-conversion[=<BOOL>]
          Run V8 garbage collection after each conversion to release memory (default: false)
          
          [env: VLC_GC_AFTER_CONVERSION=]

      --vega-plugin <path|URL>
          Vega plugin: file path (`.js`/`.mjs`) or URL (`https://...`). The plugin must be a single ESM module that exports a default function accepting a vega object. Multi-file plugins should be pre-bundled with esbuild or Rollup. URL plugins auto-allow their domain for imports. May be specified multiple times; plugins execute in order. Put inline ESM plugins in `--vlc-config`
          
          [env: VLC_VEGA_PLUGIN=]

      --plugin-import-domains <PLUGIN_IMPORT_DOMAINS>
          Domains allowed for HTTP imports in plugins, `;`-separated. Examples: `'*'` (any), `'esm.sh'`, `'*.jsdelivr.net'`. May be specified multiple times
          
          [env: VLC_PLUGIN_IMPORT_DOMAINS=]

      --font-dir <PATH>
          Additional directory to search for fonts. Repeat the flag to register multiple directories (`--font-dir /a --font-dir /b`). The combined list is registered when the process starts
          
          [env: VLC_FONT_DIR=]

      --google-fonts-cache-size-mb <MB>
          Capacity of the on-disk Google Fonts cache, in megabytes. `0` uses the default capacity of 512 MB
          
          [env: VLC_GOOGLE_FONTS_CACHE_SIZE_MB=]

      --default-theme <THEME|null>
          Default Vega-Lite theme applied when a request omits `theme`. Pass the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_THEME=]

      --default-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_FORMAT_LOCALE=]

      --default-time-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-time-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_TIME_FORMAT_LOCALE=]

      --themes <JSON|FILE.json|FILE.jsonc|null>
          Custom named themes as an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a map loaded from the `--vlc-config` file
          
          [env: VLC_THEMES=]

      --log-level <LOG_LEVEL>
          Log level for Vega/Vega-Lite messages
          
          [env: VLC_LOG_LEVEL=]
          [default: warn]
          [possible values: error, warn, info, debug]

      --log-format <LOG_FORMAT>
          Log output format. `text` is human-readable; `json` emits one structured line per event for log aggregators

          Possible values:
          - text: Human-readable text logs
          - json: Flat structured JSON logs
          
          [env: VLC_LOG_FORMAT=]
          [default: text]

      --log-filter <DIRECTIVE>
          Raw `tracing-subscriber::EnvFilter` directive (e.g. `"vl_convert=debug,tower_http=info"`). When set, this wins over `--log-level`. When unset, a directive is synthesized from `--log-level`
          
          [env: VLC_LOG_FILTER=]

  -h, --help
          Print help (see a summary with '-h')

vl2fonts#

Return font metadata for a rendered Vega-Lite specification

Usage: vl-convert vl2fonts [OPTIONS]

Options:
  -i, --input <INPUT>
          Path to input Vega-Lite file. Reads from stdin if omitted or set to "-"

      --vlc-config <disabled|PATH>
          Converter config: a path to a JSONC config file, or the reserved value `disabled` to skip config-file loading. Relative paths resolve from the current working directory. When omitted, the platform default config path is loaded if it exists
          
          [env: VLC_CONFIG=]

      --base-url <default|disabled|URL|PATH>
          Base URL for resolving relative data and image paths. Reserved values: `default` (use vega-datasets CDN), `disabled` (relative paths error). Otherwise either a URL with scheme (`https://...`, `file://...`) or an absolute filesystem path. Relative paths are rejected
          
          [env: VLC_BASE_URL=]

  -o, --output <OUTPUT>
          Path to output JSON file. Writes to stdout if omitted or set to "-"

      --allowed-base-urls <none|net|all|URL_PREFIX>
          Allowed base URLs for data and images. Reserved single-value shortcuts: `none` (block all), `net` (HTTP/HTTPS only, no filesystem), `all` (allow everything incl. filesystem). Otherwise a `;`-separated list of CSP-style patterns: `"https:"` (scheme), `"https://example.com/"` (prefix), `"/data/"` (absolute filesystem path). Long allowlists belong in `--vlc-config` JSONC
          
          [env: VLC_ALLOWED_BASE_URLS=]

  -v, --vl-version <VL_VERSION>
          Vega-Lite version. One of 5.8, 5.14, 5.15, 5.16, 5.17, 5.20, 5.21, 6.1, 6.4
          
          [default: 6.4]

      --google-font <GOOGLE_FONT>
          Register a font from Google Fonts. Use "Family" for all variants, or "Family:400,700italic" for specific weight/style combinations. May be specified multiple times; `;` separates entries when passed via `VLC_GOOGLE_FONT`
          
          [env: VLC_GOOGLE_FONT=]

      --theme <THEME>
          Named theme provided by the vega-themes package (e.g. "dark")

  -c, --config <CONFIG>
          Path to Vega-Lite config file

      --google-font-variant-threshold <N>
          Maximum number of Google Font variants one conversion may load, counting configured, requested, and automatically discovered families. The conversion fails once the cap is reached; a single family may carry the total past it. `0` disables the cap
          
          [env: VLC_GOOGLE_FONT_VARIANT_THRESHOLD=]

      --auto-google-fonts[=<BOOL>]
          Automatically download missing fonts from Google Fonts (default: false)
          
          [env: VLC_AUTO_GOOGLE_FONTS=]

      --include-font-face
          Include @font-face CSS blocks in the output

      --embed-local-fonts[=<BOOL>]
          Embed locally installed fonts as base64 @font-face in HTML and SVG output (default: false)
          
          [env: VLC_EMBED_LOCAL_FONTS=]

      --format-locale <FORMAT_LOCALE>
          d3-format locale name, inline JSON, or .json/.jsonc file

      --subset-fonts[=<BOOL>]
          Subset embedded fonts to only the characters used (default: true). Pass `=false` to embed full font files
          
          [env: VLC_SUBSET_FONTS=]

      --time-format-locale <TIME_FORMAT_LOCALE>
          d3-time-format locale name, inline JSON, or .json/.jsonc file

      --missing-fonts <MISSING_FONTS>
          Missing-font behavior: fallback silently, warn, or error
          
          [env: VLC_MISSING_FONTS=]
          [possible values: fallback, warn, error]

  -p, --pretty
          Pretty-print JSON output

      --max-v8-heap-size-mb <MAX_V8_HEAP_SIZE_MB>
          Maximum V8 heap size per worker in megabytes, at least 64 [default: 0 = no limit]
          
          [env: VLC_MAX_V8_HEAP_SIZE_MB=]

      --width <WIDTH>
          Override the chart width

      --height <HEIGHT>
          Override the chart height

      --max-v8-execution-time-secs <MAX_V8_EXECUTION_TIME_SECS>
          Maximum V8 execution time in seconds [default: 0 = no limit]
          
          [env: VLC_MAX_V8_EXECUTION_TIME_SECS=]

      --background <BACKGROUND>
          Override the chart background

      --gc-after-conversion[=<BOOL>]
          Run V8 garbage collection after each conversion to release memory (default: false)
          
          [env: VLC_GC_AFTER_CONVERSION=]

      --vega-plugin <path|URL>
          Vega plugin: file path (`.js`/`.mjs`) or URL (`https://...`). The plugin must be a single ESM module that exports a default function accepting a vega object. Multi-file plugins should be pre-bundled with esbuild or Rollup. URL plugins auto-allow their domain for imports. May be specified multiple times; plugins execute in order. Put inline ESM plugins in `--vlc-config`
          
          [env: VLC_VEGA_PLUGIN=]

      --plugin-import-domains <PLUGIN_IMPORT_DOMAINS>
          Domains allowed for HTTP imports in plugins, `;`-separated. Examples: `'*'` (any), `'esm.sh'`, `'*.jsdelivr.net'`. May be specified multiple times
          
          [env: VLC_PLUGIN_IMPORT_DOMAINS=]

      --font-dir <PATH>
          Additional directory to search for fonts. Repeat the flag to register multiple directories (`--font-dir /a --font-dir /b`). The combined list is registered when the process starts
          
          [env: VLC_FONT_DIR=]

      --google-fonts-cache-size-mb <MB>
          Capacity of the on-disk Google Fonts cache, in megabytes. `0` uses the default capacity of 512 MB
          
          [env: VLC_GOOGLE_FONTS_CACHE_SIZE_MB=]

      --default-theme <THEME|null>
          Default Vega-Lite theme applied when a request omits `theme`. Pass the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_THEME=]

      --default-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_FORMAT_LOCALE=]

      --default-time-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-time-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_TIME_FORMAT_LOCALE=]

      --themes <JSON|FILE.json|FILE.jsonc|null>
          Custom named themes as an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a map loaded from the `--vlc-config` file
          
          [env: VLC_THEMES=]

      --log-level <LOG_LEVEL>
          Log level for Vega/Vega-Lite messages
          
          [env: VLC_LOG_LEVEL=]
          [default: warn]
          [possible values: error, warn, info, debug]

      --log-format <LOG_FORMAT>
          Log output format. `text` is human-readable; `json` emits one structured line per event for log aggregators

          Possible values:
          - text: Human-readable text logs
          - json: Flat structured JSON logs
          
          [env: VLC_LOG_FORMAT=]
          [default: text]

      --log-filter <DIRECTIVE>
          Raw `tracing-subscriber::EnvFilter` directive (e.g. `"vl_convert=debug,tower_http=info"`). When set, this wins over `--log-level`. When unset, a directive is synthesized from `--log-level`
          
          [env: VLC_LOG_FILTER=]

  -h, --help
          Print help (see a summary with '-h')

vl2sg#

Convert a Vega-Lite specification to a Vega scenegraph

Usage: vl-convert vl2sg [OPTIONS]

Options:
  -i, --input <INPUT>
          Path to input Vega-Lite file. Reads from stdin if omitted or set to "-"

      --vlc-config <disabled|PATH>
          Converter config: a path to a JSONC config file, or the reserved value `disabled` to skip config-file loading. Relative paths resolve from the current working directory. When omitted, the platform default config path is loaded if it exists
          
          [env: VLC_CONFIG=]

      --base-url <default|disabled|URL|PATH>
          Base URL for resolving relative data and image paths. Reserved values: `default` (use vega-datasets CDN), `disabled` (relative paths error). Otherwise either a URL with scheme (`https://...`, `file://...`) or an absolute filesystem path. Relative paths are rejected
          
          [env: VLC_BASE_URL=]

  -o, --output <OUTPUT>
          Path to output scenegraph file. Writes to stdout if omitted or set to "-"

      --allowed-base-urls <none|net|all|URL_PREFIX>
          Allowed base URLs for data and images. Reserved single-value shortcuts: `none` (block all), `net` (HTTP/HTTPS only, no filesystem), `all` (allow everything incl. filesystem). Otherwise a `;`-separated list of CSP-style patterns: `"https:"` (scheme), `"https://example.com/"` (prefix), `"/data/"` (absolute filesystem path). Long allowlists belong in `--vlc-config` JSONC
          
          [env: VLC_ALLOWED_BASE_URLS=]

  -v, --vl-version <VL_VERSION>
          Vega-Lite version. One of 5.8, 5.14, 5.15, 5.16, 5.17, 5.20, 5.21, 6.1, 6.4
          
          [default: 6.4]

      --google-font <GOOGLE_FONT>
          Register a font from Google Fonts. Use "Family" for all variants, or "Family:400,700italic" for specific weight/style combinations. May be specified multiple times; `;` separates entries when passed via `VLC_GOOGLE_FONT`
          
          [env: VLC_GOOGLE_FONT=]

      --theme <THEME>
          Named theme provided by the vega-themes package (e.g. "dark")

  -c, --config <CONFIG>
          Path to Vega-Lite config file

      --google-font-variant-threshold <N>
          Maximum number of Google Font variants one conversion may load, counting configured, requested, and automatically discovered families. The conversion fails once the cap is reached; a single family may carry the total past it. `0` disables the cap
          
          [env: VLC_GOOGLE_FONT_VARIANT_THRESHOLD=]

      --auto-google-fonts[=<BOOL>]
          Automatically download missing fonts from Google Fonts (default: false)
          
          [env: VLC_AUTO_GOOGLE_FONTS=]

      --format-locale <FORMAT_LOCALE>
          d3-format locale name, inline JSON, or .json/.jsonc file

      --embed-local-fonts[=<BOOL>]
          Embed locally installed fonts as base64 @font-face in HTML and SVG output (default: false)
          
          [env: VLC_EMBED_LOCAL_FONTS=]

      --time-format-locale <TIME_FORMAT_LOCALE>
          d3-time-format locale name, inline JSON, or .json/.jsonc file

      --format <FORMAT>
          Output format: JSON or MessagePack
          
          [default: json]
          [possible values: json, msgpack]

      --subset-fonts[=<BOOL>]
          Subset embedded fonts to only the characters used (default: true). Pass `=false` to embed full font files
          
          [env: VLC_SUBSET_FONTS=]

      --missing-fonts <MISSING_FONTS>
          Missing-font behavior: fallback silently, warn, or error
          
          [env: VLC_MISSING_FONTS=]
          [possible values: fallback, warn, error]

  -p, --pretty
          Pretty-print JSON output

      --max-v8-heap-size-mb <MAX_V8_HEAP_SIZE_MB>
          Maximum V8 heap size per worker in megabytes, at least 64 [default: 0 = no limit]
          
          [env: VLC_MAX_V8_HEAP_SIZE_MB=]

      --width <WIDTH>
          Override the chart width

      --height <HEIGHT>
          Override the chart height

      --max-v8-execution-time-secs <MAX_V8_EXECUTION_TIME_SECS>
          Maximum V8 execution time in seconds [default: 0 = no limit]
          
          [env: VLC_MAX_V8_EXECUTION_TIME_SECS=]

      --background <BACKGROUND>
          Override the chart background

      --gc-after-conversion[=<BOOL>]
          Run V8 garbage collection after each conversion to release memory (default: false)
          
          [env: VLC_GC_AFTER_CONVERSION=]

      --vega-plugin <path|URL>
          Vega plugin: file path (`.js`/`.mjs`) or URL (`https://...`). The plugin must be a single ESM module that exports a default function accepting a vega object. Multi-file plugins should be pre-bundled with esbuild or Rollup. URL plugins auto-allow their domain for imports. May be specified multiple times; plugins execute in order. Put inline ESM plugins in `--vlc-config`
          
          [env: VLC_VEGA_PLUGIN=]

      --plugin-import-domains <PLUGIN_IMPORT_DOMAINS>
          Domains allowed for HTTP imports in plugins, `;`-separated. Examples: `'*'` (any), `'esm.sh'`, `'*.jsdelivr.net'`. May be specified multiple times
          
          [env: VLC_PLUGIN_IMPORT_DOMAINS=]

      --font-dir <PATH>
          Additional directory to search for fonts. Repeat the flag to register multiple directories (`--font-dir /a --font-dir /b`). The combined list is registered when the process starts
          
          [env: VLC_FONT_DIR=]

      --google-fonts-cache-size-mb <MB>
          Capacity of the on-disk Google Fonts cache, in megabytes. `0` uses the default capacity of 512 MB
          
          [env: VLC_GOOGLE_FONTS_CACHE_SIZE_MB=]

      --default-theme <THEME|null>
          Default Vega-Lite theme applied when a request omits `theme`. Pass the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_THEME=]

      --default-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_FORMAT_LOCALE=]

      --default-time-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-time-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_TIME_FORMAT_LOCALE=]

      --themes <JSON|FILE.json|FILE.jsonc|null>
          Custom named themes as an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a map loaded from the `--vlc-config` file
          
          [env: VLC_THEMES=]

      --log-level <LOG_LEVEL>
          Log level for Vega/Vega-Lite messages
          
          [env: VLC_LOG_LEVEL=]
          [default: warn]
          [possible values: error, warn, info, debug]

      --log-format <LOG_FORMAT>
          Log output format. `text` is human-readable; `json` emits one structured line per event for log aggregators

          Possible values:
          - text: Human-readable text logs
          - json: Flat structured JSON logs
          
          [env: VLC_LOG_FORMAT=]
          [default: text]

      --log-filter <DIRECTIVE>
          Raw `tracing-subscriber::EnvFilter` directive (e.g. `"vl_convert=debug,tower_http=info"`). When set, this wins over `--log-level`. When unset, a directive is synthesized from `--log-level`
          
          [env: VLC_LOG_FILTER=]

  -h, --help
          Print help (see a summary with '-h')

Vega Commands#

vg2svg#

Convert a Vega specification to an SVG image

Usage: vl-convert vg2svg [OPTIONS]

Options:
  -i, --input <INPUT>
          Path to input Vega file. Reads from stdin if omitted or set to "-"

      --vlc-config <disabled|PATH>
          Converter config: a path to a JSONC config file, or the reserved value `disabled` to skip config-file loading. Relative paths resolve from the current working directory. When omitted, the platform default config path is loaded if it exists
          
          [env: VLC_CONFIG=]

      --base-url <default|disabled|URL|PATH>
          Base URL for resolving relative data and image paths. Reserved values: `default` (use vega-datasets CDN), `disabled` (relative paths error). Otherwise either a URL with scheme (`https://...`, `file://...`) or an absolute filesystem path. Relative paths are rejected
          
          [env: VLC_BASE_URL=]

  -o, --output <OUTPUT>
          Path to output SVG file to be created. Writes to stdout if omitted or set to "-"

      --allowed-base-urls <none|net|all|URL_PREFIX>
          Allowed base URLs for data and images. Reserved single-value shortcuts: `none` (block all), `net` (HTTP/HTTPS only, no filesystem), `all` (allow everything incl. filesystem). Otherwise a `;`-separated list of CSP-style patterns: `"https:"` (scheme), `"https://example.com/"` (prefix), `"/data/"` (absolute filesystem path). Long allowlists belong in `--vlc-config` JSONC
          
          [env: VLC_ALLOWED_BASE_URLS=]

  -c, --config <CONFIG>
          Path to Vega config file

      --format-locale <FORMAT_LOCALE>
          d3-format locale name, inline JSON, or .json/.jsonc file

      --google-font <GOOGLE_FONT>
          Register a font from Google Fonts. Use "Family" for all variants, or "Family:400,700italic" for specific weight/style combinations. May be specified multiple times; `;` separates entries when passed via `VLC_GOOGLE_FONT`
          
          [env: VLC_GOOGLE_FONT=]

      --google-font-variant-threshold <N>
          Maximum number of Google Font variants one conversion may load, counting configured, requested, and automatically discovered families. The conversion fails once the cap is reached; a single family may carry the total past it. `0` disables the cap
          
          [env: VLC_GOOGLE_FONT_VARIANT_THRESHOLD=]

      --time-format-locale <TIME_FORMAT_LOCALE>
          d3-time-format locale name, inline JSON, or .json/.jsonc file

      --auto-google-fonts[=<BOOL>]
          Automatically download missing fonts from Google Fonts (default: false)
          
          [env: VLC_AUTO_GOOGLE_FONTS=]

      --bundle
          Bundle fonts and images into a self-contained SVG

      --embed-local-fonts[=<BOOL>]
          Embed locally installed fonts as base64 @font-face in HTML and SVG output (default: false)
          
          [env: VLC_EMBED_LOCAL_FONTS=]

      --width <WIDTH>
          Override the chart width

      --height <HEIGHT>
          Override the chart height

      --subset-fonts[=<BOOL>]
          Subset embedded fonts to only the characters used (default: true). Pass `=false` to embed full font files
          
          [env: VLC_SUBSET_FONTS=]

      --background <BACKGROUND>
          Override the chart background

      --missing-fonts <MISSING_FONTS>
          Missing-font behavior: fallback silently, warn, or error
          
          [env: VLC_MISSING_FONTS=]
          [possible values: fallback, warn, error]

      --max-v8-heap-size-mb <MAX_V8_HEAP_SIZE_MB>
          Maximum V8 heap size per worker in megabytes, at least 64 [default: 0 = no limit]
          
          [env: VLC_MAX_V8_HEAP_SIZE_MB=]

      --max-v8-execution-time-secs <MAX_V8_EXECUTION_TIME_SECS>
          Maximum V8 execution time in seconds [default: 0 = no limit]
          
          [env: VLC_MAX_V8_EXECUTION_TIME_SECS=]

      --gc-after-conversion[=<BOOL>]
          Run V8 garbage collection after each conversion to release memory (default: false)
          
          [env: VLC_GC_AFTER_CONVERSION=]

      --vega-plugin <path|URL>
          Vega plugin: file path (`.js`/`.mjs`) or URL (`https://...`). The plugin must be a single ESM module that exports a default function accepting a vega object. Multi-file plugins should be pre-bundled with esbuild or Rollup. URL plugins auto-allow their domain for imports. May be specified multiple times; plugins execute in order. Put inline ESM plugins in `--vlc-config`
          
          [env: VLC_VEGA_PLUGIN=]

      --plugin-import-domains <PLUGIN_IMPORT_DOMAINS>
          Domains allowed for HTTP imports in plugins, `;`-separated. Examples: `'*'` (any), `'esm.sh'`, `'*.jsdelivr.net'`. May be specified multiple times
          
          [env: VLC_PLUGIN_IMPORT_DOMAINS=]

      --font-dir <PATH>
          Additional directory to search for fonts. Repeat the flag to register multiple directories (`--font-dir /a --font-dir /b`). The combined list is registered when the process starts
          
          [env: VLC_FONT_DIR=]

      --google-fonts-cache-size-mb <MB>
          Capacity of the on-disk Google Fonts cache, in megabytes. `0` uses the default capacity of 512 MB
          
          [env: VLC_GOOGLE_FONTS_CACHE_SIZE_MB=]

      --default-theme <THEME|null>
          Default Vega-Lite theme applied when a request omits `theme`. Pass the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_THEME=]

      --default-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_FORMAT_LOCALE=]

      --default-time-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-time-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_TIME_FORMAT_LOCALE=]

      --themes <JSON|FILE.json|FILE.jsonc|null>
          Custom named themes as an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a map loaded from the `--vlc-config` file
          
          [env: VLC_THEMES=]

      --log-level <LOG_LEVEL>
          Log level for Vega/Vega-Lite messages
          
          [env: VLC_LOG_LEVEL=]
          [default: warn]
          [possible values: error, warn, info, debug]

      --log-format <LOG_FORMAT>
          Log output format. `text` is human-readable; `json` emits one structured line per event for log aggregators

          Possible values:
          - text: Human-readable text logs
          - json: Flat structured JSON logs
          
          [env: VLC_LOG_FORMAT=]
          [default: text]

      --log-filter <DIRECTIVE>
          Raw `tracing-subscriber::EnvFilter` directive (e.g. `"vl_convert=debug,tower_http=info"`). When set, this wins over `--log-level`. When unset, a directive is synthesized from `--log-level`
          
          [env: VLC_LOG_FILTER=]

  -h, --help
          Print help (see a summary with '-h')

vg2png#

Convert a Vega specification to a PNG image

Usage: vl-convert vg2png [OPTIONS]

Options:
  -i, --input <INPUT>
          Path to input Vega file. Reads from stdin if omitted or set to "-"

      --vlc-config <disabled|PATH>
          Converter config: a path to a JSONC config file, or the reserved value `disabled` to skip config-file loading. Relative paths resolve from the current working directory. When omitted, the platform default config path is loaded if it exists
          
          [env: VLC_CONFIG=]

      --base-url <default|disabled|URL|PATH>
          Base URL for resolving relative data and image paths. Reserved values: `default` (use vega-datasets CDN), `disabled` (relative paths error). Otherwise either a URL with scheme (`https://...`, `file://...`) or an absolute filesystem path. Relative paths are rejected
          
          [env: VLC_BASE_URL=]

  -o, --output <OUTPUT>
          Path to output PNG file to be created. Writes to stdout if omitted or set to "-"

      --allowed-base-urls <none|net|all|URL_PREFIX>
          Allowed base URLs for data and images. Reserved single-value shortcuts: `none` (block all), `net` (HTTP/HTTPS only, no filesystem), `all` (allow everything incl. filesystem). Otherwise a `;`-separated list of CSP-style patterns: `"https:"` (scheme), `"https://example.com/"` (prefix), `"/data/"` (absolute filesystem path). Long allowlists belong in `--vlc-config` JSONC
          
          [env: VLC_ALLOWED_BASE_URLS=]

  -c, --config <CONFIG>
          Path to Vega config file

      --google-font <GOOGLE_FONT>
          Register a font from Google Fonts. Use "Family" for all variants, or "Family:400,700italic" for specific weight/style combinations. May be specified multiple times; `;` separates entries when passed via `VLC_GOOGLE_FONT`
          
          [env: VLC_GOOGLE_FONT=]

      --scale <SCALE>
          Image scale factor
          
          [default: 1.0]

      --google-font-variant-threshold <N>
          Maximum number of Google Font variants one conversion may load, counting configured, requested, and automatically discovered families. The conversion fails once the cap is reached; a single family may carry the total past it. `0` disables the cap
          
          [env: VLC_GOOGLE_FONT_VARIANT_THRESHOLD=]

  -p, --ppi <PPI>
          Pixels per inch
          
          [default: 72.0]

      --auto-google-fonts[=<BOOL>]
          Automatically download missing fonts from Google Fonts (default: false)
          
          [env: VLC_AUTO_GOOGLE_FONTS=]

      --format-locale <FORMAT_LOCALE>
          d3-format locale name, inline JSON, or .json/.jsonc file

      --embed-local-fonts[=<BOOL>]
          Embed locally installed fonts as base64 @font-face in HTML and SVG output (default: false)
          
          [env: VLC_EMBED_LOCAL_FONTS=]

      --time-format-locale <TIME_FORMAT_LOCALE>
          d3-time-format locale name, inline JSON, or .json/.jsonc file

      --subset-fonts[=<BOOL>]
          Subset embedded fonts to only the characters used (default: true). Pass `=false` to embed full font files
          
          [env: VLC_SUBSET_FONTS=]

      --width <WIDTH>
          Override the chart width

      --height <HEIGHT>
          Override the chart height

      --missing-fonts <MISSING_FONTS>
          Missing-font behavior: fallback silently, warn, or error
          
          [env: VLC_MISSING_FONTS=]
          [possible values: fallback, warn, error]

      --background <BACKGROUND>
          Override the chart background

      --max-v8-heap-size-mb <MAX_V8_HEAP_SIZE_MB>
          Maximum V8 heap size per worker in megabytes, at least 64 [default: 0 = no limit]
          
          [env: VLC_MAX_V8_HEAP_SIZE_MB=]

      --max-v8-execution-time-secs <MAX_V8_EXECUTION_TIME_SECS>
          Maximum V8 execution time in seconds [default: 0 = no limit]
          
          [env: VLC_MAX_V8_EXECUTION_TIME_SECS=]

      --gc-after-conversion[=<BOOL>]
          Run V8 garbage collection after each conversion to release memory (default: false)
          
          [env: VLC_GC_AFTER_CONVERSION=]

      --vega-plugin <path|URL>
          Vega plugin: file path (`.js`/`.mjs`) or URL (`https://...`). The plugin must be a single ESM module that exports a default function accepting a vega object. Multi-file plugins should be pre-bundled with esbuild or Rollup. URL plugins auto-allow their domain for imports. May be specified multiple times; plugins execute in order. Put inline ESM plugins in `--vlc-config`
          
          [env: VLC_VEGA_PLUGIN=]

      --plugin-import-domains <PLUGIN_IMPORT_DOMAINS>
          Domains allowed for HTTP imports in plugins, `;`-separated. Examples: `'*'` (any), `'esm.sh'`, `'*.jsdelivr.net'`. May be specified multiple times
          
          [env: VLC_PLUGIN_IMPORT_DOMAINS=]

      --font-dir <PATH>
          Additional directory to search for fonts. Repeat the flag to register multiple directories (`--font-dir /a --font-dir /b`). The combined list is registered when the process starts
          
          [env: VLC_FONT_DIR=]

      --google-fonts-cache-size-mb <MB>
          Capacity of the on-disk Google Fonts cache, in megabytes. `0` uses the default capacity of 512 MB
          
          [env: VLC_GOOGLE_FONTS_CACHE_SIZE_MB=]

      --default-theme <THEME|null>
          Default Vega-Lite theme applied when a request omits `theme`. Pass the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_THEME=]

      --default-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_FORMAT_LOCALE=]

      --default-time-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-time-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_TIME_FORMAT_LOCALE=]

      --themes <JSON|FILE.json|FILE.jsonc|null>
          Custom named themes as an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a map loaded from the `--vlc-config` file
          
          [env: VLC_THEMES=]

      --log-level <LOG_LEVEL>
          Log level for Vega/Vega-Lite messages
          
          [env: VLC_LOG_LEVEL=]
          [default: warn]
          [possible values: error, warn, info, debug]

      --log-format <LOG_FORMAT>
          Log output format. `text` is human-readable; `json` emits one structured line per event for log aggregators

          Possible values:
          - text: Human-readable text logs
          - json: Flat structured JSON logs
          
          [env: VLC_LOG_FORMAT=]
          [default: text]

      --log-filter <DIRECTIVE>
          Raw `tracing-subscriber::EnvFilter` directive (e.g. `"vl_convert=debug,tower_http=info"`). When set, this wins over `--log-level`. When unset, a directive is synthesized from `--log-level`
          
          [env: VLC_LOG_FILTER=]

  -h, --help
          Print help (see a summary with '-h')

vg2jpeg#

Convert a Vega specification to a JPEG image

Usage: vl-convert vg2jpeg [OPTIONS]

Options:
  -i, --input <INPUT>
          Path to input Vega file. Reads from stdin if omitted or set to "-"

      --vlc-config <disabled|PATH>
          Converter config: a path to a JSONC config file, or the reserved value `disabled` to skip config-file loading. Relative paths resolve from the current working directory. When omitted, the platform default config path is loaded if it exists
          
          [env: VLC_CONFIG=]

      --base-url <default|disabled|URL|PATH>
          Base URL for resolving relative data and image paths. Reserved values: `default` (use vega-datasets CDN), `disabled` (relative paths error). Otherwise either a URL with scheme (`https://...`, `file://...`) or an absolute filesystem path. Relative paths are rejected
          
          [env: VLC_BASE_URL=]

  -o, --output <OUTPUT>
          Path to output JPEG file to be created. Writes to stdout if omitted or set to "-"

      --allowed-base-urls <none|net|all|URL_PREFIX>
          Allowed base URLs for data and images. Reserved single-value shortcuts: `none` (block all), `net` (HTTP/HTTPS only, no filesystem), `all` (allow everything incl. filesystem). Otherwise a `;`-separated list of CSP-style patterns: `"https:"` (scheme), `"https://example.com/"` (prefix), `"/data/"` (absolute filesystem path). Long allowlists belong in `--vlc-config` JSONC
          
          [env: VLC_ALLOWED_BASE_URLS=]

  -c, --config <CONFIG>
          Path to Vega config file

      --google-font <GOOGLE_FONT>
          Register a font from Google Fonts. Use "Family" for all variants, or "Family:400,700italic" for specific weight/style combinations. May be specified multiple times; `;` separates entries when passed via `VLC_GOOGLE_FONT`
          
          [env: VLC_GOOGLE_FONT=]

      --scale <SCALE>
          Image scale factor
          
          [default: 1.0]

      --google-font-variant-threshold <N>
          Maximum number of Google Font variants one conversion may load, counting configured, requested, and automatically discovered families. The conversion fails once the cap is reached; a single family may carry the total past it. `0` disables the cap
          
          [env: VLC_GOOGLE_FONT_VARIANT_THRESHOLD=]

  -q, --quality <QUALITY>
          JPEG quality between 0 (worst) and 100 (best)
          
          [default: 90]

      --auto-google-fonts[=<BOOL>]
          Automatically download missing fonts from Google Fonts (default: false)
          
          [env: VLC_AUTO_GOOGLE_FONTS=]

      --format-locale <FORMAT_LOCALE>
          d3-format locale name, inline JSON, or .json/.jsonc file

      --embed-local-fonts[=<BOOL>]
          Embed locally installed fonts as base64 @font-face in HTML and SVG output (default: false)
          
          [env: VLC_EMBED_LOCAL_FONTS=]

      --time-format-locale <TIME_FORMAT_LOCALE>
          d3-time-format locale name, inline JSON, or .json/.jsonc file

      --subset-fonts[=<BOOL>]
          Subset embedded fonts to only the characters used (default: true). Pass `=false` to embed full font files
          
          [env: VLC_SUBSET_FONTS=]

      --width <WIDTH>
          Override the chart width

      --height <HEIGHT>
          Override the chart height

      --missing-fonts <MISSING_FONTS>
          Missing-font behavior: fallback silently, warn, or error
          
          [env: VLC_MISSING_FONTS=]
          [possible values: fallback, warn, error]

      --background <BACKGROUND>
          Override the chart background

      --max-v8-heap-size-mb <MAX_V8_HEAP_SIZE_MB>
          Maximum V8 heap size per worker in megabytes, at least 64 [default: 0 = no limit]
          
          [env: VLC_MAX_V8_HEAP_SIZE_MB=]

      --max-v8-execution-time-secs <MAX_V8_EXECUTION_TIME_SECS>
          Maximum V8 execution time in seconds [default: 0 = no limit]
          
          [env: VLC_MAX_V8_EXECUTION_TIME_SECS=]

      --gc-after-conversion[=<BOOL>]
          Run V8 garbage collection after each conversion to release memory (default: false)
          
          [env: VLC_GC_AFTER_CONVERSION=]

      --vega-plugin <path|URL>
          Vega plugin: file path (`.js`/`.mjs`) or URL (`https://...`). The plugin must be a single ESM module that exports a default function accepting a vega object. Multi-file plugins should be pre-bundled with esbuild or Rollup. URL plugins auto-allow their domain for imports. May be specified multiple times; plugins execute in order. Put inline ESM plugins in `--vlc-config`
          
          [env: VLC_VEGA_PLUGIN=]

      --plugin-import-domains <PLUGIN_IMPORT_DOMAINS>
          Domains allowed for HTTP imports in plugins, `;`-separated. Examples: `'*'` (any), `'esm.sh'`, `'*.jsdelivr.net'`. May be specified multiple times
          
          [env: VLC_PLUGIN_IMPORT_DOMAINS=]

      --font-dir <PATH>
          Additional directory to search for fonts. Repeat the flag to register multiple directories (`--font-dir /a --font-dir /b`). The combined list is registered when the process starts
          
          [env: VLC_FONT_DIR=]

      --google-fonts-cache-size-mb <MB>
          Capacity of the on-disk Google Fonts cache, in megabytes. `0` uses the default capacity of 512 MB
          
          [env: VLC_GOOGLE_FONTS_CACHE_SIZE_MB=]

      --default-theme <THEME|null>
          Default Vega-Lite theme applied when a request omits `theme`. Pass the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_THEME=]

      --default-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_FORMAT_LOCALE=]

      --default-time-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-time-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_TIME_FORMAT_LOCALE=]

      --themes <JSON|FILE.json|FILE.jsonc|null>
          Custom named themes as an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a map loaded from the `--vlc-config` file
          
          [env: VLC_THEMES=]

      --log-level <LOG_LEVEL>
          Log level for Vega/Vega-Lite messages
          
          [env: VLC_LOG_LEVEL=]
          [default: warn]
          [possible values: error, warn, info, debug]

      --log-format <LOG_FORMAT>
          Log output format. `text` is human-readable; `json` emits one structured line per event for log aggregators

          Possible values:
          - text: Human-readable text logs
          - json: Flat structured JSON logs
          
          [env: VLC_LOG_FORMAT=]
          [default: text]

      --log-filter <DIRECTIVE>
          Raw `tracing-subscriber::EnvFilter` directive (e.g. `"vl_convert=debug,tower_http=info"`). When set, this wins over `--log-level`. When unset, a directive is synthesized from `--log-level`
          
          [env: VLC_LOG_FILTER=]

  -h, --help
          Print help (see a summary with '-h')

vg2pdf#

Convert a Vega specification to a PDF document

Usage: vl-convert vg2pdf [OPTIONS]

Options:
  -i, --input <INPUT>
          Path to input Vega file. Reads from stdin if omitted or set to "-"

      --vlc-config <disabled|PATH>
          Converter config: a path to a JSONC config file, or the reserved value `disabled` to skip config-file loading. Relative paths resolve from the current working directory. When omitted, the platform default config path is loaded if it exists
          
          [env: VLC_CONFIG=]

      --base-url <default|disabled|URL|PATH>
          Base URL for resolving relative data and image paths. Reserved values: `default` (use vega-datasets CDN), `disabled` (relative paths error). Otherwise either a URL with scheme (`https://...`, `file://...`) or an absolute filesystem path. Relative paths are rejected
          
          [env: VLC_BASE_URL=]

  -o, --output <OUTPUT>
          Path to output PDF file to be created. Writes to stdout if omitted or set to "-"

      --allowed-base-urls <none|net|all|URL_PREFIX>
          Allowed base URLs for data and images. Reserved single-value shortcuts: `none` (block all), `net` (HTTP/HTTPS only, no filesystem), `all` (allow everything incl. filesystem). Otherwise a `;`-separated list of CSP-style patterns: `"https:"` (scheme), `"https://example.com/"` (prefix), `"/data/"` (absolute filesystem path). Long allowlists belong in `--vlc-config` JSONC
          
          [env: VLC_ALLOWED_BASE_URLS=]

  -c, --config <CONFIG>
          Path to Vega config file

      --format-locale <FORMAT_LOCALE>
          d3-format locale name, inline JSON, or .json/.jsonc file

      --google-font <GOOGLE_FONT>
          Register a font from Google Fonts. Use "Family" for all variants, or "Family:400,700italic" for specific weight/style combinations. May be specified multiple times; `;` separates entries when passed via `VLC_GOOGLE_FONT`
          
          [env: VLC_GOOGLE_FONT=]

      --google-font-variant-threshold <N>
          Maximum number of Google Font variants one conversion may load, counting configured, requested, and automatically discovered families. The conversion fails once the cap is reached; a single family may carry the total past it. `0` disables the cap
          
          [env: VLC_GOOGLE_FONT_VARIANT_THRESHOLD=]

      --time-format-locale <TIME_FORMAT_LOCALE>
          d3-time-format locale name, inline JSON, or .json/.jsonc file

      --auto-google-fonts[=<BOOL>]
          Automatically download missing fonts from Google Fonts (default: false)
          
          [env: VLC_AUTO_GOOGLE_FONTS=]

      --width <WIDTH>
          Override the chart width

      --embed-local-fonts[=<BOOL>]
          Embed locally installed fonts as base64 @font-face in HTML and SVG output (default: false)
          
          [env: VLC_EMBED_LOCAL_FONTS=]

      --height <HEIGHT>
          Override the chart height

      --background <BACKGROUND>
          Override the chart background

      --subset-fonts[=<BOOL>]
          Subset embedded fonts to only the characters used (default: true). Pass `=false` to embed full font files
          
          [env: VLC_SUBSET_FONTS=]

      --missing-fonts <MISSING_FONTS>
          Missing-font behavior: fallback silently, warn, or error
          
          [env: VLC_MISSING_FONTS=]
          [possible values: fallback, warn, error]

      --max-v8-heap-size-mb <MAX_V8_HEAP_SIZE_MB>
          Maximum V8 heap size per worker in megabytes, at least 64 [default: 0 = no limit]
          
          [env: VLC_MAX_V8_HEAP_SIZE_MB=]

      --max-v8-execution-time-secs <MAX_V8_EXECUTION_TIME_SECS>
          Maximum V8 execution time in seconds [default: 0 = no limit]
          
          [env: VLC_MAX_V8_EXECUTION_TIME_SECS=]

      --gc-after-conversion[=<BOOL>]
          Run V8 garbage collection after each conversion to release memory (default: false)
          
          [env: VLC_GC_AFTER_CONVERSION=]

      --vega-plugin <path|URL>
          Vega plugin: file path (`.js`/`.mjs`) or URL (`https://...`). The plugin must be a single ESM module that exports a default function accepting a vega object. Multi-file plugins should be pre-bundled with esbuild or Rollup. URL plugins auto-allow their domain for imports. May be specified multiple times; plugins execute in order. Put inline ESM plugins in `--vlc-config`
          
          [env: VLC_VEGA_PLUGIN=]

      --plugin-import-domains <PLUGIN_IMPORT_DOMAINS>
          Domains allowed for HTTP imports in plugins, `;`-separated. Examples: `'*'` (any), `'esm.sh'`, `'*.jsdelivr.net'`. May be specified multiple times
          
          [env: VLC_PLUGIN_IMPORT_DOMAINS=]

      --font-dir <PATH>
          Additional directory to search for fonts. Repeat the flag to register multiple directories (`--font-dir /a --font-dir /b`). The combined list is registered when the process starts
          
          [env: VLC_FONT_DIR=]

      --google-fonts-cache-size-mb <MB>
          Capacity of the on-disk Google Fonts cache, in megabytes. `0` uses the default capacity of 512 MB
          
          [env: VLC_GOOGLE_FONTS_CACHE_SIZE_MB=]

      --default-theme <THEME|null>
          Default Vega-Lite theme applied when a request omits `theme`. Pass the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_THEME=]

      --default-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_FORMAT_LOCALE=]

      --default-time-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-time-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_TIME_FORMAT_LOCALE=]

      --themes <JSON|FILE.json|FILE.jsonc|null>
          Custom named themes as an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a map loaded from the `--vlc-config` file
          
          [env: VLC_THEMES=]

      --log-level <LOG_LEVEL>
          Log level for Vega/Vega-Lite messages
          
          [env: VLC_LOG_LEVEL=]
          [default: warn]
          [possible values: error, warn, info, debug]

      --log-format <LOG_FORMAT>
          Log output format. `text` is human-readable; `json` emits one structured line per event for log aggregators

          Possible values:
          - text: Human-readable text logs
          - json: Flat structured JSON logs
          
          [env: VLC_LOG_FORMAT=]
          [default: text]

      --log-filter <DIRECTIVE>
          Raw `tracing-subscriber::EnvFilter` directive (e.g. `"vl_convert=debug,tower_http=info"`). When set, this wins over `--log-level`. When unset, a directive is synthesized from `--log-level`
          
          [env: VLC_LOG_FILTER=]

  -h, --help
          Print help (see a summary with '-h')

vg2url#

Convert a Vega specification to a URL that opens the chart in the Vega editor

Usage: vl-convert vg2url [OPTIONS]

Options:
  -i, --input <INPUT>
          Path to input Vega file. Reads from stdin if omitted or set to "-"

      --vlc-config <disabled|PATH>
          Converter config: a path to a JSONC config file, or the reserved value `disabled` to skip config-file loading. Relative paths resolve from the current working directory. When omitted, the platform default config path is loaded if it exists
          
          [env: VLC_CONFIG=]

      --base-url <default|disabled|URL|PATH>
          Base URL for resolving relative data and image paths. Reserved values: `default` (use vega-datasets CDN), `disabled` (relative paths error). Otherwise either a URL with scheme (`https://...`, `file://...`) or an absolute filesystem path. Relative paths are rejected
          
          [env: VLC_BASE_URL=]

  -o, --output <OUTPUT>
          Path to output file. Writes to stdout if omitted or set to "-"

      --allowed-base-urls <none|net|all|URL_PREFIX>
          Allowed base URLs for data and images. Reserved single-value shortcuts: `none` (block all), `net` (HTTP/HTTPS only, no filesystem), `all` (allow everything incl. filesystem). Otherwise a `;`-separated list of CSP-style patterns: `"https:"` (scheme), `"https://example.com/"` (prefix), `"/data/"` (absolute filesystem path). Long allowlists belong in `--vlc-config` JSONC
          
          [env: VLC_ALLOWED_BASE_URLS=]

      --fullscreen
          Open chart in fullscreen mode

      --google-font <GOOGLE_FONT>
          Register a font from Google Fonts. Use "Family" for all variants, or "Family:400,700italic" for specific weight/style combinations. May be specified multiple times; `;` separates entries when passed via `VLC_GOOGLE_FONT`
          
          [env: VLC_GOOGLE_FONT=]

      --google-font-variant-threshold <N>
          Maximum number of Google Font variants one conversion may load, counting configured, requested, and automatically discovered families. The conversion fails once the cap is reached; a single family may carry the total past it. `0` disables the cap
          
          [env: VLC_GOOGLE_FONT_VARIANT_THRESHOLD=]

      --auto-google-fonts[=<BOOL>]
          Automatically download missing fonts from Google Fonts (default: false)
          
          [env: VLC_AUTO_GOOGLE_FONTS=]

      --embed-local-fonts[=<BOOL>]
          Embed locally installed fonts as base64 @font-face in HTML and SVG output (default: false)
          
          [env: VLC_EMBED_LOCAL_FONTS=]

      --subset-fonts[=<BOOL>]
          Subset embedded fonts to only the characters used (default: true). Pass `=false` to embed full font files
          
          [env: VLC_SUBSET_FONTS=]

      --missing-fonts <MISSING_FONTS>
          Missing-font behavior: fallback silently, warn, or error
          
          [env: VLC_MISSING_FONTS=]
          [possible values: fallback, warn, error]

      --max-v8-heap-size-mb <MAX_V8_HEAP_SIZE_MB>
          Maximum V8 heap size per worker in megabytes, at least 64 [default: 0 = no limit]
          
          [env: VLC_MAX_V8_HEAP_SIZE_MB=]

      --max-v8-execution-time-secs <MAX_V8_EXECUTION_TIME_SECS>
          Maximum V8 execution time in seconds [default: 0 = no limit]
          
          [env: VLC_MAX_V8_EXECUTION_TIME_SECS=]

      --gc-after-conversion[=<BOOL>]
          Run V8 garbage collection after each conversion to release memory (default: false)
          
          [env: VLC_GC_AFTER_CONVERSION=]

      --vega-plugin <path|URL>
          Vega plugin: file path (`.js`/`.mjs`) or URL (`https://...`). The plugin must be a single ESM module that exports a default function accepting a vega object. Multi-file plugins should be pre-bundled with esbuild or Rollup. URL plugins auto-allow their domain for imports. May be specified multiple times; plugins execute in order. Put inline ESM plugins in `--vlc-config`
          
          [env: VLC_VEGA_PLUGIN=]

      --plugin-import-domains <PLUGIN_IMPORT_DOMAINS>
          Domains allowed for HTTP imports in plugins, `;`-separated. Examples: `'*'` (any), `'esm.sh'`, `'*.jsdelivr.net'`. May be specified multiple times
          
          [env: VLC_PLUGIN_IMPORT_DOMAINS=]

      --font-dir <PATH>
          Additional directory to search for fonts. Repeat the flag to register multiple directories (`--font-dir /a --font-dir /b`). The combined list is registered when the process starts
          
          [env: VLC_FONT_DIR=]

      --google-fonts-cache-size-mb <MB>
          Capacity of the on-disk Google Fonts cache, in megabytes. `0` uses the default capacity of 512 MB
          
          [env: VLC_GOOGLE_FONTS_CACHE_SIZE_MB=]

      --default-theme <THEME|null>
          Default Vega-Lite theme applied when a request omits `theme`. Pass the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_THEME=]

      --default-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_FORMAT_LOCALE=]

      --default-time-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-time-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_TIME_FORMAT_LOCALE=]

      --themes <JSON|FILE.json|FILE.jsonc|null>
          Custom named themes as an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a map loaded from the `--vlc-config` file
          
          [env: VLC_THEMES=]

      --log-level <LOG_LEVEL>
          Log level for Vega/Vega-Lite messages
          
          [env: VLC_LOG_LEVEL=]
          [default: warn]
          [possible values: error, warn, info, debug]

      --log-format <LOG_FORMAT>
          Log output format. `text` is human-readable; `json` emits one structured line per event for log aggregators

          Possible values:
          - text: Human-readable text logs
          - json: Flat structured JSON logs
          
          [env: VLC_LOG_FORMAT=]
          [default: text]

      --log-filter <DIRECTIVE>
          Raw `tracing-subscriber::EnvFilter` directive (e.g. `"vl_convert=debug,tower_http=info"`). When set, this wins over `--log-level`. When unset, a directive is synthesized from `--log-level`
          
          [env: VLC_LOG_FILTER=]

  -h, --help
          Print help (see a summary with '-h')

vg2html#

Convert a Vega specification to an HTML file

Usage: vl-convert vg2html [OPTIONS]

Options:
  -i, --input <INPUT>
          Path to input Vega file. Reads from stdin if omitted or set to "-"

      --vlc-config <disabled|PATH>
          Converter config: a path to a JSONC config file, or the reserved value `disabled` to skip config-file loading. Relative paths resolve from the current working directory. When omitted, the platform default config path is loaded if it exists
          
          [env: VLC_CONFIG=]

      --base-url <default|disabled|URL|PATH>
          Base URL for resolving relative data and image paths. Reserved values: `default` (use vega-datasets CDN), `disabled` (relative paths error). Otherwise either a URL with scheme (`https://...`, `file://...`) or an absolute filesystem path. Relative paths are rejected
          
          [env: VLC_BASE_URL=]

  -o, --output <OUTPUT>
          Path to output HTML file to be created. Writes to stdout if omitted or set to "-"

      --allowed-base-urls <none|net|all|URL_PREFIX>
          Allowed base URLs for data and images. Reserved single-value shortcuts: `none` (block all), `net` (HTTP/HTTPS only, no filesystem), `all` (allow everything incl. filesystem). Otherwise a `;`-separated list of CSP-style patterns: `"https:"` (scheme), `"https://example.com/"` (prefix), `"/data/"` (absolute filesystem path). Long allowlists belong in `--vlc-config` JSONC
          
          [env: VLC_ALLOWED_BASE_URLS=]

  -c, --config <CONFIG>
          Path to Vega config file

  -b, --bundle
          Whether to bundle JavaScript dependencies in the HTML file instead of loading them from a CDN

      --google-font <GOOGLE_FONT>
          Register a font from Google Fonts. Use "Family" for all variants, or "Family:400,700italic" for specific weight/style combinations. May be specified multiple times; `;` separates entries when passed via `VLC_GOOGLE_FONT`
          
          [env: VLC_GOOGLE_FONT=]

      --format-locale <FORMAT_LOCALE>
          d3-format locale name, inline JSON, or .json/.jsonc file

      --google-font-variant-threshold <N>
          Maximum number of Google Font variants one conversion may load, counting configured, requested, and automatically discovered families. The conversion fails once the cap is reached; a single family may carry the total past it. `0` disables the cap
          
          [env: VLC_GOOGLE_FONT_VARIANT_THRESHOLD=]

      --auto-google-fonts[=<BOOL>]
          Automatically download missing fonts from Google Fonts (default: false)
          
          [env: VLC_AUTO_GOOGLE_FONTS=]

      --time-format-locale <TIME_FORMAT_LOCALE>
          d3-time-format locale name, inline JSON, or .json/.jsonc file

      --embed-local-fonts[=<BOOL>]
          Embed locally installed fonts as base64 @font-face in HTML and SVG output (default: false)
          
          [env: VLC_EMBED_LOCAL_FONTS=]

      --renderer <RENDERER>
          Vega renderer. One of 'svg' (default), 'canvas', or 'hybrid'

      --subset-fonts[=<BOOL>]
          Subset embedded fonts to only the characters used (default: true). Pass `=false` to embed full font files
          
          [env: VLC_SUBSET_FONTS=]

      --width <WIDTH>
          Override the chart width

      --height <HEIGHT>
          Override the chart height

      --missing-fonts <MISSING_FONTS>
          Missing-font behavior: fallback silently, warn, or error
          
          [env: VLC_MISSING_FONTS=]
          [possible values: fallback, warn, error]

      --background <BACKGROUND>
          Override the chart background

      --max-v8-heap-size-mb <MAX_V8_HEAP_SIZE_MB>
          Maximum V8 heap size per worker in megabytes, at least 64 [default: 0 = no limit]
          
          [env: VLC_MAX_V8_HEAP_SIZE_MB=]

      --max-v8-execution-time-secs <MAX_V8_EXECUTION_TIME_SECS>
          Maximum V8 execution time in seconds [default: 0 = no limit]
          
          [env: VLC_MAX_V8_EXECUTION_TIME_SECS=]

      --gc-after-conversion[=<BOOL>]
          Run V8 garbage collection after each conversion to release memory (default: false)
          
          [env: VLC_GC_AFTER_CONVERSION=]

      --vega-plugin <path|URL>
          Vega plugin: file path (`.js`/`.mjs`) or URL (`https://...`). The plugin must be a single ESM module that exports a default function accepting a vega object. Multi-file plugins should be pre-bundled with esbuild or Rollup. URL plugins auto-allow their domain for imports. May be specified multiple times; plugins execute in order. Put inline ESM plugins in `--vlc-config`
          
          [env: VLC_VEGA_PLUGIN=]

      --plugin-import-domains <PLUGIN_IMPORT_DOMAINS>
          Domains allowed for HTTP imports in plugins, `;`-separated. Examples: `'*'` (any), `'esm.sh'`, `'*.jsdelivr.net'`. May be specified multiple times
          
          [env: VLC_PLUGIN_IMPORT_DOMAINS=]

      --font-dir <PATH>
          Additional directory to search for fonts. Repeat the flag to register multiple directories (`--font-dir /a --font-dir /b`). The combined list is registered when the process starts
          
          [env: VLC_FONT_DIR=]

      --google-fonts-cache-size-mb <MB>
          Capacity of the on-disk Google Fonts cache, in megabytes. `0` uses the default capacity of 512 MB
          
          [env: VLC_GOOGLE_FONTS_CACHE_SIZE_MB=]

      --default-theme <THEME|null>
          Default Vega-Lite theme applied when a request omits `theme`. Pass the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_THEME=]

      --default-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_FORMAT_LOCALE=]

      --default-time-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-time-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_TIME_FORMAT_LOCALE=]

      --themes <JSON|FILE.json|FILE.jsonc|null>
          Custom named themes as an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a map loaded from the `--vlc-config` file
          
          [env: VLC_THEMES=]

      --log-level <LOG_LEVEL>
          Log level for Vega/Vega-Lite messages
          
          [env: VLC_LOG_LEVEL=]
          [default: warn]
          [possible values: error, warn, info, debug]

      --log-format <LOG_FORMAT>
          Log output format. `text` is human-readable; `json` emits one structured line per event for log aggregators

          Possible values:
          - text: Human-readable text logs
          - json: Flat structured JSON logs
          
          [env: VLC_LOG_FORMAT=]
          [default: text]

      --log-filter <DIRECTIVE>
          Raw `tracing-subscriber::EnvFilter` directive (e.g. `"vl_convert=debug,tower_http=info"`). When set, this wins over `--log-level`. When unset, a directive is synthesized from `--log-level`
          
          [env: VLC_LOG_FILTER=]

  -h, --help
          Print help (see a summary with '-h')

vg2fonts#

Return font metadata for a rendered Vega specification

Usage: vl-convert vg2fonts [OPTIONS]

Options:
  -i, --input <INPUT>
          Path to input Vega file. Reads from stdin if omitted or set to "-"

      --vlc-config <disabled|PATH>
          Converter config: a path to a JSONC config file, or the reserved value `disabled` to skip config-file loading. Relative paths resolve from the current working directory. When omitted, the platform default config path is loaded if it exists
          
          [env: VLC_CONFIG=]

      --base-url <default|disabled|URL|PATH>
          Base URL for resolving relative data and image paths. Reserved values: `default` (use vega-datasets CDN), `disabled` (relative paths error). Otherwise either a URL with scheme (`https://...`, `file://...`) or an absolute filesystem path. Relative paths are rejected
          
          [env: VLC_BASE_URL=]

  -o, --output <OUTPUT>
          Path to output JSON file. Writes to stdout if omitted or set to "-"

      --allowed-base-urls <none|net|all|URL_PREFIX>
          Allowed base URLs for data and images. Reserved single-value shortcuts: `none` (block all), `net` (HTTP/HTTPS only, no filesystem), `all` (allow everything incl. filesystem). Otherwise a `;`-separated list of CSP-style patterns: `"https:"` (scheme), `"https://example.com/"` (prefix), `"/data/"` (absolute filesystem path). Long allowlists belong in `--vlc-config` JSONC
          
          [env: VLC_ALLOWED_BASE_URLS=]

  -c, --config <CONFIG>
          Path to Vega config file

      --google-font <GOOGLE_FONT>
          Register a font from Google Fonts. Use "Family" for all variants, or "Family:400,700italic" for specific weight/style combinations. May be specified multiple times; `;` separates entries when passed via `VLC_GOOGLE_FONT`
          
          [env: VLC_GOOGLE_FONT=]

      --include-font-face
          Include @font-face CSS blocks in the output

      --format-locale <FORMAT_LOCALE>
          d3-format locale name, inline JSON, or .json/.jsonc file

      --google-font-variant-threshold <N>
          Maximum number of Google Font variants one conversion may load, counting configured, requested, and automatically discovered families. The conversion fails once the cap is reached; a single family may carry the total past it. `0` disables the cap
          
          [env: VLC_GOOGLE_FONT_VARIANT_THRESHOLD=]

      --auto-google-fonts[=<BOOL>]
          Automatically download missing fonts from Google Fonts (default: false)
          
          [env: VLC_AUTO_GOOGLE_FONTS=]

      --time-format-locale <TIME_FORMAT_LOCALE>
          d3-time-format locale name, inline JSON, or .json/.jsonc file

      --embed-local-fonts[=<BOOL>]
          Embed locally installed fonts as base64 @font-face in HTML and SVG output (default: false)
          
          [env: VLC_EMBED_LOCAL_FONTS=]

  -p, --pretty
          Pretty-print JSON output

      --subset-fonts[=<BOOL>]
          Subset embedded fonts to only the characters used (default: true). Pass `=false` to embed full font files
          
          [env: VLC_SUBSET_FONTS=]

      --width <WIDTH>
          Override the chart width

      --height <HEIGHT>
          Override the chart height

      --missing-fonts <MISSING_FONTS>
          Missing-font behavior: fallback silently, warn, or error
          
          [env: VLC_MISSING_FONTS=]
          [possible values: fallback, warn, error]

      --background <BACKGROUND>
          Override the chart background

      --max-v8-heap-size-mb <MAX_V8_HEAP_SIZE_MB>
          Maximum V8 heap size per worker in megabytes, at least 64 [default: 0 = no limit]
          
          [env: VLC_MAX_V8_HEAP_SIZE_MB=]

      --max-v8-execution-time-secs <MAX_V8_EXECUTION_TIME_SECS>
          Maximum V8 execution time in seconds [default: 0 = no limit]
          
          [env: VLC_MAX_V8_EXECUTION_TIME_SECS=]

      --gc-after-conversion[=<BOOL>]
          Run V8 garbage collection after each conversion to release memory (default: false)
          
          [env: VLC_GC_AFTER_CONVERSION=]

      --vega-plugin <path|URL>
          Vega plugin: file path (`.js`/`.mjs`) or URL (`https://...`). The plugin must be a single ESM module that exports a default function accepting a vega object. Multi-file plugins should be pre-bundled with esbuild or Rollup. URL plugins auto-allow their domain for imports. May be specified multiple times; plugins execute in order. Put inline ESM plugins in `--vlc-config`
          
          [env: VLC_VEGA_PLUGIN=]

      --plugin-import-domains <PLUGIN_IMPORT_DOMAINS>
          Domains allowed for HTTP imports in plugins, `;`-separated. Examples: `'*'` (any), `'esm.sh'`, `'*.jsdelivr.net'`. May be specified multiple times
          
          [env: VLC_PLUGIN_IMPORT_DOMAINS=]

      --font-dir <PATH>
          Additional directory to search for fonts. Repeat the flag to register multiple directories (`--font-dir /a --font-dir /b`). The combined list is registered when the process starts
          
          [env: VLC_FONT_DIR=]

      --google-fonts-cache-size-mb <MB>
          Capacity of the on-disk Google Fonts cache, in megabytes. `0` uses the default capacity of 512 MB
          
          [env: VLC_GOOGLE_FONTS_CACHE_SIZE_MB=]

      --default-theme <THEME|null>
          Default Vega-Lite theme applied when a request omits `theme`. Pass the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_THEME=]

      --default-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_FORMAT_LOCALE=]

      --default-time-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-time-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_TIME_FORMAT_LOCALE=]

      --themes <JSON|FILE.json|FILE.jsonc|null>
          Custom named themes as an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a map loaded from the `--vlc-config` file
          
          [env: VLC_THEMES=]

      --log-level <LOG_LEVEL>
          Log level for Vega/Vega-Lite messages
          
          [env: VLC_LOG_LEVEL=]
          [default: warn]
          [possible values: error, warn, info, debug]

      --log-format <LOG_FORMAT>
          Log output format. `text` is human-readable; `json` emits one structured line per event for log aggregators

          Possible values:
          - text: Human-readable text logs
          - json: Flat structured JSON logs
          
          [env: VLC_LOG_FORMAT=]
          [default: text]

      --log-filter <DIRECTIVE>
          Raw `tracing-subscriber::EnvFilter` directive (e.g. `"vl_convert=debug,tower_http=info"`). When set, this wins over `--log-level`. When unset, a directive is synthesized from `--log-level`
          
          [env: VLC_LOG_FILTER=]

  -h, --help
          Print help (see a summary with '-h')

vg2sg#

Convert a Vega specification to a Vega scenegraph

Usage: vl-convert vg2sg [OPTIONS]

Options:
  -i, --input <INPUT>
          Path to input Vega file. Reads from stdin if omitted or set to "-"

      --vlc-config <disabled|PATH>
          Converter config: a path to a JSONC config file, or the reserved value `disabled` to skip config-file loading. Relative paths resolve from the current working directory. When omitted, the platform default config path is loaded if it exists
          
          [env: VLC_CONFIG=]

      --base-url <default|disabled|URL|PATH>
          Base URL for resolving relative data and image paths. Reserved values: `default` (use vega-datasets CDN), `disabled` (relative paths error). Otherwise either a URL with scheme (`https://...`, `file://...`) or an absolute filesystem path. Relative paths are rejected
          
          [env: VLC_BASE_URL=]

  -o, --output <OUTPUT>
          Path to output scenegraph file. Writes to stdout if omitted or set to "-"

      --allowed-base-urls <none|net|all|URL_PREFIX>
          Allowed base URLs for data and images. Reserved single-value shortcuts: `none` (block all), `net` (HTTP/HTTPS only, no filesystem), `all` (allow everything incl. filesystem). Otherwise a `;`-separated list of CSP-style patterns: `"https:"` (scheme), `"https://example.com/"` (prefix), `"/data/"` (absolute filesystem path). Long allowlists belong in `--vlc-config` JSONC
          
          [env: VLC_ALLOWED_BASE_URLS=]

  -c, --config <CONFIG>
          Path to Vega config file

      --format-locale <FORMAT_LOCALE>
          d3-format locale name, inline JSON, or .json/.jsonc file

      --google-font <GOOGLE_FONT>
          Register a font from Google Fonts. Use "Family" for all variants, or "Family:400,700italic" for specific weight/style combinations. May be specified multiple times; `;` separates entries when passed via `VLC_GOOGLE_FONT`
          
          [env: VLC_GOOGLE_FONT=]

      --google-font-variant-threshold <N>
          Maximum number of Google Font variants one conversion may load, counting configured, requested, and automatically discovered families. The conversion fails once the cap is reached; a single family may carry the total past it. `0` disables the cap
          
          [env: VLC_GOOGLE_FONT_VARIANT_THRESHOLD=]

      --time-format-locale <TIME_FORMAT_LOCALE>
          d3-time-format locale name, inline JSON, or .json/.jsonc file

      --auto-google-fonts[=<BOOL>]
          Automatically download missing fonts from Google Fonts (default: false)
          
          [env: VLC_AUTO_GOOGLE_FONTS=]

      --format <FORMAT>
          Output format: JSON or MessagePack
          
          [default: json]
          [possible values: json, msgpack]

      --embed-local-fonts[=<BOOL>]
          Embed locally installed fonts as base64 @font-face in HTML and SVG output (default: false)
          
          [env: VLC_EMBED_LOCAL_FONTS=]

  -p, --pretty
          Pretty-print JSON output

      --subset-fonts[=<BOOL>]
          Subset embedded fonts to only the characters used (default: true). Pass `=false` to embed full font files
          
          [env: VLC_SUBSET_FONTS=]

      --width <WIDTH>
          Override the chart width

      --height <HEIGHT>
          Override the chart height

      --missing-fonts <MISSING_FONTS>
          Missing-font behavior: fallback silently, warn, or error
          
          [env: VLC_MISSING_FONTS=]
          [possible values: fallback, warn, error]

      --background <BACKGROUND>
          Override the chart background

      --max-v8-heap-size-mb <MAX_V8_HEAP_SIZE_MB>
          Maximum V8 heap size per worker in megabytes, at least 64 [default: 0 = no limit]
          
          [env: VLC_MAX_V8_HEAP_SIZE_MB=]

      --max-v8-execution-time-secs <MAX_V8_EXECUTION_TIME_SECS>
          Maximum V8 execution time in seconds [default: 0 = no limit]
          
          [env: VLC_MAX_V8_EXECUTION_TIME_SECS=]

      --gc-after-conversion[=<BOOL>]
          Run V8 garbage collection after each conversion to release memory (default: false)
          
          [env: VLC_GC_AFTER_CONVERSION=]

      --vega-plugin <path|URL>
          Vega plugin: file path (`.js`/`.mjs`) or URL (`https://...`). The plugin must be a single ESM module that exports a default function accepting a vega object. Multi-file plugins should be pre-bundled with esbuild or Rollup. URL plugins auto-allow their domain for imports. May be specified multiple times; plugins execute in order. Put inline ESM plugins in `--vlc-config`
          
          [env: VLC_VEGA_PLUGIN=]

      --plugin-import-domains <PLUGIN_IMPORT_DOMAINS>
          Domains allowed for HTTP imports in plugins, `;`-separated. Examples: `'*'` (any), `'esm.sh'`, `'*.jsdelivr.net'`. May be specified multiple times
          
          [env: VLC_PLUGIN_IMPORT_DOMAINS=]

      --font-dir <PATH>
          Additional directory to search for fonts. Repeat the flag to register multiple directories (`--font-dir /a --font-dir /b`). The combined list is registered when the process starts
          
          [env: VLC_FONT_DIR=]

      --google-fonts-cache-size-mb <MB>
          Capacity of the on-disk Google Fonts cache, in megabytes. `0` uses the default capacity of 512 MB
          
          [env: VLC_GOOGLE_FONTS_CACHE_SIZE_MB=]

      --default-theme <THEME|null>
          Default Vega-Lite theme applied when a request omits `theme`. Pass the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_THEME=]

      --default-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_FORMAT_LOCALE=]

      --default-time-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-time-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_TIME_FORMAT_LOCALE=]

      --themes <JSON|FILE.json|FILE.jsonc|null>
          Custom named themes as an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a map loaded from the `--vlc-config` file
          
          [env: VLC_THEMES=]

      --log-level <LOG_LEVEL>
          Log level for Vega/Vega-Lite messages
          
          [env: VLC_LOG_LEVEL=]
          [default: warn]
          [possible values: error, warn, info, debug]

      --log-format <LOG_FORMAT>
          Log output format. `text` is human-readable; `json` emits one structured line per event for log aggregators

          Possible values:
          - text: Human-readable text logs
          - json: Flat structured JSON logs
          
          [env: VLC_LOG_FORMAT=]
          [default: text]

      --log-filter <DIRECTIVE>
          Raw `tracing-subscriber::EnvFilter` directive (e.g. `"vl_convert=debug,tower_http=info"`). When set, this wins over `--log-level`. When unset, a directive is synthesized from `--log-level`
          
          [env: VLC_LOG_FILTER=]

  -h, --help
          Print help (see a summary with '-h')

SVG Commands#

svg2png#

Convert an SVG image to a PNG image

Usage: vl-convert svg2png [OPTIONS]

Options:
  -i, --input <INPUT>
          Path to input SVG file. Reads from stdin if omitted or set to "-"

      --vlc-config <disabled|PATH>
          Converter config: a path to a JSONC config file, or the reserved value `disabled` to skip config-file loading. Relative paths resolve from the current working directory. When omitted, the platform default config path is loaded if it exists
          
          [env: VLC_CONFIG=]

      --base-url <default|disabled|URL|PATH>
          Base URL for resolving relative data and image paths. Reserved values: `default` (use vega-datasets CDN), `disabled` (relative paths error). Otherwise either a URL with scheme (`https://...`, `file://...`) or an absolute filesystem path. Relative paths are rejected
          
          [env: VLC_BASE_URL=]

  -o, --output <OUTPUT>
          Path to output PNG file to be created. Writes to stdout if omitted or set to "-"

      --allowed-base-urls <none|net|all|URL_PREFIX>
          Allowed base URLs for data and images. Reserved single-value shortcuts: `none` (block all), `net` (HTTP/HTTPS only, no filesystem), `all` (allow everything incl. filesystem). Otherwise a `;`-separated list of CSP-style patterns: `"https:"` (scheme), `"https://example.com/"` (prefix), `"/data/"` (absolute filesystem path). Long allowlists belong in `--vlc-config` JSONC
          
          [env: VLC_ALLOWED_BASE_URLS=]

      --scale <SCALE>
          Image scale factor
          
          [default: 1.0]

      --google-font <GOOGLE_FONT>
          Register a font from Google Fonts. Use "Family" for all variants, or "Family:400,700italic" for specific weight/style combinations. May be specified multiple times; `;` separates entries when passed via `VLC_GOOGLE_FONT`
          
          [env: VLC_GOOGLE_FONT=]

  -p, --ppi <PPI>
          Pixels per inch
          
          [default: 72.0]

      --google-font-variant-threshold <N>
          Maximum number of Google Font variants one conversion may load, counting configured, requested, and automatically discovered families. The conversion fails once the cap is reached; a single family may carry the total past it. `0` disables the cap
          
          [env: VLC_GOOGLE_FONT_VARIANT_THRESHOLD=]

      --auto-google-fonts[=<BOOL>]
          Automatically download missing fonts from Google Fonts (default: false)
          
          [env: VLC_AUTO_GOOGLE_FONTS=]

      --embed-local-fonts[=<BOOL>]
          Embed locally installed fonts as base64 @font-face in HTML and SVG output (default: false)
          
          [env: VLC_EMBED_LOCAL_FONTS=]

      --subset-fonts[=<BOOL>]
          Subset embedded fonts to only the characters used (default: true). Pass `=false` to embed full font files
          
          [env: VLC_SUBSET_FONTS=]

      --missing-fonts <MISSING_FONTS>
          Missing-font behavior: fallback silently, warn, or error
          
          [env: VLC_MISSING_FONTS=]
          [possible values: fallback, warn, error]

      --max-v8-heap-size-mb <MAX_V8_HEAP_SIZE_MB>
          Maximum V8 heap size per worker in megabytes, at least 64 [default: 0 = no limit]
          
          [env: VLC_MAX_V8_HEAP_SIZE_MB=]

      --max-v8-execution-time-secs <MAX_V8_EXECUTION_TIME_SECS>
          Maximum V8 execution time in seconds [default: 0 = no limit]
          
          [env: VLC_MAX_V8_EXECUTION_TIME_SECS=]

      --gc-after-conversion[=<BOOL>]
          Run V8 garbage collection after each conversion to release memory (default: false)
          
          [env: VLC_GC_AFTER_CONVERSION=]

      --vega-plugin <path|URL>
          Vega plugin: file path (`.js`/`.mjs`) or URL (`https://...`). The plugin must be a single ESM module that exports a default function accepting a vega object. Multi-file plugins should be pre-bundled with esbuild or Rollup. URL plugins auto-allow their domain for imports. May be specified multiple times; plugins execute in order. Put inline ESM plugins in `--vlc-config`
          
          [env: VLC_VEGA_PLUGIN=]

      --plugin-import-domains <PLUGIN_IMPORT_DOMAINS>
          Domains allowed for HTTP imports in plugins, `;`-separated. Examples: `'*'` (any), `'esm.sh'`, `'*.jsdelivr.net'`. May be specified multiple times
          
          [env: VLC_PLUGIN_IMPORT_DOMAINS=]

      --font-dir <PATH>
          Additional directory to search for fonts. Repeat the flag to register multiple directories (`--font-dir /a --font-dir /b`). The combined list is registered when the process starts
          
          [env: VLC_FONT_DIR=]

      --google-fonts-cache-size-mb <MB>
          Capacity of the on-disk Google Fonts cache, in megabytes. `0` uses the default capacity of 512 MB
          
          [env: VLC_GOOGLE_FONTS_CACHE_SIZE_MB=]

      --default-theme <THEME|null>
          Default Vega-Lite theme applied when a request omits `theme`. Pass the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_THEME=]

      --default-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_FORMAT_LOCALE=]

      --default-time-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-time-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_TIME_FORMAT_LOCALE=]

      --themes <JSON|FILE.json|FILE.jsonc|null>
          Custom named themes as an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a map loaded from the `--vlc-config` file
          
          [env: VLC_THEMES=]

      --log-level <LOG_LEVEL>
          Log level for Vega/Vega-Lite messages
          
          [env: VLC_LOG_LEVEL=]
          [default: warn]
          [possible values: error, warn, info, debug]

      --log-format <LOG_FORMAT>
          Log output format. `text` is human-readable; `json` emits one structured line per event for log aggregators

          Possible values:
          - text: Human-readable text logs
          - json: Flat structured JSON logs
          
          [env: VLC_LOG_FORMAT=]
          [default: text]

      --log-filter <DIRECTIVE>
          Raw `tracing-subscriber::EnvFilter` directive (e.g. `"vl_convert=debug,tower_http=info"`). When set, this wins over `--log-level`. When unset, a directive is synthesized from `--log-level`
          
          [env: VLC_LOG_FILTER=]

  -h, --help
          Print help (see a summary with '-h')

svg2jpeg#

Convert an SVG image to a JPEG image

Usage: vl-convert svg2jpeg [OPTIONS]

Options:
  -i, --input <INPUT>
          Path to input SVG file. Reads from stdin if omitted or set to "-"

      --vlc-config <disabled|PATH>
          Converter config: a path to a JSONC config file, or the reserved value `disabled` to skip config-file loading. Relative paths resolve from the current working directory. When omitted, the platform default config path is loaded if it exists
          
          [env: VLC_CONFIG=]

      --base-url <default|disabled|URL|PATH>
          Base URL for resolving relative data and image paths. Reserved values: `default` (use vega-datasets CDN), `disabled` (relative paths error). Otherwise either a URL with scheme (`https://...`, `file://...`) or an absolute filesystem path. Relative paths are rejected
          
          [env: VLC_BASE_URL=]

  -o, --output <OUTPUT>
          Path to output JPEG file to be created. Writes to stdout if omitted or set to "-"

      --allowed-base-urls <none|net|all|URL_PREFIX>
          Allowed base URLs for data and images. Reserved single-value shortcuts: `none` (block all), `net` (HTTP/HTTPS only, no filesystem), `all` (allow everything incl. filesystem). Otherwise a `;`-separated list of CSP-style patterns: `"https:"` (scheme), `"https://example.com/"` (prefix), `"/data/"` (absolute filesystem path). Long allowlists belong in `--vlc-config` JSONC
          
          [env: VLC_ALLOWED_BASE_URLS=]

      --scale <SCALE>
          Image scale factor
          
          [default: 1.0]

      --google-font <GOOGLE_FONT>
          Register a font from Google Fonts. Use "Family" for all variants, or "Family:400,700italic" for specific weight/style combinations. May be specified multiple times; `;` separates entries when passed via `VLC_GOOGLE_FONT`
          
          [env: VLC_GOOGLE_FONT=]

  -q, --quality <QUALITY>
          JPEG quality between 0 (worst) and 100 (best)
          
          [default: 90]

      --google-font-variant-threshold <N>
          Maximum number of Google Font variants one conversion may load, counting configured, requested, and automatically discovered families. The conversion fails once the cap is reached; a single family may carry the total past it. `0` disables the cap
          
          [env: VLC_GOOGLE_FONT_VARIANT_THRESHOLD=]

      --auto-google-fonts[=<BOOL>]
          Automatically download missing fonts from Google Fonts (default: false)
          
          [env: VLC_AUTO_GOOGLE_FONTS=]

      --embed-local-fonts[=<BOOL>]
          Embed locally installed fonts as base64 @font-face in HTML and SVG output (default: false)
          
          [env: VLC_EMBED_LOCAL_FONTS=]

      --subset-fonts[=<BOOL>]
          Subset embedded fonts to only the characters used (default: true). Pass `=false` to embed full font files
          
          [env: VLC_SUBSET_FONTS=]

      --missing-fonts <MISSING_FONTS>
          Missing-font behavior: fallback silently, warn, or error
          
          [env: VLC_MISSING_FONTS=]
          [possible values: fallback, warn, error]

      --max-v8-heap-size-mb <MAX_V8_HEAP_SIZE_MB>
          Maximum V8 heap size per worker in megabytes, at least 64 [default: 0 = no limit]
          
          [env: VLC_MAX_V8_HEAP_SIZE_MB=]

      --max-v8-execution-time-secs <MAX_V8_EXECUTION_TIME_SECS>
          Maximum V8 execution time in seconds [default: 0 = no limit]
          
          [env: VLC_MAX_V8_EXECUTION_TIME_SECS=]

      --gc-after-conversion[=<BOOL>]
          Run V8 garbage collection after each conversion to release memory (default: false)
          
          [env: VLC_GC_AFTER_CONVERSION=]

      --vega-plugin <path|URL>
          Vega plugin: file path (`.js`/`.mjs`) or URL (`https://...`). The plugin must be a single ESM module that exports a default function accepting a vega object. Multi-file plugins should be pre-bundled with esbuild or Rollup. URL plugins auto-allow their domain for imports. May be specified multiple times; plugins execute in order. Put inline ESM plugins in `--vlc-config`
          
          [env: VLC_VEGA_PLUGIN=]

      --plugin-import-domains <PLUGIN_IMPORT_DOMAINS>
          Domains allowed for HTTP imports in plugins, `;`-separated. Examples: `'*'` (any), `'esm.sh'`, `'*.jsdelivr.net'`. May be specified multiple times
          
          [env: VLC_PLUGIN_IMPORT_DOMAINS=]

      --font-dir <PATH>
          Additional directory to search for fonts. Repeat the flag to register multiple directories (`--font-dir /a --font-dir /b`). The combined list is registered when the process starts
          
          [env: VLC_FONT_DIR=]

      --google-fonts-cache-size-mb <MB>
          Capacity of the on-disk Google Fonts cache, in megabytes. `0` uses the default capacity of 512 MB
          
          [env: VLC_GOOGLE_FONTS_CACHE_SIZE_MB=]

      --default-theme <THEME|null>
          Default Vega-Lite theme applied when a request omits `theme`. Pass the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_THEME=]

      --default-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_FORMAT_LOCALE=]

      --default-time-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-time-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_TIME_FORMAT_LOCALE=]

      --themes <JSON|FILE.json|FILE.jsonc|null>
          Custom named themes as an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a map loaded from the `--vlc-config` file
          
          [env: VLC_THEMES=]

      --log-level <LOG_LEVEL>
          Log level for Vega/Vega-Lite messages
          
          [env: VLC_LOG_LEVEL=]
          [default: warn]
          [possible values: error, warn, info, debug]

      --log-format <LOG_FORMAT>
          Log output format. `text` is human-readable; `json` emits one structured line per event for log aggregators

          Possible values:
          - text: Human-readable text logs
          - json: Flat structured JSON logs
          
          [env: VLC_LOG_FORMAT=]
          [default: text]

      --log-filter <DIRECTIVE>
          Raw `tracing-subscriber::EnvFilter` directive (e.g. `"vl_convert=debug,tower_http=info"`). When set, this wins over `--log-level`. When unset, a directive is synthesized from `--log-level`
          
          [env: VLC_LOG_FILTER=]

  -h, --help
          Print help (see a summary with '-h')

svg2pdf#

Convert an SVG image to a PDF document

Usage: vl-convert svg2pdf [OPTIONS]

Options:
  -i, --input <INPUT>
          Path to input SVG file. Reads from stdin if omitted or set to "-"

      --vlc-config <disabled|PATH>
          Converter config: a path to a JSONC config file, or the reserved value `disabled` to skip config-file loading. Relative paths resolve from the current working directory. When omitted, the platform default config path is loaded if it exists
          
          [env: VLC_CONFIG=]

      --base-url <default|disabled|URL|PATH>
          Base URL for resolving relative data and image paths. Reserved values: `default` (use vega-datasets CDN), `disabled` (relative paths error). Otherwise either a URL with scheme (`https://...`, `file://...`) or an absolute filesystem path. Relative paths are rejected
          
          [env: VLC_BASE_URL=]

  -o, --output <OUTPUT>
          Path to output PDF file to be created. Writes to stdout if omitted or set to "-"

      --allowed-base-urls <none|net|all|URL_PREFIX>
          Allowed base URLs for data and images. Reserved single-value shortcuts: `none` (block all), `net` (HTTP/HTTPS only, no filesystem), `all` (allow everything incl. filesystem). Otherwise a `;`-separated list of CSP-style patterns: `"https:"` (scheme), `"https://example.com/"` (prefix), `"/data/"` (absolute filesystem path). Long allowlists belong in `--vlc-config` JSONC
          
          [env: VLC_ALLOWED_BASE_URLS=]

      --google-font <GOOGLE_FONT>
          Register a font from Google Fonts. Use "Family" for all variants, or "Family:400,700italic" for specific weight/style combinations. May be specified multiple times; `;` separates entries when passed via `VLC_GOOGLE_FONT`
          
          [env: VLC_GOOGLE_FONT=]

      --google-font-variant-threshold <N>
          Maximum number of Google Font variants one conversion may load, counting configured, requested, and automatically discovered families. The conversion fails once the cap is reached; a single family may carry the total past it. `0` disables the cap
          
          [env: VLC_GOOGLE_FONT_VARIANT_THRESHOLD=]

      --auto-google-fonts[=<BOOL>]
          Automatically download missing fonts from Google Fonts (default: false)
          
          [env: VLC_AUTO_GOOGLE_FONTS=]

      --embed-local-fonts[=<BOOL>]
          Embed locally installed fonts as base64 @font-face in HTML and SVG output (default: false)
          
          [env: VLC_EMBED_LOCAL_FONTS=]

      --subset-fonts[=<BOOL>]
          Subset embedded fonts to only the characters used (default: true). Pass `=false` to embed full font files
          
          [env: VLC_SUBSET_FONTS=]

      --missing-fonts <MISSING_FONTS>
          Missing-font behavior: fallback silently, warn, or error
          
          [env: VLC_MISSING_FONTS=]
          [possible values: fallback, warn, error]

      --max-v8-heap-size-mb <MAX_V8_HEAP_SIZE_MB>
          Maximum V8 heap size per worker in megabytes, at least 64 [default: 0 = no limit]
          
          [env: VLC_MAX_V8_HEAP_SIZE_MB=]

      --max-v8-execution-time-secs <MAX_V8_EXECUTION_TIME_SECS>
          Maximum V8 execution time in seconds [default: 0 = no limit]
          
          [env: VLC_MAX_V8_EXECUTION_TIME_SECS=]

      --gc-after-conversion[=<BOOL>]
          Run V8 garbage collection after each conversion to release memory (default: false)
          
          [env: VLC_GC_AFTER_CONVERSION=]

      --vega-plugin <path|URL>
          Vega plugin: file path (`.js`/`.mjs`) or URL (`https://...`). The plugin must be a single ESM module that exports a default function accepting a vega object. Multi-file plugins should be pre-bundled with esbuild or Rollup. URL plugins auto-allow their domain for imports. May be specified multiple times; plugins execute in order. Put inline ESM plugins in `--vlc-config`
          
          [env: VLC_VEGA_PLUGIN=]

      --plugin-import-domains <PLUGIN_IMPORT_DOMAINS>
          Domains allowed for HTTP imports in plugins, `;`-separated. Examples: `'*'` (any), `'esm.sh'`, `'*.jsdelivr.net'`. May be specified multiple times
          
          [env: VLC_PLUGIN_IMPORT_DOMAINS=]

      --font-dir <PATH>
          Additional directory to search for fonts. Repeat the flag to register multiple directories (`--font-dir /a --font-dir /b`). The combined list is registered when the process starts
          
          [env: VLC_FONT_DIR=]

      --google-fonts-cache-size-mb <MB>
          Capacity of the on-disk Google Fonts cache, in megabytes. `0` uses the default capacity of 512 MB
          
          [env: VLC_GOOGLE_FONTS_CACHE_SIZE_MB=]

      --default-theme <THEME|null>
          Default Vega-Lite theme applied when a request omits `theme`. Pass the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_THEME=]

      --default-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_FORMAT_LOCALE=]

      --default-time-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-time-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_TIME_FORMAT_LOCALE=]

      --themes <JSON|FILE.json|FILE.jsonc|null>
          Custom named themes as an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a map loaded from the `--vlc-config` file
          
          [env: VLC_THEMES=]

      --log-level <LOG_LEVEL>
          Log level for Vega/Vega-Lite messages
          
          [env: VLC_LOG_LEVEL=]
          [default: warn]
          [possible values: error, warn, info, debug]

      --log-format <LOG_FORMAT>
          Log output format. `text` is human-readable; `json` emits one structured line per event for log aggregators

          Possible values:
          - text: Human-readable text logs
          - json: Flat structured JSON logs
          
          [env: VLC_LOG_FORMAT=]
          [default: text]

      --log-filter <DIRECTIVE>
          Raw `tracing-subscriber::EnvFilter` directive (e.g. `"vl_convert=debug,tower_http=info"`). When set, this wins over `--log-level`. When unset, a directive is synthesized from `--log-level`
          
          [env: VLC_LOG_FILTER=]

  -h, --help
          Print help (see a summary with '-h')

JavaScript Bundling#

bundle-js#

Produce the JavaScript bundle used by Vega Embed integrations

Usage: vl-convert bundle-js [OPTIONS]

Options:
      --snippet <SNIPPET>
          Path to a JavaScript snippet to bundle. Reads from stdin if set to "-"

      --vlc-config <disabled|PATH>
          Converter config: a path to a JSONC config file, or the reserved value `disabled` to skip config-file loading. Relative paths resolve from the current working directory. When omitted, the platform default config path is loaded if it exists
          
          [env: VLC_CONFIG=]

      --base-url <default|disabled|URL|PATH>
          Base URL for resolving relative data and image paths. Reserved values: `default` (use vega-datasets CDN), `disabled` (relative paths error). Otherwise either a URL with scheme (`https://...`, `file://...`) or an absolute filesystem path. Relative paths are rejected
          
          [env: VLC_BASE_URL=]

  -o, --output <OUTPUT>
          Path to output JavaScript file. Writes to stdout if omitted or set to "-"

      --allowed-base-urls <none|net|all|URL_PREFIX>
          Allowed base URLs for data and images. Reserved single-value shortcuts: `none` (block all), `net` (HTTP/HTTPS only, no filesystem), `all` (allow everything incl. filesystem). Otherwise a `;`-separated list of CSP-style patterns: `"https:"` (scheme), `"https://example.com/"` (prefix), `"/data/"` (absolute filesystem path). Long allowlists belong in `--vlc-config` JSONC
          
          [env: VLC_ALLOWED_BASE_URLS=]

  -v, --vl-version <VL_VERSION>
          Vega-Lite version. One of 5.8, 5.14, 5.15, 5.16, 5.17, 5.20, 5.21, 6.1, 6.4
          
          [default: 6.4]

      --google-font <GOOGLE_FONT>
          Register a font from Google Fonts. Use "Family" for all variants, or "Family:400,700italic" for specific weight/style combinations. May be specified multiple times; `;` separates entries when passed via `VLC_GOOGLE_FONT`
          
          [env: VLC_GOOGLE_FONT=]

      --google-font-variant-threshold <N>
          Maximum number of Google Font variants one conversion may load, counting configured, requested, and automatically discovered families. The conversion fails once the cap is reached; a single family may carry the total past it. `0` disables the cap
          
          [env: VLC_GOOGLE_FONT_VARIANT_THRESHOLD=]

      --auto-google-fonts[=<BOOL>]
          Automatically download missing fonts from Google Fonts (default: false)
          
          [env: VLC_AUTO_GOOGLE_FONTS=]

      --embed-local-fonts[=<BOOL>]
          Embed locally installed fonts as base64 @font-face in HTML and SVG output (default: false)
          
          [env: VLC_EMBED_LOCAL_FONTS=]

      --subset-fonts[=<BOOL>]
          Subset embedded fonts to only the characters used (default: true). Pass `=false` to embed full font files
          
          [env: VLC_SUBSET_FONTS=]

      --missing-fonts <MISSING_FONTS>
          Missing-font behavior: fallback silently, warn, or error
          
          [env: VLC_MISSING_FONTS=]
          [possible values: fallback, warn, error]

      --max-v8-heap-size-mb <MAX_V8_HEAP_SIZE_MB>
          Maximum V8 heap size per worker in megabytes, at least 64 [default: 0 = no limit]
          
          [env: VLC_MAX_V8_HEAP_SIZE_MB=]

      --max-v8-execution-time-secs <MAX_V8_EXECUTION_TIME_SECS>
          Maximum V8 execution time in seconds [default: 0 = no limit]
          
          [env: VLC_MAX_V8_EXECUTION_TIME_SECS=]

      --gc-after-conversion[=<BOOL>]
          Run V8 garbage collection after each conversion to release memory (default: false)
          
          [env: VLC_GC_AFTER_CONVERSION=]

      --vega-plugin <path|URL>
          Vega plugin: file path (`.js`/`.mjs`) or URL (`https://...`). The plugin must be a single ESM module that exports a default function accepting a vega object. Multi-file plugins should be pre-bundled with esbuild or Rollup. URL plugins auto-allow their domain for imports. May be specified multiple times; plugins execute in order. Put inline ESM plugins in `--vlc-config`
          
          [env: VLC_VEGA_PLUGIN=]

      --plugin-import-domains <PLUGIN_IMPORT_DOMAINS>
          Domains allowed for HTTP imports in plugins, `;`-separated. Examples: `'*'` (any), `'esm.sh'`, `'*.jsdelivr.net'`. May be specified multiple times
          
          [env: VLC_PLUGIN_IMPORT_DOMAINS=]

      --font-dir <PATH>
          Additional directory to search for fonts. Repeat the flag to register multiple directories (`--font-dir /a --font-dir /b`). The combined list is registered when the process starts
          
          [env: VLC_FONT_DIR=]

      --google-fonts-cache-size-mb <MB>
          Capacity of the on-disk Google Fonts cache, in megabytes. `0` uses the default capacity of 512 MB
          
          [env: VLC_GOOGLE_FONTS_CACHE_SIZE_MB=]

      --default-theme <THEME|null>
          Default Vega-Lite theme applied when a request omits `theme`. Pass the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_THEME=]

      --default-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_FORMAT_LOCALE=]

      --default-time-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-time-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_TIME_FORMAT_LOCALE=]

      --themes <JSON|FILE.json|FILE.jsonc|null>
          Custom named themes as an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a map loaded from the `--vlc-config` file
          
          [env: VLC_THEMES=]

      --log-level <LOG_LEVEL>
          Log level for Vega/Vega-Lite messages
          
          [env: VLC_LOG_LEVEL=]
          [default: warn]
          [possible values: error, warn, info, debug]

      --log-format <LOG_FORMAT>
          Log output format. `text` is human-readable; `json` emits one structured line per event for log aggregators

          Possible values:
          - text: Human-readable text logs
          - json: Flat structured JSON logs
          
          [env: VLC_LOG_FORMAT=]
          [default: text]

      --log-filter <DIRECTIVE>
          Raw `tracing-subscriber::EnvFilter` directive (e.g. `"vl_convert=debug,tower_http=info"`). When set, this wins over `--log-level`. When unset, a directive is synthesized from `--log-level`
          
          [env: VLC_LOG_FILTER=]

  -h, --help
          Print help (see a summary with '-h')

Themes and Config#

ls-themes#

List available themes

Usage: vl-convert ls-themes [OPTIONS]

Options:
      --vlc-config <disabled|PATH>
          Converter config: a path to a JSONC config file, or the reserved value `disabled` to skip config-file loading. Relative paths resolve from the current working directory. When omitted, the platform default config path is loaded if it exists
          
          [env: VLC_CONFIG=]

      --base-url <default|disabled|URL|PATH>
          Base URL for resolving relative data and image paths. Reserved values: `default` (use vega-datasets CDN), `disabled` (relative paths error). Otherwise either a URL with scheme (`https://...`, `file://...`) or an absolute filesystem path. Relative paths are rejected
          
          [env: VLC_BASE_URL=]

      --allowed-base-urls <none|net|all|URL_PREFIX>
          Allowed base URLs for data and images. Reserved single-value shortcuts: `none` (block all), `net` (HTTP/HTTPS only, no filesystem), `all` (allow everything incl. filesystem). Otherwise a `;`-separated list of CSP-style patterns: `"https:"` (scheme), `"https://example.com/"` (prefix), `"/data/"` (absolute filesystem path). Long allowlists belong in `--vlc-config` JSONC
          
          [env: VLC_ALLOWED_BASE_URLS=]

      --google-font <GOOGLE_FONT>
          Register a font from Google Fonts. Use "Family" for all variants, or "Family:400,700italic" for specific weight/style combinations. May be specified multiple times; `;` separates entries when passed via `VLC_GOOGLE_FONT`
          
          [env: VLC_GOOGLE_FONT=]

      --google-font-variant-threshold <N>
          Maximum number of Google Font variants one conversion may load, counting configured, requested, and automatically discovered families. The conversion fails once the cap is reached; a single family may carry the total past it. `0` disables the cap
          
          [env: VLC_GOOGLE_FONT_VARIANT_THRESHOLD=]

      --auto-google-fonts[=<BOOL>]
          Automatically download missing fonts from Google Fonts (default: false)
          
          [env: VLC_AUTO_GOOGLE_FONTS=]

      --embed-local-fonts[=<BOOL>]
          Embed locally installed fonts as base64 @font-face in HTML and SVG output (default: false)
          
          [env: VLC_EMBED_LOCAL_FONTS=]

      --subset-fonts[=<BOOL>]
          Subset embedded fonts to only the characters used (default: true). Pass `=false` to embed full font files
          
          [env: VLC_SUBSET_FONTS=]

      --missing-fonts <MISSING_FONTS>
          Missing-font behavior: fallback silently, warn, or error
          
          [env: VLC_MISSING_FONTS=]
          [possible values: fallback, warn, error]

      --max-v8-heap-size-mb <MAX_V8_HEAP_SIZE_MB>
          Maximum V8 heap size per worker in megabytes, at least 64 [default: 0 = no limit]
          
          [env: VLC_MAX_V8_HEAP_SIZE_MB=]

      --max-v8-execution-time-secs <MAX_V8_EXECUTION_TIME_SECS>
          Maximum V8 execution time in seconds [default: 0 = no limit]
          
          [env: VLC_MAX_V8_EXECUTION_TIME_SECS=]

      --gc-after-conversion[=<BOOL>]
          Run V8 garbage collection after each conversion to release memory (default: false)
          
          [env: VLC_GC_AFTER_CONVERSION=]

      --vega-plugin <path|URL>
          Vega plugin: file path (`.js`/`.mjs`) or URL (`https://...`). The plugin must be a single ESM module that exports a default function accepting a vega object. Multi-file plugins should be pre-bundled with esbuild or Rollup. URL plugins auto-allow their domain for imports. May be specified multiple times; plugins execute in order. Put inline ESM plugins in `--vlc-config`
          
          [env: VLC_VEGA_PLUGIN=]

      --plugin-import-domains <PLUGIN_IMPORT_DOMAINS>
          Domains allowed for HTTP imports in plugins, `;`-separated. Examples: `'*'` (any), `'esm.sh'`, `'*.jsdelivr.net'`. May be specified multiple times
          
          [env: VLC_PLUGIN_IMPORT_DOMAINS=]

      --font-dir <PATH>
          Additional directory to search for fonts. Repeat the flag to register multiple directories (`--font-dir /a --font-dir /b`). The combined list is registered when the process starts
          
          [env: VLC_FONT_DIR=]

      --google-fonts-cache-size-mb <MB>
          Capacity of the on-disk Google Fonts cache, in megabytes. `0` uses the default capacity of 512 MB
          
          [env: VLC_GOOGLE_FONTS_CACHE_SIZE_MB=]

      --default-theme <THEME|null>
          Default Vega-Lite theme applied when a request omits `theme`. Pass the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_THEME=]

      --default-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_FORMAT_LOCALE=]

      --default-time-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-time-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_TIME_FORMAT_LOCALE=]

      --themes <JSON|FILE.json|FILE.jsonc|null>
          Custom named themes as an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a map loaded from the `--vlc-config` file
          
          [env: VLC_THEMES=]

      --log-level <LOG_LEVEL>
          Log level for Vega/Vega-Lite messages
          
          [env: VLC_LOG_LEVEL=]
          [default: warn]
          [possible values: error, warn, info, debug]

      --log-format <LOG_FORMAT>
          Log output format. `text` is human-readable; `json` emits one structured line per event for log aggregators

          Possible values:
          - text: Human-readable text logs
          - json: Flat structured JSON logs
          
          [env: VLC_LOG_FORMAT=]
          [default: text]

      --log-filter <DIRECTIVE>
          Raw `tracing-subscriber::EnvFilter` directive (e.g. `"vl_convert=debug,tower_http=info"`). When set, this wins over `--log-level`. When unset, a directive is synthesized from `--log-level`
          
          [env: VLC_LOG_FILTER=]

  -h, --help
          Print help (see a summary with '-h')

cat-theme#

Print the config JSON for a theme

Usage: vl-convert cat-theme [OPTIONS] <THEME>

Arguments:
  <THEME>
          Name of a theme

Options:
      --vlc-config <disabled|PATH>
          Converter config: a path to a JSONC config file, or the reserved value `disabled` to skip config-file loading. Relative paths resolve from the current working directory. When omitted, the platform default config path is loaded if it exists
          
          [env: VLC_CONFIG=]

      --base-url <default|disabled|URL|PATH>
          Base URL for resolving relative data and image paths. Reserved values: `default` (use vega-datasets CDN), `disabled` (relative paths error). Otherwise either a URL with scheme (`https://...`, `file://...`) or an absolute filesystem path. Relative paths are rejected
          
          [env: VLC_BASE_URL=]

      --allowed-base-urls <none|net|all|URL_PREFIX>
          Allowed base URLs for data and images. Reserved single-value shortcuts: `none` (block all), `net` (HTTP/HTTPS only, no filesystem), `all` (allow everything incl. filesystem). Otherwise a `;`-separated list of CSP-style patterns: `"https:"` (scheme), `"https://example.com/"` (prefix), `"/data/"` (absolute filesystem path). Long allowlists belong in `--vlc-config` JSONC
          
          [env: VLC_ALLOWED_BASE_URLS=]

      --google-font <GOOGLE_FONT>
          Register a font from Google Fonts. Use "Family" for all variants, or "Family:400,700italic" for specific weight/style combinations. May be specified multiple times; `;` separates entries when passed via `VLC_GOOGLE_FONT`
          
          [env: VLC_GOOGLE_FONT=]

      --google-font-variant-threshold <N>
          Maximum number of Google Font variants one conversion may load, counting configured, requested, and automatically discovered families. The conversion fails once the cap is reached; a single family may carry the total past it. `0` disables the cap
          
          [env: VLC_GOOGLE_FONT_VARIANT_THRESHOLD=]

      --auto-google-fonts[=<BOOL>]
          Automatically download missing fonts from Google Fonts (default: false)
          
          [env: VLC_AUTO_GOOGLE_FONTS=]

      --embed-local-fonts[=<BOOL>]
          Embed locally installed fonts as base64 @font-face in HTML and SVG output (default: false)
          
          [env: VLC_EMBED_LOCAL_FONTS=]

      --subset-fonts[=<BOOL>]
          Subset embedded fonts to only the characters used (default: true). Pass `=false` to embed full font files
          
          [env: VLC_SUBSET_FONTS=]

      --missing-fonts <MISSING_FONTS>
          Missing-font behavior: fallback silently, warn, or error
          
          [env: VLC_MISSING_FONTS=]
          [possible values: fallback, warn, error]

      --max-v8-heap-size-mb <MAX_V8_HEAP_SIZE_MB>
          Maximum V8 heap size per worker in megabytes, at least 64 [default: 0 = no limit]
          
          [env: VLC_MAX_V8_HEAP_SIZE_MB=]

      --max-v8-execution-time-secs <MAX_V8_EXECUTION_TIME_SECS>
          Maximum V8 execution time in seconds [default: 0 = no limit]
          
          [env: VLC_MAX_V8_EXECUTION_TIME_SECS=]

      --gc-after-conversion[=<BOOL>]
          Run V8 garbage collection after each conversion to release memory (default: false)
          
          [env: VLC_GC_AFTER_CONVERSION=]

      --vega-plugin <path|URL>
          Vega plugin: file path (`.js`/`.mjs`) or URL (`https://...`). The plugin must be a single ESM module that exports a default function accepting a vega object. Multi-file plugins should be pre-bundled with esbuild or Rollup. URL plugins auto-allow their domain for imports. May be specified multiple times; plugins execute in order. Put inline ESM plugins in `--vlc-config`
          
          [env: VLC_VEGA_PLUGIN=]

      --plugin-import-domains <PLUGIN_IMPORT_DOMAINS>
          Domains allowed for HTTP imports in plugins, `;`-separated. Examples: `'*'` (any), `'esm.sh'`, `'*.jsdelivr.net'`. May be specified multiple times
          
          [env: VLC_PLUGIN_IMPORT_DOMAINS=]

      --font-dir <PATH>
          Additional directory to search for fonts. Repeat the flag to register multiple directories (`--font-dir /a --font-dir /b`). The combined list is registered when the process starts
          
          [env: VLC_FONT_DIR=]

      --google-fonts-cache-size-mb <MB>
          Capacity of the on-disk Google Fonts cache, in megabytes. `0` uses the default capacity of 512 MB
          
          [env: VLC_GOOGLE_FONTS_CACHE_SIZE_MB=]

      --default-theme <THEME|null>
          Default Vega-Lite theme applied when a request omits `theme`. Pass the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_THEME=]

      --default-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_FORMAT_LOCALE=]

      --default-time-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-time-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_TIME_FORMAT_LOCALE=]

      --themes <JSON|FILE.json|FILE.jsonc|null>
          Custom named themes as an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a map loaded from the `--vlc-config` file
          
          [env: VLC_THEMES=]

      --log-level <LOG_LEVEL>
          Log level for Vega/Vega-Lite messages
          
          [env: VLC_LOG_LEVEL=]
          [default: warn]
          [possible values: error, warn, info, debug]

      --log-format <LOG_FORMAT>
          Log output format. `text` is human-readable; `json` emits one structured line per event for log aggregators

          Possible values:
          - text: Human-readable text logs
          - json: Flat structured JSON logs
          
          [env: VLC_LOG_FORMAT=]
          [default: text]

      --log-filter <DIRECTIVE>
          Raw `tracing-subscriber::EnvFilter` directive (e.g. `"vl_convert=debug,tower_http=info"`). When set, this wins over `--log-level`. When unset, a directive is synthesized from `--log-level`
          
          [env: VLC_LOG_FILTER=]

  -h, --help
          Print help (see a summary with '-h')

config-path#

Print the default vlc-config file path

Usage: vl-convert config-path [OPTIONS]

Options:
      --vlc-config <disabled|PATH>
          Converter config: a path to a JSONC config file, or the reserved value `disabled` to skip config-file loading. Relative paths resolve from the current working directory. When omitted, the platform default config path is loaded if it exists
          
          [env: VLC_CONFIG=]

      --base-url <default|disabled|URL|PATH>
          Base URL for resolving relative data and image paths. Reserved values: `default` (use vega-datasets CDN), `disabled` (relative paths error). Otherwise either a URL with scheme (`https://...`, `file://...`) or an absolute filesystem path. Relative paths are rejected
          
          [env: VLC_BASE_URL=]

      --allowed-base-urls <none|net|all|URL_PREFIX>
          Allowed base URLs for data and images. Reserved single-value shortcuts: `none` (block all), `net` (HTTP/HTTPS only, no filesystem), `all` (allow everything incl. filesystem). Otherwise a `;`-separated list of CSP-style patterns: `"https:"` (scheme), `"https://example.com/"` (prefix), `"/data/"` (absolute filesystem path). Long allowlists belong in `--vlc-config` JSONC
          
          [env: VLC_ALLOWED_BASE_URLS=]

      --google-font <GOOGLE_FONT>
          Register a font from Google Fonts. Use "Family" for all variants, or "Family:400,700italic" for specific weight/style combinations. May be specified multiple times; `;` separates entries when passed via `VLC_GOOGLE_FONT`
          
          [env: VLC_GOOGLE_FONT=]

      --google-font-variant-threshold <N>
          Maximum number of Google Font variants one conversion may load, counting configured, requested, and automatically discovered families. The conversion fails once the cap is reached; a single family may carry the total past it. `0` disables the cap
          
          [env: VLC_GOOGLE_FONT_VARIANT_THRESHOLD=]

      --auto-google-fonts[=<BOOL>]
          Automatically download missing fonts from Google Fonts (default: false)
          
          [env: VLC_AUTO_GOOGLE_FONTS=]

      --embed-local-fonts[=<BOOL>]
          Embed locally installed fonts as base64 @font-face in HTML and SVG output (default: false)
          
          [env: VLC_EMBED_LOCAL_FONTS=]

      --subset-fonts[=<BOOL>]
          Subset embedded fonts to only the characters used (default: true). Pass `=false` to embed full font files
          
          [env: VLC_SUBSET_FONTS=]

      --missing-fonts <MISSING_FONTS>
          Missing-font behavior: fallback silently, warn, or error
          
          [env: VLC_MISSING_FONTS=]
          [possible values: fallback, warn, error]

      --max-v8-heap-size-mb <MAX_V8_HEAP_SIZE_MB>
          Maximum V8 heap size per worker in megabytes, at least 64 [default: 0 = no limit]
          
          [env: VLC_MAX_V8_HEAP_SIZE_MB=]

      --max-v8-execution-time-secs <MAX_V8_EXECUTION_TIME_SECS>
          Maximum V8 execution time in seconds [default: 0 = no limit]
          
          [env: VLC_MAX_V8_EXECUTION_TIME_SECS=]

      --gc-after-conversion[=<BOOL>]
          Run V8 garbage collection after each conversion to release memory (default: false)
          
          [env: VLC_GC_AFTER_CONVERSION=]

      --vega-plugin <path|URL>
          Vega plugin: file path (`.js`/`.mjs`) or URL (`https://...`). The plugin must be a single ESM module that exports a default function accepting a vega object. Multi-file plugins should be pre-bundled with esbuild or Rollup. URL plugins auto-allow their domain for imports. May be specified multiple times; plugins execute in order. Put inline ESM plugins in `--vlc-config`
          
          [env: VLC_VEGA_PLUGIN=]

      --plugin-import-domains <PLUGIN_IMPORT_DOMAINS>
          Domains allowed for HTTP imports in plugins, `;`-separated. Examples: `'*'` (any), `'esm.sh'`, `'*.jsdelivr.net'`. May be specified multiple times
          
          [env: VLC_PLUGIN_IMPORT_DOMAINS=]

      --font-dir <PATH>
          Additional directory to search for fonts. Repeat the flag to register multiple directories (`--font-dir /a --font-dir /b`). The combined list is registered when the process starts
          
          [env: VLC_FONT_DIR=]

      --google-fonts-cache-size-mb <MB>
          Capacity of the on-disk Google Fonts cache, in megabytes. `0` uses the default capacity of 512 MB
          
          [env: VLC_GOOGLE_FONTS_CACHE_SIZE_MB=]

      --default-theme <THEME|null>
          Default Vega-Lite theme applied when a request omits `theme`. Pass the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_THEME=]

      --default-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_FORMAT_LOCALE=]

      --default-time-format-locale <LOCALE|JSON|FILE.json|FILE.jsonc|null>
          Default d3-time-format locale: a locale name string, an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a value loaded from the `--vlc-config` file
          
          [env: VLC_DEFAULT_TIME_FORMAT_LOCALE=]

      --themes <JSON|FILE.json|FILE.jsonc|null>
          Custom named themes as an inline JSON object literal, a path to a `.json` / `.jsonc` file, or the literal string `null` to clear a map loaded from the `--vlc-config` file
          
          [env: VLC_THEMES=]

      --log-level <LOG_LEVEL>
          Log level for Vega/Vega-Lite messages
          
          [env: VLC_LOG_LEVEL=]
          [default: warn]
          [possible values: error, warn, info, debug]

      --log-format <LOG_FORMAT>
          Log output format. `text` is human-readable; `json` emits one structured line per event for log aggregators

          Possible values:
          - text: Human-readable text logs
          - json: Flat structured JSON logs
          
          [env: VLC_LOG_FORMAT=]
          [default: text]

      --log-filter <DIRECTIVE>
          Raw `tracing-subscriber::EnvFilter` directive (e.g. `"vl_convert=debug,tower_http=info"`). When set, this wins over `--log-level`. When unset, a directive is synthesized from `--log-level`
          
          [env: VLC_LOG_FILTER=]

  -h, --help
          Print help (see a summary with '-h')

Server#

serve#

See the server CLI reference for startup options.