Repository navigation
Releases
0.7.0b8 — the Action can be listed, and the engine runs in a browser tab
uv tool install semlayer==0.7.0b8
The Action is named semlayer SQL check, so it can be listed
The GitHub Marketplace refuses an Action whose name matches an existing user
or organisation, and semlayer is one. The name: in action.yml is now
semlayer SQL check. That is the listing title only. A workflow refers to
the repository, so nothing that uses the Action changes:
- uses: semlayer-dev/semlayer@v0.7.0-beta.8
with:
mode: lint # or drift, to fail when the warehouse moved
layer: layer.yamlThe engine runs where there are no threads, and says what it is doing
Three changes made for running the engine inside a browser tab on Pyodide,
which is what https://try.semlayer.dev does. A native run behaves as before.
- The package imports and infers without
mcpinstalled. Only
build_serverneeds it. - A query watchdog that cannot start its timer runs the query without one
and records that, andrun_sqlno longer reports a time limit it could
not arm. - Progress events carry more: Profile names the table it is on, Link emits
afoundevent listing the relationships before it finishes, and Enrich
reports five steps where it reported none. A consumer that switches on
the event kind must ignore kinds it does not know.
0.7.0b7 — who executes the SQL, why a query was refused, Codex
uv tool install semlayer==0.7.0b7
status and context_for_question say who executes the SQL
semlayer used to tell your agent to try run_sql first. That is wrong
wherever semlayer holds no warehouse credentials and your own SQL tool does:
the agent pays a failed call per question before giving up, and has to read a
vendor error string to know that it should.
Both tools now return an execution block — available, via, target
and a note — naming the executor and the fully-qualified database the SQL
is expected to run against. The instructions no longer name an executor at
all; this is a fact about your session, so the session states it.
It flips on the only unambiguous proof there is: a connection that will not
open. A statement the warehouse accepted and then refused says the
connection works and the SQL or the grant does not — a foreign tool would be
told the same thing, so that case flips nothing. One wasted round trip per
session rather than one per question.
When the block says semlayer cannot execute, the handoff is explicit: run
what check_sql approves verbatim, never re-drafted, and confirm the
other tool is pointed at the named target. A connector left on a different
database answers the query, returns rows that look right, and is wrong.
A refused query says why it was refused
run_sql used to hand the agent a warehouse error and a paragraph telling it
to work out, from the message, whether the problem was a grant or the SQL.
One judgement call per failure, on text that differs per warehouse, with no
way to test the answer.
The result now carries error_kind, decided from SQLSTATE, driver error
number, HTTP status and only then the message, with a signal field naming
what decided it:
permission— the warehouse parsed the statement and refused it for
want of a privilege. Norepairblock is offered, because nothing is
broken: run it verbatim elsewhere, or name the missing grant.permission_or_missing— Snowflake's002003is one error for two
causes, on purpose, so a role cannot discover objects it may not see. We
do not know which it was either, so the agent is sent both ways.statement— the warehouse's own terms. The repair loop, unchanged.
A missing table is deliberately statement and not a grant problem: routing
it elsewhere would waste a call and then report the same failure.
semlayer client add codex — and with it, ChatGPT desktop
semlayer client add codex
Codex keeps its MCP servers in $CODEX_HOME/config.toml, and the Codex CLI,
the Codex IDE extension and the ChatGPT desktop app all read that one
file. One entry reaches all three, which is the only local-config route to a
ChatGPT user — ChatGPT on the web reads nothing on your machine.
It is the first client whose config is not JSON, so it is not written the way
the others are. A config.toml is a file someone wrote by hand, so the entry
is edited in place: the [mcp_servers.semlayer] table is replaced or
appended and every other byte stays where it was, including a comment on the
line above and an env sub-table under our own entry. The key is
mcp_servers, snake_case; mcpServers there parses and does nothing.
Two things it refuses rather than breaks. A file that is not valid TOML is
left alone. And an entry in a form the text edit cannot see — an inline
mcp_servers = {...}, or a quoted key — is reported instead of appended,
because a duplicate key stops the whole file parsing and would cost you every
other server in it, not just ours.
Also in this release: the .mcpb bundle for one-click install in Claude
Desktop is attached below. Benchmark numbers in docs/benchmark.md are
measured as of this release and reproduce from the committed cassettes with
no API key.
0.7.0b6 — findings say where they are
Four things, and the first makes the other three worth having.
Findings say where they are
semlayer lint --json now reports line, col, start and end for every finding, and offset for every statement. Nothing searches text for them: sqlglot has been recording exact positions on every Identifier all along, and the linter simply never read them. col is normalised to where the name begins — sqlglot stores the column of a token's last character, which is not what an editor wants.
$ semlayer lint layer.yaml revenue.sql
revenue.sql:4:14: [error] fanout_aggregate ord_hdr.tot_amt: SUM(ord_hdr.tot_amt) in a block that joins ord_ln multiplies ord_hdr's values
fix: aggregate ord_ln in a subquery first…
The VS Code extension's 187 lines of position reconstruction are deleted as a result. Its README had to admit the underlines were "close, not exact", and it had a quiet bug: two identical statements in one file both underlined the first one.
A GitHub Action
- uses: semlayer-dev/semlayer@v0.7.0-beta.6
with:
mode: lint # or drift, to fail when the warehouse moved
layer: layer.yamlFindings land on the pull request diff, at the identifier, with the fix underneath. fail-on: never annotates without failing — the way into a repository that already has years of SQL in it. Lint mode installs without the warehouse drivers, because linting opens no warehouse.
semlayer client add
Writes semlayer into an MCP client's config — Claude Code, Claude Desktop, Cursor, Cline, and VS Code's own agent — so nobody hand-edits JSON. It records an absolute command (a client launched from a dock does not inherit your shell's PATH), keeps arguments as arguments, merges without touching any other server, and refuses rather than overwrites a file that is not valid JSON.
semlayer client list
semlayer client add claude-code --dry-run
A one-click bundle for Claude Desktop
semlayer-0.7.0b6.mcpb is attached to this release. Download and double-click, or Settings → Extensions → Install Extension. It is 11 kB: server.type: "uv" means Desktop's own runtime provisions Python and the dependencies on first launch, so nothing is vendored and nothing is platform-specific.
Also: llms-install.md is now linked from the README — an agent asked to "install the semlayer MCP server" could previously only find it by guessing — the MCP registry listing is mentioned, and the "with nothing installed" section no longer opens by assuming you have uv.
0.7.0b5 — a loaded layer brings its warehouse
Everything in this release was found by one person walking the VS Code extension's three steps on a clean machine and reporting what happened. Each item is something that stopped someone, not something that looked wrong in review.
A layer loaded from a path brings its warehouse with it
The agent loaded the layer, picked the right tables, wrote correct SQL — and run_sql answered "no warehouse connection is selected for this session", while status listed that warehouse as available.
load_layer and autoload both read semantic_layer.warehouse from the document. Session.load(path) did not — and that is the path semlayer mcp <layer> takes, which is how every editor and client config starts this server. The commonest way in was the only one that produced a layer you can read and cannot query.
warehouse_of(doc, layer_path) is now the single place that reads it, and it resolves a relative DuckDB path against the document's own directory. The engine records the path inference ran with, so a server started anywhere else was selecting a file that is not there — the same defect one step later and harder to see. An explicit --connection still wins: it chooses the warehouse, and a named document overrides only the document.
The instructions told agents there was no layer
Asked about revenue with a 36-table layer loaded, an agent replied that no semantic layer was loaded and one would have to be built from a warehouse. It had called nothing — it was repeating the second sentence of this server's own instructions, which described the empty case before saying to call status.
The instructions now lead with the call and make the empty case explicitly conditional, and context_for_question no longer says to start there "once a layer is loaded" — every tool already answers with status rather than failing, so there was never anything for the agent to check first.
Install the engine, then point the client at it
docs/mcp.md and llms-install.md led with "command": "uvx". That makes a client's first launch fetch a Python and about sixty-five packages — long enough that most clients time out and report the server as failed — and uvx then reuses a cached environment, so a newer release goes unnoticed. Both now lead with uv tool install, explain why a bare command name can fail inside a client launched from a dock, and keep uvx as a folded alternative with both costs stated.
Both also say what to do after writing a config: start a new session. A client reads its MCP server list once, at startup, so one that was already running has never seen the entry — and that failure is indistinguishable from a broken config, which is what sends people to debug the wrong thing.
The VS Code extension is in this tree and is not released by this tag; it ships on an ext-v* tag.
0.7.0b4 — `semlayer discover`, and a model you can choose
The engine half of a week spent walking the VS Code extension end to end on a clean machine. Everything here is something that walk ran into.
semlayer discover
The first question a new user faces is "which warehouse?", and until now the only answer the CLI could give was a blank prompt. semlayer discover lists the connections visible from here — DuckDB files in the working directory, connections.toml profiles, dbt targets, environment variables — each with where it was found, whether it is usable, and what is missing when it is not. --json for agents and editors.
The logic is not new. session.discover() has backed the MCP tool discover_connections since the MCP server shipped; it had no CLI surface, so a person at a terminal and an agent over MCP were answering the same first question with different amounts of help.
The interesting row is the half-configured one. An account set in SNOWFLAKE_ACCOUNT with nothing else is reported as found-but-unusable, naming the variables still needed, rather than being silently omitted or offered as though it would work.
Choosing a model
semlayer infer --model <id> and semlayer maintain --model <id>, or SEMLAYER_MODEL=<id> in $SEMLAYER_HOME/.env — the same file the API key can live in, and the only channel an MCP server launched by a desktop client reliably sees. The model was a constant in the engine with no flag and no override.
The default does not move, deliberately: the published cost model (~$0.70 per 100 tables) and every committed cassette are measured on the cheap tier. A different model is a different cassette key, so naming one means live calls rather than replay — the cassette holds what one model said, and replaying it for another would report a run that never happened. The model that ran is recorded in generated_by.model.
drift --json is always JSON
When nothing had drifted — the commonest outcome, and the one a nightly job hits — it printed the sentence no drift detected whether or not --json was passed. Every agent and CI step consuming the flag had to special-case one line of prose, against a fallback shape written down nowhere. It now emits an empty changeset carrying all seven keys the non-empty one does.
A missing DuckDB file is an error message
semlayer infer duckdb:nope.duckdb raised a raw IOException from the driver. It now raises a SourceError naming the path it resolved, the working directory it resolved against, and what DuckDB said — because the usual cause is a relative path interpreted from somewhere other than where you thought, and the resolved path is the one fact that makes that obvious.
The VS Code extension is in this tree and is not released by this tag; it ships on an ext-v* tag.
semlayer for VS Code 0.1.0
The semlayer extension for VS Code and Cursor. First release.
Three steps, in the sidebar. Connect a warehouse, create the semantic layer, query it from an MCP client. Each step stays visible once done and is a link back to its screen — swapping the sample warehouse for a real one is step one again.
- Connect lists what the machine can already reach: DuckDB files in the folder you opened,
connections.tomlprofiles, dbt targets, environment variables — with the minimal read-only grant script for the warehouse you pick, and a sample warehouse for anyone who has none. - Create shows what the warehouse offers and what the run will cost and take, before anything is spent. Every inference setting is here, with the exact
semlayer infercommand it builds. - Query writes the MCP config for Claude Code, Cline, Cursor or Claude Desktop — and tells you to start a new session of that client, because they read their server list once, at startup.
With nothing installed, one button. uv and the engine in a single command. uv brings its own Python, so no Python is required.
SQL diagnostics as you type, from semlayer lint. The findings that matter are the two that execute cleanly and return a wrong number: a join that fans out an aggregate, and a required filter nobody declared.
Day 2: what drifted in the warehouse since the layer was built, the review queue with both consequences shown before you click, and the open count as a badge on the activity-bar icon.
Requires the semlayer engine, 0.7.0b5 or newer — the panel installs it for you.
0.7.0b3 — semlayer demo, and the no-Python path actually works
semlayer demo: a warehouse for people who do not have one
The first thing a new user needs is something to point infer at, and "find
a warehouse first" is a wall in front of the only thing that would show them
what this does. semlayer demo writes one: thirty-six tables with cryptic
names, no declared primary or foreign keys anywhere in the DDL, an SCD2
customer dimension, two aggregate tables that reconcile with their facts only
under a filter nobody wrote down, and two deprecated legacy tables.
A clean tutorial schema would prove nothing. The claim semlayer makes is
about warehouses where the keys are undeclared and the rules are unwritten,
so the thing handed to a new user has to be one of those. Everything the
engine finds in it, it finds without help from the catalog.
The generator moved out of fixtures/ into the package to make this
possible: a person who installed from PyPI has no copy of the repository,
which is exactly the person who needs a warehouse to try.
The documented "with nothing installed" path did not work
docs/mcp.md and llms-install.md told users to run
uvx --with "semlayer[warehouses]" semlayer mcp
On a machine with no Python that fails. With no Python present uv
downloads the newest CPython -- 3.15 today -- and duckdb publishes wheels
only to cp314, so the install falls back to building from source, wants
CMake, and dies after about two and a half minutes. requires-python = ">=3.10" has no upper bound, so uv considered 3.15 fair game.
Every uvx invocation in the docs now pins --python 3.13. Reproduced and
fixed against a sandbox holding only a shell, curl and coreutils, where the
whole path now works: uv installs in 4.7s, semlayer demo writes the
warehouse, infer --no-llm produces a valid layer over 36 tables, and lint
catches both the fan-out and the required filter. Cached calls take 0.28s.
Raise or drop the pin once every dependency ships wheels for the Python uv
would otherwise pick.
A VS Code and Cursor extension
Lives in extension/. It carries no engine and speaks no MCP: it runs
semlayer <command> --json and renders the result, so the editor cannot
disagree with the terminal. SQL diagnostics as you type, the review queue as
a two-pane screen, drift, inference settings, and one click to write an MCP
client's config.
See docs/vscode.md.
llms-install.md, and an icon on the registry entry
Agent-driven installers read README.md and llms-install.md and nothing
else. The MCP configuration lived in docs/mcp.md, one link away, so an
agent asked to set semlayer up had to guess at it. llms-install.md now
carries the config block inline, along with the three things such an agent
otherwise gets wrong: that --with semlayer[warehouses] is load-bearing
rather than decorative, that no API key is required so setup must not block
on one, and that status is how you verify the install.
The missing extra is worth naming because of how it fails. Without the
warehouse drivers the server starts cleanly and finds a warehouse it
cannot open, so the configuration looks correct until the first real
request.
server.json gains icons, pointing at the mark now served from
semlayer.dev. Clients and directories render it; an entry without one looks
abandoned beside entries that have one.
A container image, and the version clients were shown was the SDK's
Dockerfile and .dockerignore land in the repository. The image runs the
MCP server over stdio as an unprivileged user, carries the warehouses
extra so a first connection can actually reach a warehouse, and is built
from the source tree so it matches the commit rather than the last release.
ENTRYPOINT is the binary and CMD is the subcommand, so docker run ... infer works without --entrypoint.
-i is not optional when running it: the MCP stdio transport IS the
container's stdin and stdout, and without it the server reads EOF and exits.
The ignore file is an allowlist rather than a blocklist, which is not
stylistic: the repository is about 5 GB, 4.5 GB of that fixtures, and the
wheel needs 2.6 MB of it. Every build would otherwise stream all of it to
the daemon. A build-time dependency added later has to be added there too.
Found while writing the image's smoke test: every client was being told
serverInfo.version: 1.28.1, which is the version of the mcp SDK, not of
semlayer. FastMCP does not forward a version to the low-level server, and
the SDK falls back to its own package version when that is None. Clients
display it, and bug reports quote it, so the number people have been
reporting was never ours. It now reports the real version, and the
handshake also carries websiteUrl.
Releases register themselves with the MCP Registry
server.json now lives in the repository, and release.yml publishes it to
the official MCP Registry after the PyPI upload. It has to run in that order:
the registry checks that the named package exists at the named version on
PyPI and that its published description carries the mcp-name marker, and
neither is true until the upload succeeds.
Both version fields in server.json are written from pyproject.toml at
publish time rather than from the git tag, because the tag says
v0.7.0-beta.2 and the package says 0.7.0b2 -- it is PyPI the registry
checks against, so PyPI is what the file is pinned to. The committed copy
cannot drift from a release as a result.
Registry versions are immutable, so re-running a successful release reports a
duplicate version. That one error is treated as success -- the listing
already describes the release -- and every other failure fails the job
loudly rather than continue-on-error, which is how the benchmark gate
rotted across two releases.
v0.7.0-beta.2 — the benchmark, re-measured
The benchmark table is re-measured, and one headline number went down
docs/benchmark.md claimed to describe 0.6.0b1 and said so at the top,
because 0.7.0b1 shipped without re-recording the answers that had stopped
replaying. That debt is paid: 190 answers re-recorded against the pinned
models, every published row named explicitly rather than through the
Haiku-only default command, and the replay step in release.yml is blocking
again -- which was always the condition for having made it advisory.
messy_mart with a Haiku-class answerer: semantic 0.89 -> 0.82. Three
questions, two in complex and one in simple. That is beyond the ~1
question of run-to-run variance the page documents, so it is reported as a
real movement. The linter, which previously added a question on that fixture,
now adds none there. Against that: the Sonnet row improved (0.87 -> 0.89, and
0.89 -> 0.92 with lint), and the ontology column rose 0.79 -> 0.82 to sit
exactly level with the flat layer rather than below it.
The claim that the layer "equalises models" is weakened and has been
rewritten rather than quietly kept. Haiku and Sonnet are now three questions
apart with the layer where they were one; on raw schema they are five apart.
The defensible statement is that the layer moves the cheap model from well
behind to close behind.
Every schema_only cell is unchanged on both models, and fan_trap and
tpcds_clean replayed without re-recording at all, so the raw-schema
baseline is the same measurement it was. The derived figures were recomputed
rather than carried over: the untouched-30 arithmetic is 0.47 -> 0.80 (+70%
relative), and the eight reworded questions pass 7/8 under the layer, not 8/8.
The repository moved to github.com/semlayer-dev/semlayer
Same code, same maintainer, new home: the project now lives under an
organisation named for the product rather than for the company that
currently holds it. GitHub redirects the old path, so an existing clone,
remote or bookmark keeps working and nothing needs to be re-cloned.
What changed in this repository: project.urls, the CLA bot's document
link, the telemetry docs link the CLI prints, the clone instruction
semlayer benchmark gives when run from a wheel, and the beta-feedback
link. Nightly's live job is gated on github.repository_owner, so that
gate moved too -- left alone it would have stopped matching and the job
would have gone quiet without ever failing.
The security contact in SECURITY.md is now hello@semlayer.dev, on the
domain the project actually publishes under. The package's authors
field is now semlayer; the FSL copyright in LICENSE.md and the CLA's
grant are unchanged, because those name the legal licensor and not the
product.
A mcp-name: dev.semlayer/mcp marker is now in this README. The official
MCP Registry reads it off the published PyPI description to confirm that
whoever claims the dev.semlayer namespace also controls the package.
route_intent no longer tells an agent to use a summary table it may not use
Every aggregate the engine finds arrives as mapping_source: heuristic with
routing.status: advisory, and SPEC 2.7 says such a table MUST NOT be
routed to automatically. route_intent listed it under use anyway, next
to the fact table, and the ROUTING line in context_for_question said
"use ord_hdr, dly_sls_agg, mth_cust_agg". On any layer with a reconciled
aggregate, every agent was handed the instruction the spec forbids.
The document was never wrong: repo_knowledge.routing[].use is the
producer's pointer list, and docs/metrics.md said a consumer must read the
aggregate's grain and status before following it. The MCP tool is that
consumer, so the rule now lives there. An aggregate stays in use only when
its routing status is verified; otherwise it moves to aggregates, with
its grain, mapping source, consistency and a one-sentence caveat. A
deprecated or orphaned aggregate appears in neither. The ROUTING line
renders the same split, and the offered table is still disclosed in full so
the agent can see the grain it has to cover. The layer file is not modified
by the read, and semlayer review rejecting a mapping still removes it from
the producer's list as before.
The agent context is part of the benchmark prompt, so the messy_mart answer
cassettes miss after this change. They already missed before it (the
release-gate note at 0.7.0-beta.1 records the re-record as owed), so no
test that replayed yesterday skips today.
Whether the answer step worked is now a measurement
The session event recorded which MCP tools were called and could not say
whether any of them produced an answer. tools says run_sql was called;
it cannot say whether rows came back, whether the statement was refused,
whether check_sql stopped it, or whether the warehouse rejected it. A
session refused four times and a session that answered four questions were
the same row.
run_sql on mcp events is four integer counts — ran, refused,
lint_blocked, warehouse_error — all four always present, each capped at
999. Never the SQL, never the error text, never a table name, never a
per-call timestamp, and a test asserts that over the whole serialized
event rather than over the one field.
Counted where each outcome happens rather than classified afterwards,
because one of them cannot be recognised after the fact: the refusal while
an inference holds the connection returns the same shape as a warehouse
rejection, so anything reading the result would file "we made you wait"
under "your warehouse is failing".
This is the measurement the keyless default was argued on — whether a layer
built with no model key actually answers questions — and it did not exist
when that decision was made. schema is 5.
A field can no longer ship undocumented
host, event_id, tools, via and requested_connector all reached
users with docs/telemetry.md updated by hand and the internal field spec
untouched, for two weeks, with every check green. The spec claimed a unit
test asserted the whitelist was complete; that test only proved the
serializer drops unknown keys, which is a different property, and nothing
tied the shipped field list to any document.
Every key the serializer can write must now appear in docs/telemetry.md
or the suite fails naming it. The public page is the promise that has to be
right, so that is what the test reads.
v0.7.0-beta.1 — the whole loop runs in the chat
This release finishes the job you can do from a chat. Add the MCP server to Claude Code, Claude Desktop or Cursor and the whole loop happens there: connect to a warehouse, build the semantic layer, get the context for a question, run the SQL, see what the answer assumed, correct it, and save or export the result. No terminal step, and with uv installed, nothing to install first:
{ "mcpServers": { "semlayer": {
"command": "uvx",
"args": ["--with", "semlayer[warehouses]", "semlayer", "mcp"] } } }You do not need a model key to get a layer
Statistics, primary and foreign keys, join paths, metrics, routing knowledge and the lint all run with no ANTHROPIC_API_KEY. What you lose is the written descriptions, and the layer now says so plainly instead of leaving you to infer it from a model: none string. A layer somebody hand-wrote reports nothing rather than claiming to be ours.
Every answer carries what it assumed
run_sql runs one read-only SELECT and returns the rows with assumptions underneath: the claims nobody has confirmed, what the engine saw, and whether accepting one would change behaviour. Say yes and review_answer records it, signed, and writes it through to the layer file — the claim stops appearing on the next answer, and the verdict outlives the session.
Who may decide what is a line, not a setting. An agent may accept a claim where accepting changes no behaviour. It may not accept one that unlocks behaviour — a decode guess, an aggregate table becoming routable, a discovered filter, two columns being the same thing. There it proposes with its reasoning and a person confirms.
SELECT-only, decided by parsing
DELETE, UPDATE, INSERT, MERGE, CREATE, DROP, TRUNCATE, GRANT, COPY, SELECT … INTO and a second statement after a semicolon are refused. A column named deleted_at is not a write, and a parse knows that where a word search does not. Your SQL is never rewritten — no LIMIT appended, no filter injected: a required filter is reported and left undone, so what ran is what you can be shown. Ten-minute default time limit, enforced by the warehouse itself.
infer shows a progress bar, and the server answers while it runs
The four loops that take the time report from inside themselves, so you get "profiling table 24 of 36", a monotonic percentage and a rough ETA, streamed to your client as MCP progress. The stage weights behind that percentage were measured on a live 116-table run, not assumed.
A synchronous infer used to freeze the whole server for the length of its wait — a status sent one second in went unanswered for 5.9 more. It is now answered in hundredths of a second, with a regression test that fails against the old version.
A credential pasted into the chat works, for that session only
The agent is still told never to ask for one. When it happens anyway, the value is held in memory and goes nowhere else: not to disk, not to a log, not into telemetry, the layer, the run report or the cache key. status shows the connection redacted, and the redacted form is what the cache is keyed on.
The benchmark table was not re-measured for this release
docs/benchmark.md still describes 0.6.0b1, and this release does not restate it. Read every row as 0.6.0b1. The engine has since changed in a way that reaches the benchmark's prompts, so some committed recordings no longer replay; the release workflow runs that check and prints its result, and at this release it does not block publishing. Re-recording and re-measuring is owed before any number on that page can carry 0.7.0b1. Both causes are written down at the check itself.
Telemetry: the new MCP tools and the setup prompt join the tools whitelist, and an inference started by an agent is recorded with via: mcp. No new fields. What is sent and what is never sent: docs/telemetry.md.
Full detail in CHANGELOG.md.
v0.6.0-beta.1 — telemetry is now sent
This release sends anonymous usage statistics. Earlier versions recorded them to a local file and transmitted nothing. The first run prints a notice saying so, once.
semlayer telemetry --show # exactly what would be sent, before it is
semlayer telemetry --off # off permanently
semlayer telemetry --on # back on
semlayer telemetry # which switch is in effectSent: command, duration, outcome, error class, warehouse type, bucketed table and column counts, per-stage timings, version, Python major.minor, OS, architecture.
Never sent: table or column names, schema or database names, connection URIs, credentials, SQL, cell values, file paths.
That is enforced rather than promised. Every field passes through a whitelist — a caller cannot send an undeclared key, and counts are bucketed in the serializer rather than at call sites, so an exact count cannot escape even by mistake. Full field list and reasoning: docs/telemetry.md.
Events collected by earlier versions are discarded, not sent. They were recorded while the documentation promised nothing left your machine, so transmitting them would make that promise retroactively false. The first run of this version deletes the existing spool and starts fresh.
Sending happens at the end of a command, in a background thread with a 1.5-second deadline. A slow or unreachable endpoint cannot slow or hang your command, and the spool is cleared only when the server confirms receipt — a failure never destroys pending events.
Ordinary mistakes no longer look like crashes
A mistyped filename and an unsupported warehouse URI both produced a Python traceback. They now produce an error and a hint:
$ semlayer validate nope.yaml
FAIL nope.yaml
file not found: nope.yaml
$ semlayer infer snowflake://nope
error: unsupported source uri: snowflake://nope
hint: expected one of: snowflake, bigquery, duckdb:<path>, postgres, postgresql://<dsn>
validate reports a missing file and carries on with the rest, rather than stopping on the first.
The telemetry off switch now works
telemetry.py previously documented a telemetry key in ~/.semlayer/config as a way to disable it. Nothing ever read that file — there is no config file in this package. Only SEMLAYER_TELEMETRY worked, so anyone who followed that instruction had not opted out. Nothing was transmitted either way, because no sender existed; this was fixed before one did.
--no-llm is documented more precisely
SECURITY.md said it meant "nothing leaves your environment at all". It means no schema, column names, or sample values reach a model provider — a statement about where your data goes, not about all network traffic. Corrected before telemetry made the old phrasing false, not after.
Install: pip install semlayer==0.6.0b1