bino preview

bino preview starts a local HTTP server that renders your report in a browser. It reloads automatically when you change manifests or data files.

Usage

bino preview [flags]

Common flags:

• --work-dir - report bundle directory (default: .).
• --port - HTTP port (default: 45678), bound on 127.0.0.1.
• --addr - full listen address, overriding --port (e.g. 0.0.0.0:8080). Needed inside a container, where the default loopback bind is the container’s own. A non-loopback bind exposes the unauthenticated /__explorer/query SQL endpoint to anything that can reach it, and suppresses the automatic browser open.
• --artefact - preview only specified artefact names (can be repeated).
• --exclude-artefact - skip specified artefact names (can be repeated).
• --log-sql - log executed SQL queries.
• --lint - run lint rules on each refresh (disabled by default).
• --data-validation - data validation mode: warn (default), fail, or off.

Documents

DocumentArtefacts render at /doc/<name> with the same live reload as report artefacts: editing a markdown source re-renders only the affected document, and edits to an embedded component or its data propagate into the open page. The preview pins the page to the artefact’s paper width and marks page breaks and header/footer bands, but real pagination and TOC page numbers appear only in a PDF. Use the toolbar’s PDF button for a quick check, or bino build for the final file. See Previewing documents for the exact contract. --artefact and --exclude-artefact filter document artefacts too.

PDF preview

Select a report or document artefact and click PDF in the toolbar. bino builds the artefact with the same code as bino build, shows the PDF in the browser and offers Download. Every page is marked PREVIEW.

The PDF preview is less strict than bino build:

• Warnings: a failing dataset query, a failed data validation (reports only) and an unset ${VAR} do not stop the build. They are listed above the PDF, and the affected parts of the PDF can be empty.
• Skipped: build hooks, signing, the dependency graph file and lint.
• Errors: a manifest that does not load, a render failure, a render timeout or a missing Chrome stop the build. The message is shown instead of the PDF.

Things to know:

• Chrome is found as in bino build: the chrome-path under [build.args] in bino.toml, then CHROME_PATH, then the browser installed by bino setup.
• The artefact is built in build mode, so mode constraints select the same pages as bino build. Environment variables come from [preview.env].
• The PDF is a snapshot. It is not rebuilt on live reload; close the window and click PDF again. Live reload waits while a PDF is being built.
• The button needs a browser tab. Inside the VS Code preview panel it shows a link to open the preview in your browser.

Dependency graph

Select an artefact and click Graph in the toolbar. The window shows the dependency tree of the artefact, down to its datasets and datasources. Click a component to see the dataset columns it reads, grouped by dataset and role. See Column references for the roles.

Default Arguments via bino.toml

You can set default values for preview flags in your project’s bino.toml file. These defaults are applied automatically and can be overridden by explicit command-line flags:

[preview.args]
port = 9000
log-sql = true
lint = true
data-validation = "warn"
artefact = ["monthly", "weekly"]
exclude-artefact = ["draft"]

When you override a TOML default, the CLI logs an info message:

$ bino preview --port 8080
Overriding port from bino.toml (9000 -> 8080)

Environment Variables via bino.toml

You can also set environment variables for preview in your bino.toml. This is useful for configuring query limits during development:

[preview.env]
BNR_MAX_QUERY_ROWS = "10000"
BNR_CDN_MAX_BYTES = "10485760"
DATABASE_URL = "postgres://localhost/dev"

Actual environment variables always take precedence over TOML values. When an env var overrides a TOML value, the CLI logs a message:

$ BNR_MAX_QUERY_ROWS=5000 bino preview
Environment variable BNR_MAX_QUERY_ROWS overrides bino.toml ("10000" -> "5000")

See bino init for the full configuration reference.

Examples

Preview the bundle in the current directory:

bino preview

Preview a different workdir and log SQL:

bino preview --work-dir my-report --log-sql

Preview only selected artefacts - useful for speeding up the live-reload loop in bundles with many artefacts:

bino preview --artefact monthly_sales --artefact annual_sales

If the browser does not open automatically, open http://127.0.0.1:45678/ manually.