Tooling

The Livt CLI

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

The livt command-line tool is the main entry point for working with Livt projects. It creates projects, validates source files, builds design output, runs simulations, manages packages, prepares vendor projects, and publishes reusable packages.

All project commands expect a livt.toml in the current directory or a parent directory. When a command accepts a project path, use --project to point Livt at a specific project folder.

Everyday Workflow

Most projects use the same short loop:

bash

livt validate
livt build
livt test

Use validate when you want fast diagnostics without creating build output. Use build when you want the current design artifacts. Use test when behavior must be checked in simulation.

Commands Overview

Command	Purpose
`livt init`	Initialize a project in the current directory
`livt new <name>`	Create a new Livt project
`livt validate`	Check source files and report diagnostics
`livt build`	Build a Livt project
`livt test`	Run simulation tests
`livt format <file>`	Format a Livt source file in place
`livt stats`	Show project statistics
`livt clean`	Remove build output and temporary files
`livt search <query>`	Search the package registry
`livt show <package>`	Show information about an installed package
`livt add <package>`	Add a dependency
`livt remove <package>`	Remove a dependency
`livt sync`	Download and update dependencies
`livt lock`	Update the project lock file
`livt vendor <template>`	Create files for a vendor tool flow
`livt publish`	Publish a package

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

Creating Projects

Create a new project in a new folder:

bash

livt new packet-filter

Initialize the current folder instead:

bash

livt init

A project contains a livt.toml, source files, optional tests, and package metadata. Keep the project file under version control so the build, dependencies, and test components are visible to everyone using the project.

Validate and Build

bash

livt validate
livt build

validate checks source files and reports diagnostics. build performs the full project build and writes build output to the configured output folder.

Useful build options include:

bash

livt build --project path/to/project
livt build --verbose
livt build -W all
livt build -W no-variable-divisor
livt build -O all
livt build -O none

Warnings can also be configured in livt.toml:

toml

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

Test

bash

livt test

test builds the project, prepares configured test components, and runs them in the configured simulator. GHDL is the default simulator.

Run one test component:

bash

livt test --run MyComponentTest

Run one test method:

bash

livt test --run MyComponentTest:ChecksResetState

The short form is also available:

bash

livt test -r MyComponentTest

Test components can be listed in livt.toml:

toml

[tests]
components = ["MyComponentTest"]

Simulator Configuration

GHDL is the default simulator for livt test. If it is not on the system path, configure it in the project:

toml

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

For machine-specific setup, use environment variables instead:

bash

export LIVT_SIMULATOR=ghdl
export LIVT_GHDL_PATH=/opt/ghdl/bin/ghdl

The older simulator.path setting remains useful for existing projects that only need to specify the GHDL executable path.

Package Commands

Search the package registry:

bash

livt search EthernetFrameClassifier

Add a dependency from search output:

bash

livt add EthernetFrameClassifier@0.1.0

Synchronize dependencies and update the lock file:

bash

livt sync
livt lock

Remove a dependency:

bash

livt remove EthernetFrameClassifier

Show package information for a package available in the project:

bash

livt show Livt.IO

Dependencies are recorded in livt.toml:

toml

[dependencies]
Livt.IO = "0.2.0"

Vendor Integration

Vendor templates create project files for external tool flows:

bash

livt vendor vivado
livt vendor vivado-ip

The Vivado templates accept an optional part argument:

bash

livt vendor vivado-ip xc7a100tcsg324-1

The command shows the selected template and important options before invoking the vendor tool. Vivado output is placed under .livt/vendor, including project scripts, logs, openable projects, and package output where applicable.

Common Vivado settings live in livt.toml:

toml

[vendor.vivado]
part = "xc7a100tcsg324-1"

[vendor.vivado.ip]
component = "WebApp"
wrapper = "auto"
top = "webapp_wrapper"
include_tests = true

See the Vendor Integration chapter for wrapper behavior, standalone projects, and IP package details.

Format, Stats, and Clean

Format one source file:

bash

livt format src/MyComponent.lvt

Show project statistics:

bash

livt stats

Remove build output and temporary files:

bash

livt clean

clean is useful when switching branches, checking a fresh build, or removing old artifacts before a vendor flow.

Publish

bash

livt publish

Publishing uploads the current package to the package registry. Before publishing, make sure the package metadata is complete, the project builds, and all tests pass.

Common Options

Option	Use
`--help`, `-h`	Show global or command-specific help
`--version`	Print the Livt version
`--verbose`, `-v`	Show more detailed command output
`--project <path>`, `-p <path>`	Run a command for a specific project folder
`--warning <flags>`, `-W <flags>`	Configure warnings for this run
`--optimize <flags>`, `-O <flags>`	Configure build optimizations
`--run <filter>`, `-r <filter>`	Filter `livt test` to a component or method

Prefer project configuration for team-wide behavior and command-line options for one-off local runs.

Exit Codes

Livt commands return process exit codes so scripts and CI systems can react to success or failure. Treat 0 as success and any non-zero value as a failed run. For CI, run at least:

bash

livt validate
livt test

Larger projects often add package checks, vendor project creation, or synthesis jobs after the core Livt checks are green.

Troubleshooting

Symptom	First check
`livt` is not found	Run `livt --version` and inspect `PATH`.
No project is found	Run from a directory containing `livt.toml`, or pass `--project`.
Validation passes but simulation fails	Check GHDL and read the first assertion or analysis error.
A dependency cannot be resolved	Review `[dependencies]`, run `livt sync`, and inspect lock state.
Generated output looks stale	Confirm project and profile; use `livt clean` only when discarding generated output is intended.
A vendor command uses the wrong target	Review part, component, wrapper, and top settings.

Summary

The Livt CLI is the practical workflow surface for Livt projects. Start with livt validate, livt build, and livt test; use package commands to manage reuse; use vendor templates when a project needs integration artifacts; and keep project-level settings in livt.toml so builds are reproducible across machines.