Skip to content

Use from command line

Installation

Using Nix

If you have Nix, you can install Lutra CLI with:

$ nix profile install 'git+https://codeberg.org/lutra/lutra-data.git'

Using Cargo

Prerequisites:

To install the CLI, run:

$ cargo install lutra-cli

Note

The CLI depends on DuckDB. Make sure you have the DuckDB library installed on your system. On most Linux distributions, you can install it via your package manager (e.g., apt install libduckdb-dev on Debian/Ubuntu). On macOS, you can use brew install duckdb.

Alteratively, you can use --features bundled to compile DuckDB from source. This requires a C++ compiler.

Command run

The most basic command is run, which executes a Lutra program.

Options:

  • choice of a runner, which can be set to either:

    • --interpreter, or
    • --postgres <connection-string>

  • --program <Lutra expression> which is the program to execute. Default to main (a reference to the main function).

  • --project <file.lt> path to a project file.
  • --input <file.lb> path to the input file in Lutra binary format.
  • --output <file.lb>path to the output file in Lutra binary format.

Examples

Execute a program on a local interpreter:

$ lutra run \
    --interpreter \
    --program 'std::fold([1, 2, 3], 0: int32, func (s, v) -> s + v)'
6

Execute a program on PostgreSQL:

$ lutra run \
    --postgres 'postgresql://postgres:password@localhost:5432/postgres' \
    --program 'std::fold([1, 2, 3], 0: int32, func (s, v) -> s + v)'
6

Use a project file:

# project.lt

func hello(name: text): text -> (
    f"Hello, {name}!"
)

$ lutra run \
    --interpreter \
    --project ./project.lt \
    --program 'hello("world")'
"Hello, world!"

Write and read Lutra binary files:

$ lutra run \
    --interpreter \
    --program '{a = false, name = "world"}' \
    --output ./data.lb
Output written to ./data.lb (14 bytes)

$ lutra run \
    --interpreter \
    --input ./data.lb \
    --program 'func(x: {a: bool, name: text}) -> f"Hello, {x.name}!"'
"Hello, world!"

Command check

Validates a Lutra project. Parses all files and resolves all names and types.

Options:

  • --program <Lutra expression> the program to check.
  • --project <file.lt> path to a project file.

Examples

Validate a project file:

$ lutra check --project ./project.lt

Command codegen

Generates bindings of a Lutra project for a target language (Rust or Python).

Arguments:

  • <project> path to a project file.
  • <output file> path to the output file.

The output file path must end with .rs or .py depending on the target language.

Examples

Generate Rust bindings:

$ lutra codegen --project ./project.lt ./lutra.rs
Used files:
- project.lt
Output written to lutra.rs
Done.

Other commands

There other, less stable commands.

$ lutra --help
Usage: lutra [OPTIONS] <COMMAND>

Commands:
  discover         Read the project
  check            Validate the project
  compile          Compile a program
  run              Compile a program and run it
  pull             Pull interface from the runner
  codegen          Compile the project and generate bindings code
  format           Format source files
  language-server  Start language server (LSP)
  help             Print this message or the help of the given subcommand(s)

Options:
  -v, --verbose
  -h, --help     Print help