@bonnard/cli

The semantic engine for MCP clients. Define metrics once, query from anywhere.

Docs · Getting Started · Changelog · Discord · Website

Bonnard is an agent-native semantic layer CLI. Deploy an MCP server and governed analytics API in minutes -for AI agents, BI tools, and data teams. Define metrics and dimensions in YAML, validate locally, and ship to production. Works with Snowflake, BigQuery, Databricks, and PostgreSQL. Ships with native integrations for Claude Code, Cursor, and Codex. Built with TypeScript.

Why Bonnard?

Most semantic layers were built for dashboards and retrofitted for AI. Bonnard was built the other way around -agent-native from day one with Model Context Protocol (MCP) as a core feature, not a plugin. One CLI takes you from an empty directory to a production semantic layer serving AI agents, BI tools, and human analysts through a single governed API.

Quick Start

No install required. Run directly with npx:

npx @bonnard/cli init

Or install globally:

npm install -g @bonnard/cli

Then follow the setup flow:

bon init                      # Scaffold project + agent configs
bon datasource add            # Connect your warehouse
bon validate                  # Check your models locally
bon login                     # Authenticate
bon deploy                    # Ship it

No warehouse yet? Start exploring with a full retail demo dataset:

bon datasource add --demo

Requires Node.js 20+.

Agent-Native from Day One

When you run bon init, Bonnard generates context files so AI coding agents understand your semantic layer from the first prompt:

you@work my-project % bon init

Initialised Bonnard project
Core files:
  bon.yaml
  bonnard/cubes/
  bonnard/views/
Agent support:
  .claude/rules/bonnard.md
  .claude/skills/bonnard-get-started/
  .cursor/rules/bonnard.mdc
  AGENTS.md

Agent	What gets generated
Claude Code	.claude/rules/bonnard.md + skill templates in .claude/skills/
Cursor	.cursor/rules/bonnard.mdc with frontmatter configuration
Codex	AGENTS.md + skills directory

Set up your MCP server so agents can query your semantic layer directly:

bon mcp                       # Show MCP server setup instructions
bon mcp test                  # Verify the connection

Auto-Detected from Your Project

Bonnard automatically detects your warehouses and data tools. Point it at your project and it discovers schemas, tables, and relationships.

• Snowflake -full support including Snowpark
• Google BigQuery -native integration
• Databricks -SQL warehouses and Unity Catalog
• PostgreSQL -including cloud-hosted variants (Supabase, Neon, RDS)
• DuckDB -local development and testing
• dbt -model and profile import
• Dagster, Prefect, Airflow -orchestration tools
• Looker, Cube, Evidence -existing BI layers
• SQLMesh, Soda, Great Expectations -data quality and transformation

Querying

Query your semantic layer from the terminal using JSON or SQL syntax:

# JSON query
bon query --measures revenue,order_count --dimensions product_category --time-dimension created_at

# SQL query
bon query --sql "SELECT product_category, MEASURE(revenue) FROM orders GROUP BY 1"

Agents connected via MCP can run the same queries programmatically, with full access to your governed metric definitions.

Project Structure

my-project/
├── bon.yaml              # Project configuration
├── bonnard/
│   ├── cubes/            # Metric and dimension definitions
│   └── views/            # Curated query interfaces
├── .bon/                 # Local credentials (gitignored)
├── .claude/              # Claude Code agent context
├── .cursor/              # Cursor agent context
└── AGENTS.md             # Codex agent context

CI/CD

Deploy from your pipeline with the --ci flag for non-interactive mode:

bon deploy --ci

Handles automatic datasource synchronisation and skips interactive prompts. Fits into GitHub Actions, GitLab CI, or any pipeline that runs Node.js.

Commands

Command	Description
bon init	Scaffold a new project with agent configs
bon datasource add	Connect a data source (or --demo for sample data)
bon datasource add --from-dbt	Import from dbt profiles
bon datasource list	List connected data sources
bon validate	Validate models locally before deploying
bon deploy	Deploy semantic layer to production
bon deployments	List active deployments
bon diff	Preview changes before deploying
bon annotate	Add metadata and descriptions to models
bon query	Run queries from the terminal (JSON or SQL)
bon mcp	Show MCP server setup instructions
bon mcp test	Test MCP connection
bon dashboard dev	Preview a markdown dashboard locally with live reload
bon dashboard deploy	Deploy a markdown or HTML dashboard
bon dashboard list	List deployed dashboards
bon dashboard remove	Remove a deployed dashboard
bon dashboard open	Open a dashboard in the browser
bon pull	Download deployed models to local project
bon keys list / create / revoke	Manage API keys
bon docs	Browse or search documentation from the CLI
bon login / bon logout	Manage authentication
bon whoami	Check current session

For the full CLI reference, see the documentation.

Documentation

• Getting Started -from zero to deployed in minutes
• CLI Reference -every command, flag, and option
• Modeling Guide -cubes, views, metrics, and dimensions
• Querying -JSON and SQL query syntax
• Changelog -what shipped and when

Community

• Discord -ask questions, share feedback, connect with the team
• GitHub Issues -bug reports and feature requests
• LinkedIn -follow for updates
• Website -learn more about Bonnard

Contributions are welcome. If you find a bug or have an idea, open an issue or submit a pull request.

License

MIT