bino

Pixel-perfect PDF reports from YAML manifests and SQL queries.

Documentation · Download · Discussions

Warning

bino is under active development. Configuration and CLI APIs are not yet stable — expect breaking changes between releases.

Note

bino is currently tightly coupled to bn-template-engine as its visualization engine. This coupling will be removed in a future release, making the Viz Engine pluggable.

What is bino?

bino is a command-line tool that turns declarative YAML manifests and SQL queries into production-ready PDF reports. It uses DuckDB as an embedded SQL engine and Chrome headless shell for pixel-perfect PDF rendering.

For full documentation, visit cli.bino.bi.

Highlights

• Declarative reports — Define data sources, queries, layouts, and artefacts in YAML. No imperative code required.
• SQL-native — Query CSV, Excel, Parquet, and databases using DuckDB's full SQL dialect.
• Pixel-perfect PDFs — Chrome headless shell renders HTML templates to PDF with precise control over layout, pagination, and styling.
• Live preview — bino preview watches for changes and hot-reloads in the browser via SSE.
• Validation & linting — bino lint catches manifest errors before build. JSON Schemas power IDE auto-completion.
• VS Code extension — YAML validation and auto-completion for bino manifests, available in vscode-bino/.

Quick Start

Install

macOS (Homebrew):

brew install bino-bi/tap/bino-cli

Linux / macOS (script):

curl -fsSL https://github.com/bino-bi/bino-cli-releases/releases/latest/download/install.sh | bash

Windows (PowerShell):

irm https://github.com/bino-bi/bino-cli-releases/releases/latest/download/install.ps1 | iex

Or download a binary from the latest release.

First Report

bino init my-report      # scaffold a new report bundle
cd my-report
bino build               # build all artefacts

See the Getting Started guide for a full walkthrough.

Architecture

Manifest Discovery → YAML Parsing → Validation → Datasource Collection → Dataset Execution → HTML Rendering → PDF Generation

Manifests are YAML documents typed by a kind field (DataSource, DataSet, LayoutPage, ReportArtefact, etc.). DuckDB serves as the embedded SQL engine for all data queries. Chrome headless shell converts rendered HTML into PDF output.

Template Engine Compatibility

Each bino release declares the range of bn-template-engine versions it supports. The contract lives in internal/engine/compat.go as SupportedEngineRanges and is enforced by build, preview, serve, lint, and lsp. On a mismatch, build/preview/serve exit non-zero before any pipeline work; lint reports rule engine-version-incompatible and exits non-zero; lsp (and the VS Code extension) publishes an error-severity diagnostic on the engine-version line of bino.toml.

Range syntax follows npm conventions (comparators, hyphen ranges, x-ranges, tilde, caret, AND within an entry, OR across entries) with npm pre-release inclusion semantics: a pre-release version satisfies a range only when at least one comparator in that range explicitly mentions a pre-release of the same MAJOR.MINOR.PATCH.

Current supported ranges: >=1.0.0-alpha, <2.0.0-0 — any 1.x release or pre-release is accepted; 0.x and 2.0.0+ are rejected. To use a specific engine version, pin it in bino.toml:

engine-version = "v1.0.0-alpha.14"

If the version is not yet cached locally, run bino setup --template-engine --engine-version v1.0.0-alpha.14.

Directory structure

cmd/bino/main.go        Entry point with signal handling and context setup
internal/cli/            CLI commands (build, preview, serve, lint, graph, init, lsp, cache)
internal/report/         Core report processing engine
  config/                  YAML manifest loading and validation
  spec/                    Schema and constraint definitions
  datasource/              Data source collection (CSV, Excel, databases via DuckDB)
  dataset/                 SQL query execution
  pipeline/                Build orchestration
  render/                  HTML/PDF rendering
pkg/duckdb/              Exportable DuckDB session wrapper
vscode-bino/             VS Code extension (TypeScript)
docs/                    Documentation website (cli.bino.bi)

Building from Source

Prerequisites

• Go 1.25 or later
• CGO enabled (required for DuckDB)
• Chrome headless shell (for PDF rendering — bino setup downloads it automatically)

Build

goreleaser build --snapshot --clean --single-target

On macOS, copy the binary to your PATH and sign it:

cp ./dist/bino_darwin_arm64_v8.0/bino ~/go/bin/bino
codesign --force --sign - ~/go/bin/bino

Development

go test -v -race ./...          # run all tests
golangci-lint run ./...         # run linter
go test -run TestName ./...     # run specific test
go test -v -race -coverprofile=coverage.out ./...  # test with coverage

Runtime limit overrides

Variable	Default	Description
BNR_MAX_MANIFEST_FILES	500	Max manifest files to scan
BNR_MAX_QUERY_ROWS	100,000	Max rows returned per query
BNR_MAX_QUERY_DURATION_MS	60,000	Query timeout in milliseconds
CI	—	Set to 1 to disable update check

VS Code Extension

The vscode-bino/ directory contains a VS Code extension providing YAML validation and auto-completion for bino manifests. See vscode-bino/ for build instructions.

Contributing

Contributions are welcome! Please read the Contributing Guide before submitting a pull request.

Security

To report a vulnerability, please see our Security Policy.

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPLv3) — see the LICENCE file for details.

Commercial licensing

bino/bino-cli is also available under separate commercial terms for customers who cannot comply with AGPLv3 (e.g., closed-source SaaS deployments or embedding bino in proprietary products). Contact sven@bino.bi for a commercial license quote.

All contributions are accepted under a Contributor License Agreement that permits this dual-licensing model.

Third-Party Dependencies

Run bino about to list all direct dependencies with their licenses and upstream URLs.