bino serve

bino serve starts a production HTTP server that serves a LiveReportArtefact as an interactive web application. Unlike preview, serve does not watch for file changes and renders on-demand per request.

Usage

bino serve --live <name> [flags]

Required flags:

• --live – name of the LiveReportArtefact to serve (required).

Common flags:

• --work-dir – report bundle directory (default: .).
• --port – HTTP port (default: 8080).
• --addr – full listen address (overrides --port, e.g. 0.0.0.0:8080).
• --log-sql – log executed SQL queries.

How it works

1. Loads configuration – reads all manifests from the work directory.
2. Validates routes – ensures the selected LiveReportArtefact has a root route and all referenced ReportArtefacts exist.
3. Serves on-demand – renders reports when requested, using caches for efficiency.
4. Nvigation – enables smooth client-side navigation without full page reloads.

Query parameters

Each route in a LiveReportArtefact can define its own query parameters that are substituted into report documents using ${VAR} syntax. This allows dynamic filtering and customization of reports on a per-route basis.

Query parameters support different input types in the serve UI sidebar:

• string (default) – text input
• number – numeric input with optional min/max/step
• number_range – dual range slider for range filtering
• select – dropdown with static items or options from a DataSet
• date – date picker
• date_time – date and time picker

Parameters are required by default. To make a parameter optional, either:

• Set a default value, or
• Set optional: true (the parameter will be empty if not provided)

If a required parameter is missing, the server returns HTTP 400 with a JSON error listing the missing parameters.

apiVersion: bino.bi/v1alpha1
kind: LiveReportArtefact
metadata:
  name: sales-dashboard
spec:
  title: "Sales Dashboard"
  routes:
    "/":
      artefact: overview-report
    "/region":
      artefact: region-report
      title: "Regional Sales"
      queryParams:
        - name: REGION
          type: select
          default: "all"
          description: "Filter by region (has default)"
          options:
            items:
              - value: "all"
                label: "All Regions"
              - value: "EU"
                label: "Europe"
              - value: "US"
                label: "United States"
        - name: YEAR
          type: number
          description: "Year to display (required)"
          options:
            min: 2000
            max: 2030
        - name: NOTES
          optional: true
          description: "Optional notes filter"

Access with: http://localhost:8080/region?REGION=EU&YEAR=2024

See LiveReportArtefact reference for full documentation of parameter types and options.

Default Arguments via bino.toml

Set default values for serve flags in your project’s bino.toml:

[serve.args]
port = 8080
live = "sales-dashboard"
log-sql = true

Environment Variables via bino.toml

Set environment variables for serve in bino.toml:

[serve.env]
BNR_MAX_QUERY_ROWS = "100000"
DATABASE_URL = "postgres://localhost/prod"

Examples

Serve a live report artefact:

bino serve --live sales-dashboard

Serve on a specific port with SQL logging:

bino serve --live sales-dashboard --port 3000 --log-sql

Serve bound to all interfaces (for Docker/Kubernetes):

bino serve --live sales-dashboard --addr 0.0.0.0:8080

Comparison with preview

Feature	bino preview	bino serve
File watching	✓ Yes	✗ No
Hot reload	✓ Yes	✗ No
Query param substitution	✗ No	✓ Yes
Production-ready	✗ No	✓ Yes
Navigation	✗ No	✓ Yes
Default port	45678	8080

Use preview during development for fast iteration. Use serve for production deployments.