Reference¶

Complete reference for all nodes and properties supported in a lets.kdl file.

Top-level nodes¶

description¶

Top-level help text shown in lets --help.

description "My project tasks"

config¶

Global configuration.

config {
    sorted       // Sort commands alphabetically
    shell "zsh"  // Default shell for all commands
}

include¶

Import commands from another KDL file. Paths are relative to the including file.

include "tasks/db.kdl"

Command nodes¶

Any top-level node that isn't description, config, or include defines a command.

One-liner syntax¶

command-name "shell command"
command-name "shell command" description="Help text"

Block syntax¶

command-name {
    // child nodes...
}

Command child nodes¶

description¶

Short help text shown in command lists.

description "Deploy the application"

long-description¶

Extended help text shown in lets <command> --help.

long-description """
    Extended description with multiple lines.
    Shown when viewing the command's own help.
    """

examples¶

Usage examples shown at the bottom of --help.

examples """
    lets deploy staging
    lets deploy prod --dry-run
    """

run¶

Shell command to execute. Multiple run nodes execute sequentially.

run "cargo build --release"
run "echo done"

run-macos, run-linux, run-windows¶

Platform-specific run commands. Falls back to run if no match.

run-macos "brew install libpq"
run-linux "apt-get install libpq-dev"

arg¶

Positional argument.

arg name
arg name help="Description" default="value"
arg environment "dev" "staging" "prod"

flag¶

Boolean or valued flag.

flag verbose
flag verbose "-v" help="Enable verbose output"
flag count "-c" type="int" default="3"

deps¶

Tasks to run in parallel before this command.

deps "lint" "test"
deps "db migrate"

steps¶

Tasks to run sequentially before this command.

steps "lint" "test" "build"

before, after¶

Shell commands to run before/after the main run.

before "echo Starting..."
after "echo Done!"

env¶

Set environment variables.

env PORT="3000" RUST_LOG="debug"

env-file¶

Load environment variables from a file. Explicit env values override.

env-file ".env.local"

dir¶

Set working directory.

dir "packages/web"

shell¶

Override the shell (default: sh or global config shell).

shell "bash"

platform¶

Restrict to specific platforms: "macos", "linux", "windows".

platform "macos" "linux"

confirm¶

Yes/no confirmation prompt. Supports interpolation. Bypassed with --yes.

confirm "Deploy to {environment}?"

prompt¶

Text input bound to a variable.

prompt name "What is your name?" default="world"

choose¶

Selection menu bound to a variable.

choose environment "dev" "staging" "prod"

alias¶

Alternative names for this command.

alias "t" "tst"

timeout¶

Kill after a duration. Formats: ms, s, m, h, or plain seconds.

timeout "30s"

retry¶

Retry on failure.

retry count=3 delay="2s"

silent / quiet¶

Suppress output unless the command fails.

silent

hide¶

Hide from --help and --list. Command still works when invoked directly.

hide

deprecated¶

Mark as deprecated with optional message.

deprecated
deprecated "Use 'new-cmd' instead"

cmd¶

Escape reserved names as subcommands.

cmd alias {
    run "echo managing aliases"
}

Interpolation¶

Execution order¶

1. deps (parallel)
2. steps (sequential)
3. Interactive: choose, prompt
4. confirm
5. before hook
6. run commands (sequential, with interpolation)
7. after hook