### BinoBI CLI Setup Commands

Source: https://cli.bino.bi/cli/setup

Demonstrates various ways to initialize the BinoBI environment, including installing dependencies, specifying versions, and performing dry runs.

```bash
bino setup
bino setup --template-engine
bino setup --template-engine --engine-version v0.37.0
bino setup --dry-run
```

--------------------------------

### Bino Build Examples

Source: https://cli.bino.bi/cli/build

Examples demonstrating how to use the bino build command for different scenarios, such as building all reports, specific artefacts, or changing output directories.

```bash
# Build all reports in the current directory
bino build
```

```bash
# Build only selected artefacts
bino build --artefact monthly_sales --artefact annual_sales
```

```bash
# Change the output directory and log SQL
bino build --out-dir dist/reports --log-sql
```

--------------------------------

### Configure Asset Source Examples

Source: https://cli.bino.bi/reference/asset

Examples showing how to define assets using local file paths, remote URLs, and embedded font configurations.

```yaml
---
apiVersion: bino.bi/v1alpha1
kind: Asset
metadata:
  name: brandLogo
  description: Main brand logo
spec:
  type: image
  mediaType: image/png
  source:
    localPath: ./assets/brand-logo.png
```

```yaml
---
apiVersion: bino.bi/v1alpha1
kind: Asset
metadata:
  name: sampleReportPreview
  description: Sample report preview screenshot
spec:
  type: image
  mediaType: image/png
  source:
    remoteURL: https://via.placeholder.com/1200x800?text=Report+Preview
```

```yaml
---
apiVersion: bino.bi/v1alpha1
kind: Asset
metadata:
  name: corporateHeadingFont
  description: Heading font for corporate reports
spec:
  type: font
  mediaType: font/woff2
  source:
    localPath: ./assets/fonts/corporate-heading.woff2
```

--------------------------------

### Bino Lint Examples

Source: https://cli.bino.bi/cli/lint

Examples demonstrating various ways to use the bino lint command, including linting all manifests in the current directory, a specific project, outputting JSON logs for CI, and executing queries for deep validation.

```bash
bino lint
```

```bash
bino lint --work-dir ./reports
```

```bash
bino lint --log-format json
```

```bash
bino lint --execute-queries
```

--------------------------------

### Bino CLI Plugin Execution Examples

Source: https://cli.bino.bi/guides/plugins

Demonstrates how to execute Bino plugins from the command line using the 'bino plugin exec' command. These examples show how to invoke specific plugin functionalities, such as Salesforce authentication and data synchronization, by passing relevant arguments.

```bash
bino plugin exec salesforce:auth --instance https://myorg.salesforce.com
bino plugin exec salesforce:sync --object Account
```

--------------------------------

### Apply Configuration Best Practices

Source: https://cli.bino.bi/guides/layoutpage-params

Examples of naming conventions and default value usage for Bino BI parameters.

```yaml
# Good
params:
  - name: FISCAL_YEAR
  - name: BUSINESS_UNIT
  - name: INCLUDE_FORECAST

# Avoid
params:
  - name: Y
  - name: BU
  - name: FC

# Defaults
params:
  - name: YEAR
    type: number
    default: "2024"
  - name: SHOW_DETAILS
    type: boolean
    default: "false"
```

--------------------------------

### GET /plugins/list

Source: https://cli.bino.bi/guides/plugins

Lists all installed and active plugins registered within the BinoBI environment.

```APIDOC
## GET /plugins/list

### Description
Lists all plugins currently installed and recognized by the BinoBI CLI. This command verifies that the plugin binaries are correctly placed in the project-local, user-global, or system PATH directories.

### Method
GET

### Endpoint
`bino plugin list`

### Response
#### Success Response (200)
- **plugins** (array) - A list of registered plugin names and their current status.

#### Response Example
```json
[
  { "name": "salesforce", "version": "1.2.0", "status": "active" },
  { "name": "myplugin", "version": "0.1.0", "status": "active" }
]
```
```

--------------------------------

### Example: ROI Driver Tree with Labels

Source: https://cli.bino.bi/reference/tree

An example of a ROI driver tree structure using Label nodes to display key performance indicators.

```APIDOC
## Example: ROI Driver Tree with Labels

```yaml
---
apiVersion: bino.bi/v1alpha1
kind: Tree
metadata:
  name: roi_driver_tree
  description: Return on Investment decomposition
spec:
  edges:
    - { from: "roi", to: "ros", operator: "x" }
    - { from: "roi", to: "capital-turnover" }
    - { from: "ros", to: "profit", operator: "/" }
    - { from: "ros", to: "revenue" }
    - { from: "capital-turnover", to: "revenue", operator: "/" }
    - { from: "capital-turnover", to: "capital" }
  direction: ltr
  edgeStyle: orthogonal
  levelSpacing: 80
  nodeSpacing: 30
  showOperators: true
  nodes:
    - id: roi
      kind: Label
      spec:
        value: "<div class='kpi-box'><span class='label'>ROI</span><span class='value'>12.5%</span></div>"
    - id: ros
      kind: Label
      spec:
        value: "<div class='kpi-box'><span class='label'>ROS</span><span class='value'>8.3%</span></div>"
    - id: capital-turnover
      kind: Label
      spec:
        value: "<div class='kpi-box'><span class='label'>Capital Turnover</span><span class='value'>1.5x</span></div>"
    - id: profit
      kind: Label
      spec:
        value: "<div class='kpi-box'><span class='label'>Profit</span><span class='value'>50M EUR</span></div>"
    - id: revenue
      kind: Label
      spec:
        value: "<div class='kpi-box'><span class='label'>Revenue</span><span class='value'>600M EUR</span></div>"
    - id: capital
      kind: Label
      spec:
        value: "<div class='kpi-box'><span class='label'>Capital</span><span class='value'>400M EUR</span></div>"
```
```

--------------------------------

### GET bino about

Source: https://cli.bino.bi/cli/version-about

Retrieves product information and a list of third-party dependencies with license details.

```APIDOC
## GET bino about

### Description
Prints product information and a list of direct dependencies including license identifiers and URLs.

### Method
GET

### Endpoint
bino about

### Request Example
`bino about`

### Response
#### Success Response (200)
- **product_info** (object) - General product metadata.
- **dependencies** (array) - List of dependencies with license and URL fields.

#### Response Example
{
  "product": "BinoBI CLI",
  "dependencies": [
    {
      "name": "example-lib",
      "license": "MIT",
      "url": "https://example.com/license"
    }
  ]
}
```

--------------------------------

### Install BinoBI CLI

Source: https://cli.bino.bi/manifests/dataset

Installs the BinoBI CLI tool using a shell script. This command downloads and executes the latest release script from the official GitHub repository.

```bash
/bin/bash -c "$(curl -fsSL https://github.com/bino-bi/bino-cli-releases/releases/latest/download/install.sh)"
```

--------------------------------

### Full ScreenshotArtefact Configuration Example (YAML)

Source: https://cli.bino.bi/reference/screenshot-artefact

This example demonstrates a comprehensive configuration for ScreenshotArtefact, including options for filename pattern, image format, orientation, language, scale, and specific component references.

```yaml
apiVersion: bino.bi/v1alpha1
kind: ScreenshotArtefact
metadata:
  name: chart_exports
spec:
  filenamePrefix: quarterly-report
  format: full-hd
  orientation: landscape
  language: de
  scale: device
  imageFormat: png
  filenamePattern: ref
  refs:
    - kind: ChartStructure
      name: sales_by_region
    - kind: Table
      name: summary_table
```

--------------------------------

### CLI Command: bino setup

Source: https://cli.bino.bi/cli/setup

Configures and downloads necessary dependencies for the BinoBI CLI, including Chrome headless shell and the template engine.

```APIDOC
## CLI COMMAND: bino setup

### Description
Downloads and configures the Chrome headless shell and the bn-template-engine required for PDF rendering. Dependencies are cached locally in the user's home directory.

### Method
CLI Execution

### Endpoint
bino setup [flags]

### Parameters
#### Flags
- **--template-engine** (boolean) - Optional - Download or update the bn-template-engine.
- **--engine-version** (string) - Optional - Specify the version of the template engine (default: latest).
- **--dry-run** (boolean) - Optional - Show installation plan without downloading files.
- **--quiet** (boolean) - Optional - Suppress verbose installer output.

### Request Example
`bino setup --template-engine --engine-version v0.37.0`

### Response
#### Success Response
- **Status** (string) - Installation complete or skipped if already present.

#### Response Example
`Successfully installed bn-template-engine v0.37.0 to ~/.bino/cdn/bn-template-engine/`
```

--------------------------------

### Complete Product Comparison Grid Example

Source: https://cli.bino.bi/reference/grid

A comprehensive example of a Grid component used for product comparison, featuring multiple component types (Text, ChartTime, Table, ChartStructure) across rows and columns. It includes detailed row and column headers with IDs.

```yaml
---
apiVersion: bino.bi/v1alpha1
kind: Grid
metadata:
  name: product-comparison
  description: Quarterly product performance comparison
spec:
  chartTitle: Product Performance Matrix
  rowHeaders:
    - label: Laptops
      id: laptops
    - label: Tablets
      id: tablets
    - label: Phones
      id: phones
  columnHeaders:
    - label: Revenue
      id: rev
    - label: Units Sold
      id: units
    - label: Trend
      id: trend
  showRowHeaders: true
  showColumnHeaders: true
  showBorders: true
  rowHeaderWidth: 120px
  cellGap: 4px
  children:
    # Laptop row
    - row: laptops
      column: rev
      kind: Text
      spec:
        dataset: laptop-revenue
        value: "${total_revenue} EUR"
    - row: laptops
      column: units
      kind: Text
      spec:
        dataset: laptop-units
        value: "${units_sold}"
    - row: laptops
      column: trend
      kind: ChartTime
      ref: laptop-trend-chart

    # Tablet row
    - row: tablets
      column: rev
      kind: Table
      ref: tablet-revenue-table
    - row: tablets
      column: units
      kind: Text
      spec:
        dataset: tablet-units
        value: "${units_sold}"
    - row: tablets
      column: trend
      kind: ChartTime
      ref: tablet-trend-chart

    # Phone row
    - row: phones
      column: rev
      kind: ChartStructure
      ref: phone-revenue-chart
    - row: phones
      column: units
      kind: Text
      spec:
        dataset: phone-units
        value: "${units_sold}"
    - row: phones
      column: trend
      kind: ChartTime
      ref: phone-trend-chart
```

--------------------------------

### BinoBI Configuration File Structure

Source: https://cli.bino.bi/cli/init

Example structure of the bino.toml file, defining project identifiers, build arguments, and environment variables.

```toml
report-id = "550e8400-e29b-41d4-a716-446655440000"

[build.args]
out-dir = "dist"
browser = "chromium"
log-sql = false
no-lint = false

[build.env]
BNR_MAX_QUERY_ROWS = "50000"
DATABASE_URL = "postgres://localhost/mydb"

[preview.args]
port = 8080
lint = true

[preview.env]
BNR_MAX_QUERY_ROWS = "10000"
```

--------------------------------

### Define Plugin Configuration in bino.toml

Source: https://cli.bino.bi/guides/plugins

Example structure for defining plugin paths and custom configuration parameters in the BinoBI project file.

```toml
[plugins.salesforce]
path = ".bino/plugins/bino-plugin-salesforce"
version = "1.2.0"

[plugins.salesforce.config]
instance_url = "https://myorg.salesforce.com"
api_version = "58.0"
```

--------------------------------

### Initialize BinoBI Project

Source: https://cli.bino.bi/cli/init

Commands to initialize a new BinoBI project, including interactive mode, custom directory setup, and non-interactive execution.

```bash
bino init
bino init --directory monthly-report --title "Monthly Sales" --language en
bino init -d my-report -y --force
```

--------------------------------

### Install BinoBI CLI and Chrome Headless Shell

Source: https://cli.bino.bi/recipes/ci-cd-pipeline

Installs the BinoBI binary and the required Chrome headless shell for PDF rendering. The CI environment variable is set to disable interactive prompts.

```bash
# Install bino
/bin/bash -c "$(curl -fsSL https://github.com/bino-bi/bino-cli-releases/releases/latest/download/install.sh)"

# Install Chrome headless shell (required for PDF rendering)
bino setup
```

--------------------------------

### Seed Data on Preview Start (Python)

Source: https://cli.bino.bi/guides/hooks-and-etl

Utilizes the `pre-preview` hook to execute a script once when the preview server starts. This is ideal for slow operations like database seeding or large API calls that do not need to run on every refresh.

```toml
[preview.hooks]
pre-preview = ["python scripts/seed_data.py"]
```

--------------------------------

### Implement Custom DataSources and Components

Source: https://cli.bino.bi/guides/plugins

YAML manifest examples for utilizing plugin-provided data sources and custom visual components.

```yaml
apiVersion: bino.bi/v1alpha1
kind: SalesforceDataSource
metadata:
  name: opportunities
spec:
  object: Opportunity
  query: "SELECT Id, Name, Amount FROM Opportunity WHERE StageName = 'Closed Won'"
```

```yaml
apiVersion: bino.bi/v1alpha1
kind: ExampleChart
metadata:
  name: revenue_chart
spec:
  dataset: monthly_revenue
  chartType: bar
  title: Monthly Revenue
```

--------------------------------

### BinoBI CLI Build Commands

Source: https://cli.bino.bi/cli/build-logs

Various command-line interface examples for building reports with different logging, data embedding, and redaction configurations.

```bash
bino build --log-format=json
bino build --log-format=json --embed-data-csv --detailed-execution-plan
bino build --embed-data-csv --embed-data-max-rows=50 --embed-data-max-bytes=131072
bino build --embed-data-csv --embed-data-redact=false
```

--------------------------------

### Define Grid Headers

Source: https://cli.bino.bi/reference/grid

Examples showing both simple and explicit formats for defining row and column headers in a BinoBI Grid specification.

```yaml
spec:
  rowHeaders: [Electronics, Apparel, Home]
  columnHeaders: [Q1, Q2, Q3]
```

```yaml
spec:
  rowHeaders:
    - label: Electronics
      id: electronics
    - label: Apparel
      id: apparel
  columnHeaders:
    - label: Q1 2024
      id: q1
    - label: Q2 2024
      id: q2
```

--------------------------------

### Log Parsing with jq

Source: https://cli.bino.bi/cli/build-logs

Examples of using the `jq` command-line tool to parse and extract information from Bino's JSON logs.

```APIDOC
## GET /api/logs/parse

### Description
This section provides examples of how to use the `jq` utility to parse and query the JSON output logs generated by Bino. It demonstrates extracting various pieces of information such as build duration, query performance, and execution plan details.

### Method
GET

### Endpoint
/api/logs/parse

### Parameters
#### Query Parameters
- **log_file_path** (string) - Required - The path to the JSON log file to be parsed (e.g., `dist/bino-build-*.json`).

### Request Example
```bash
# Get total build duration
jq '.duration_ms' dist/bino-build-*.json

# List all queries with their durations
jq '.queries[] | {id, duration_ms, row_count}' dist/bino-build-*.json

# Find slow queries (>100ms)
jq '.queries[] | select(.duration_ms > 100) | {id, query, duration_ms}' dist/bino-build-*.json

# Get execution plan summary
jq '.execution_plan[] | {name, phase, duration_ms, status}' dist/bino-build-*.json
```

### Response
#### Success Response (200)
- **output** (string) - The output from the `jq` command, which varies based on the query.

#### Response Example
```json
{
  "output": "1500\n1200\n..."
}
```
```

--------------------------------

### Define DocumentArtefact Manifests

Source: https://cli.bino.bi/reference/document-artefact

Examples of various DocumentArtefact configurations, ranging from minimal setups to complex documents with TOC, custom CSS, and glob-based source inclusion.

```yaml
apiVersion: bino.bi/v1alpha1
kind: DocumentArtefact
metadata:
  name: user_guide
spec:
  format: a4
  filename: user-guide.pdf
  title: "User Guide"
  tableOfContents: true
  sources:
    - ./docs/**/*.md
```

```yaml
apiVersion: bino.bi/v1alpha1
kind: DocumentArtefact
metadata:
  name: branded_manual
spec:
  filename: manual.pdf
  stylesheet: ./styles/brand.css
  headerTemplate: |
    <div style="font-size: 10px;">ACME Corp</div>
  sources:
    - ./manual/introduction.md
```

--------------------------------

### Standalone Text Manifest Example

Source: https://cli.bino.bi/reference/text

Example of a standalone Text manifest defining a main title for a report.

```APIDOC
## Standalone Text Manifest

### Example
```yaml
---
apiVersion: bino.bi/v1alpha1
kind: Text
metadata:
  name: mainTitle
spec:
  value: "Sales Overview Report"
```
```

--------------------------------

### Example: Mixed Content Tree

Source: https://cli.bino.bi/reference/tree

An example of a tree structure that includes various node types like Labels, Charts, and Tables.

```APIDOC
## Example: Mixed content with charts and tables

```yaml
---
apiVersion: bino.bi/v1alpha1
kind: Tree
metadata:
  name: sales_analysis_tree
spec:
  edges:
    - { from: "total", to: "by-region", operator: "=" }
    - { from: "total", to: "by-product" }
    - { from: "by-region", to: "trend" }
  direction: ttb
  levelSpacing: 100
  nodeSpacing: 40
  nodes:
    # Root: simple label
    - id: total
      kind: Label
      spec:
        value: "<h3>Total Sales</h3><p>$12.5M</p>"

    # Child: structure chart showing regional breakdown
    - id: by-region
      kind: ChartStructure
      spec:
        dataset: sales_by_region
        scenarios: ["ac1"]
        level: category
        limit: 5

    # Child: table with product details
    - id: by-product
      kind: Table
      ref: product_sales_table

    # Grandchild: time series trend
    - id: trend
      kind: ChartTime
      spec:
        dataset: monthly_sales
        type: line
        dateInterval: month
```
```

--------------------------------

### POST /plugins/init

Source: https://cli.bino.bi/guides/plugins

Initializes a plugin with configuration parameters defined in bino.toml.

```APIDOC
## POST /plugins/init

### Description
When the BinoBI CLI starts a pipeline, it launches the plugin as a subprocess and sends an Init call. The configuration defined in the `[plugins.<name>.config]` section of `bino.toml` is passed to the plugin.

### Method
POST

### Endpoint
Internal gRPC Init Call

### Request Body
- **config** (map) - Key-value pairs defined in `bino.toml`.

### Request Example
```toml
[plugins.salesforce.config]
instance_url = "https://myorg.salesforce.com"
api_version = "58.0"
```

### Response
#### Success Response (200)
- **status** (string) - Initialization success confirmation.
```

--------------------------------

### Date Parameter Type Example (YAML)

Source: https://cli.bino.bi/guides/layoutpage-params

Example of defining a date parameter type for a LayoutPage. It accepts date values in YYYY-MM-DD format.

```yaml
params:
  - name: REPORT_DATE
    type: date
    default: "2024-01-01"
```

--------------------------------

### Boolean Parameter Type Example (YAML)

Source: https://cli.bino.bi/guides/layoutpage-params

Example of defining a boolean parameter type for a LayoutPage. This parameter accepts true or false values.

```yaml
params:
  - name: SHOW_DETAILS
    type: boolean
    default: "false"
```

--------------------------------

### Initialize a BinoBI Project

Source: https://cli.bino.bi/getting-started/first-report

Scaffolds a new report bundle directory (workdir) with starter files. Accepts defaults non-interactively with -y/--yes. A custom directory can be specified using --directory.

```bash
bino init
bino init --directory my-report
```

--------------------------------

### Bino Build CI Tips

Source: https://cli.bino.bi/cli/build

Tips for using the bino build command in Continuous Integration environments, including setting work directories, failing builds early, and archiving output.

```bash
# Use --work-dir to point at the repository checkout
bino build --work-dir /path/to/repo/checkout
```

```bash
# 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` for reproducible CI builds
# Use `--data-validation=fail` in CI to catch data issues before reports reach production
```

--------------------------------

### Build and Configure BinoBI Plugins

Source: https://cli.bino.bi/guides/plugins

Instructions for compiling a Go-based plugin and registering it within the bino.toml configuration file.

```bash
cd my-bino-plugin
go build -o bino-plugin-myplugin .
```

```toml
[plugins.myplugin]
[plugins.myplugin.config]
api_key = "${MY_API_KEY}"
```

--------------------------------

### DateTime Parameter Type Example (YAML)

Source: https://cli.bino.bi/guides/layoutpage-params

Example of defining a date_time parameter type for a LayoutPage. It accepts date and time values in ISO 8601 format.

```yaml
params:
  - name: REPORT_TIMESTAMP
    type: date_time
    default: "2024-01-01T00:00:00Z"
```

--------------------------------

### Number Parameter Type Example (YAML)

Source: https://cli.bino.bi/guides/layoutpage-params

Example of defining a number parameter type for a LayoutPage. It includes optional range validation with minimum and maximum values.

```yaml
params:
  - name: YEAR
    type: number
    default: "2024"
    options:
      min: 2000
      max: 2030
```

--------------------------------

### Initialize BinoBI Project

Source: https://cli.bino.bi/concepts/project-configuration

Commands to initialize a new project directory with a generated bino.toml file or create one manually.

```bash
bino init --directory my-reports
```

```toml
report-id = "your-unique-id-here"
```

--------------------------------

### BinoBI CLI Preview Examples

Source: https://cli.bino.bi/cli/preview

Common usage patterns for the preview command, including running in the current directory or specifying a custom working directory with SQL logging enabled.

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

--------------------------------

### Minimal Bino Plugin Structure (Go)

Source: https://cli.bino.bi/guides/plugins

Provides a basic Go code structure for a Bino plugin. It shows the necessary package import and the 'main' function that initializes the plugin by calling 'sdk.Serve' with essential options like name and version. This serves as a starting point for developing more complex plugins.

```go
package main

import sdk "github.com/bino-bi/bino-plugin-sdk"

func main() {
    sdk.Serve(&sdk.PluginOpts{
        Name:    "myplugin",
        Version: "0.1.0",
        // ... register capabilities
    })
}
```

--------------------------------

### Select Parameter Type Example (YAML)

Source: https://cli.bino.bi/guides/layoutpage-params

Example of defining a select parameter type for a LayoutPage. It allows users to choose from a predefined list of options, each with a value and an optional label.

```yaml
params:
  - name: REGION
    type: select
    required: true
    options:
      items:
        - value: "EU"
          label: "Europe"
        - value: "US"
          label: "North America"
        - value: "APAC"
          label: "Asia Pacific"
```

--------------------------------

### String Parameter Type Example (YAML)

Source: https://cli.bino.bi/guides/layoutpage-params

Example of defining a string parameter type for a LayoutPage. This is the default type and allows for free-form text input without specific validation.

```yaml
params:
  - name: TITLE
    type: string
    default: "Untitled Report"
```

--------------------------------

### Configure Build and Preview Defaults

Source: https://cli.bino.bi/cli/init

Defining command-specific flags and environment variables in bino.toml to control build output and preview server behavior.

```toml
[build.args]
out-dir = "output"
browser = "firefox"
log-sql = true
no-graph = true
no-lint = false
log-format = "json"

[preview.args]
port = 9000
log-sql = true
lint = true

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

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

--------------------------------

### Manage Dynamic Environment Parameters

Source: https://cli.bino.bi/guides/layoutpage-params

Demonstrates how to reference environment variables within configuration files and how to pass them during build processes.

```yaml
layoutPages:
  - page: sales-summary
    params:
      REGION: ${DEFAULT_REGION}        # From environment
      YEAR: ${REPORT_YEAR:2024}        # With fallback
      MANAGER: ${MANAGER_NAME:Unknown}
```

```bash
# Set via environment
export DEFAULT_REGION=US
export REPORT_YEAR=2023
bino build --artefact regional-report

# Or inline
DEFAULT_REGION=EU bino build --artefact regional-report
```

--------------------------------

### BinoBI Grouped Table with Drilldown Example

Source: https://cli.bino.bi/reference/table

An example of a BinoBI Table manifest configured for grouped data with drilldown capabilities. It specifies dataset, titles, measures, grouping, scenarios, variances, and detailed drilldown configurations for rows and columns.

```yaml
---
apiVersion: bino.bi/v1alpha1
kind: Table
metadata:
  name: revenue_grouped_table
spec:
  dataset: revenue_detail
  tableTitle: "Revenue by segment and product"
  measureScale: M
  measureType: currency
  measureUnit: "EUR"
  grouped: true
  showGroupTitle: true
  categoryWidth: w25
  type: list
  limit: 5
  scenarios: ["ac1", "py1"]
  variances: ["dpy1_ac1_pos"]
  thereof:
    - rowGroup: "Revenue"
      category: "Applications"
      subCategory: "Applications-A"
  partof:
    - rowGroup: "Revenue"
      category: "Applications"
  columnthereof:
    - scenario: "ac1"
      name: "DE"
      subGroups: ["Berlin", "Hamburg"]
```

--------------------------------

### Build for Specific Client using Bino CLI

Source: https://cli.bino.bi/recipes/monthly-client-report

Demonstrates how to build a Bino project for a specific client by setting environment variables like CLIENT_ID, CLIENT_NAME, and REPORT_MONTH before running the 'bino build' command. It also shows a bash script for iterating through a list of clients from a CSV file to perform builds for each.

```bash
CLIENT_ID=acme CLIENT_NAME="Acme Corp" REPORT_MONTH=2024-11 bino build
```

```bash
#!/bin/bash
for row in $(cat clients.csv | tail -n +2); do
  IFS=',' read -r id name <<< "$row"
  CLIENT_ID="$id" CLIENT_NAME="$name" REPORT_MONTH="$(date -d '-1 month' +%Y-%m)" \
    bino build --out-dir "dist/$id/"
done
```

--------------------------------

### Sample Object Configuration (YAML)

Source: https://cli.bino.bi/reference/datasource

Provides an example of the sample object configuration in YAML for BinoBI CLI, specifying the size and method for sampling rows from a data source.

```yaml
spec:
  sample:
    size: 10000
    method: reservoir  # bernoulli | system | reservoir
```

--------------------------------

### Constraint Syntax Examples (YAML)

Source: https://cli.bino.bi/concepts/constraints-and-scoped-names

Illustrates the different ways to define constraints in BinoBI CLI. It covers the concise string format, the IDE-friendly structured format, and a mixed format combining both.

```yaml
metadata:
  constraints:
    - mode==preview
    - labels.env==prod
    - spec.format in [pdf,png]
```

```yaml
metadata:
  constraints:
    - field: mode
      operator: "=="
      value: preview
    - field: labels.env
      operator: in
      value: [dev, staging, prod]
```

```yaml
metadata:
  constraints:
    - mode==preview                    # String format (quick)
    - field: spec.output.format        # Structured format (IDE autocomplete)
      operator: in
      value: [pdf, png]
```

--------------------------------

### Text as a Layout Child

Source: https://cli.bino.bi/reference/text

Example of using a Text manifest as a child within a LayoutPage.

```APIDOC
## Text as a Layout Child

### Example
```yaml
---
apiVersion: bino.bi/v1alpha1
kind: LayoutPage
metadata:
  name: sales_layout
spec:
  pageLayout: full
  children:
    - kind: Text
      spec:
        value: "Sales Overview Report"
        scale: auto
```
```

--------------------------------

### Run Preview and Build - BinoBI CLI

Source: https://cli.bino.bi/guides/data-from-csv-and-excel

Commands for interacting with BinoBI CLI. 'bino preview --log-sql' generates a preview of the output and logs the SQL queries. 'bino build' compiles the project into a final PDF document.

```bash
bino preview --log-sql
```

```bash
bino build
```

--------------------------------

### Configure simple aggregation DataSet

Source: https://cli.bino.bi/reference/dataset

An example of defining a DataSource and a corresponding DataSet that performs a SQL aggregation on that source.

```yaml
---
apiVersion: bino.bi/v1alpha1
kind: DataSource
metadata:
  name: sales_csv
spec:
  type: csv
  path: ./data/sales.csv
---
apiVersion: bino.bi/v1alpha1
kind: DataSet
metadata:
  name: sales_by_region
spec:
  query: |
    SELECT
      region,
      SUM(amount) AS total_amount
    FROM sales_csv
    GROUP BY region
  dependencies:
    - sales_csv
```

--------------------------------

### Build Bino BI Reports (Shell)

Source: https://cli.bino.bi/recipes/compliance-report

Shell commands to build Bino BI reports. Demonstrates setting environment variables for development (using mock data) and production (connecting to a data warehouse). Includes specifying output directories and build artifacts.

```shell
# Development — uses inline mock data
REPORT_ENV=dev REPORT_PERIOD=Q4-2024 REPORT_DATE=2025-01-15 bino build

# Production — uses real database
REPORT_ENV=prod REPORT_PERIOD=Q4-2024 REPORT_DATE=2025-01-15 \
  DWH_HOST=dwh.internal DWH_PASSWORD=secret \
  bino build --out-dir dist/
```

--------------------------------

### Initialize BinoBI Project

Source: https://cli.bino.bi/concepts/project-configuration

The bino init command is used to create a new project by generating a bino.toml file. This file is required for the VS Code extension to activate and for CLI commands to function correctly.

```bash
bino init
```

--------------------------------

### Create Parquet Datasource

Source: https://cli.bino.bi/cli/add

Sets up a Parquet file datasource by providing the source file path. The resulting configuration is saved to a YAML manifest.

```bash
bino add datasource events \
  --type parquet \
  --file data/events.parquet \
  --output datasources/events.yaml \
  --no-prompt
```

--------------------------------

### Configuring a Multi-Region Report

Source: https://cli.bino.bi/guides/layoutpage-params

An example of defining a LayoutPage with select parameters and a ReportArtefact that generates a multi-page PDF document.

```yaml
---
# pages.yaml
apiVersion: bino.bi/v1alpha1
kind: LayoutPage
metadata:
  name: region-page
  params:
    - name: REGION
      type: select
      required: true
      options:
        items:
          - value: "EMEA"
            label: "Europe, Middle East & Africa"
          - value: "AMERICAS"
            label: "Americas"
          - value: "APAC"
            label: "Asia Pacific"
    - name: CURRENCY
      type: select
      default: "USD"
      options:
        items:
          - value: "USD"
          - value: "EUR"
          - value: "GBP"
spec:
  titleBusinessUnit: "${REGION_LABEL}"
  pageLayout: 2x2
  children:
    - kind: Text
      metadata:
        name: header
      spec:
        value: "${REGION_LABEL} Sales Report"
        style:
          fontSize: 28
          fontWeight: bold
    - kind: ChartStructure
      spec:
        dataset: regional-sales
        chartTitle: "Revenue (${CURRENCY})"
    - kind: Table
      spec:
        dataset: regional-sales
        tableTitle: "Top Products"
        limit: 10
    - kind: ChartTime
      spec:
        dataset: regional-trends
        chartTitle: "12-Month Trend"

---
# report.yaml
apiVersion: bino.bi/v1alpha1
kind: ReportArtefact
metadata:
  name: global-sales-report
spec:
  format: xga
  orientation: landscape
  layoutPages:
    - cover-page
    - page: region-page
      params:
        REGION: EMEA
        CURRENCY: EUR
    - page: region-page
      params:
        REGION: AMERICAS
        CURRENCY: USD
    - page: region-page
      params:
        REGION: APAC
        CURRENCY: USD
    - summary-page
  filename: global-sales.pdf
  title: "Global Sales Report"
```

--------------------------------

### Best Practices for Parameters

Source: https://cli.bino.bi/reference/layout-page

Guidelines for defining and using parameters effectively in Bino.bi configurations.

```APIDOC
## Best Practices for Parameters

This section outlines best practices for using parameters in Bino.bi configurations to ensure clarity, consistency, and maintainability.

### Best Practices

1.  **Use descriptive parameter names**: Use clear, uppercase names like `REGION`, `YEAR`, `PRODUCT_LINE`.
2.  **Provide defaults**: Always provide sensible defaults for non-required parameters.
3.  **Document parameters**: Use the `description` field to explain what each parameter controls.
4.  **Validate with types**: Use appropriate types (`number`, `select`, `date`, `date_time`) to ensure valid values.
5.  **Keep parameter lists short**: If you need many parameters, consider breaking the page into smaller, focused components.
6.  **Use consistent naming**: If the same concept (e.g., region, year) appears in multiple pages, use the same parameter name.
```

--------------------------------

### PostgreSQL Credentials via Environment Variable

Source: https://cli.bino.bi/reference/connection-secret

Example of configuring PostgreSQL credentials using an environment variable for the ConnectionSecret.

```APIDOC
## PostgreSQL credentials via environment variable

```yaml
---
apiVersion: bino.bi/v1alpha1
kind: ConnectionSecret
metadata:
  name: postgresCredentials
spec:
  type: postgres
  postgres:
    passwordFromEnv: POSTGRES_PASSWORD
```

**Use the secret from a datasource:**

```yaml
apiVersion: bino.bi/v1alpha1
kind: DataSource
metadata:
  name: orders_pg
spec:
  type: postgres_query
  connection:
    host: "${DB_HOST:db.example.com}"
    port: 5432
    database: analytics
    schema: public
    user: reporting
    secret: postgresCredentials
  query: |
    SELECT * FROM fact_orders;
```
```

--------------------------------

### Internationalization with YAML Content

Source: https://cli.bino.bi/reference/internationalization

Example of providing translation keys as a nested YAML object within the spec.content field.

```yaml
---
apiVersion: bino.bi/v1alpha1
kind: Internationalization
metadata:
  name: systemTexts_de
spec:
  code: de-DE
  namespace: _system
  content:
    report.title.sales_overview: "Sales Overview"
    report.subtitle.q1_2024: "Q1 2024"
    card.title.revenue: "Revenue"
    card.title.ebit: "EBIT"
```

--------------------------------

### bino serve Command

Source: https://cli.bino.bi/cli/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.

```APIDOC
## bino serve

### Description
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]
```

### Parameters
#### Required Flags
- **--live** (string) - Required - Name of the `LiveReportArtefact` to serve.

#### Common Flags
- **--work-dir** (string) - Optional - Report bundle directory (default: `.`).
- **--port** (number) - Optional - HTTP port (default: `8080`).
- **--addr** (string) - Optional - Full listen address (overrides `--port`, e.g. `0.0.0.0:8080`).
- **--log-sql** (boolean) - Optional - 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 `ReportArtefact`s exist.
3. **Serves on-demand**: Renders reports when requested, using caches for efficiency.
4. **Navigation**: 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:
- `string` (default)
- `number`
- `number_range`
- `select`
- `date`
- `date_time`

Parameters are **required** by default. To make a parameter optional, set a `default` value or `optional: true`.

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

**Example LiveReportArtefact with Query Parameters:**
```yaml
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"
```

**Accessing a route with query parameters:**
`http://localhost:8080/region?REGION=EU&YEAR=2024`

### Default Arguments via bino.toml
Set default values for serve flags in your project’s `bino.toml`:
```toml
[serve.args]
port = 8080
live = "sales-dashboard"
log-sql = true
```

### Environment Variables via bino.toml
Set environment variables for serve in `bino.toml`:
```toml
[serve.env]
BNR_MAX_QUERY_ROWS = "100000"
DATABASE_URL = "postgres://localhost/prod"
```

### Examples

**Serve a live report artefact:**
```bash
bino serve --live sales-dashboard
```

**Serve on a specific port with SQL logging:**
```bash
bino serve --live sales-dashboard --port 3000 --log-sql
```

**Serve bound to all interfaces (for Docker/Kubernetes):**
```bash
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.
```

--------------------------------

### Manage BinoBI Plugins via CLI

Source: https://cli.bino.bi/guides/plugins

Commands to verify installation and sign binaries on macOS for security compliance.

```bash
bino plugin list
codesign --force --sign - bino-plugin-myplugin
```

--------------------------------

### Configure Post-Build Upload Hook

Source: https://cli.bino.bi/recipes/monthly-client-report

Shows how to define a post-build hook in the 'bino.toml' configuration file to execute a script after the build process completes. The example uses a shell script to upload generated PDF reports to an AWS S3 bucket, dynamically setting the destination path using environment variables like BINO_OUTPUT_DIR and CLIENT_ID.

```toml
# bino.toml
[build.hooks]
post-build = ["./scripts/upload.sh"]
```

```bash
#!/bin/bash
# scripts/upload.sh
aws s3 cp "$BINO_OUTPUT_DIR"/*.pdf \
  "s3://client-reports/${CLIENT_ID}/$(date +%Y-%m)/"
```

--------------------------------

### Manage Template Engine Versions

Source: https://cli.bino.bi/concepts/project-configuration

Commands to ensure specific template engine versions are installed for reproducible builds.

```bash
bino setup --template-engine --engine-version v0.37.0
```

--------------------------------

### GET /regional (Parameterized LayoutPages)

Source: https://cli.bino.bi/reference/live-report-artefact

Retrieves a dashboard layout where query parameters are passed into specific layout pages.

```APIDOC
## GET /regional

### Description
Displays a regional dashboard by mapping query parameters to internal LayoutPage parameters.

### Method
GET

### Endpoint
/regional

### Parameters
#### Query Parameters
- **REGION** (select) - Optional - Region code (EU, US, APAC) (Default: EU)
- **YEAR** (number) - Optional - Year for analysis (Default: 2024)

### Request Example
GET /regional?REGION=US&YEAR=2023

### Response
#### Success Response (200)
- **layout** (object) - The rendered layout with regional-sales page populated by the provided parameters.
```