Tooling

The Livt CLI

Build, test, package, and integrate Livt projects from one command-line workflow.

The livt command is the daily workflow for Livt projects. It validates source files, builds project output, runs simulations, manages packages, and prepares vendor projects from the same project file.

Overview

Most projects use a short loop while developing:

bash

livt validate
livt build
livt test

Run livt --help for the command list, or livt <command> --help for command-specific help.

Everyday Commands

Command	Use
`livt init`	Initialize a project in the current folder.
`livt new <name>`	Create a new project folder.
`livt validate`	Check source files and report diagnostics.
`livt build`	Build the project.
`livt test`	Run configured simulation tests.
`livt format <file>`	Format one Livt source file.
`livt stats`	Show project statistics.
`livt clean`	Remove build output and temporary files.

Build and Test

Use validate for fast checks, build when you need current project output, and test when behavior must be verified in simulation.

bash

livt build --verbose
livt test --run MyComponentTest
livt test --run MyComponentTest:ChecksResetState

Test components can also be configured in livt.toml:

toml

[tests]
components = ["MyComponentTest"]

Package Commands

Package commands make reusable code discoverable and reproducible. Search first, then add the package name and version directly from the result.

bash

livt search EthernetFrameClassifier
livt add EthernetFrameClassifier@0.1.0
livt sync
livt lock

Remove or inspect dependencies with:

bash

livt remove EthernetFrameClassifier
livt show Livt.IO

Vendor Commands

Vendor templates prepare project files for external tool flows. The Vivado templates place their workspace under .livt/vendor and show the selected options before the vendor tool is invoked.

bash

livt vendor vivado
livt vendor vivado-ip
livt vendor vivado-ip xc7a100tcsg324-1

See Vendor Integration for wrapper configuration, IP packaging, and test inclusion.

Configuration and Tools

Keep team-wide behavior in livt.toml. Use command-line flags for local one-off runs.

toml

[simulator]
tool = "ghdl"
path = "/opt/ghdl/bin/ghdl"

[build.debug]
warnings = ["all", "no-variable-divisor"]

GHDL is the default simulator. Machine-specific paths can also be supplied through LIVT_SIMULATOR and LIVT_GHDL_PATH.

Automation

Scripts and CI jobs should start with the same commands a developer runs locally:

bash

livt validate
livt test

Add package, vendor, and release jobs as the project matures. See CI/CD for a larger team workflow.

Exit Codes

Livt returns 0 on success and a non-zero exit code when a command fails. CI systems should treat any non-zero result as a failed run and show the command output to the developer.

Summary

Start with livt validate, livt build, and livt test. Use package commands for reuse, vendor commands for integration projects, and project configuration for settings that should be shared by the team.