Talk to governed Databricks data from your terminal and .NET applications.
lakespeak.net — what it does, with real terminal output.
LakeSpeak.NET is an independent open-source .NET client, terminal application, and automation toolkit for Databricks Genie Agents.
New here? Getting started walks from nothing to a working answer, including what a Genie Agent is and how to tell whether you have one.
Not a Databricks product. LakeSpeak.NET is an independent open-source community project. It is not an official Databricks product, is not endorsed by Databricks, and is not supported under any Databricks service-level agreement. "Databricks", "Databricks Genie" and "Unity Catalog" are trademarks of Databricks, Inc.
v0.1.0. See Verification status for what has actually been tested and
what has not. Nothing here is stable until v1.0; the CLI surface and the LakeSpeak.Genie public
API may both change, and before v1.0 a minor version is allowed to break them.
dotnet tool install --global LakeSpeak.CliDatabricks Genie answers questions about your data in plain English: you ask, it writes SQL against tables someone has curated, runs it on a SQL warehouse, and answers. A Genie Agent is one such configured surface. Genie normally lives in the Databricks web UI — LakeSpeak puts it in your .NET code, your scripts and your terminal, while keeping the generated SQL visible so you can check the answer.
You need a Genie Agent to already exist in your workspace and be shared with you. LakeSpeak cannot create one, and sees only what your own Databricks identity can see.
Start with what you may not need this for. The official CLI has a good terminal experience for Genie:
databricks genie ask -s sales --include-sql "How did revenue change last month?"That holds a conversation across calls, shows the SQL, and prints JSON with -o json. If a terminal
answer is all you want, it ships with the Databricks CLI and it is fine.
Two things it does not cover.
There is no Databricks SDK for .NET. Python, Java, Go and R are covered; .NET is not. A .NET
service that needs a Genie answer in-process has no first-party option, and shelling out to a CLI
from a hosted service is not one. LakeSpeak.Genie is a typed client with DI registration,
cancellation, typed failures, and no credential of its own.
Question Packs have no equivalent. A set of business questions, version-controlled, reviewed like code, run on a schedule, producing a deterministic Markdown report. That is a different artifact from a terminal command, and nothing else produces it.
The terminal client exists because the library needed proving and because --agent with
configured aliases targets a named Agent, which the official ask exposes
no flag for.
lakespeak ask --agent sales "How did revenue change last month?"
The generated SQL is shown because the answer is only as trustworthy as the query behind it.
It is deliberately narrow. It is not a Databricks SDK for .NET and not a replacement for the official CLI. It is also not a Genie MCP server: Databricks ships managed MCP endpoints for Genie, and although those are stateless — every question starts over — building a stateful one would be a second product, and this is deliberately one. See ADR 0001, including its correction.
dotnet tool install --global LakeSpeak.CliOr add the client to a .NET project:
dotnet add package LakeSpeak.GenieLakeSpeak uses your existing Databricks CLI login rather than asking for a token of its own:
databricks auth login --profile company
lakespeak chat --profile companyAsk a one-shot question:
lakespeak ask --agent sales "Who were our five fastest-growing customers?"Get machine-readable output for scripts and coding agents:
lakespeak ask --agent finance --format json "What was recognized revenue yesterday?"$r = lakespeak ask --agent finance --format json "Revenue yesterday?" | ConvertFrom-Json
$r.result.rowsservices.AddLakeSpeak(options => options.Profile = "production");
var response = await genie.AskAsync(
agentId: salesAgentId,
question: "Which customers had the largest revenue decline?",
cancellationToken);
Console.WriteLine(response.Text);
if (response.Query is not null)
{
Console.WriteLine(response.Query.Sql);
}Abbreviated for orientation. The complete version — DI registration, using directives, reading
the rows, and typed error handling on GenieFailureKind — is in
Getting started → Using it from .NET, and it is
compiled against the library rather than written by hand.
A Question Pack turns a set of business questions into a reviewable, version-controlled report.
apiVersion: lakespeak.net/v1alpha1
kind: QuestionPack
metadata:
name: daily-platform-brief
spec:
agent: platform-operations
questions:
- id: failed-jobs
title: Failed production jobs
ask: Which production jobs failed during the last 24 hours?
output:
format: markdown
path: reports/daily-platform-brief.mdlakespeak pack run daily-platform-brief.yamlSee the Question Pack guide for the schema and failure semantics.
- It does not bypass Unity Catalog. You see exactly what your Databricks identity is permitted to see, and LakeSpeak has no way to widen that.
- It does not guarantee that a Genie answer is correct. Natural-language querying produces generated SQL, and generated SQL can be wrong in ways that read as plausible. LakeSpeak preserves the SQL, the source metadata and the message ids precisely so you can check.
- It does not execute arbitrary SQL, edit generated SQL, or modify Genie Agent definitions.
- It does not store your questions, answers, or query results anywhere except files you explicitly export.
LakeSpeak never persists an access token. It brokers short-lived OAuth tokens through the Databricks CLI and holds them in memory for the life of the process.
Your questions and the answers you get back can contain sensitive business information, and exported results contain governed data. Once you export a CSV, that file is yours to look after. In CI, remember that job logs are usually readable by everyone with repository access.
Every release is signed with a SLSA build provenance attestation, and one command checks that a download really came from this repository's release workflow.
Report vulnerabilities privately — see SECURITY.md. For how the project's controls map to the SOC 2 Trust Services Criteria, and the several places they deliberately stop, see docs/compliance/soc2-mapping.md.
This table records what has been run against what. It is not a support matrix and it is not a promise; it is a record of evidence.
| Area | Status |
|---|---|
| Unit and contract tests | Run on Windows and Linux in CI, on every push and pull request |
| Azure Databricks, live workspace | agents list, ask, pack run and every output format verified against a real Genie Agent on 2026-08-01 |
chat |
Verified live on 2026-08-06 — the REPL, a follow-up keeping its context, and /sql. Its other slash commands were not exercised |
| Feedback, full-result download, visualizations | Contract tests only — not exercised live |
| Chunked results assembled beyond the first chunk | Mechanism verified live on 2026-08-05 — chunk reads on a Genie-executed statement are permitted, and the link, response shape and row arithmetic all behave as the client assumes. Genie emitting a multi-chunk result was not reproduced |
| Unattended service-principal authentication | Request shape verified against the live token endpoint; the exchange with real service-principal credentials was not run |
| AWS Databricks | Not tested — #51 |
| GCP Databricks | Not tested — #52 |
| Windows / Linux | Covered by the CI matrix |
| macOS | Binary is built, not tested — #53 |
Paths that have not been exercised against a real workspace are labelled as such in docs/compatibility.md rather than being quietly presented as working.
- Getting started — zero to a working answer
- Commands — every command, flag and exit code
- Configuration — the config file, aliases and defaults
examples/— a runnable .NET console sample, a complete Question Pack, and a scheduled GitHub Actions workflow- Container image — running a Question Pack on a schedule
- Authentication — profiles, environment tokens, and what is not supported
- Question Packs — the schema and its failure semantics
- Troubleshooting
- Limitations — read this one
- Decisions — ADRs for the load-bearing choices
- Genie API surface — every wire claim, labelled verified or not
- SOC 2 control mapping
- Releasing — how a version is cut, and how to rehearse one
Issues and pull requests are welcome. Start with CONTRIBUTING.md, and see GOVERNANCE.md for how decisions get made and what is deliberately out of scope.
Good first issues are labelled good first issue.
Core authentication and security work is not labelled that way, on purpose.
Apache License 2.0. See NOTICE.