Lambë

Lambë

*A query language for structured data that shows you what you're working with.*

lam queries JSON, YAML, TOML, HCL, CSV, TSV, and Markdown. Unlike other query tools, it tells you what your query *does* before you run it — the shape at each pipe stage, which output formats can serialize the result, what would go wrong.

Use it when you don't already know the data: inspecting an unfamiliar API response, auditing a Helm chart, verifying a CI pipeline's assumptions, or asking an AI agent to extract something without guessing at the structure.

$ lam --to toml '.dependencies | keys' pubspec.yaml

Error: TOML output requires a map at the root, got list . Try appending one of: | as(toml) # Wraps the list under a single-entry map (equivalent to {items: .}).

$ lam --to toml '.dependencies | keys | as(toml)' pubspec.yaml items = ["rumil", "rumil_parsers", "rumil_expressions"]

Queries are bounded and always terminate. No recursion, no lambdas, no def. That's the tradeoff: Lambë doesn't try to be a programming language, so its shape inference, --explain, --schema, and error remediations all work.

*Lambë (pronounced "lam-beh") means "language" in Quenya (Tolkien's elvish). The package name is lambe for ASCII compatibility.*

Installation

One-line installer (Linux and macOS, no sudo, verifies SHA256 checksums):

curl -fsSL https://raw.githubusercontent.com/hakimjonas/lambe/main/install.sh | sh

This downloads lam and lam-mcp from the latest GitHub release into ~/.local/bin/. Environment variables LAMBE_VERSION (pin a version) and LAMBE_PREFIX (change install dir) are supported; see the script for details.

Other options:

# From pub.dev (Dart users)

dart pub global activate lambe

Dart library

dart pub add lambe

Build from source

git clone https://github.com/hakimjonas/lambe.git && cd lambe dart compile exe bin/lam.dart -o lam

See Getting started for all installation options.

Shape-aware output

Lambë checks the result of your query against the shape the target format can serialize. When they match, output is produced. When they don't, the error names the required shape and lists query fragments that would bridge it. In an interactive terminal, Lambë offers to apply the chosen fragment and retry in place.

$ lam --to toml '.name' pubspec.yaml

TOML output requires a map at the root, got string. Try appending one of: | as(toml) # Wraps the scalar under a single-entry map (equivalent to {value: .}).

Apply a bridge? [1] | as(toml) # Wraps the scalar under a single-entry map (equivalent to {value: .}). [q] cancel

1

value = "rumil"

The same flow applies to CSV and TSV (which require a list of records at the root) and HCL (which requires a map).

Suggestions surface the intent-level as( ) form. The explanation names the raw fragment ({value: .}, to_entries, etc.) the bridge composes, so --explain and manual composition stay available to anyone who wants them.

Non-scalar cells in CSV/TSV

By default, nested lists or maps in CSV/TSV cells are rejected — there is no faithful delimited rendering for them. When you need a quick export and lossy is acceptable, pass --flatten-cells json (CLI) or :flatten-cells json (REPL) to encode them as JSON strings inline. Round-tripping the resulting file back into Lambë does not recover the original structure; prefer reshaping the data query-side when fidelity matters.

as(fmt) — bridging in the query language

When the shape of the target format is known up front, as(fmt) performs the bridge inside the query. The combinator is a no-op when the input already satisfies the target, applies a single curated bridge when one exists, and lists the candidates when more than one could apply.

$ lam --to toml '.dependencies | as(toml)' pubspec.yaml

rumil = "^0.6.0" rumil_parsers = "^0.6.0" rumil_expressions = "^0.6.0"

$ lam --to csv '.dependencies | as(csv)' pubspec.yaml key,value rumil,^0.6.0 rumil_parsers,^0.6.0 rumil_expressions,^0.6.0

as accepts json, yaml, toml, csv, tsv, and hcl.

--explain — see the shape at every pipe stage

--explain walks the pipe backbone of a query and reports the shape at each stage, followed by the set of output formats the final shape can be serialized as. It performs static analysis only and does not evaluate the query; pass a data file to seed with real shape information, or omit it to trace against an unknown input.

$ lam --explain '.dependencies | keys' pubspec.yaml

.dependencies : map | keys : list

Writable as: json, yaml, csv, tsv Not writable as: toml, hcl

Explain flags provably-empty filters (filter(.missing) on a known shape) and runtime-rejection mismatches (filter on a non-list input) by default. Pass --explain-trivial to also flag sort_by/group_by/map/unique_by whose argument references a missing field (often a typo, sometimes intentional). For agent tooling and build pipelines, --explain-json emits the same information as a structured JSON document.

--schema — declare a shape and let Lambë check your work

When you have a JSON Schema for your data — from an API contract, OpenAPI spec, or hand-written docs — point --schema at it:

$ lam --schema api.schema.json --explain '.users | map(.email)' response.json

.users : list >> | map(.email) : list >

Writable as: json, yaml, csv, tsv Not writable as: toml, hcl

The schema fills in information data alone can't express: optional fields (from JSON Schema's required), element shapes of empty lists, types shapeOf couldn't infer from sampling. --explain shows them; the evaluator trusts them.

With data present, Lambë also validates: a schema saying age: number against data with age: "30" exits 1 at load time with a JSON-path-annotated diagnostic. No silent drift, no running a query against data that doesn't match its contract.

A sibling .schema.json is auto-detected, so a project convention of placing schemas next to data works without explicit flags.

The reverse direction is symmetrical: lam --print-shape data.json emits the inferred shape as a JSON Schema document. Round-trip:

lam --print-shape data.json > data.schema.json    # bootstrap a schema from data

lam --schema data.schema.json '.users' data.json # use it back

Accepted JSON Schema keywords: type, properties, items, required. Value-level constraints (minimum, pattern, enum, etc.), structural combinators (allOf, oneOf), $ref, and conditional schemas are rejected with a per-keyword error. Lambë is a shape system, not a validation engine — for richer validation, reach for ajv or check-jsonschema.

Query Syntax

Queries start with . (the current data) and chain operations with |:

.                              the whole document

.name access a field .users[0] index into a list .users[0].address.city chain access .users | filter(.age > 30) pipe into an operation .users | map(.name) transform each element

Pipelines read left to right. Each | passes its result to the next operation:

.users | filter(.active) | sort_by(.name) | map(.name)

This takes .users, keeps active ones, sorts by name, and extracts names.

Expressions

.price * .qty                  arithmetic (+, -, *, /, %)

.age > 30 comparison (<, >, <=, >=, ==, !=) .active && .verified logic (&&, ||, !) if .age > 65 then "senior" else "active" conditional {name, total: .price * .qty} construct a new object "\(.name) is \(.age)" string interpolation .[1:3] slice a list or string

Operations

Operations follow | and transform the piped value:

. | filter(.age > 30)          keep matching elements

. | map(.name) transform each element . | sort_by(.age) sort by a key . | group_by(.dept) group into [{key, values}] . | length count elements . | first first element . | sum sum numbers . | keys map keys or list indices . | has("field") check if a field exists . | unique remove duplicates . | flatten flatten one level of nesting . | to_entries map to [{key, value}] pairs . | filter_values(. > 5) filter a map's values . | as(toml) bridge to an output format

See the full list in Pipeline Operations below.

CLI

# Extract values

lam '.database.host' config.toml lam '.spec.containers[0].image' deployment.yaml

Filter and transform

lam '.users | filter(.age > 30) | map(.name)' data.json

Aggregate

lam '.items | map(.price) | sum' data.json

Sort and pick

lam '.items | sort_by(.price) | first' data.json

Object construction

lam '.users | map({name, senior: .age > 65})' data.json

String interpolation

lam '.users | map("\(.name) is \(.age)")' data.json

Shape trace

lam --explain '.users | map(.name)' data.json

Shape inspection (JSON Schema output)

lam --print-shape data.json

Schema-checked queries: validate data against a schema as it runs

lam --schema api.schema.json '.users | map(.email)' response.json

CI validation

lam --assert '.version != "0.0.0"' package.json lam --assert '.replicas >= 2' deployment.yaml

Format conversion

lam --to yaml '.config' data.json lam --to csv '.users | map({name, age})' data.json lam --to toml '.config | as(toml)' data.json lam --to csv --flatten-cells json '.users' data.json # encode nested cells as JSON

Line-delimited JSON (logs, event streams)

lam --ndjson '.user.id' events.ndjson tail -f app.log | lam --ndjson '.level'

Query any format (auto-detected from extension)

lam '. | filter(.status != "closed")' issues.csv lam '.resource | map(._labels)' main.tf lam '.children | filter(.type == "heading") | map(.children[0].text)' README.md

Pipe from stdin

curl -s https://api.example.com/users | lam '.results | filter(.active)'

Interactive REPL

lam -i data.json

lambe v0.14.0 - type :help for commands, :q to quit

Data loaded: {3 fields, 42 users}

lambe> .users | filter(.age > 30) | map(.name) ["Bob", "Carol"]

lambe> .users[0] {name: "Alice", age: 25, active: true}

lambe> :schema {users: [{name: "string", age: "number", active: "boolean"}]}

lambe> :to yaml Output format: yaml

When a query produces a result the current output format cannot serialize, the REPL lists the available bridges inline; pressing the number of a suggestion applies it and prints the bridged output. Tab completion works on field names (.us ) and pipeline operations (| fil ). The REPL also supports syntax highlighting, persistent history (~/.lambe_history), Ctrl+R reverse search, and multi-line input with \ continuation.

Library

import 'package:lambe/lambe.dart';

// Query pre-parsed data final name = query('.users[0].name', data);

// Query a JSON string final version = queryJson('.version', '{"version": "1.0.0"}');

// Query any format final host = queryString('.database.host', tomlString, format: Format.toml);

// Parse once, evaluate many times final ast = parseAst('.users | filter(.active) | map(.name)'); final result1 = evaluateAst(ast, dataset1); final result2 = evaluateAst(ast, dataset2);

// Format conversion final yaml = formatOutput(data, OutputFormat.yaml); final csv = formatOutput(users, OutputFormat.csv);

// Shape inference and JSON Schema output final shape = shapeOf(data); // Shape ADT final schemaJson = renderJsonSchema(shape); // JSON Schema text

//