Open source · Reporting as Code

Reporting as Code. Strictly IBCS®.

Write a report as YAML and SQL. bino renders it as an IBCS PDF. The files live in Git, so every change is reviewed and every report can be built again.

Get started 🚀Try the tutorial

The tutorial runs in your browser. It takes you from your first manifest to a PDF, with no install.

bino-bi/bino-cli6$ brew install bino-bi/tap/bino-cli

Page 1 of the Kestrel report: revenue by month against plan, and a table by region.

kestrel-2025.pdf · 4 pages · 258 KB · built by bino

Follow this report

YAML and SQL
DuckDB inside
PDF from headless Chrome
IBCS notation
Reviewed in Git
Built in CI
MCP server for agents
Language server
AGPL-3.0

One report, start to finish

From a CSV file to a PDF in four steps

Kestrel Outdoor GmbH is a made-up company with a real report. Scroll through the files that build it. Next to each file you see the data, or what bino built at that step.

Step 1 of 4

Point bino at the data

A DataSource names a file, a database or a URL. bino loads it into DuckDB under its name. Here it is one CSV file with 240 rows: month, region, product line, and revenue and cost of goods as actual, plan and last year.

apiVersion: bino.bi/v1alpha1
kind: DataSource
metadata:
  name: kestrel
  description: Fictional monthly revenue and cost of goods 2025 (AC, PY, PL) of Kestrel Outdoor GmbH
spec:
  type: csv
  path: ../data/kestrel_2025.csv

Open datasources/kestrel.yaml

data/kestrel_2025.csv240 rows · loaded as kestrel

First rows of data/kestrel_2025.csv
month	region	product	revenue_ac	revenue_py	revenue_pl	cogs_ac	cogs_py	cogs_pl
2025-01-01	North	Tents	47200	43500	46900	27400	25500	27200
2025-01-01	North	Backpacks	36400	33800	37300	19300	17800	19400
2025-01-01	North	Apparel	30400	30800	33100	14200	14600	15600
2025-01-01	North	Footwear	21000	18600	20700	11800	10300	11400
2025-01-01	South	Tents	62600	55900	61900	33800	31100	34100
2025-01-01	South	Backpacks	51600	45500	49200	25200	22700	24300
2025-01-01	South	Apparel	43100	39700	43700	19600	17900	19500
2025-01-01	South	Footwear	28500	25900	27300	15100	13700	14300

Step 2 of 4

Shape it with SQL

A DataSet is a SQL query. This one adds up the months. Months after REPORT_MONTH become a forecast: plan times the ratio of actual to plan so far.

apiVersion: bino.bi/v1alpha1
kind: DataSet
metadata:
  name: monthly
  description: >-
    Revenue per month in kEUR. Months up to REPORT_MONTH are actual (ac1), later months are a
    run-rate forecast (fc1): plan times the year-to-date ratio of actual to plan.
spec:
  dependencies: [kestrel]
  query: |
    WITH m AS (
      SELECT month, SUM(revenue_ac) AS ac, SUM(revenue_pl) AS pl, SUM(revenue_py) AS py
      FROM kestrel GROUP BY month
    ),
    rate AS (
      SELECT SUM(ac) / SUM(pl) AS r FROM m WHERE month(month) <= ${REPORT_MONTH:12}
    )
    SELECT
      strftime(month, '%Y-%m-%d') AS date,
      CASE WHEN month(month) <= ${REPORT_MONTH:12} THEN ROUND(ac / 1000) END AS ac1,
      CASE WHEN month(month) > ${REPORT_MONTH:12} THEN ROUND(pl * rate.r / 1000) END AS fc1,
      ROUND(pl / 1000) AS pl1,
      ROUND(py / 1000) AS pp1
    FROM m, rate
    ORDER BY month

Open datasets/monthly.yaml

The ChartTime component built from this DataSet: revenue per month against plan, with the relative variance on top. — components/monthly_chart.yaml, rendered by a bino ScreenshotArtefact with REPORT_MONTH=8

Step 3 of 4

Describe the page

A LayoutPage places a chart, a table and a text, and writes the IBCS title: who, what, when. Each dot on the page explains one part of it.

apiVersion: bino.bi/v1alpha1
kind: LayoutPage
metadata:
  name: monthly
  description: Revenue by month and region, year to date
spec:
  selectedStyle: kestrel
  pageFormat: a4
  pageOrientation: landscape
  pageLayout: custom-template
  pageCustomTemplate: '"a a a a" "a a a a" "b b b c"'
  pageGridGap: "12"
  titleBusinessUnit: Kestrel Outdoor GmbH
  titleMeasures:
    - name: Revenue
      unit: kEUR
  titleScenarios: [ac1, fc1, pl1, pp1]
  titleVariances: [dac1_pl1_pos, drac1_pl1_pos]
  titleDateStart: "2025-01-01"
  titleDateEnd: "2025-12-31"
  titleDateFormat: month
  titleDateLink: interval
  footerText: "Fictional data: data/kestrel_2025.csv"
  children:
    - kind: ChartTime
      ref: monthly_chart
    - kind: Table
      ref: region_table
    - kind: Text
      ref: commentary

Open pages/monthly.yaml

The page built for August: actual months are solid, September to December are a hatched forecast. — pages/monthly.yaml, built with REPORT_MONTH=8

Step 4 of 4

Build the PDF

bino build validates every file, runs the queries and prints the pages with headless Chrome. The same command runs on your laptop and in CI, so the PDF can always be built again.

apiVersion: bino.bi/v1alpha1
kind: ReportArtefact
metadata:
  name: kestrel
  description: The full report, four pages
spec:
  filename: kestrel-2025.pdf
  title: Kestrel Outdoor GmbH - Revenue and gross profit 2025
  language: en
  format: a4
  orientation: landscape
  layoutPages: [monthly, structure, profit, portfolio]

Open reports/kestrel.yaml

BINO 0.100.0
 
ℹ INFO build: Using template engine v1.0.0-next.29
→ Loading manifests...
✓ Validated 29 document(s) (26ms)
 
ℹ Manifest summary:
 
→ Building 1 artefact(s)...
→ Rendering kestrel...
 
Generated 1 artefact(s):
  • kestrel → dist/kestrel-2025.pdf (+graph)
 
✓ Build complete in 1.31s

Monthly close

Same files.
Twelve months.

REPORT_MONTH is an environment variable. Every frame here is a real bino build of the same page, from January to December. Actual months turn solid, the forecast stays hatched, and a SQL query writes the comment.

$ REPORT_MONTH=5 bino build --artefact monthly✓ Build complete in 1.03s

Pick a month, or use the arrow keys.

The monthly report as bino built it with REPORT_MONTH=5.

IBCS built in

Charts that follow the rules

Scenarios and variances follow IBCS without extra work. Every card is a bino ScreenshotArtefact of one component of the Kestrel report, built for August. Turn a card over to read its YAML.

ChartTime

Months as columns. Actual, forecast and plan in IBCS notation, with the relative variance on top.

components/monthly_chart.yaml

apiVersion: bino.bi/v1alpha1
kind: ChartTime
metadata:
  name: monthly_chart
spec:
  dataset: monthly
  dateInterval: month
  scenarios: [ac1, fc1, pl1]
  variances: [drac1_pl1_pos]
  measureUnit: kEUR
  measureScale: _
  unitScaling: 360
  percentageScaling: 1.2
  showOverlayAvg: false
  scale: 1.3

Tree

A calculation tree where every node is a chart: gross profit is revenue minus cost of goods.

components/profit_tree.yaml

apiVersion: bino.bi/v1alpha1
kind: Tree
metadata:
  name: profit_tree
spec:
  direction: ltr
  edgeStyle: orthogonal
  levelSpacing: 70
  nodeSpacing: 24
  showOperators: true
  edges:
    - { from: gross_profit, to: revenue, operator: "-" }
    - { from: gross_profit, to: cogs, operator: "-" }
  nodes:
    - id: gross_profit
      kind: ChartStructure
      spec:
        dataset: pnl
        chartTitle: Gross profit
        filter: "rowGroup = 'Gross profit'"
        level: category
        order: categoryindex
        scenarios: [pl1, ac1]
        variances: [drac1_pl1_pos]
        measureUnit: kEUR
        measureScale: _
        unitScaling: 350
        percentageScaling: 2
        scale: 1.25
    - id: revenue
      kind: ChartStructure
      spec:
        dataset: pnl
        chartTitle: Revenue
        filter: "rowGroup = 'Revenue'"
        level: category
        order: categoryindex
        scenarios: [pl1, ac1]
        variances: [drac1_pl1_pos]
        measureUnit: kEUR
        measureScale: _
        unitScaling: 350
        percentageScaling: 2
        scale: 1.25
    - id: cogs
      kind: ChartStructure
      spec:
        dataset: pnl
        chartTitle: Cost of goods
        filter: "rowGroup = 'Cost of goods'"
        level: category
        order: categoryindex
        scenarios: [pl1, ac1]
        variances: [drac1_pl1_neg]
        measureUnit: kEUR
        measureScale: _
        unitScaling: 350
        percentageScaling: 2
        scale: 1.25

Table

Scenarios, absolute and relative variances, and bars in the cells.

components/region_table.yaml

apiVersion: bino.bi/v1alpha1
kind: Table
metadata:
  name: region_table
spec:
  dataset: region_ytd
  type: sum
  sumTitle: Year to date
  order: categoryindex
  scenarios: [pp1, pl1, ac1]
  variances: [dac1_pl1_pos, drac1_pl1_pos]
  barColumns: [dac1_pl1_pos, drac1_pl1_pos]
  measureType: currency
  measureUnit: kEUR
  measureScale: _
  dataFormatDigitsDecimal: 0
  scale: 1.3

ChartStructure

Categories as bars, against last year, with both variances next to them.

components/region_chart.yaml

apiVersion: bino.bi/v1alpha1
kind: ChartStructure
metadata:
  name: region_chart
spec:
  dataset: region_ytd
  chartTitle: Regions against last year
  level: category
  order: categoryindex
  scenarios: [pp1, ac1]
  variances: [dac1_pp1_pos, drac1_pp1_pos]
  measureUnit: kEUR
  measureScale: _
  unitScaling: 600
  percentageScaling: 4
  scale: 1.5

ChartBubble

Growth, margin and revenue per region in one view.

components/portfolio_bubble.yaml

apiVersion: bino.bi/v1alpha1
kind: ChartBubble
metadata:
  name: portfolio_bubble
spec:
  dataset: portfolio
  chartTitle: Regions year to date
  x:
    measure: ac1
    label: Growth against last year
    unit: "%"
    refLine: 0
  y:
    measure: ac2
    label: Margin
    unit: "%"
  size:
    measure: ac3
    label: Revenue
    unit: kEUR

ChartStructure

The same component against plan, sorted by actual.

components/product_chart.yaml

apiVersion: bino.bi/v1alpha1
kind: ChartStructure
metadata:
  name: product_chart
spec:
  dataset: product_ytd
  chartTitle: Product lines against plan
  level: category
  order: ac1
  orderDirection: desc
  scenarios: [pl1, ac1]
  variances: [drac1_pl1_pos]
  measureUnit: kEUR
  measureScale: _
  unitScaling: 800
  percentageScaling: 4
  scale: 1.5

The build script of the Kestrel report The 4-page PDF

Agentic reporting

An agent writes the report. bino checks it.

A bino report is plain YAML and SQL, so an AI agent can write it. bino mcp gives the agent tools to read your data, check every draft and render the result. The IBCS rules stay the same. The agent is one more way to write the report.

This video shows a real run: an agent built an IBCS report from a CSV file with only the bino tools, and a person reviewed the PDF twice.See the prompt, the reviews, every tool call and the PDFs →

1validate_draft
Check the draft
The agent writes a manifest. bino validates it against the schema in memory, before anything is saved.
2write_manifest
Write it
bino validates the manifest again and only then writes it to disk.
3get_rows
Check the numbers
The agent queries its own DataSet and compares the rows with what the page should say.
4build
Render the PDF
The same bino build as on your machine. The PDF is what you review.

bino mcp docs Claude Code plugin

Projects

One workflow, three projects

bino cli is open source under AGPL-3.0. The sandbox and the registry are free hosted services around it.

bino cliOpen source

IBCS reports from YAML + SQL

$ brew install bino-bi/tap/bino-cli

Learn more→GitHub

bino sandbox

Report-as-code runtime in the browser

Learn more→

bino registry

Share report definitions with the community

$ bino registry add @acme/base-layout

Learn more→

Plugins · early access

Extend bino with plugins

A plugin adds data sources, visual components, lint rules, pipeline hooks or commands to bino. You write it in Go with the plugin SDK (Apache-2.0). The SDK is at v0.0.x, so the API can still change.

Plugin guide bino-plugin-sdk on GitHub

Blog

From the blog

All posts →

Pattern recognition

Colors

Why colors in reporting should be used as sparingly as possible — and why red and green belong to variances.

Yuan Chun·December 4, 2023· 2 min

Pattern recognition

Why pattern recognition and visual standards are the key to efficient business reporting.

Yuan Chun·November 5, 2023· 2 min

Time

Scenarios

In which order scenarios such as previous year, plan, forecast, and actual should be displayed.

Yuan Chun·September 21, 2023· 1 min

Your turn

Your first report is three commands away.

bino init standard writes a full starter report: a CSV data source, a dataset, an IBCS table and chart, a style and translations. bino preview shows it in your browser and reloads on every save.

Get started Try the tutorial

Need help running bino in your team? See services →
Questions about your reports, a bug, or working together? Write to us →

$ brew install bino-bi/tap/bino-cli
$ bino init standard --directory my-report
$ cd my-report && bino preview

Reporting as Code. Strictly IBCS®.

From a CSV file to a PDF in four steps

Point bino at the data

Shape it with SQL

Describe the page

Build the PDF

Same files.Twelve months.

Charts that follow the rules

An agent writes the report. bino checks it.

Check the draft

Write it

Check the numbers

Render the PDF

One workflow, three projects

Extend bino with plugins

From the blog

Colors

Pattern recognition

Scenarios

Your first report is three commands away.

Same files.
Twelve months.