CLI Reference#
Start the server with vl-convert serve. Global converter options can appear before or after serve. Server-specific options must follow it:
vl-convert [GLOBAL OPTIONS] serve [SERVER OPTIONS]
The help below is generated from the executable used to build the documentation. See Server Overview for a startup example and Configuration for configuration files and environment variables.
serve#
Run the HTTP conversion server
Usage: vl-convert serve [OPTIONS]
Options:
--host <HOST>
Bind address for the main HTTP listener (TCP). Mutually exclusive with `--unix-socket`
[env: VLC_HOST=]
--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=]
--port <PORT>
Port for the main HTTP listener (TCP). Mutually exclusive with `--unix-socket`
[env: VLC_PORT=]
--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=]
--unix-socket <PATH>
Bind the main HTTP listener on a UDS path instead of TCP (Unix only). Mutually exclusive with `--host` and `--port`
[env: VLC_UNIX_SOCKET=]
--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=]
--socket-mode <OCTAL>
Unix permission mode for UDS listeners (octal, e.g. 0600). Defaults to 0o600 when unset
[env: VLC_SOCKET_MODE=]
--admin-port <PORT>
Bind an admin listener on `<--admin-host>:<port>` for runtime reconfiguration (default host `127.0.0.1`). Mutually exclusive with `--admin-unix-socket`
[env: VLC_ADMIN_PORT=]
--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=]
--admin-host <HOST>
Bind address for the admin HTTP listener (TCP). Defaults to `127.0.0.1` and requires `--admin-port` (the admin listener is opt-in; setting only the host has no effect). Non-loopback values require `--admin-api-key` and fail validation without it
[env: VLC_ADMIN_HOST=]
--auto-google-fonts[=<BOOL>]
Automatically download missing fonts from Google Fonts (default: false)
[env: VLC_AUTO_GOOGLE_FONTS=]
--admin-unix-socket <PATH>
Bind the admin HTTP listener on a UDS path instead of TCP (Unix only). Mutually exclusive with `--admin-port`
[env: VLC_ADMIN_UNIX_SOCKET=]
--embed-local-fonts[=<BOOL>]
Embed locally installed fonts as base64 @font-face in HTML and SVG output (default: false)
[env: VLC_EMBED_LOCAL_FONTS=]
--admin-api-key <KEY>
API key for Bearer-token authentication on the admin listener. Independent of `--api-key`. When unset, access depends on UDS filesystem permissions or TCP loopback. A non-loopback TCP admin listener without a key fails startup
[env: VLC_ADMIN_API_KEY=]
--subset-fonts[=<BOOL>]
Subset embedded fonts to only the characters used (default: true). Pass `=false` to embed full font files
[env: VLC_SUBSET_FONTS=]
--dump-openapi[=<SPEC>]
Print an OpenAPI JSON document to stdout and exit. Defaults to the public API; pass `--dump-openapi=admin` for the admin API
[possible values: public, admin]
--missing-fonts <MISSING_FONTS>
Missing-font behavior: fallback silently, warn, or error
[env: VLC_MISSING_FONTS=]
[possible values: fallback, warn, error]
--api-key <KEY>
API key for Bearer-token authentication on the main listener
[env: VLC_API_KEY=]
--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=]
--workers <N>
Number of converter worker threads (must be >= 1). Defaults to the value loaded from `--vlc-config`, or 1 when the config does not set it
[env: VLC_WORKERS=]
--gc-after-conversion[=<BOOL>]
Run V8 garbage collection after each conversion to release memory (default: false)
[env: VLC_GC_AFTER_CONVERSION=]
--max-concurrent-requests <N>
Maximum simultaneous in-flight requests
[env: VLC_MAX_CONCURRENT_REQUESTS=]
--request-timeout-secs <SECS>
HTTP request timeout in seconds
[env: VLC_REQUEST_TIMEOUT_SECS=]
--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=]
--drain-timeout-secs <SECS>
Graceful shutdown drain timeout in seconds (default: 30)
[env: VLC_DRAIN_TIMEOUT_SECS=]
[default: 30]
--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=]
--reconfig-drain-timeout-secs <SECS>
Per-reconfig drain timeout in seconds. Defaults to the same value as `--drain-timeout-secs`
[env: VLC_RECONFIG_DRAIN_TIMEOUT_SECS=]
--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=]
--max-body-size-mb <MB>
Maximum request body size in megabytes
[env: VLC_MAX_BODY_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=]
--opaque-errors[=<BOOL>]
Return only HTTP status codes on error (no message bodies)
[env: VLC_OPAQUE_ERRORS=]
--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=]
--require-user-agent[=<BOOL>]
Reject requests without a User-Agent header
[env: VLC_REQUIRE_USER_AGENT=]
--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=]
--trust-proxy[=<BOOL>]
Trust X-Forwarded-For and X-Real-IP headers for client IP extraction. Only enable behind a trusted reverse proxy
[env: VLC_TRUST_PROXY=]
--cors-origin <ORIGIN>
Allowed CORS origin(s), comma-separated or `*`
[env: VLC_CORS_ORIGIN=]
--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]
--per-ip-budget-ms <MS>
Conversion-time budget per IP, in milliseconds per minute
[env: VLC_PER_IP_BUDGET_MS=]
--global-budget-ms <MS>
Total conversion-time budget for the server, in milliseconds per minute
[env: VLC_GLOBAL_BUDGET_MS=]
--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]
--budget-hold-ms <MS>
Per-request budget hold in milliseconds. Must be positive
[env: VLC_BUDGET_HOLD_MS=]
--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=]
--google-font-cache-miss-penalty-ms <MS>
Budget milliseconds charged for each Google Fonts cache miss
[env: VLC_GOOGLE_FONT_CACHE_MISS_PENALTY_MS=]
--ready-json[=<BOOL>]
Emit one JSON readiness line on stdout after all listeners bind. Useful for orchestrators / process supervisors
[env: VLC_READY_JSON=]
[default: false]
--exit-on-parent-close[=<BOOL>]
Exit when the parent process closes stdin (auto-enabled when a UDS listener is in use). Pass `=true`/`=false` to override the auto rule
[env: VLC_EXIT_ON_PARENT_CLOSE=]
--allow-google-fonts[=<BOOL>]
Allow per-request `google_fonts` overrides
[env: VLC_ALLOW_GOOGLE_FONTS=]
--allow-per-request-plugins[=<BOOL>]
Allow per-request Vega plugin overrides
[env: VLC_ALLOW_PER_REQUEST_PLUGINS=]
--max-ephemeral-workers <N>
Maximum concurrent ephemeral workers for per-request plugins
[env: VLC_MAX_EPHEMERAL_WORKERS=]
--per-request-plugin-import-domains <DOMAIN;DOMAIN;...>
Domains allowed for HTTP imports in per-request plugins. `;`-separated. May be specified multiple times
[env: VLC_PER_REQUEST_PLUGIN_IMPORT_DOMAINS=]
-h, --help
Print help (see a summary with '-h')