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 a Node script, lved-cli.js, 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

The CLI ships as a self-contained Node script.

1. Download the latest CLI archive from the Releases page and unzip it.
2. Install Node.js 18 or newer (CI is tested on Node 22).
3. Run commands to test, validate, build, etc the UI project

Run it directly with Node:

node lved-cli.js --help

Authentication

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

• Environment variable (recommended): set LVGL_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 LVGL_CLI_TOKEN="your-token"
node lved-cli.js generate path/to/project

# Or pass it explicitly
node lved-cli.js generate path/to/project --token "your-token"

Quick start

# Generate C and H files from your XML project
node lved-cli.js generate path/to/project

# Validate XML and report problems
node lved-cli.js validate path/to/project

# Compile and run all UI tests headlessly
node lved-cli.js run-all-tests path/to/project

# Capture a screen as a PNG
node lved-cli.js screenshot path/to/project screens/home.xml --out home.png

Commands

Reference

Run node lved-cli.js <command> --help for the full, up-to-date options of any command.

generate

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

node lved-cli.js 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.

node lved-cli.js 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.

node lved-cli.js 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.

node lved-cli.js run-test <project-path> <testing-file> [options]
node lved-cli.js 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.

node lved-cli.js 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.

node lved-cli.js 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
      LVGL_CLI_TOKEN: ${{ secrets.LVGL_CLI_TOKEN }}
    steps:
      - uses: actions/checkout@v4

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

      - name: Download CLI
        # Latest Linux/macOS CLI build; see https://github.com/lvgl/lvgl_editor/releases for all assets
        run: |
          curl -L https://github.com/lvgl/lvgl_editor/releases/download/nightly/LVGL_Pro_CLI-nightly-linux-mac.zip -o lvgl-cli.zip
          unzip lvgl-cli.zip -d lvgl-cli

      - name: Generate code
        run: node ./lvgl-cli/lved-cli.js generate examples -s

      - name: Compile to run tests
        run: node ./lvgl-cli/lved-cli.js compile examples --target cli

      - name: Run UI tests
        run: node ./lvgl-cli/lved-cli.js run-all-tests examples

A full, working example lives in the project's PR-check workflow.

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
node lved-cli.js validate path/to/project --errorlimit 25
node lved-cli.js generate path/to/project

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