CLI

The LVGL Pro command-line tool generates and compiles C code, validates and tests XML UIs, and captures screenshots — built for CI/CD pipelines and AI-driven workflows.

The CLI, along with the Editor, Figma plugin, and online viewer, is part of LVGL Pro, a professional toolkit to develop embedded UIs.

The LVGL Pro CLI is a command line tool bringing the great power of the Editor to the terminal. It's an npm-installed lvglpro command that generates and compiles C code from your XML, validates projects, runs headless UI tests, and captures screenshots, all without opening the GUI.

Because it's scriptable and headless, the CLI is the bridge between LVGL Pro and your automation: continuous integration, regression testing, and AI agents that write, validate, and visually verify UI on their own.

Why use the CLI?

Installation

1. Install Node.js 18 or newer (CI is tested on Node 22).
2. Install the CLI globally with npm:

npm install --global @lvgl/lvglpro

This puts lvglpro on your PATH.

lvglpro --help

Authentication

The CLI requires a Product or Platform license token. Provide it in one of two ways:

• Environment variable (recommended): set LVGLPRO_CLI_TOKEN and the CLI picks it up automatically. This is the best fit for CI, where you'd store the token as an encrypted secret.
• Command-line flag: pass --token <your-token> on any command.

# Picked up automatically from the environment
export LVGLPRO_CLI_TOKEN="your-token"
lvglpro generate path/to/project

# Or pass it explicitly
lvglpro generate path/to/project --token "your-token"

Quick start

# Generate C and H files from your XML project
lvglpro generate path/to/project

# Validate XML and report problems
lvglpro validate path/to/project

# Compile and run all UI tests headlessly
lvglpro run-all-tests path/to/project

# Capture a screen as a PNG
lvglpro screenshot path/to/project screens/home.xml --out home.png

Commands

Reference

Run lvglpro <command> --help for the full, up-to-date options of any command.

generate

Generate C and H code from the project's XML files.

lvglpro generate <project-path> [options]

compile

Compile the project into a runnable binary (runtime) for previewing or testing.

The runtime contains the compiled LVGL, the C code of the UI project, and some editor-specific C code. It is required to run the UI in the Editor or in the CLI.

lvglpro compile <project-path> [options]

validate

Check the project's XML for errors and report them. Exits non-zero on failure, so it doubles as a gate in CI and a fast feedback signal for AI agents.

lvglpro validate <project-path> [options]

run-test / run-all-tests

Run headless UI interaction tests defined in XML. run-test runs one file; run-all-tests discovers and runs every test in the project.

lvglpro run-test <project-path> <testing-file> [options]
lvglpro run-all-tests <project-path> [options]

<testing-file> is the path to a test XML, relative to <project-path>.

screenshot

Render a screen and save it as a PNG. Perfect for visual diffs and AI vision feedback.

lvglpro screenshot <project-path> <screen> [options]

<screen> is the path of the screen to capture, relative to <project-path>.

compare

Compare two project directories by file presence and normalized content. Use it to assert that generated output matches a known-good reference.

lvglpro compare <generated-path> <reference-path>

Use case: CI/CD pipelines

Run the CLI on every pull request to generate code, compile it, and run your UI tests automatically. Here's a GitHub Actions workflow that does exactly that:

name: LVGL Pro Check
on: [push, pull_request]

jobs:
    ui-check:
        runs-on: ubuntu-latest
        env:
            # Store your Pro license token as an encrypted repository secret
            LVGLPRO_CLI_TOKEN: ${{ secrets.LVGLPRO_CLI_TOKEN }}
        steps:
            - uses: actions/checkout@v4

            - uses: actions/setup-node@v4
              with:
                  node-version: '22'

            - name: Install CLI
              run: npm install --global @lvgl/lvglpro

            - name: Generate code
              run: lvglpro generate examples

            - name: Compile to run tests
              run: lvglpro compile examples --target cli

            - name: Run UI tests
              run: lvglpro run-all-tests examples

Use case: AI-driven UI development

The CLI gives an AI agent two things a language model otherwise lacks: objective validation and eyes. Together they form a closed feedback loop the model can run on its own.

1. Generate: the AI writes or edits XML for a component or screen.
2. Validate: validate returns precise, machine-readable errors. The AI fixes them and repeats until the project is clean. generate can also be used to export code.
3. See: screenshot renders the screen to a PNG.
4. Judge: a vision-capable model inspects the image, compares it to the intent, and decides what to change.
5. Iterate: back to step 1 until the UI looks right.

# 1–2: write XML, then check it
lvglpro validate path/to/project --errorlimit 25
lvglpro generate path/to/project

# 3: render what the user will actually see
lvglpro screenshot path/to/project screens/home.xml --out home.png --delay 200