Write SQL. Get a dashboard.

Write the SQL query you already know how to write, add a few -- @ comments, and asql renders it into a polished, self-contained HTML analytics report. No BI tool, no notebook, no JavaScript, no <div> wrangling. Your SQL runs through an embedded DuckDB engine, with no server to stand up.

$curl -fsSL https://www.asql.dev/install.sh | sh

$docker pull ghcr.io/cuiqanalytics/asql

Free. First dashboard in about 60 seconds. No account, no telemetry.

Apple Silicon? The image is linux/amd64 only: add --platform linux/amd64.

Monthly Revenue by Channel

Direct Paid Partner

Built by asql build report.sql from the query below.

From a prompt to a `git diff` in 46 seconds

Prompt → readable SQL → dashboard → one-word edit → git diff. No cuts.

A few comments in. A chart out.

Above the query, -- @report names the report and -- @chart: trend names the intent. asql reads the result columns, date, series and value, and draws a multi-series line chart with axes, legend and number formats.

The file is still plain SQL. duckdb < report.sql runs it unchanged.

-- @report
-- title: Revenue Dashboard
-- subtitle: 2026

-- @chart: trend
-- title: Monthly Revenue by Channel

SELECT
    date_trunc('month', d)                AS date,
    channel                               AS series,
    base + date_diff('month', DATE '2025-01-01', d) * growth
        + (random() * 20000)::int         AS value
FROM range(DATE '2025-01-01', DATE '2026-01-01', INTERVAL 1 MONTH) AS t(d),
     (VALUES ('Direct', 190000, 46000),
             ('Paid', 160000, 25000),
             ('Partner', 55000, 26000)) AS c(channel, base, growth)
ORDER BY 1;

$ asql build report.sql
Wrote report.html

See it while you write it.

asql preview report.sql serves the report on localhost:4321. Every save rebuilds it and reloads the open tab. No build step, no refresh.

A broken query shows its error in place of the chart and recovers on your next save. Each chart has an ✎ Edit button: change its chart type, SQL or metadata in the browser, and asql writes the change back to your .sql file.

$ asql preview report.sql
Serving http://localhost:4321 — watching report.sql for changes

Real reports, real SQL

Two excerpts from the reports shipped in asql-cli's examples/. Flip a card to see the annotated query on one side and the report it builds on the other.

growth_dashboard.sql

-- @report
-- title: Northwind Cloud — Growth Monitor
-- format: dashboard
-- filter: segment

-- @chart: trend
-- title: Blended net revenue retention (%)
-- target: 100 | Breakeven | #8a8a8a

SELECT month AS date, blended_nrr AS value
FROM nrr_monthly ORDER BY 1;

The interactive Northwind Cloud growth dashboard

Interactive dashboard

growth_review.sql

-- @report
-- title: Where Northwind Cloud Should Put
--        Its Next Two Hires
-- format: narrative

-- @markdown

-- **Recommendation.** Move our two open
-- go-to-market hires from SMB new-business
-- into Mid-Market expansion, starting next
-- quarter.

The same data as a print-ready decision memo

Narrative decision memo

Why asql

The chart is inferred, not configured.

Above your query, one comment names the intent: -- @chart: trend, ranking, funnel, waterfall, heatmap and more. asql reads the result shape to pick the mark, axes, series grouping, colors and number formats. No charting API to learn, just a keyword in a comment.

One file in, one file out.

Input is runnable SQL. Output is a single .html with no asset folder. Email it, commit it, drop it on any static host.

It stays SQL.

Every annotation is a -- comment. duckdb < report.sql still works, because asql runs on DuckDB under the hood. The file never stops being valid, runnable SQL.

Two audiences, one source.

The same file builds an interactive dashboard or a print-ready narrative memo. One metadata line switches format.

Simple by default, precise when you need it.

Name your columns date, series, value and most reports need no overrides at all. When one does, add a single line (@x, target, series-color) only where you need it; the defaults never disappear. A Claude Code skill teaches an AI agent the whole syntax, so even the overrides are one prompt away.

Any DuckDB extension, right in your SQL.

A -- @setup block runs before every query, so any community extension you can INSTALL in DuckDB (read spreadsheets, diff tables, attach Postgres or MySQL) is available to every chart in the report.

It's a compiler, not a generator.

AI assistants now build dashboards on request, and they're great for exploring a question. asql is for what comes after you have the answer: a report that has to be reproducible, reviewed, shared with people who don't have a seat, and hosted where your data lives. AI assistants answer the question. asql ships the answer, on your infrastructure.

Self-hosted, end to end.

Queries run in DuckDB on your machine or server, against your files or attached databases. Nothing in the build or the output calls a vendor. Rebuild from cron or CI with the Docker image, publish on an intranet or a bucket. Works air-gapped.

The query is the dashboard.

Other tools show you the SQL behind a chart so you can check it. In asql the SQL is the source, and the chart is compiled from it.

Same input, same output, every time.

A prompt-generated dashboard is a fresh one-off each time you ask. Re-run it and you may get a different layout, different chart choices, different code. asql build report.sql renders the same result every time.

Still just SQL, not a new app to maintain.

A generated dashboard is either a new codebase (React, config, glue) that only the AI that wrote it really understands, or it lives inside someone else's app. Changing an asql report means editing the query you already had.

Diffable and reviewable.

git diff report.sql is a SQL diff anyone can read. No generated UI code to review.

No runtime you depend on.

One static .html file: no hosted app, no seat or vendor account to view it, no server in the loop. Open it in five years.

One source, two audiences.

Add one line, -- format: narrative, and the same file builds as a print-ready, single-column document with a table of contents and templated prose that pulls real numbers from the queries.

Same source. Different audience.

The same asql report built as a narrative memo: title, table of contents, prose and inline figures.

Or just ask Claude

asql ships with two Claude Code skills. asql knows the annotation syntax, the chart intents and the column names asql picks up on its own. asql-exec adds a review pass for reports headed to leadership: it leads with the decision and flags buried leads, unsupported claims and charts that mislead. Claude builds the report with asql and checks the result before it hands it over.

$~/.local/lib/asql/install-skills.sh

Turn orders.csv into a dashboard with monthly revenue by channel and our top ten customers.

I'll write orders.sql with a -- @chart: trend block that returns date, series and value, and a -- @chart: ranking block for the top customers. Then I'll run asql build orders.sql and check every chart renders before handing it over.

It grows with you.

Today asql is free, runs on your machine, and leaves nothing behind but a file you own. That isn't a limitation to be fixed later; it's the foundation.

The same annotated SQL that builds a file on your laptop is what will keep a dashboard current on a schedule, on servers you run. Same input, more places to put the output.

$curl -fsSL https://www.asql.dev/install.sh | sh

Read the docs

Questions

Does asql need internet access or an account?

No account and no telemetry, and builds run offline. Opening a dashboard is different: the page loads its charting library (Vega) from a public CDN, so the person viewing it needs internet access. Narrative reports draw their charts as inline SVG and only use the CDN to render math.

Where does my data go?

Queries run in DuckDB on your machine or server, and nothing is sent to us. The query results are embedded in the .html file, which is what lets filters work without a server. Anyone who has the file can read those rows, so share it the way you'd share the data.

What data can it read?

Anything DuckDB can: CSV, Parquet and JSON files, DuckDB databases, and Postgres or MySQL through DuckDB's extensions. Put the ATTACH or INSTALL in a -- @setup block and every chart in the report can use it.

Does it run on macOS and Windows?

The native binary is for Linux (x86-64). On macOS and Windows, use the Docker image: docker pull ghcr.io/cuiqanalytics/asql. On Apple Silicon, add --platform linux/amd64. asql preview isn't reachable from outside the container, so live preview needs the native install.

How is this different from a BI tool?

There's no server to run and no seats to buy. A report is a .sql file in your repo, and the output is a static .html file anyone can open. You review changes with git diff, not in a vendor's UI.

Can I keep a report up to date?

Yes. Run asql build from cron or CI, for example with the Docker image, and publish the file wherever you host static pages. --var client=acme builds one report per client or month from the same .sql file. Repeat builds skip queries that haven't changed.

Can I change how reports look?

Yes. A theme is a small CSS file of variables for colors, fonts and the chart palette. Pass it with --theme. Five themes ship in themes/.

Is asql free?

Yes. The binary and the Docker image are free to use. The source code isn't open.

Who owns the reports I build?

You do. The .sql files and the reports you generate with asql are yours.

Can an AI assistant use asql?

Yes. Install the Claude Code skills and describe the dashboard you want. Claude writes the .sql file, builds it with asql and checks that every chart renders.