Evidence (evidence-dev/evidence): SQL and Markdown Reports Instead of Drag-and-Drop BI

What Evidence Replaces, and for Whom

Evidence is described in its README as an open-source, code-based alternative to drag-and-drop business intelligence tools. That single sentence sets the audience: people who are comfortable writing SQL and markdown and who find a visual query builder slower than a text editor. The README frames the output as reports, not dashboards in the abstract, and lists SQL and markdown as the two authoring surfaces. The topics attached to the repository include analytics, business-intelligence, data-engineering, data-visualization, dbt, duckdb and webassembly, which suggests the intended neighborhood is the analytics-engineering stack rather than the general office reporting market. The problem it addresses is the gap between where analysis actually happens (SQL files, dbt models, notebooks) and where it gets presented (a separate BI tool with its own query layer, its own permissions model and its own copy of the logic). Evidence keeps the query in text and the page in text, so both can live in a git repository and be reviewed like code. Who it is for, concretely: an analyst or analytics engineer who already has a warehouse and already writes SQL, and who wants the report to be a build artifact rather than a saved object inside a vendor's database.

The Mechanism: SQL and Markdown Compiled to a Static Site

The repository layout shows the split clearly. There is a cli/ directory and a core/ directory at the top level, plus docs/, patches/ and a pnpm workspace file. The root package.json is private and declares [email protected] as the package manager, with workspace scripts that filter on @evidence/core and @evidence/cli. That tells you the tool is a monorepo with a command-line front end and a rendering engine behind it, not a single bundled application. The README's own description of the flow is short: create reports in code using SQL and markdown, develop locally or through an agent, then self-host or publish on Evidence Studio. The publishing line is the important architectural claim. Evidence does not appear to serve reports from a long-running application server that you must operate; the README says you can self-host the generated static site on your own infrastructure. Static output plus SQL at build time is a different trade-off from a BI server that queries on every page load. It means the data is materialized when the site is built, which is fast to serve and easy to put behind a CDN, and it also means freshness is a build concern rather than a query concern. The recent release list shows separate published packages, including @evidence-dev/universal-sql, @evidence-dev/trino and @evidence-dev/tailwind, so the SQL layer, connector layer and styling layer are versioned independently. The topics list mentions Svelte and Tailwind CSS, which is consistent with a compiled front end rather than a runtime dashboard framework.

Installing Evidence and Running a First Project

The README gives a one-line installer per platform. On macOS or Linux the shell script is piped to sh, and on Windows the PowerShell script is piped to iex. Both are followed by evidence help, which is the command that confirms the binary is on your path and prints the available subcommands. Run the version for your platform only; the README does not describe a package-manager install path such as npm or Homebrew, so treat the installer script as the documented route.

curl -fsSL https://evidence.studio/install.sh | sh
evidence help

On Windows the equivalent is a PowerShell invocation. The README shows the same pattern: fetch the script, pipe it into the expression evaluator, then ask the CLI for help. If your environment blocks remote script execution, the README does not document an offline alternative, so that is a question for the project's Slack channel.

irm https://evidence.studio/install.ps1 | iex
evidence help

With the CLI installed, project creation is three commands from the README: initialize a project, change into it, and start the development server. The README does not state which port evidence dev binds to, so watch the terminal output after starting it rather than assuming a number.

evidence init my-project
cd my-project
evidence dev

What you should see: evidence init scaffolds a project directory named my-project, and evidence dev starts a local development server that serves the report pages. The README does not enumerate the files that init creates, so open the generated directory and read it before editing. To publish, the README points to two routes: Evidence Studio for hosted reports, or self-hosting the generated static site. The publishing documentation lives at https://docs.evidence.studio/publishing.

Where Evidence Is the Wrong Tool

The static-site model is the main constraint, and the README does not pretend otherwise. If your users need to slice data interactively against a live warehouse connection, with filters that trigger new queries on demand, a build-time SQL model will not give them that without a rebuild. The README's language is reports and static site, not live query console. A second limitation is the install path itself. The documented install is a remote script piped into a shell. That is a normal pattern for developer CLIs, but it is also the kind of command that many corporate environments block outright, and the README offers no documented fallback such as a package registry install. A third issue is what the README does not say. It does not document rollback, it does not document the file layout that evidence init produces, and it does not document which database backends ship by default. The presence of a @evidence-dev/trino package in the release list implies connector packages exist, but the README does not list the supported sources, so anyone evaluating Evidence against a specific warehouse has to read the docs rather than the front page. Finally, the repository's own search footprint is a warning about naming: the project competes for the word evidence with legal, scientific and everyday uses of the term, which makes documentation and internal naming harder than for a project with a distinctive name.

Compared with a Notebook or a dbt Docs Site

The closest thing to a real alternative in Evidence's own framing is the drag-and-drop BI tool, but the more useful comparison for a data team is a notebook plus a static site generator, or a dbt docs site. A notebook keeps SQL and prose together and is excellent for exploration, but its output is a document, not a parameterized report page with shared components. A dbt docs site is generated from a dbt project and describes models, tests and lineage; it is documentation of the transformation layer, not a place to lay out charts for a business audience. Evidence sits between them: the README says you write SQL and markdown, and the output is a published report site. The difference in approach is that Evidence treats the report page as the primary artifact and the query as an input to it, whereas dbt treats the model as the primary artifact and documentation as a byproduct. If your team already runs dbt, the topics list on the repository includes dbt, so the two are meant to coexist rather than replace each other. The practical question is whether you want your presentation layer to be a separate build from your transformation layer. Evidence says yes by design.

Maintenance, Release Cadence and Licence

The repository is not archived, and the last push was on 2026-09-09. That is recent enough that the project should be treated as maintained, but note the shape of the release history: the most recent releases listed are @evidence-dev/[email protected], @evidence-dev/[email protected] and @evidence-dev/[email protected], all dated 2026-02-06. Those are scoped packages with independent version numbers, and the major version on universal-sql is 3, which tells you the SQL layer has already gone through breaking changes. If you depend on that package directly rather than through the CLI, plan for major-version upgrades. The root package.json pins [email protected] and carries a long overrides block covering transitive dependencies such as zod, lodash, esbuild, undici, vite and postcss, plus patched dependencies for ssf, [email protected] and zrender. That overrides list is a maintenance signal in both directions: the maintainers are actively pinning known-vulnerable transitive packages, and the list is long enough that dependency drift is a real ongoing cost for anyone building from source. The licence is MIT, stated in the README and in the LICENSE file at the repository root. MIT is permissive and places few obligations on how you redistribute or host the output, but the README does not describe the terms of Evidence Studio hosting, which is a separate service from the open-source code. Check the Studio terms separately if you plan to publish there rather than self-host.

Editorial conclusion

Adopt Evidence if your team already keeps SQL in version control and wants report pages that build from that SQL rather than from a drag-and-drop canvas, and if you accept that the README documents the CLI path but not deployment internals. Do not adopt it if you need a hosted BI product with a documented rollback story or a GUI-first authoring model for non-technical staff. Before committing, verify three things in the repository and docs: what evidence init writes into a new project, what evidence dev serves locally, and which publishing route (Evidence Studio or self-hosted static output) matches your environment. The README points at https://docs.evidence.studio/publishing for the second of those, and that page is where the real deployment decision lives.

Frequently asked questions

Official sources

1. evidence-dev/evidence on GitHub
2. License: MIT
3. Project website
4. README
5. Releases