@bonnard/cli 0.2.11 → 0.2.12

package/README.md

@@ -1,87 +1,202 @@
-# @bonnard/cli
+<p align="center">
+  <a href="https://www.bonnard.dev">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="./assets/banner-dark.png" />
+      <source media="(prefers-color-scheme: light)" srcset="./assets/banner-light.png" />
+      <img alt="Bonnard -the semantic engine for MCP clients, AI agents, and data teams" src="./assets/banner-light.png" width="100%" />
+    </picture>
+  </a>
+</p>
 
-The Bonnard CLI (`bon`) takes you from zero to a deployed semantic layer in minutes. Define metrics in YAML, validate locally, deploy, and query — from your terminal or AI coding agent.
+<p align="center">
+  <strong>The semantic engine for MCP clients. Define metrics once, query from anywhere.</strong>
+</p>
 
-**Open source** — [view source on GitHub](https://github.com/meal-inc/bonnard-cli)
+<p align="center">
+  <a href="https://www.npmjs.com/package/@bonnard/cli"><img src="https://img.shields.io/npm/v/@bonnard/cli?style=flat-square&color=0891b2" alt="npm version" /></a>
+  <a href="https://github.com/meal-inc/bonnard-cli/blob/main/LICENSE"><img src="https://img.shields.io/github/license/meal-inc/bonnard-cli?style=flat-square" alt="MIT License" /></a>
+  <a href="https://discord.com/invite/RQuvjGRz"><img src="https://img.shields.io/badge/Discord-Join%20us-5865F2?style=flat-square&logo=discord&logoColor=white" alt="Discord" /></a>
+</p>
 
-## Quick start
+<p align="center">
+  <a href="https://docs.bonnard.dev/docs/">Docs</a> &middot;
+  <a href="https://docs.bonnard.dev/docs/getting-started">Getting Started</a> &middot;
+  <a href="https://docs.bonnard.dev/docs/changelog">Changelog</a> &middot;
+  <a href="https://discord.com/invite/RQuvjGRz">Discord</a> &middot;
+  <a href="https://www.bonnard.dev">Website</a>
+</p>
+
+---
+
+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.
+
+<p align="center">
+  <img src="./assets/architecture.png" alt="Bonnard architecture -data sources flow through the semantic layer to AI agents, BI tools, and MCP clients" width="100%" />
+</p>
+
+## Quick Start
+
+No install required. Run directly with npx:
 
 ```bash
-npx @bonnard/cli init           # Create project structure + agent templates
-bon datasource add --demo       # Add demo dataset (no warehouse needed)
-bon validate                    # Check syntax
-bon login                       # Authenticate with Bonnard
-bon deploy -m "Initial deploy"  # Deploy to Bonnard
+npx @bonnard/cli init
 ```
 
-No install needed — `npx` runs the CLI directly. Or install globally for shorter commands:
+Or install globally:
 
 ```bash
 npm install -g @bonnard/cli
 ```
 
+Then follow the setup flow:
+
+```bash
+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:
+
+```bash
+bon datasource add --demo
+```
+
 Requires Node.js 20+.
 
-## Commands
+## Agent-Native from Day One
 
-| Command | Description |
-|---------|-------------|
-| `bon init` | Create project structure and AI agent templates |
-| `bon login` | Authenticate with Bonnard |
-| `bon logout` | Remove stored credentials |
-| `bon whoami` | Show current login status |
-| `bon datasource add` | Add a data source (interactive) |
-| `bon datasource add --demo` | Add read-only demo dataset |
-| `bon datasource add --from-dbt` | Import from dbt profiles |
-| `bon datasource list` | List configured data sources |
-| `bon datasource remove <name>` | Remove a data source |
-| `bon validate` | Validate cube and view YAML |
-| `bon deploy -m "message"` | Deploy to Bonnard |
-| `bon deployments` | List deployment history |
-| `bon diff <id>` | View changes in a deployment |
-| `bon annotate <id>` | Add context to deployment changes |
-| `bon query '{"measures":["orders.count"]}'` | Query the semantic layer (JSON) |
-| `bon query "SELECT ..." --sql` | Query the semantic layer (SQL) |
-| `bon mcp` | MCP setup instructions for AI agents |
-| `bon mcp test` | Test MCP server connectivity |
-| `bon docs [topic]` | Browse modeling documentation |
-| `bon docs --search "joins"` | Search documentation |
+When you run `bon init`, Bonnard generates context files so AI coding agents understand your semantic layer from the first prompt:
 
-## Agent-ready from the start
+```
+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
+```
 
-`bon init` generates context files for your AI coding tools:
+| 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 |
 
-- **Claude Code** — `.claude/rules/` + get-started skill
-- **Cursor** — `.cursor/rules/` with auto-apply frontmatter
-- **Codex** — `AGENTS.md` + skills folder
+Set up your MCP server so agents can query your semantic layer directly:
 
-Your agent understands Bonnard's modeling language from the first prompt.
+```bash
+bon mcp setup                 # Configure MCP server
+bon mcp test                  # Verify the connection
+```
 
-## Project structure
+## Auto-Detected from Your Project
 
-After `bon init`:
+<p align="center">
+  <img src="./assets/datasources.png" alt="Auto-detected warehouses and data tools -Snowflake, BigQuery, PostgreSQL, Databricks, DuckDB, dbt, Dagster, Prefect, Airflow, Looker, Cube, Evidence, SQLMesh, Soda, Great Expectations" width="100%" />
+</p>
+
+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:
+
+```bash
+# 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/            # Cube definitions (measures, dimensions, joins)
-│   └── views/            # View definitions (curated query interfaces)
-└── .bon/                 # Local config (gitignored)
-    └── datasources.yaml  # Data source credentials
+│   ├── 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:
+
 ```bash
-bon deploy --ci -m "CI deploy"
+bon deploy --ci
 ```
 
-Non-interactive mode for pipelines. Datasources are synced automatically.
+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 setup` | Configure MCP server for agent access |
+| `bon mcp test` | Test MCP connection |
+| `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](https://docs.bonnard.dev/docs/cli-reference).
 
 ## Documentation
 
-- [Getting Started](https://docs.bonnard.dev/docs/getting-started)
-- [CLI Reference](https://docs.bonnard.dev/docs/cli)
-- [Modeling Guide](https://docs.bonnard.dev/docs/modeling/cubes)
-- [Querying](https://docs.bonnard.dev/docs/querying)
+- [Getting Started](https://docs.bonnard.dev/docs/getting-started) -from zero to deployed in minutes
+- [CLI Reference](https://docs.bonnard.dev/docs/cli-reference) -every command, flag, and option
+- [Modeling Guide](https://docs.bonnard.dev/docs/modeling) -cubes, views, metrics, and dimensions
+- [Querying](https://docs.bonnard.dev/docs/querying) -JSON and SQL query syntax
+- [Changelog](https://docs.bonnard.dev/docs/changelog) -what shipped and when
+
+## Community
+
+- [Discord](https://discord.com/invite/RQuvjGRz) -ask questions, share feedback, connect with the team
+- [GitHub Issues](https://github.com/meal-inc/bonnard-cli/issues) -bug reports and feature requests
+- [LinkedIn](https://www.linkedin.com/company/bonnarddev/) -follow for updates
+- [Website](https://www.bonnard.dev) -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](./LICENSE)

package/dist/bin/bon.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { n as getProjectPaths, t as BONNARD_DIR } from "./project-Dj085D_B.mjs";
-import { a as loadCredentials, i as clearCredentials, n as get, o as saveCredentials, r as post } from "./api-DqgY-30K.mjs";
+import { a as loadCredentials, i as clearCredentials, n as get, o as saveCredentials, r as post, t as del } from "./api-DqgY-30K.mjs";
 import { i as ensureBonDir, n as addLocalDatasource, o as loadLocalDatasources, r as datasourceExists, s as removeLocalDatasource, t as isDatasourcesTrackedByGit } from "./local-ByvuW3eV.mjs";
 import { createRequire } from "node:module";
 import { program } from "commander";
@@ -117,7 +117,8 @@ function mapDbtType(dbtType) {
 		postgresql: "postgres",
 		redshift: "redshift",
 		bigquery: "bigquery",
-		databricks: "databricks"
+		databricks: "databricks",
+		duckdb: "duckdb"
 	}[dbtType.toLowerCase()] ?? null;
 }
 /**
@@ -190,6 +191,8 @@ const PYTHON_PACKAGES = {
 	"dbt-postgres": "dbt",
 	"dbt-bigquery": "dbt",
 	"dbt-databricks": "dbt",
+	"dbt-duckdb": "dbt",
+	duckdb: "duckdb",
 	dagster: "dagster",
 	sqlmesh: "sqlmesh",
 	"apache-airflow": "airflow",
@@ -374,7 +377,8 @@ function extractWarehouseFromEnv(cwd) {
 				postgres: "postgres",
 				redshift: "redshift",
 				bigquery: "bigquery",
-				databricks: "databricks"
+				databricks: "databricks",
+				duckdb: "duckdb"
 			}[cubeDbType[1].trim().toLowerCase()];
 			if (type) return {
 				type,
@@ -395,6 +399,11 @@ function extractWarehouseFromEnv(cwd) {
 			source: "env",
 			config: {}
 		};
+		if (content.match(/^MOTHERDUCK_TOKEN=/m) || content.match(/^CUBEJS_DB_DUCKDB_DATABASE_PATH=/m)) return {
+			type: "duckdb",
+			source: "env",
+			config: {}
+		};
 	} catch {}
 	return null;
 }
@@ -907,6 +916,19 @@ function mapDatabricks(config) {
 	};
 }
 /**
+* Map DuckDB dbt config to Bonnard format
+*/
+function mapDuckDB(config) {
+	const dbPath = getString(config, "path") || getString(config, "database");
+	return {
+		config: {
+			...dbPath && { database_path: dbPath },
+			...getString(config, "schema") && { schema: getString(config, "schema") }
+		},
+		credentials: { ...getString(config, "motherduck_token") && { motherduck_token: getString(config, "motherduck_token") } }
+	};
+}
+/**
 * Map a parsed dbt connection to Bonnard format
 * Values are copied as-is, including {{ env_var(...) }} patterns
 */
@@ -926,6 +948,9 @@ function mapDbtConnection(connection) {
 		case "databricks":
 			mapped = mapDatabricks(config);
 			break;
+		case "duckdb":
+			mapped = mapDuckDB(config);
+			break;
 		default: throw new Error(`Unsupported warehouse type: ${type}`);
 	}
 	return { datasource: {
@@ -1120,6 +1145,26 @@ const WAREHOUSE_CONFIGS = [
 			secret: true,
 			required: true
 		}]
+	},
+	{
+		value: "duckdb",
+		label: "DuckDB",
+		configFields: [{
+			name: "database_path",
+			flag: "databasePath",
+			message: "Database path (file path, :memory:, or md:db_name for MotherDuck)",
+			required: true
+		}, {
+			name: "schema",
+			message: "Schema name",
+			default: "main"
+		}],
+		credentialFields: [{
+			name: "motherduck_token",
+			flag: "motherduckToken",
+			message: "MotherDuck token (required for md: paths)",
+			secret: true
+		}]
 	}
 ];
 /**
@@ -1135,8 +1180,10 @@ function formatType$1(type) {
 	return {
 		snowflake: "Snowflake",
 		postgres: "Postgres",
+		redshift: "Redshift",
 		bigquery: "BigQuery",
-		databricks: "Databricks"
+		databricks: "Databricks",
+		duckdb: "DuckDB"
 	}[type] || type;
 }
 /**
@@ -1170,7 +1217,7 @@ async function importFromDbt(options) {
 	}
 	if (connections.length === 0) {
 		console.log(pc.yellow("No supported connections found in dbt profiles."));
-		console.log(pc.dim("Supported types: snowflake, postgres, bigquery, databricks"));
+		console.log(pc.dim("Supported types: snowflake, postgres, redshift, bigquery, databricks, duckdb"));
 		process.exit(0);
 	}
 	if (typeof options.fromDbt === "string") {
@@ -1286,7 +1333,7 @@ async function addManual(options) {
 	const warehouseConfig = WAREHOUSE_CONFIGS.find((w) => w.value === warehouseType);
 	if (!warehouseConfig) {
 		console.error(pc.red(`Invalid warehouse type: ${warehouseType}`));
-		console.log(pc.dim("Valid types: snowflake, postgres, bigquery, databricks"));
+		console.log(pc.dim("Valid types: snowflake, postgres, redshift, bigquery, databricks, duckdb"));
 		process.exit(1);
 	}
 	const config = {};
@@ -1310,6 +1357,7 @@ async function addManual(options) {
 		let value;
 		if (field.name === "password" && options.passwordEnv) value = envVarRef(options.passwordEnv);
 		else if (field.name === "token" && options.tokenEnv) value = envVarRef(options.tokenEnv);
+		else if (field.name === "motherduck_token" && options.motherduckTokenEnv) value = envVarRef(options.motherduckTokenEnv);
 		else value = getOptionValue(options, field);
 		if (!value && !nonInteractive) if (field.secret) value = await password({ message: field.message + ":" });
 		else value = await input({ message: field.message + ":" });
@@ -3694,6 +3742,110 @@ async function metabaseAnalyzeCommand(options) {
 	console.log(pc.dim(`Full report: ${outputPath}`));
 }
 
+//#endregion
+//#region src/commands/keys/list.ts
+function formatDate(dateStr) {
+	if (!dateStr) return "—";
+	return new Date(dateStr).toLocaleDateString("en-US", {
+		month: "short",
+		day: "numeric",
+		year: "numeric"
+	});
+}
+function printKeyTable(keys, title, description) {
+	console.log(pc.bold(title));
+	console.log(pc.dim(description));
+	console.log();
+	if (keys.length === 0) {
+		console.log(pc.dim("  No keys."));
+		return;
+	}
+	const maxNameLen = Math.max(...keys.map((k) => k.name.length), 4);
+	const maxPrefixLen = Math.max(...keys.map((k) => k.key_prefix.length + 3), 3);
+	const header = `  ${"NAME".padEnd(maxNameLen)}  ${"KEY".padEnd(maxPrefixLen)}  ${"CREATED".padEnd(14)}  LAST USED`;
+	console.log(pc.dim(header));
+	console.log(pc.dim("  " + "─".repeat(header.length - 2)));
+	for (const k of keys) {
+		const name = k.name.padEnd(maxNameLen);
+		const prefix = (k.key_prefix + "...").padEnd(maxPrefixLen);
+		const created = formatDate(k.created_at).padEnd(14);
+		const lastUsed = formatDate(k.last_used_at);
+		console.log(`  ${pc.bold(name)}  ${pc.dim(prefix)}  ${created}  ${lastUsed}`);
+	}
+}
+async function keysListCommand() {
+	try {
+		const result = await get("/api/web/keys");
+		printKeyTable(result.publishableKeys, "Publishable Keys", "Client-side, read-only access");
+		console.log();
+		printKeyTable(result.secretKeys, "Secret Keys", "Server-side, full access");
+		const total = result.publishableKeys.length + result.secretKeys.length;
+		console.log();
+		console.log(pc.dim(`${total} key${total !== 1 ? "s" : ""} total`));
+	} catch (err) {
+		console.error(pc.red(`Error: ${err.message}`));
+		process.exit(1);
+	}
+}
+
+//#endregion
+//#region src/commands/keys/create.ts
+async function keysCreateCommand(options) {
+	const { name, type } = options;
+	if (type !== "publishable" && type !== "secret") {
+		console.error(pc.red("Error: --type must be 'publishable' or 'secret'"));
+		process.exit(1);
+	}
+	try {
+		const result = await post("/api/web/keys", {
+			name,
+			type
+		});
+		console.log(pc.green("Key created successfully."));
+		console.log();
+		console.log(pc.bold("  Name:  ") + result.name);
+		console.log(pc.bold("  Type:  ") + type);
+		console.log(pc.bold("  Key:   ") + result.key);
+		console.log();
+		console.log(pc.yellow("⚠ Save this key now — it won't be shown again."));
+	} catch (err) {
+		console.error(pc.red(`Error: ${err.message}`));
+		process.exit(1);
+	}
+}
+
+//#endregion
+//#region src/commands/keys/revoke.ts
+async function keysRevokeCommand(nameOrPrefix) {
+	try {
+		const result = await get("/api/web/keys");
+		let match;
+		let type;
+		for (const k of result.publishableKeys) if (k.name === nameOrPrefix || k.key_prefix.startsWith(nameOrPrefix)) {
+			match = k;
+			type = "publishable";
+			break;
+		}
+		if (!match) {
+			for (const k of result.secretKeys) if (k.name === nameOrPrefix || k.key_prefix.startsWith(nameOrPrefix)) {
+				match = k;
+				type = "secret";
+				break;
+			}
+		}
+		if (!match || !type) {
+			console.error(pc.red(`No key found matching "${nameOrPrefix}".`));
+			console.error(pc.dim("Use `bon keys list` to see available keys."));
+			process.exit(1);
+		}
+		await del(`/api/web/keys/${match.id}?type=${type}`);
+		console.log(pc.green(`Revoked ${type} key "${match.name}" (${match.key_prefix}...).`));
+	} catch (err) {
+		console.error(pc.red(`Error: ${err.message}`));
+		process.exit(1);
+	}
+}
+
 //#endregion
 //#region src/bin/bon.ts
 const { version } = createRequire(import.meta.url)("../../package.json");
@@ -3703,7 +3855,7 @@ program.command("login").description("Authenticate with Bonnard via your browser
 program.command("logout").description("Remove stored credentials").action(logoutCommand);
 program.command("whoami").description("Show current login status").option("--verify", "Verify session is still valid with the server").action(whoamiCommand);
 const datasource = program.command("datasource").description("Manage warehouse data source connections");
-datasource.command("add").description("Add a data source to .bon/datasources.yaml. Use --name and --type together for non-interactive mode").option("--demo", "Add a read-only demo datasource (Contoso retail dataset) for testing").option("--from-dbt [profile]", "Import from dbt profiles.yml (optionally specify profile/target)").option("--target <target>", "Target name when using --from-dbt").option("--all", "Import all connections from dbt profiles").option("--default-targets", "Import only default targets from dbt profiles (non-interactive)").option("--name <name>", "Datasource name (required for non-interactive mode)").option("--type <type>", "Warehouse type: snowflake, postgres, bigquery, databricks (required for non-interactive mode)").option("--account <account>", "Snowflake account identifier").option("--database <database>", "Database name").option("--schema <schema>", "Schema name").option("--warehouse <warehouse>", "Warehouse name (Snowflake)").option("--role <role>", "Role (Snowflake)").option("--host <host>", "Host (Postgres)").option("--port <port>", "Port (Postgres, default: 5432)").option("--project-id <projectId>", "GCP Project ID (BigQuery)").option("--dataset <dataset>", "Dataset name (BigQuery)").option("--location <location>", "Location (BigQuery)").option("--hostname <hostname>", "Server hostname (Databricks)").option("--http-path <httpPath>", "HTTP path (Databricks)").option("--catalog <catalog>", "Catalog name (Databricks)").option("--user <user>", "Username").option("--password <password>", "Password (use --password-env for env var reference)").option("--token <token>", "Access token (use --token-env for env var reference)").option("--service-account-json <json>", "Service account JSON (BigQuery)").option("--keyfile <path>", "Path to service account key file (BigQuery)").option("--password-env <varName>", "Env var name for password, stores as {{ env_var('NAME') }}").option("--token-env <varName>", "Env var name for token, stores as {{ env_var('NAME') }}").option("--force", "Overwrite existing datasource without prompting").action(datasourceAddCommand);
+datasource.command("add").description("Add a data source to .bon/datasources.yaml. Use --name and --type together for non-interactive mode").option("--demo", "Add a read-only demo datasource (Contoso retail dataset) for testing").option("--from-dbt [profile]", "Import from dbt profiles.yml (optionally specify profile/target)").option("--target <target>", "Target name when using --from-dbt").option("--all", "Import all connections from dbt profiles").option("--default-targets", "Import only default targets from dbt profiles (non-interactive)").option("--name <name>", "Datasource name (required for non-interactive mode)").option("--type <type>", "Warehouse type: snowflake, postgres, redshift, bigquery, databricks, duckdb (required for non-interactive mode)").option("--account <account>", "Snowflake account identifier").option("--database <database>", "Database name").option("--schema <schema>", "Schema name").option("--warehouse <warehouse>", "Warehouse name (Snowflake)").option("--role <role>", "Role (Snowflake)").option("--host <host>", "Host (Postgres)").option("--port <port>", "Port (Postgres, default: 5432)").option("--project-id <projectId>", "GCP Project ID (BigQuery)").option("--dataset <dataset>", "Dataset name (BigQuery)").option("--location <location>", "Location (BigQuery)").option("--hostname <hostname>", "Server hostname (Databricks)").option("--http-path <httpPath>", "HTTP path (Databricks)").option("--catalog <catalog>", "Catalog name (Databricks)").option("--database-path <databasePath>", "Database path: file path, :memory:, or md:db_name for MotherDuck (DuckDB)").option("--motherduck-token <token>", "MotherDuck token (DuckDB, for md: paths)").option("--motherduck-token-env <varName>", "Env var name for MotherDuck token, stores as {{ env_var('NAME') }}").option("--user <user>", "Username").option("--password <password>", "Password (use --password-env for env var reference)").option("--token <token>", "Access token (use --token-env for env var reference)").option("--service-account-json <json>", "Service account JSON (BigQuery)").option("--keyfile <path>", "Path to service account key file (BigQuery)").option("--password-env <varName>", "Env var name for password, stores as {{ env_var('NAME') }}").option("--token-env <varName>", "Env var name for token, stores as {{ env_var('NAME') }}").option("--force", "Overwrite existing datasource without prompting").action(datasourceAddCommand);
 datasource.command("list").description("List data sources (shows both local and remote by default)").option("--local", "Show only local data sources from .bon/datasources.yaml").option("--remote", "Show only remote data sources from Bonnard server (requires login)").action(datasourceListCommand);
 datasource.command("remove").description("Remove a data source from .bon/datasources.yaml (local by default)").argument("<name>", "Data source name").option("--remote", "Remove from Bonnard server instead of local (requires login)").action(datasourceRemoveCommand);
 program.command("validate").description("Validate YAML syntax in bonnard/cubes/ and bonnard/views/").action(validateCommand);
@@ -3714,6 +3866,10 @@ program.command("annotate").description("Annotate deployment changes with reason
 program.command("mcp").description("MCP connection info and setup instructions").action(mcpCommand).command("test").description("Test MCP server connectivity").action(mcpTestCommand);
 program.command("query").description("Execute a query against the deployed semantic layer").argument("<query>", "JSON query or SQL (with --sql flag)").option("--sql", "Use SQL API instead of JSON format").option("--limit <limit>", "Max rows to return").option("--format <format>", "Output format: toon or json", "toon").action(cubeQueryCommand);
 program.command("docs").description("Browse documentation for building cubes and views").argument("[topic]", "Topic to display (e.g., cubes, cubes.measures)").option("-r, --recursive", "Show topic and all child topics").option("-s, --search <query>", "Search topics for a keyword").option("-f, --format <format>", "Output format: markdown or json", "markdown").action(docsCommand).command("schema").description("Show JSON schema for a type (cube, view, measure, etc.)").argument("<type>", "Schema type to display").action(docsSchemaCommand);
+const keys = program.command("keys").description("Manage API keys for the Bonnard SDK");
+keys.command("list").description("List all API keys for your organization").action(keysListCommand);
+keys.command("create").description("Create a new API key").requiredOption("--name <name>", "Key name (e.g. 'Production SDK')").requiredOption("--type <type>", "Key type: publishable or secret").action(keysCreateCommand);
+keys.command("revoke").description("Revoke an API key by name or prefix").argument("<name-or-prefix>", "Key name or key prefix to revoke").action(keysRevokeCommand);
 const metabase = program.command("metabase").description("Connect to and explore Metabase content");
 metabase.command("connect").description("Configure Metabase API connection").option("--url <url>", "Metabase instance URL").option("--api-key <key>", "Metabase API key").option("--force", "Overwrite existing configuration").action(metabaseConnectCommand);
 metabase.command("explore").description("Browse Metabase databases, collections, cards, and dashboards").argument("[resource]", "databases, collections, cards, dashboards, card, dashboard, database, table, collection").argument("[id]", "Resource ID (e.g. card <id>, dashboard <id>, database <id>, table <id>, collection <id>)").action(metabaseExploreCommand);

package/dist/docs/topics/dashboards.examples.md

@@ -15,50 +15,45 @@ description: Monthly revenue trends and breakdowns
 # Revenue Overview
 
 ` ``query total_revenue
-cube: orders
-measures: [total_revenue]
+measures: [orders.total_revenue]
 ` ``
 
 ` ``query order_count
-cube: orders
-measures: [count]
+measures: [orders.count]
 ` ``
 
 ` ``query avg_order
-cube: orders
-measures: [avg_order_value]
+measures: [orders.avg_order_value]
 ` ``
 
 <Grid cols="3">
-<BigValue data={total_revenue} value="total_revenue" title="Total Revenue" />
-<BigValue data={order_count} value="count" title="Orders" />
-<BigValue data={avg_order} value="avg_order_value" title="Avg Order" />
+<BigValue data={total_revenue} value="orders.total_revenue" title="Total Revenue" />
+<BigValue data={order_count} value="orders.count" title="Orders" />
+<BigValue data={avg_order} value="orders.avg_order_value" title="Avg Order" />
 </Grid>
 
 ## Monthly Trend
 
 ` ``query monthly_revenue
-cube: orders
-measures: [total_revenue]
+measures: [orders.total_revenue]
 timeDimension:
-  dimension: created_at
+  dimension: orders.created_at
   granularity: month
   dateRange: [2025-01-01, 2025-12-31]
 ` ``
 
-<LineChart data={monthly_revenue} x="created_at" y="total_revenue" title="Monthly Revenue" />
+<LineChart data={monthly_revenue} x="orders.created_at" y="orders.total_revenue" title="Monthly Revenue" />
 
 ## By Category
 
 ` ``query by_category
-cube: orders
-measures: [total_revenue, count]
-dimensions: [category]
+measures: [orders.total_revenue, orders.count]
+dimensions: [orders.category]
 orderBy:
-  total_revenue: desc
+  orders.total_revenue: desc
 ` ``
 
-<BarChart data={by_category} x="category" y="total_revenue" title="Revenue by Category" />
+<BarChart data={by_category} x="orders.category" y="orders.total_revenue" title="Revenue by Category" />
 <DataTable data={by_category} />
 ```
 
@@ -75,43 +70,40 @@ description: Order status breakdown and city analysis
 # Sales Pipeline
 
 ` ``query by_status
-cube: orders
-measures: [count]
-dimensions: [status]
+measures: [orders.count]
+dimensions: [orders.status]
 ` ``
 
-<PieChart data={by_status} name="status" value="count" title="Order Status" />
+<PieChart data={by_status} name="orders.status" value="orders.count" title="Order Status" />
 
 ## Top Cities
 
 ` ``query top_cities
-cube: orders
-measures: [total_revenue, count]
-dimensions: [city]
+measures: [orders.total_revenue, orders.count]
+dimensions: [orders.city]
 orderBy:
-  total_revenue: desc
+  orders.total_revenue: desc
 limit: 10
 ` ``
 
-<BarChart data={top_cities} x="city" y="total_revenue" horizontal />
+<BarChart data={top_cities} x="orders.city" y="orders.total_revenue" horizontal />
 <DataTable data={top_cities} />
 
 ## Completed Orders Over Time
 
 ` ``query completed_trend
-cube: orders
-measures: [total_revenue]
+measures: [orders.total_revenue]
 timeDimension:
-  dimension: created_at
+  dimension: orders.created_at
   granularity: week
   dateRange: [2025-01-01, 2025-06-30]
 filters:
-  - dimension: status
+  - dimension: orders.status
     operator: equals
     values: [completed]
 ` ``
 
-<AreaChart data={completed_trend} x="created_at" y="total_revenue" title="Completed Order Revenue" />
+<AreaChart data={completed_trend} x="orders.created_at" y="orders.total_revenue" title="Completed Order Revenue" />
 ```
 
 ## Multi-Series Dashboard
@@ -127,39 +119,37 @@ description: Multi-series charts showing revenue breakdown by sales channel
 # Revenue by Channel
 
 ` ``query revenue_by_channel
-cube: orders
-measures: [total_revenue]
-dimensions: [channel]
+measures: [orders.total_revenue]
+dimensions: [orders.channel]
 timeDimension:
-  dimension: created_at
+  dimension: orders.created_at
   granularity: month
   dateRange: [2025-01-01, 2025-12-31]
 ` ``
 
 ## Stacked Bar (default)
 
-<BarChart data={revenue_by_channel} x="created_at" y="total_revenue" series="channel" title="Revenue by Channel" />
+<BarChart data={revenue_by_channel} x="orders.created_at" y="orders.total_revenue" series="orders.channel" title="Revenue by Channel" />
 
 ## Grouped Bar
 
-<BarChart data={revenue_by_channel} x="created_at" y="total_revenue" series="channel" type="grouped" title="Revenue by Channel (Grouped)" />
+<BarChart data={revenue_by_channel} x="orders.created_at" y="orders.total_revenue" series="orders.channel" type="grouped" title="Revenue by Channel (Grouped)" />
 
 ## Multi-Line
 
 ` ``query trend
-cube: orders
-measures: [total_revenue, count]
+measures: [orders.total_revenue, orders.count]
 timeDimension:
-  dimension: created_at
+  dimension: orders.created_at
   granularity: month
   dateRange: [2025-01-01, 2025-12-31]
 ` ``
 
-<LineChart data={trend} x="created_at" y="total_revenue,count" title="Revenue vs Orders" />
+<LineChart data={trend} x="orders.created_at" y="orders.total_revenue,orders.count" title="Revenue vs Orders" />
 
 ## Stacked Area by Channel
 
-<AreaChart data={revenue_by_channel} x="created_at" y="total_revenue" series="channel" type="stacked" title="Revenue by Channel" />
+<AreaChart data={revenue_by_channel} x="orders.created_at" y="orders.total_revenue" series="orders.channel" type="stacked" title="Revenue by Channel" />
 ```
 
 ## Formatted Dashboard
@@ -175,40 +165,37 @@ description: Formatted revenue metrics and trends
 # Sales Performance
 
 ` ``query totals
-cube: orders
-measures: [total_revenue, count, avg_order_value]
+measures: [orders.total_revenue, orders.count, orders.avg_order_value]
 ` ``
 
 <Grid cols="3">
-<BigValue data={totals} value="total_revenue" title="Revenue" fmt="eur2" />
-<BigValue data={totals} value="count" title="Orders" fmt="num0" />
-<BigValue data={totals} value="avg_order_value" title="Avg Order" fmt="eur2" />
+<BigValue data={totals} value="orders.total_revenue" title="Revenue" fmt="eur2" />
+<BigValue data={totals} value="orders.count" title="Orders" fmt="num0" />
+<BigValue data={totals} value="orders.avg_order_value" title="Avg Order" fmt="eur2" />
 </Grid>
 
 ## Revenue Trend
 
 ` ``query monthly
-cube: orders
-measures: [total_revenue]
+measures: [orders.total_revenue]
 timeDimension:
-  dimension: created_at
+  dimension: orders.created_at
   granularity: month
   dateRange: [2025-01-01, 2025-12-31]
 ` ``
 
-<LineChart data={monthly} x="created_at" y="total_revenue" title="Monthly Revenue" yFmt="eur" />
+<LineChart data={monthly} x="orders.created_at" y="orders.total_revenue" title="Monthly Revenue" yFmt="eur" />
 
 ## Detail Table
 
 ` ``query details
-cube: orders
-measures: [total_revenue, count]
-dimensions: [category]
+measures: [orders.total_revenue, orders.count]
+dimensions: [orders.category]
 orderBy:
-  total_revenue: desc
+  orders.total_revenue: desc
 ` ``
 
-<DataTable data={details} fmt="total_revenue:eur2,count:num0" />
+<DataTable data={details} fmt="orders.total_revenue:eur2,orders.count:num0" />
 ```
 
 ## Interactive Dashboard
@@ -224,47 +211,43 @@ description: Sales dashboard with date and channel filters
 # Interactive Sales
 
 <DateRange name="period" default="last-6-months" label="Time Period" />
-<Dropdown name="channel" dimension="channel" data={channels} queries="trend,by_city" label="Channel" />
+<Dropdown name="channel" dimension="orders.channel" data={channels} queries="trend,by_city" label="Channel" />
 
 ` ``query channels
-cube: orders
-dimensions: [channel]
+dimensions: [orders.channel]
 ` ``
 
 ` ``query kpis
-cube: orders
-measures: [total_revenue, count]
+measures: [orders.total_revenue, orders.count]
 ` ``
 
 <Grid cols="2">
-<BigValue data={kpis} value="total_revenue" title="Revenue" fmt="eur2" />
-<BigValue data={kpis} value="count" title="Orders" fmt="num0" />
+<BigValue data={kpis} value="orders.total_revenue" title="Revenue" fmt="eur2" />
+<BigValue data={kpis} value="orders.count" title="Orders" fmt="num0" />
 </Grid>
 
 ## Revenue Trend
 
 ` ``query trend
-cube: orders
-measures: [total_revenue]
+measures: [orders.total_revenue]
 timeDimension:
-  dimension: created_at
+  dimension: orders.created_at
   granularity: month
 ` ``
 
-<LineChart data={trend} x="created_at" y="total_revenue" title="Monthly Revenue" yFmt="eur" />
+<LineChart data={trend} x="orders.created_at" y="orders.total_revenue" title="Monthly Revenue" yFmt="eur" />
 
 ## By City
 
 ` ``query by_city
-cube: orders
-measures: [total_revenue]
-dimensions: [city]
+measures: [orders.total_revenue]
+dimensions: [orders.city]
 orderBy:
-  total_revenue: desc
+  orders.total_revenue: desc
 limit: 10
 ` ``
 
-<BarChart data={by_city} x="city" y="total_revenue" title="Top Cities" yFmt="eur" />
+<BarChart data={by_city} x="orders.city" y="orders.total_revenue" title="Top Cities" yFmt="eur" />
 ```
 
 The `<DateRange>` automatically applies to all queries with a `timeDimension` (here: `trend`). The `<Dropdown>` filters `trend` and `by_city` by channel. The `channels` query populates the dropdown and is never filtered by it.
@@ -273,12 +256,12 @@ The `<DateRange>` automatically applies to all queries with a `timeDimension` (h
 
 - **Start with KPIs**: Use `BigValue` in a `Grid` at the top for key metrics
 - **One query per chart**: Each component gets its own query — keep them focused
-- **Use views**: Prefer view names over cube names when available for cleaner field names
+- **Use views**: Prefer view names over cube names when available
 - **Name queries descriptively**: `monthly_revenue` is better than `q1`
 - **Limit large datasets**: Add `limit` to dimension queries to avoid oversized charts
 - **Time series**: Always use `timeDimension` with `granularity` for time-based charts
-- **Multi-series**: Use `series="column"` to split data by a dimension. For bars, default is stacked; use `type="grouped"` for side-by-side
-- **Multiple y columns**: Use comma-separated values like `y="revenue,cases"` to show multiple measures on one chart
+- **Multi-series**: Use `series="cube.column"` to split data by a dimension. For bars, default is stacked; use `type="grouped"` for side-by-side
+- **Multiple y columns**: Use comma-separated values like `y="orders.revenue,orders.cases"` to show multiple measures on one chart
 
 ## See Also
 

package/dist/docs/topics/dashboards.inputs.md

@@ -54,7 +54,7 @@ Targeting lets you control which queries a filter affects — useful when some c
 Renders a dropdown selector populated from a query's dimension values. Adds a filter on the specified dimension to targeted queries.
 
 ```markdown
-<Dropdown name="channel" dimension="channel" data={channels} queries="main,trend" label="Channel" />
+<Dropdown name="channel" dimension="orders.channel" data={channels} queries="main,trend" label="Channel" />
 ```
 
 ### Props
@@ -86,14 +86,13 @@ title: Revenue Trends
 <DateRange name="period" default="last-6-months" label="Time Period" />
 
 ` ``query monthly_revenue
-cube: orders
-measures: [total_revenue]
+measures: [orders.total_revenue]
 timeDimension:
-  dimension: created_at
+  dimension: orders.created_at
   granularity: month
 ` ``
 
-<LineChart data={monthly_revenue} x="created_at" y="total_revenue" />
+<LineChart data={monthly_revenue} x="orders.created_at" y="orders.total_revenue" />
 ```
 
 The DateRange automatically applies to `monthly_revenue` because it has a `timeDimension`. No hardcoded `dateRange` needed in the query.
@@ -106,19 +105,17 @@ title: Sales by Channel
 ---
 
 ` ``query channels
-cube: orders
-dimensions: [channel]
+dimensions: [orders.channel]
 ` ``
 
-<Dropdown name="ch" dimension="channel" data={channels} queries="main" label="Channel" />
+<Dropdown name="ch" dimension="orders.channel" data={channels} queries="main" label="Channel" />
 
 ` ``query main
-cube: orders
-measures: [total_revenue]
-dimensions: [city]
+measures: [orders.total_revenue]
+dimensions: [orders.city]
 ` ``
 
-<BarChart data={main} x="city" y="total_revenue" />
+<BarChart data={main} x="orders.city" y="orders.total_revenue" />
 ```
 
 ### Combined inputs
@@ -129,30 +126,27 @@ title: Sales Dashboard
 ---
 
 <DateRange name="period" default="last-6-months" label="Time Period" />
-<Dropdown name="channel" dimension="channel" data={channels} queries="trend,by_city" label="Channel" />
+<Dropdown name="channel" dimension="orders.channel" data={channels} queries="trend,by_city" label="Channel" />
 
 ` ``query channels
-cube: orders
-dimensions: [channel]
+dimensions: [orders.channel]
 ` ``
 
 ` ``query trend
-cube: orders
-measures: [total_revenue]
+measures: [orders.total_revenue]
 timeDimension:
-  dimension: created_at
+  dimension: orders.created_at
   granularity: month
 ` ``
 
-<LineChart data={trend} x="created_at" y="total_revenue" />
+<LineChart data={trend} x="orders.created_at" y="orders.total_revenue" />
 
 ` ``query by_city
-cube: orders
-measures: [total_revenue]
-dimensions: [city]
+measures: [orders.total_revenue]
+dimensions: [orders.city]
 ` ``
 
-<BarChart data={by_city} x="city" y="total_revenue" />
+<BarChart data={by_city} x="orders.city" y="orders.total_revenue" />
 ```
 
 Both inputs work together: the DateRange scopes the time window on `trend` (which has a timeDimension), and the Dropdown filters both `trend` and `by_city` by channel.

package/dist/docs/topics/dashboards.md

@@ -27,19 +27,17 @@ description: Key metrics for the orders pipeline
 # Order Summary
 
 ` ``query order_count
-cube: orders
-measures: [count]
+measures: [orders.count]
 ` ``
 
-<BigValue data={order_count} value="count" title="Total Orders" />
+<BigValue data={order_count} value="orders.count" title="Total Orders" />
 
 ` ``query by_status
-cube: orders
-measures: [count]
-dimensions: [status]
+measures: [orders.count]
+dimensions: [orders.status]
 ` ``
 
-<BarChart data={by_status} x="status" y="count" />
+<BarChart data={by_status} x="orders.status" y="orders.count" />
 ```
 
 ## Frontmatter

package/dist/docs/topics/dashboards.queries.md

@@ -6,7 +6,7 @@
 
 Each query fetches data from your semantic layer and makes it available to chart components. Queries use the same measures and dimensions defined in your cubes and views — field names stay consistent whether you're querying from a dashboard, MCP, or the API.
 
-Query blocks have a unique name and map to a `QueryOptions` shape. Components reference them using `data={query_name}`. Field names are unqualified — use `count` not `orders.count` — because the `cube` property provides the context.
+Query blocks have a unique name and map to a `QueryOptions` shape. Components reference them using `data={query_name}`. All field names must be fully qualified with the cube or view name (e.g. `orders.count`, `orders.created_at`).
 
 ## Syntax
 
@@ -14,10 +14,9 @@ Query blocks use fenced code with the `query` language tag followed by a name:
 
 ````markdown
 ```query revenue_trend
-cube: orders
-measures: [total_revenue]
+measures: [orders.total_revenue]
 timeDimension:
-  dimension: created_at
+  dimension: orders.created_at
   granularity: month
   dateRange: [2025-01-01, 2025-12-31]
 ```
@@ -27,19 +26,18 @@ timeDimension:
 
 | Property | Type | Required | Description |
 |----------|------|----------|-------------|
-| `cube` | string | Yes | The cube or view to query (e.g. `orders`) |
-| `measures` | string[] | No | Measures to aggregate (e.g. `[count, total_revenue]`) |
-| `dimensions` | string[] | No | Dimensions to group by (e.g. `[status, city]`) |
+| `measures` | string[] | No | Fully qualified measures to aggregate (e.g. `[orders.count, orders.total_revenue]`) |
+| `dimensions` | string[] | No | Fully qualified dimensions to group by (e.g. `[orders.status, orders.city]`) |
 | `filters` | Filter[] | No | Row-level filters |
 | `timeDimension` | object | No | Time-based grouping and date range |
-| `orderBy` | object | No | Sort specification (e.g. `{total_revenue: desc}`) |
+| `orderBy` | object | No | Sort specification (e.g. `{orders.total_revenue: desc}`) |
 | `limit` | number | No | Maximum rows to return |
 
 ### timeDimension
 
 | Property | Type | Required | Description |
 |----------|------|----------|-------------|
-| `dimension` | string | Yes | Time dimension name (e.g. `created_at`) |
+| `dimension` | string | Yes | Fully qualified time dimension name (e.g. `orders.created_at`) |
 | `granularity` | string | No | `day`, `week`, `month`, `quarter`, or `year` |
 | `dateRange` | string[] | No | `[start, end]` in `YYYY-MM-DD` format |
 
@@ -59,8 +57,7 @@ Each filter is an object with:
 
 ````markdown
 ```query total_orders
-cube: orders
-measures: [count]
+measures: [orders.count]
 ```
 ````
 
@@ -68,11 +65,10 @@ measures: [count]
 
 ````markdown
 ```query revenue_by_city
-cube: orders
-measures: [total_revenue]
-dimensions: [city]
+measures: [orders.total_revenue]
+dimensions: [orders.city]
 orderBy:
-  total_revenue: desc
+  orders.total_revenue: desc
 limit: 10
 ```
 ````
@@ -81,10 +77,9 @@ limit: 10
 
 ````markdown
 ```query monthly_revenue
-cube: orders
-measures: [total_revenue]
+measures: [orders.total_revenue]
 timeDimension:
-  dimension: created_at
+  dimension: orders.created_at
   granularity: month
   dateRange: [2025-01-01, 2025-12-31]
 ```
@@ -94,11 +89,10 @@ timeDimension:
 
 ````markdown
 ```query completed_orders
-cube: orders
-measures: [count, total_revenue]
-dimensions: [category]
+measures: [orders.count, orders.total_revenue]
+dimensions: [orders.category]
 filters:
-  - dimension: status
+  - dimension: orders.status
     operator: equals
     values: [completed]
 ```
@@ -108,8 +102,7 @@ filters:
 
 - Query names must be valid identifiers (letters, numbers, `_`, `$`)
 - Query names must be unique within a dashboard
-- Every query must specify a `cube`
-- Field names are unqualified (use `count` not `orders.count`) — the `cube` provides the context
+- All field names must be fully qualified with the cube or view name (e.g. `orders.count`, not `count`)
 - Components reference queries by name: `data={query_name}`
 
 ## See Also

package/dist/docs/topics/querying.sdk.md

@@ -18,11 +18,10 @@ const bonnard = createClient({
 });
 
 const result = await bonnard.query({
-  cube: 'orders',
-  measures: ['revenue', 'count'],
-  dimensions: ['status'],
+  measures: ['orders.revenue', 'orders.count'],
+  dimensions: ['orders.status'],
   timeDimension: {
-    dimension: 'created_at',
+    dimension: 'orders.created_at',
     granularity: 'month',
     dateRange: ['2025-01-01', '2025-12-31'],
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bonnard/cli",
-  "version": "0.2.11",
+  "version": "0.2.12",
   "type": "module",
   "bin": {
     "bon": "./dist/bin/bon.mjs"