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.