Tooling

CLI Reference

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

The livt command-line tool creates projects, checks source files, generates hardware descriptions, runs simulation tests, and manages packages. It complements the Livt extension in Visual Studio Code: both work with the same livt.toml manifest, so you can use the editor for interactive work and commands for repeatable tasks and automation.

This reference explains the common workflows and the options that change their behaviour. The examples can be run in the VS Code integrated terminal or another shell. Start with Installation if the livt command is not yet available.

Run commands for a project

Run project commands from the directory containing livt.toml. To target another project explicitly, use --project on commands that support it. This is especially useful when a workspace contains several projects: the terminal’s current directory determines the default target, independently of what you are viewing in the editor.

bash

livt validate
livt build
livt test

livt build --project path/to/project

Validation reports source problems without generating HDL. Building produces the configured design output. Testing prepares and runs simulation tests. Choose the command for the result you need; a successful build alone does not establish that the design behaves correctly.

Use livt --help for the command list and livt <command> --help for a command’s arguments and options. Command-specific help is also the place to check which options apply to that operation.

bash

livt --help
livt test --help
livt --version

test command help in the VS Code terminal — Command-specific help lists test selection, reporting, build settings, and automation options.

Choose options for the operation

Keep shared settings in livt.toml and use command options for an individual invocation. Options are not interchangeable between all commands. For example, --run selects tests, while --out-dir selects build output.

Option	Where to use it	Effect
`--help`, `-h`	Global or command help	Describe available arguments and options.
`--project`, `-p`	Project commands	Select the project directory. For `new`, select the parent directory instead.
`--verbose`, `-v`	Commands that offer detailed logging	Include more diagnostic output; for tests, include complete raw simulator output.
`--warning`, `-W`	`validate`, `build`, `test`	Control visible warnings and whether they fail the command.
`--optimize`, `-O`	`build`, `test`, `vendor`	Select optimisation passes.
`--release`, `-R`	Build, test, and vendor workflows	Select release generation. On `validate`, select release-profile warning settings.
`--json`	Commands with structured output	Return machine-readable results; check the command’s help for support.
`--quiet`, `-q`	Automation	Suppress informational logging.
`--lock-timeout`	Project operations	Limit how long to wait for an operation lock; it is not a simulation timeout.

Find the right command

Use this overview to find the relevant workflow. Inspection commands help explain the current project or environment; commands such as format, add, and clean change files or project state.

Task	Commands	Purpose
Project creation	`livt new`, `livt init`	Create a project directory or initialise an existing directory.
Validation and building	`livt validate`, `livt build`	Check sources and generate design output.
Simulation	`livt test`	Discover, select, and run tests.
Dependencies	`livt search`, `livt show`, `livt add`, `livt sync`, `livt lock`, `livt remove`	Inspect registry packages and manage the project’s dependencies.
Publishing	`livt publish`	Upload a configured package to the registry.
Hardware integration	`livt vendor`	Generate files for the selected vendor workflow.
Inspection	`livt doctor`, `livt contexts`, `livt stats`	Inspect installation health, clock contexts, and project metrics.
Maintenance	`livt format`, `livt clean`	Format source files or remove generated output.

Create a project

Use new when you want Livt to create a directory for the project. The default Hello World template supplies a manifest, a source component, and a test component, giving you a small project that you can immediately validate and test.

bash

livt new CliDemo
cd CliDemo
livt validate
livt test

Use livt init when the target directory already exists. Both commands accept --template helloworld explicitly. For new, --project names the parent in which the new folder will be created; for init, it names the directory to initialise.

bash

livt init --project path/to/existing-directory

Keep the manifest, source, and tests under version control. See Hello, Livt! for the introductory project and Project Configuration for source roots, entry components, and build settings.

Validate and build

livt validate checks source and test files by default without generating HDL. Use --sources-only when you intentionally want to exclude tests. Validation does not automatically synchronise dependencies: use --sync to request that preparation, or --offline when local dependencies must already be available.

bash

livt validate
livt validate --sources-only
livt validate --sync
livt validate --offline

Read the reported file, line, and diagnostic before trying a build. In the example below, SayHelloWorld() deliberately calls an undefined ReportGreeting() function. Correcting the source removes the validation error; repeating the build without that correction cannot resolve it.

source validation diagnostic in the VS Code terminal — Validation names the undefined function and reports its source location.

livt build generates output using the project configuration and synchronises dependencies when needed. It can reuse current build results. Use --force when you specifically need regeneration and --out-dir to select another output directory for the invocation.

bash

livt build
livt build --force
livt build --out-dir out-review

Choose build behaviour

The default build uses debug generation. Use --release for release generation, which removes non-test assertions and simulation-only reporting and waits by default. To retain application assertions in a release build, set --strip-assertions=false. Test assertions and compile-time checks remain. Profile selection and optimisation controls serve different purposes.

bash

livt build --release
livt build --release --strip-assertions=false
livt build -O all
livt build -O none
livt build -O all,no-loop-unrolling

Warning flags let you choose how diagnostics affect a run. -W all reveals warnings suppressed by the manifest; -W no-variable-divisor explicitly suppresses that diagnostic; -W error treats visible warnings as errors. Combine flags with commas when you want both behaviours, for example -W all,error. These options do not rewrite the manifest.

bash

livt build -W all,error
livt build -W all,no-variable-divisor

Use Project Configuration to make team-wide profile and warning choices persistent. See Build results to understand the generated output; selecting optimisation passes is not a substitute for measuring the target design.

Override the default reset behaviour

build, test, and vendor accept --default-reset-style sync or async. The option overrides build.default_reset_style for that invocation; without either setting, the default is synchronous. Explicit requirements and reset behaviour inherited through context bindings still apply. Reset selection is independent of release generation and optimisation.

bash

livt build --default-reset-style sync

Inspect compilation time

Use livt build --profile-generation to investigate compilation cost. It forces a rebuild and writes reports beneath .livt/reports/. This option belongs to build; it is not accepted by test or vendor.

bash

livt build --profile-generation

Report	Contents
`compilation.json`	Compiler phases and run outcome, including work before generation.
`vhdl-generation.json`	Detailed generation measurements when supplied by the VHDL generator.

Subsequent profiled builds reuse these paths, so copy reports elsewhere before comparing runs. A failed build can leave a compilation report without a completed generator report. Compare equivalent inputs and settings, accounting for warm caches. These reports measure compiler work, not simulated cycles, FPGA resource use, or physical timing.

Discover and run tests

Start with --list to see which tests Livt discovers without building or simulating them. Run all configured tests with livt test, select a component with --run, or append a colon and method name to select one test. The default template provides the names used here; use your own discovered names in other projects.

bash

livt test --list
livt test
livt test --run MyComponentTest
livt test --run MyComponentTest:TestSayHelloWorld

The short form -r is equivalent to --run. Tests are prepared and run in the configured simulator, with the final result reporting passed, failed, and skipped tests. For a failure, inspect the assertion or simulator diagnostic; use --verbose when you need the complete simulator output. --force requests a fresh build before the run.

filtered test run in the VS Code terminal — A component-and-method filter runs one test; the JUnit option also writes a report for automation.

Configure the simulator

GHDL is the default simulator. In VS Code, use Livt: Manage Livt Installation to manage the installation. On another machine or a CI runner, make GHDL available on PATH or set LIVT_GHDL_PATH to its executable. Simulator installation paths belong to the machine, not a simulator table in livt.toml.

bash

export LIVT_GHDL_PATH=/opt/ghdl/bin/ghdl

The example above uses a POSIX shell; set the equivalent environment variable in your shell or CI configuration. The terminal and VS Code extension can inherit different environments. See Testing for writing assertions, observing clocked behaviour, and configuring test discovery.

Manage dependencies and publish packages

Search the registry to find a package, then use show to inspect its registry information. Once you have selected a package, add updates the manifest and synchronises dependencies. An explicit version uses the form package@version; replace the version placeholder below before running the command.

bash

livt search Livt.IO
livt show Livt.IO
livt add "Livt.IO@<selected-version>"

Use livt sync after checking out a project or changing dependency declarations when the local packages need updating. It uses a lock file that still satisfies the manifest and refreshes an existing lock when declarations require a new resolution. Use livt lock when you explicitly need to create or update the lock file, including manually declared dependencies without an existing lock. You do not need to run both after every build.

bash

livt sync

# Create or update the lock file when needed.
livt lock

To stop using a dependency, remove its source references and run livt remove Livt.IO. The command updates the manifest and synchronises the remaining dependencies. Review manifest and lock-file changes, then validate and test affected code. See Packages and Dependencies for version selection, local packages, and the VS Code workflow.

Publish a package

livt publish uploads the configured package to the registry. Complete its package and version metadata, review the files intended for distribution, and run validation and tests before publishing. Unlike a local build, this command makes a package available through the registry and requires the appropriate registry access.

bash

livt publish

Generate vendor projects

Use livt vendor list --json to inspect available templates without building a project. Select the standalone or IP template that matches the consuming tool. The command builds the required output and performs the selected template’s steps; it can invoke the vendor tool, so the tool and target settings need to be available.

bash

livt vendor list --json
livt vendor vivado
livt vendor vivado-ip xc7a100tcsg324-1

The two Vivado commands are alternative workflows: vivado creates a standalone project, while vivado-ip prepares an IP integration for the selected part. Review the reported component, part, wrapper, and top. Vivado results live under .livt/vendor/vivado/design or .livt/vendor/vivado/ip, including scripts, logs, and the generated project or package.

A generated project does not by itself establish timing closure or produce a programmed device. See Hardware Integration for template configuration, wrapper connections, constraints, and the next steps in the vendor tool.

Inspect and maintain a project

When the environment is the problem, begin with livt doctor. It checks the compiler, Java runtime, licence, filesystem, project configuration, dependency state, and simulator. Use its findings to distinguish an installation problem from a source diagnostic.

bash

livt doctor
livt contexts
livt stats

livt contexts analyses saved project clock-context connections without generating HDL; synchronise dependencies first if needed. It helps explain which instances share a context and where crossings occur. livt stats reports source metrics and available generated-code ratios; add --semantic for semantic model counts. Source metrics are not FPGA resource or timing estimates.

Formatting changes source files in place. Supply one file or a directory to limit the scope, or run livt format without a target to format the project’s sources and tests. Review the resulting diff before committing.

bash

livt format src/MyComponent.lvt
livt format src

Use livt clean when you need to remove generated output. It removes the complete configured output directory, simulator artefacts, and dependency state caches. Keep authored files outside the output directory. By default, downloaded dependencies and vendor workspaces remain available.

Command	Additional cleanup
`livt clean`	Preserves `.livt/deps/` and `.livt/vendor/`.
`livt clean --deps`	Also removes local dependencies; synchronise them again before use.
`livt clean --vendor`	Also removes vendor workspaces; regenerate them before use.
`livt clean --all`	Also removes both dependency and vendor folders.

A routine build can reuse valid results, so cleaning is not a prerequisite for each run. Choose the cleanup scope deliberately, especially when a vendor workspace contains changes made in the external tool.

Use commands in automation

A successful command exits with code 0; a non-zero code signals failure. Make the script propagate that failure before starting dependent work. In a POSIX shell, the following sequence validates the project and only then runs its tests:

bash

livt validate --sync &&
livt test --junit test-results.xml

The shell returns the failed command’s status, so a validation failure cannot be hidden by a later successful command. Configure the CI runner to collect test-results.xml even when tests fail. The JUnit report records test results for the runner; it does not replace the process exit status.

Use structured output when another tool needs to consume results. --json returns schema-versioned command data, while livt test --events streams lifecycle events as JSON lines. Choose the format your consumer expects and parse the documented fields instead of human-readable progress text.

bash

livt test --list --json > discovered-tests.json
livt test --events
livt validate --json > validation.json

Keep standard output and standard error separate when capturing JSON; progress and diagnostic logging can use standard error. --quiet reduces informational logging, while --verbose helps investigation. --lock-timeout controls how long a command waits for another project operation, not how long a test may run.

For tooling integrations, livt capabilities describes compiler capabilities and livt server --stdio exposes the compiler protocol. livt usage reports local compiler usage. These complement the everyday project commands; use their help for the integration-specific details.

Combine these commands with the documented exit codes to assemble an automated pipeline, including dependency preparation, test reports, and vendor jobs.