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')