LVGL Pro CLI

The LVGL Pro CLI provides command-line access to LVGL Pro Editor workflows. It can generate C code from XML projects, compile project runtimes, validate projects, compare generated output, run XML interaction tests, and capture screenshots.

NOTE: The LVGL Pro CLI requires a token to operate. You can obtain the token from your https://lvgl.io/pro dashboard, if your license supports it.

Features

• Generate C code from LVGL XML projects
• Compile editor or CLI runtimes
• Validate project XML and report contextual errors
• Compare generated output against reference directories
• Run one or all XML interaction tests in a headless runtime
• Capture screenshots from LVGL 9.5 or newer projects
• Keep the local LVGL resource cache synchronized with the CLI package

Installation

npm install --global @lvgl/lvglpro

Usage

lvglpro <command> [arguments] [options]

Use --help for the complete command list or <command> --help for command-specific options:

lvglpro --help
lvglpro generate --help

Authentication

Every command requires a valid LVGL license token. Pass it to an individual command with --token:

lvglpro generate ./my-project --token <license-token>

Alternatively, set LVGLPRO_CLI_TOKEN for the current shell or CI job:

# macOS/Linux
export LVGLPRO_CLI_TOKEN=<license-token>

# PowerShell
$env:LVGLPRO_CLI_TOKEN = '<license-token>'

The --token value takes precedence over LVGLPRO_CLI_TOKEN.

Resources

The CLI distribution includes lvgl-resources.zip. During normal setup, the CLI checks the cached resource hash and extracts updated resources into:

• Windows: %APPDATA%\lvgl-editor\resources
• macOS: ~/Library/Application Support/lvgl-editor/resources
• Linux: ~/.config/lvgl-editor/resources

generate and compile accept --skip-resources when the cache has already been prepared. This skips both the hash check and resource copy.

Commands

generate <project-path>

Generate C code from the XML project.

Options:

• --token <license-token>: Provide the license token for this command.
• --ignore-fonts: Skip font conversion.
• --ignore-images: Skip image conversion.
• --skip-resources: Skip checking and copying the resource cache.

compile <project-path>

Compile the project runtime.

Options:

• --target <target>: Build cli or editor output. Defaults to cli.
• --token <license-token>: Provide the license token for this command.
• --skip-resources: Skip checking and copying the resource cache.

The cli target builds the Node runtime used by test and screenshot commands. The editor target builds the web runtime used by the editor.

validate <project-path>

Validate the XML project and report files containing errors.

Options:

• -l, --errorlimit <amount>: Maximum number of errors to display. Defaults to 10.
• --token <license-token>: Provide the license token for this command.

compare <first-project-path> <second-project-path>

Recursively compare two directories and report missing, additional, or changed files.

Options:

• --token <license-token>: Provide the license token for this command.

run-test <project-path> <testing-file>

Run one XML interaction test. testing-file is relative to the project directory. A CLI runtime is built automatically if the project does not already contain one.

Options:

• --slowdown <number>: Delay test execution for observation. 0 is fastest and is the default.
• --token <license-token>: Provide the license token for this command.

run-all-tests <project-path>

Recursively run project XML files whose names start with test and end with .xml. A CLI runtime is built automatically if necessary.

Options:

• --slowdown <number>: Delay test execution for observation. 0 is fastest and is the default.
• --token <license-token>: Provide the license token for this command.

screenshot <project-path> <screen>

Capture a PNG of the selected screen. Screenshots require LVGL 9.5 or newer. A CLI runtime is built automatically if necessary.

Options:

• --out <out-file>: Output path. Defaults to <screen-name>.png in the current directory.
• --delay <delay>: Delay capture by the given number of milliseconds. Defaults to 0.
• --token <license-token>: Provide the license token for this command.

Examples

# Generate code without converting fonts or images
lvglpro generate ./my-project --ignore-fonts --ignore-images

# Generate code using an already-prepared resource cache
lvglpro generate ./my-project --skip-resources

# Compile the Node runtime used by CLI tests
lvglpro compile ./my-project --target cli

# Compile the editor web runtime
lvglpro compile ./my-project --target editor

# Validate a project and display at most five errors
lvglpro validate ./my-project --errorlimit 5

# Compare generated output with a reference directory
lvglpro compare ./output ./expected

# Run one interaction test
lvglpro run-test ./my-project tests/test-navigation.xml --slowdown 2

# Run every interaction test
lvglpro run-all-tests ./my-project

# Capture a screen after a 500 ms delay
lvglpro screenshot ./my-project screens/main.xml --delay 500 --out ./main.png