bino build

bino build is the main command for producing PDFs from your report bundle. It validates manifests, runs SQL in the embedded query engine, and renders PDFs via the rendering engine.

Usage

bino build [flags]

Common flags:

• --work-dir – report bundle directory (default: .).
• --out-dir – output directory relative to workdir (default: dist).
• --artefact – build only specified artefact names (can be repeated).
• --exclude-artefact – skip specified artefact names (can be repeated).
• --browser – browser engine for the rendering runtime (for example chromium, firefox, webkit).
• --no-graph – skip writing dependency graph files.
• --no-lint – skip running lint rules (lint runs by default).
• --log-sql – log executed SQL queries.
• --data-validation – data validation mode: warn (default), fail, or off. See Data Validation.

Advanced flags:

• --driver-dir – override Playwright driver cache directory.

Build log flags:

• --log-format – log format: text (default) or json.
• --embed-data-csv – embed CSV data previews in JSON log.
• --embed-data-max-rows – maximum rows to embed per query (default: 10).
• --embed-data-max-bytes – maximum bytes per embedded CSV (default: 65536).
• --embed-data-base64 – base64 encode embedded CSV data (default: true).
• --embed-data-redact – redact sensitive columns in embedded data (default: true).
• --detailed-execution-plan – include step-by-step timing.

See Build Logs for full documentation on JSON logs, CSV embedding, and execution plan tracking.

Default Arguments via bino.toml

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

[build.args]
out-dir = "output"
browser = "firefox"
log-sql = true
no-lint = false
artefact = ["monthly", "weekly"]
exclude-artefact = ["draft"]

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

$ bino build --browser webkit
Overriding browser from bino.toml ("firefox" -> "webkit")

Environment Variables via bino.toml

You can also set environment variables for builds in your bino.toml. This is useful for configuring query limits or connection strings:

[build.env]
BNR_MAX_QUERY_ROWS = "100000"
BNR_MAX_QUERY_DURATION_MS = "120000"
DATABASE_URL = "postgres://prod-server/reports"

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=200000 bino build
Environment variable BNR_MAX_QUERY_ROWS overrides bino.toml ("100000" -> "200000")

See bino init for the full configuration reference.

Examples

Build all reports in the current directory:

bino build

Build only selected artefacts:

bino build --artefact monthly_sales --artefact annual_sales

Change the output directory and log SQL:

bino build --out-dir dist/reports --log-sql

Data Validation

bino can validate query results against the DataSet schema to catch data structure issues early. Validation checks include:

• Type validation: Ensures fields like category are strings and ac1 are numbers.
• Enum validation: Verifies operation is "+" or "-".
• Date format: Checks date fields are ISO 8601 format (YYYY-MM-DD).
• Dependent required: Ensures paired fields are present (e.g., rowGroup requires rowGroupIndex).

Validation modes:

• --data-validation=warn (default) – log validation warnings and continue building.
• --data-validation=fail – treat validation errors as fatal and exit with code 1.
• --data-validation=off – skip data validation entirely.

For efficiency, only the first rows are validated (default: 10). Configure via BNR_DATA_VALIDATION_SAMPLE_SIZE:

BNR_DATA_VALIDATION_SAMPLE_SIZE=100 bino build

CI tips

• Use --work-dir to point at the repository checkout.
• Fail builds early by ensuring environment variables for secrets are set.
• Archive the dist/ directory as a build artefact.
• Set consistent build options in bino.toml to ensure reproducible CI builds.
• Use --data-validation=fail in CI to catch data issues before reports reach production.