The complete guide, start to finish. Install, ingest, query — then open
the same data to your agents over MCP and your team over SQL and the SDKs.
1
Install with curl
One line installs the prebuilt less binary (macOS arm64/x64, Linux x64).
$ curl -fsSL https://packages.lessdb.dev/install.sh | sh
# The installer fetches the release for your OS/arch from the
# Cloudflare package host and puts `less` on your PATH.
$ less version # lessdb 0.1.0
# Prefer building from source? (Rust ≥ 1.85)
$ cargo install --path crates/less-cli --features cloud,gpu --locked
The installer only writes to ~/.lessdb plus one PATH line — delete both to uninstall.
2
Your first database
$ less init # creates .less/ here — or --dir /data/mydb
3
Tables + data
$ less create "CREATE TABLE events (
id Int64, kind String, amount Float64, ts DateTime
) ENGINE = MergeTree ORDER BY (kind, id) UNIQUE (kind) COMPRESSION = 'zstd'"
# CSV headers map to columns (any order); empty/`\N` cells are NULL:
$ less insert events --csv events.csv # or --jsonl / --parquet / --arrow
$ less sql "INSERT INTO events VALUES (2, 'view', 1.5, '2025-01-01 10:01:00')"
$ less sql "COPY (SELECT * FROM events) TO 'export.parquet'"
4
Query (SQL-first)
$ less sql "SELECT kind, count(*) AS c, sum(amount) AS total
FROM events GROUP BY kind ORDER BY total DESC"
$ less sql "SELECT * FROM events WHERE kind = 'click' AND ts > '2025-01-01'"
$ less sql # interactive REPL (end with ;)
$ less sql "EXPLAIN SELECT ..." # plan + part-pruning info
Full SQL surface: joins, CTEs, window functions, subqueries.
UNIQUE columns dedup keep-last at flush/merge; run
less optimize events to enforce across parts.
less describe events / less parts events show storage state.
5
Vector search
$ less vector create docs 3 --metric cosine # flat exact
$ less vector create big 256 --index ivf_pq --nlist 64 --m 8 # ANN
$ less vector add docs --vectors '[[1,0,0],[0,1,0],[0.9,0.1,0]]' \
--payloads '[{"title":"rust"},{"title":"python"},{"title":"rust-like"}]'
$ less vector search docs '[1,0,0]' --k 2
$ less vector embed "rust database" # built-in trigram embedder (demo)
# SQL, too — and you can join/filter the hits:
$ less sql "SELECT id, payload FROM vector_search('docs', [1.0,0.0,0.0], 10)
WHERE payload LIKE '%rust%'"
6
Knowledge graph: contexts + links
Link notes, tasks, and projects in the same data dir — no extra services.
$ less context put proj/lessdb "LessDB" "Analytical DB in Rust" --tag db --kind project
$ less context put task/123 "GPU kernels" "wgpu filtered-sum + dot" --tag gpu --kind task
$ less context link task/123 proj/lessdb depends_on
$ less context find gpu
$ less context neighbors task/123 && less context path task/123 proj/lessdb
$ less memory create people --field id:Int64 --field name:Utf8 --pk id
$ less memory insert people '[{"id":1,"name":"ada"},{"id":2,"name":"grace"}]'
$ less memory sql "SELECT count(*) FROM people"
Everything persists under .less/memory/.
7
Open the agent door (MCP)
One stdio connection exposes 27 tools to any MCP client — no plugins, no sync jobs.
$ less mcp # stdio JSON-RPC, uses --dir .less by default
# Lock the door and hold agents accountable:
$ less token create claude --role read --tenant default # prints the token once
$ less mcp --require-auth # tokens required, roles enforced, fail-closed
$ less audit --since 24h # every call, both doors, newest first
Claude Code:
$ claude mcp add lessdb -- less mcp --dir /abs/path/to/mydb
Claude Desktop claude_desktop_config.json:
{ "mcpServers": { "lessdb": { "command": "less", "args": ["mcp", "--dir", "/abs/path/to/mydb"] } } }
Agents get 27 tools: less_query/explain/schema/stats/tables/optimize,
context_*, memory_*, vector_*.
8
HTTP server (+ Prometheus, LDAP)
$ less server --addr 127.0.0.1:7080
$ curl -s localhost:7080/health
$ curl -s localhost:7080/v1/sql -H 'content-type: application/json' \
-d '{"sql":"SELECT count(*) FROM events"}' # JSON
$ curl -s localhost:7080/metrics # Prometheus text
# LDAP/AD auth (fail-closed group→role mapping):
$ less init --auth @auth.json # see docs/ARCHITECTURE.md §9 for the schema
$ curl -u alice:secret -H 'content-type: application/json' \
-d '{"sql":"SELECT 1"}' localhost:7080/v1/sql
Prometheus:
scrape_configs:
- job_name: lessdb
static_configs: [{ targets: ["localhost:7080"] }]
9
Cloud-native: compute/storage separation
$ less init --shared s3://my-bucket/lessdb # parts + catalog in S3
Any node with the same --shared URL sees the same tables instantly;
local disk stays ephemeral (buffers/caches only). file:// for local dev.
10
Python / Node (embedded)
# Python — wheels served from the Cloudflare package host:
$ pip install lessdb --index-url https://packages.lessdb.dev/simple
$ python -c "
import lessdb
db = lessdb.open('mydb')
db.create_table('CREATE TABLE t (x Int64) ENGINE = MergeTree ORDER BY (x)')
db.insert_json('t', [{'x': 1}, {'x': 2}])
print(db.sql('SELECT sum(x) FROM t'))"
# Node — tarballs served from the same host:
$ npm install @lessdb/node --registry https://packages.lessdb.dev/npm/
$ node -e "const {open}=require('@lessdb/node'); const db=open('mydb');
db.queryJson('SELECT 40+2').then(console.log)"
⚡
Benchmarks & GPU
$ less bench --rows 5000000 # insert + scan/filter/group-by throughput
$ less gpu # GPU vs CPU kernels (Metal/Vulkan)
$ less metrics # this process's Prometheus metrics
More: README.md, docs/ARCHITECTURE.md,
docs/ROADMAP.md, and the agent skills in skills/.