Evidence: SQL and Markdown Reports That Compile to a Static Site
Business intelligence as code: build fast, interactive data visualizations in SQL and markdown
At a glance
- What is it?
- Evidence is an MIT-licensed TypeScript tool that turns SQL queries and markdown pages into interactive reports you can self-host. The pitch is business intelligence as code, and the README is short enough that the interesting questions sit in the parts it leaves out.
- Who is it for?
- Adopt Evidence if your team already keeps SQL in version control and wants dashboards that live in the same repository, and if you are willing to treat the CLI as the interface. Do not adopt it if you need a governed semantic layer or a point-and-click builder for non-technical authors, because the README describes neither.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The Problem Evidence Targets: Dashboards That Live in Git
Drag-and-drop BI tools keep the report inside the tool. The query, the layout and the formatting live in a vendor's database, and the only way to review a change is to open the tool. Evidence inverts that. The repository describes the project as an open-source, code-based alternative to drag-and-drop business intelligence tools, and the README's first bullet is the whole design: create reports in code using SQL and markdown. The audience follows from that. It is for analysts and data engineers who already write SQL and already use git, and who would rather review a dashboard change as a diff than as a screenshot. It is a poor fit for someone whose job is to hand a non-technical colleague a builder canvas, because nothing in the supplied material describes one. The second audience is newer and worth naming: the README says you can develop using Evidence's Agent, or on your local machine with Claude Code or Cursor. That places the project in the camp of tools designed to be edited by coding agents as much as by people.
What Actually Runs: SQL, Markdown, and a Build Step
The README does not document an architecture, so the mechanism has to be read off the surface. The inputs are SQL and markdown. The output, per the publish section, is a generated static site: you either publish on Evidence Studio for hosted reports, or self-host the generated static site on your own infrastructure. That single sentence is the most consequential technical fact available, because it means the report is a build artifact rather than a live application querying a warehouse on every page load. The topics list on the repository points at the pieces involved: Svelte, Tailwind, WebAssembly, DuckDB, dbt, and a set of connector packages. The release feed confirms that connectors are shipped as separate versioned packages rather than baked into one binary. The most recent releases listed are @evidence-dev/universal-sql, @evidence-dev/trino and @evidence-dev/tailwind, each on its own version number. So the practical picture is a monorepo of npm packages, one per data source plus shared runtime pieces, assembled by a CLI. Anything beyond that, such as how queries are cached at build time or how the WASM layer is used, is not stated in the material I have and I will not guess at it.
Installing and Scaffolding: The Three Commands That Matter
The install path is a shell script piped to sh on macOS and Linux, and a PowerShell equivalent on Windows. The README gives both verbatim: curl -fsSL https://evidence.studio/install.sh | sh followed by evidence help, and irm https://evidence.studio/install.ps1 | iex followed by evidence help. Piping a remote script into a shell is a normal pattern for developer CLIs and it is also a supply-chain decision, so on a managed machine you may want to read the script before running it. Project creation is three commands: evidence init my-project, then cd my-project, then evidence dev. The init step is where a data source would be wired up, though the README does not show that step or name any configuration keys, so I cannot tell you what the generated config file is called or what it contains. That gap matters more than it looks. The topics list names dbt, DuckDB and Trino, and the release feed shows a Trino connector package, but the README never explains how a project points at a warehouse. If you are evaluating this, the first thing to do after evidence init is open the generated project and read its config, because that is where the connector story actually lives.
Two Publish Paths and the Trade-off Between Them
Evidence offers hosted and self-hosted publishing, and they are not equivalent. Evidence Studio gives you hosted reports, which is the low-effort path and the one the README leads with. Self-hosting means taking the generated static site and serving it from your own infrastructure. The self-hosted route is the reason a team with data residency constraints would look at this project at all, and it is also the route with the least documentation in the material supplied. A static site is easy to serve and hard to permission. There is no mention of row-level security, user authentication, or per-viewer filtering anywhere in the README. If your reports contain anything that not every viewer should see, the static export model means access control is a property of the host and the network, not of the report. That is a real constraint, not a nitpick, and it is the kind of thing that gets discovered late when a dashboard is moved from a laptop to a shared URL.
Where the README Stops Being Useful
The documentation gaps are consistent enough to be a pattern. There is no supported data source list in the README, only topics and a Trino package in the release feed. There is no configuration reference. There is no description of how the build handles a slow query, a failed connector, or a schema change, which are the three things that break a build-time report pipeline in practice. There is no versioning or upgrade guidance beyond the existence of independently versioned packages. The README points to docs.evidence.studio and a Slack channel, so the assumption is clearly that the real documentation lives elsewhere. That is a reasonable choice for a project of this shape, but it means the README alone is not enough to decide whether Evidence fits your warehouse. The release cadence visible in the feed is also worth reading carefully: the three most recent releases are all dated 2026-02-06, which suggests coordinated package bumps rather than a single product release, so pinning versions across the @evidence-dev scope is likely to matter more here than in a project that ships one artifact.
How Evidence Differs From a Semantic-Layer BI Tool
The obvious comparison is a warehouse-native BI tool that sits on top of a semantic model, where metrics are defined once and every chart references that definition. Evidence's approach is the opposite by default: the SQL is in the report file, next to the markdown that frames it. The difference shows up when two reports need the same number. With a semantic layer, you change the definition and both reports move. With SQL in the page, you either duplicate the query or find some other way to share it, and nothing in the README describes a shared metric layer. The topics list does include dbt, which is a signal that the intended pattern is to push transformation and metric definition upstream into dbt models and keep the Evidence queries thin. That is a coherent architecture and it is also an assumption the README never states outright. If your team does not already run dbt or something like it, the SQL-in-markdown model will drift toward copy-pasted queries faster than a semantic-layer tool would.
Licence, Maintenance, and Upgrade Cost
The licence is MIT, stated in the README and confirmed by the repository metadata. MIT is permissive: you can use, modify and redistribute the code, including in commercial settings, provided the copyright notice and licence text are preserved. That is the general shape of the licence and not legal advice; if you are embedding Evidence in a product, have counsel read the LICENSE file. The maintenance picture is more interesting than the licence. Because the tool is published as a set of scoped packages with independent version numbers, an upgrade is not one decision. The feed shows @evidence-dev/universal-sql at 3.0.1, @evidence-dev/trino at 1.0.11 and @evidence-dev/tailwind at 3.1.4, all released on the same day. A major bump in the SQL runtime and a patch in a connector can arrive together, and the connector's compatibility with the runtime is something you would need to verify per upgrade. The practical cost is that someone on the team has to own the dependency graph, not just the report content. The compensating factor is that the output is a static site, so a broken upgrade is caught at build time rather than in front of a viewer.
Who Should Adopt Evidence, and What to Check First
Adopt it if your analysts write SQL, your team reviews changes through pull requests, and you want the report to be a build artifact you can host yourself. The MIT licence and the static output make it easy to reason about where the data ends up. Do not adopt it if you need a governed metric layer, per-user permissions, or a drag-and-drop authoring surface, because the README describes none of those and the static publish model actively works against the second one. If you are on the fence, the cheapest test is to run evidence init, open the generated project, and read the config file to see which connector it wires up by default. That single file will tell you more about fit than the rest of the README does, because the connector list is the boundary of what Evidence can actually query.
Editorial conclusion
Adopt Evidence if your team already keeps SQL in version control and wants dashboards that live in the same repository, and if you are willing to treat the CLI as the interface. Do not adopt it if you need a governed semantic layer or a point-and-click builder for non-technical authors, because the README describes neither. Before committing, verify three things against your own data: that a connector exists for your warehouse, that the self-hosted build output fits your deployment target, and that the generated site is acceptable to whoever owns data access, since a static export is only as private as the host you put it on.
Community notes