@bonnard/cli 0.2.15 → 0.3.0

package/README.md

@@ -98,7 +98,7 @@ Agent support:
 Set up your MCP server so agents can query your semantic layer directly:
 
 ```bash
-bon mcp setup                 # Configure MCP server
+bon mcp                       # Show MCP server setup instructions
 bon mcp test                  # Verify the connection
 ```
 
@@ -172,8 +172,15 @@ Handles automatic datasource synchronisation and skips interactive prompts. Fits
 | `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` | 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 |

package/dist/bin/bon.mjs

@@ -13,6 +13,8 @@ import YAML from "yaml";
 import http from "node:http";
 import crypto from "node:crypto";
 import { encode } from "@toon-format/toon";
+import { createInterface } from "node:readline";
+import open from "open";
 
 //#region \0rolldown/runtime.js
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
@@ -555,36 +557,120 @@ function loadJsonTemplate(relativePath) {
 	return JSON.parse(content);
 }
 /**
-* Write a template file, appending if target exists and doesn't already have Bonnard content
+* Write a template file.
+* - init mode: skip if file contains `# Bonnard`, append if exists without it, create if missing
+* - update mode: overwrite if changed, create if missing
 */
-function writeTemplateFile(content, targetPath, createdFiles) {
+function writeTemplateFile(content, targetPath, results, mode = "init") {
+	const relativePath = path.relative(process.cwd(), targetPath);
 	if (fs.existsSync(targetPath)) {
-		if (!fs.readFileSync(targetPath, "utf-8").includes("# Bonnard")) {
+		const existingContent = fs.readFileSync(targetPath, "utf-8");
+		if (mode === "update") if (existingContent === content) results.push({
+			action: "unchanged",
+			path: relativePath
+		});
+		else {
+			fs.writeFileSync(targetPath, content);
+			results.push({
+				action: "updated",
+				path: relativePath
+			});
+		}
+		else if (!existingContent.includes("# Bonnard")) {
+			fs.appendFileSync(targetPath, `\n\n${content}`);
+			results.push({
+				action: "appended",
+				path: relativePath
+			});
+		}
+	} else {
+		fs.writeFileSync(targetPath, content);
+		results.push({
+			action: mode === "update" ? "added" : "created",
+			path: relativePath
+		});
+	}
+}
+/**
+* Write a file that may contain user content alongside the Bonnard section.
+* In update mode, replaces only content from `# Bonnard Semantic Layer` onwards,
+* preserving any user content before it. Falls back to overwrite if marker not found.
+*/
+function writeBonnardSection(content, targetPath, results, mode = "init") {
+	const relativePath = path.relative(process.cwd(), targetPath);
+	const SECTION_MARKER = "# Bonnard Semantic Layer";
+	if (fs.existsSync(targetPath)) {
+		const existingContent = fs.readFileSync(targetPath, "utf-8");
+		if (mode === "update") {
+			const sectionStart = existingContent.indexOf(SECTION_MARKER);
+			let newContent;
+			if (sectionStart > 0) newContent = existingContent.slice(0, sectionStart).trimEnd() + "\n\n" + content;
+			else newContent = content;
+			if (existingContent === newContent) results.push({
+				action: "unchanged",
+				path: relativePath
+			});
+			else {
+				fs.writeFileSync(targetPath, newContent);
+				results.push({
+					action: "updated",
+					path: relativePath
+				});
+			}
+		} else if (!existingContent.includes("# Bonnard")) {
 			fs.appendFileSync(targetPath, `\n\n${content}`);
-			createdFiles.push(`${path.relative(process.cwd(), targetPath)} (appended)`);
+			results.push({
+				action: "appended",
+				path: relativePath
+			});
 		}
 	} else {
 		fs.writeFileSync(targetPath, content);
-		createdFiles.push(path.relative(process.cwd(), targetPath));
+		results.push({
+			action: mode === "update" ? "added" : "created",
+			path: relativePath
+		});
 	}
 }
 /**
 * Merge settings.json, preserving existing settings
 */
-function mergeSettingsJson(templateSettings, targetPath, createdFiles) {
+function mergeSettingsJson(templateSettings, targetPath, results, mode = "init") {
+	const relativePath = path.relative(process.cwd(), targetPath);
 	if (fs.existsSync(targetPath)) {
-		const existingContent = JSON.parse(fs.readFileSync(targetPath, "utf-8"));
+		const existingRaw = fs.readFileSync(targetPath, "utf-8");
+		const existingContent = JSON.parse(existingRaw);
 		const templatePerms = templateSettings.permissions;
 		if (templatePerms?.allow) {
 			existingContent.permissions = existingContent.permissions || {};
 			existingContent.permissions.allow = existingContent.permissions.allow || [];
 			for (const permission of templatePerms.allow) if (!existingContent.permissions.allow.includes(permission)) existingContent.permissions.allow.push(permission);
 		}
-		fs.writeFileSync(targetPath, JSON.stringify(existingContent, null, 2) + "\n");
-		createdFiles.push(`${path.relative(process.cwd(), targetPath)} (merged)`);
+		const newRaw = JSON.stringify(existingContent, null, 2) + "\n";
+		if (mode === "update") if (existingRaw === newRaw) results.push({
+			action: "unchanged",
+			path: relativePath
+		});
+		else {
+			fs.writeFileSync(targetPath, newRaw);
+			results.push({
+				action: "updated",
+				path: relativePath
+			});
+		}
+		else {
+			fs.writeFileSync(targetPath, newRaw);
+			results.push({
+				action: "merged",
+				path: relativePath
+			});
+		}
 	} else {
 		fs.writeFileSync(targetPath, JSON.stringify(templateSettings, null, 2) + "\n");
-		createdFiles.push(path.relative(process.cwd(), targetPath));
+		results.push({
+			action: mode === "update" ? "added" : "created",
+			path: relativePath
+		});
 	}
 }
 /**
@@ -601,8 +687,8 @@ alwaysApply: ${alwaysApply}
 /**
 * Create agent templates (Claude Code, Cursor, and Codex)
 */
-function createAgentTemplates(cwd, env) {
-	const createdFiles = [];
+function createAgentTemplates(cwd, env, mode = "init") {
+	const results = [];
 	let sharedBonnard = loadTemplate("shared/bonnard.md");
 	if (env) sharedBonnard += "\n\n" + generateProjectContext(env);
 	const claudeRulesDir = path.join(cwd, ".claude", "rules");
@@ -611,31 +697,65 @@ function createAgentTemplates(cwd, env) {
 	fs.mkdirSync(path.join(claudeSkillsDir, "bonnard-get-started"), { recursive: true });
 	fs.mkdirSync(path.join(claudeSkillsDir, "bonnard-metabase-migrate"), { recursive: true });
 	fs.mkdirSync(path.join(claudeSkillsDir, "bonnard-design-guide"), { recursive: true });
-	writeTemplateFile(sharedBonnard, path.join(claudeRulesDir, "bonnard.md"), createdFiles);
-	writeTemplateFile(loadTemplate("claude/skills/bonnard-get-started/SKILL.md"), path.join(claudeSkillsDir, "bonnard-get-started", "SKILL.md"), createdFiles);
-	writeTemplateFile(loadTemplate("claude/skills/bonnard-metabase-migrate/SKILL.md"), path.join(claudeSkillsDir, "bonnard-metabase-migrate", "SKILL.md"), createdFiles);
-	writeTemplateFile(loadTemplate("claude/skills/bonnard-design-guide/SKILL.md"), path.join(claudeSkillsDir, "bonnard-design-guide", "SKILL.md"), createdFiles);
-	mergeSettingsJson(loadJsonTemplate("claude/settings.json"), path.join(cwd, ".claude", "settings.json"), createdFiles);
+	fs.mkdirSync(path.join(claudeSkillsDir, "bonnard-build-dashboard"), { recursive: true });
+	writeBonnardSection(sharedBonnard, path.join(claudeRulesDir, "bonnard.md"), results, mode);
+	writeTemplateFile(loadTemplate("claude/skills/bonnard-get-started/SKILL.md"), path.join(claudeSkillsDir, "bonnard-get-started", "SKILL.md"), results, mode);
+	writeTemplateFile(loadTemplate("claude/skills/bonnard-metabase-migrate/SKILL.md"), path.join(claudeSkillsDir, "bonnard-metabase-migrate", "SKILL.md"), results, mode);
+	writeTemplateFile(loadTemplate("claude/skills/bonnard-design-guide/SKILL.md"), path.join(claudeSkillsDir, "bonnard-design-guide", "SKILL.md"), results, mode);
+	writeTemplateFile(loadTemplate("claude/skills/bonnard-build-dashboard/SKILL.md"), path.join(claudeSkillsDir, "bonnard-build-dashboard", "SKILL.md"), results, mode);
+	mergeSettingsJson(loadJsonTemplate("claude/settings.json"), path.join(cwd, ".claude", "settings.json"), results, mode);
 	const cursorRulesDir = path.join(cwd, ".cursor", "rules");
 	fs.mkdirSync(cursorRulesDir, { recursive: true });
-	writeTemplateFile(withCursorFrontmatter(sharedBonnard, "Bonnard semantic layer project context", true), path.join(cursorRulesDir, "bonnard.mdc"), createdFiles);
-	writeTemplateFile(loadTemplate("cursor/rules/bonnard-get-started.mdc"), path.join(cursorRulesDir, "bonnard-get-started.mdc"), createdFiles);
-	writeTemplateFile(loadTemplate("cursor/rules/bonnard-metabase-migrate.mdc"), path.join(cursorRulesDir, "bonnard-metabase-migrate.mdc"), createdFiles);
-	writeTemplateFile(loadTemplate("cursor/rules/bonnard-design-guide.mdc"), path.join(cursorRulesDir, "bonnard-design-guide.mdc"), createdFiles);
+	writeTemplateFile(withCursorFrontmatter(sharedBonnard, "Bonnard semantic layer project context", true), path.join(cursorRulesDir, "bonnard.mdc"), results, mode);
+	writeTemplateFile(loadTemplate("cursor/rules/bonnard-get-started.mdc"), path.join(cursorRulesDir, "bonnard-get-started.mdc"), results, mode);
+	writeTemplateFile(loadTemplate("cursor/rules/bonnard-metabase-migrate.mdc"), path.join(cursorRulesDir, "bonnard-metabase-migrate.mdc"), results, mode);
+	writeTemplateFile(loadTemplate("cursor/rules/bonnard-design-guide.mdc"), path.join(cursorRulesDir, "bonnard-design-guide.mdc"), results, mode);
+	writeTemplateFile(loadTemplate("cursor/rules/bonnard-build-dashboard.mdc"), path.join(cursorRulesDir, "bonnard-build-dashboard.mdc"), results, mode);
 	const codexSkillsDir = path.join(cwd, ".agents", "skills");
 	fs.mkdirSync(path.join(codexSkillsDir, "bonnard-get-started"), { recursive: true });
 	fs.mkdirSync(path.join(codexSkillsDir, "bonnard-metabase-migrate"), { recursive: true });
 	fs.mkdirSync(path.join(codexSkillsDir, "bonnard-design-guide"), { recursive: true });
-	writeTemplateFile(sharedBonnard, path.join(cwd, "AGENTS.md"), createdFiles);
-	writeTemplateFile(loadTemplate("claude/skills/bonnard-get-started/SKILL.md"), path.join(codexSkillsDir, "bonnard-get-started", "SKILL.md"), createdFiles);
-	writeTemplateFile(loadTemplate("claude/skills/bonnard-metabase-migrate/SKILL.md"), path.join(codexSkillsDir, "bonnard-metabase-migrate", "SKILL.md"), createdFiles);
-	writeTemplateFile(loadTemplate("claude/skills/bonnard-design-guide/SKILL.md"), path.join(codexSkillsDir, "bonnard-design-guide", "SKILL.md"), createdFiles);
-	return createdFiles;
+	fs.mkdirSync(path.join(codexSkillsDir, "bonnard-build-dashboard"), { recursive: true });
+	writeBonnardSection(sharedBonnard, path.join(cwd, "AGENTS.md"), results, mode);
+	writeTemplateFile(loadTemplate("claude/skills/bonnard-get-started/SKILL.md"), path.join(codexSkillsDir, "bonnard-get-started", "SKILL.md"), results, mode);
+	writeTemplateFile(loadTemplate("claude/skills/bonnard-metabase-migrate/SKILL.md"), path.join(codexSkillsDir, "bonnard-metabase-migrate", "SKILL.md"), results, mode);
+	writeTemplateFile(loadTemplate("claude/skills/bonnard-design-guide/SKILL.md"), path.join(codexSkillsDir, "bonnard-design-guide", "SKILL.md"), results, mode);
+	writeTemplateFile(loadTemplate("claude/skills/bonnard-build-dashboard/SKILL.md"), path.join(codexSkillsDir, "bonnard-build-dashboard", "SKILL.md"), results, mode);
+	return results;
+}
+function formatFileResult(result) {
+	switch (result.action) {
+		case "appended": return `${result.path} (appended)`;
+		case "merged": return `${result.path} (merged)`;
+		default: return result.path;
+	}
 }
-async function initCommand() {
+async function initCommand(options = {}) {
 	const cwd = process.cwd();
-	const projectName = path.basename(cwd);
 	const paths = getProjectPaths(cwd);
+	if (options.update) {
+		if (!fs.existsSync(paths.config)) {
+			console.log(pc.red("No bon.yaml found. Run `bon init` first."));
+			process.exit(1);
+		}
+		const env = detectProjectEnvironment(cwd);
+		const results = createAgentTemplates(cwd, env.tools.length > 0 || env.warehouse ? env : void 0, "update");
+		const updated = results.filter((r) => r.action === "updated");
+		const added = results.filter((r) => r.action === "added");
+		if (updated.length === 0 && added.length === 0) console.log(pc.green("All agent templates are up to date."));
+		else {
+			const parts = [];
+			if (updated.length > 0) parts.push(`updated ${updated.length} file${updated.length !== 1 ? "s" : ""}`);
+			if (added.length > 0) parts.push(`added ${added.length} new file${added.length !== 1 ? "s" : ""}`);
+			console.log(pc.green(`Agent templates: ${parts.join(", ")}.`));
+			for (const r of [...updated, ...added]) {
+				const label = r.action === "added" ? pc.cyan("new") : pc.yellow("updated");
+				console.log(`  ${label} ${pc.dim(r.path)}`);
+			}
+		}
+		return;
+	}
+	const projectName = path.basename(cwd);
 	if (fs.existsSync(paths.config)) {
 		console.log(pc.red("A bon.yaml already exists in this directory."));
 		process.exit(1);
@@ -658,7 +778,7 @@ async function initCommand() {
 	if (agentFiles.length > 0) {
 		console.log();
 		console.log(pc.bold("Agent support:"));
-		for (const file of agentFiles) console.log(`  ${pc.dim(file)}`);
+		for (const file of agentFiles) console.log(`  ${pc.dim(formatFileResult(file))}`);
 	}
 	if (env.tools.length > 0 || env.warehouse) {
 		console.log();
@@ -670,12 +790,12 @@ async function initCommand() {
 
 //#endregion
 //#region src/commands/login.ts
-const APP_URL = process.env.BON_APP_URL || "https://app.bonnard.dev";
+const APP_URL$4 = process.env.BON_APP_URL || "https://app.bonnard.dev";
 const TIMEOUT_MS = 120 * 1e3;
 async function loginCommand() {
 	const state = crypto.randomUUID();
 	const { port, close } = await startCallbackServer(state);
-	const url = `${APP_URL}/auth/device?state=${state}&port=${port}`;
+	const url = `${APP_URL$4}/auth/device?state=${state}&port=${port}`;
 	console.log(pc.dim(`Opening browser to ${url}`));
 	const open = (await import("open")).default;
 	await open(url);
@@ -3870,11 +3990,237 @@ async function keysRevokeCommand(nameOrPrefix) {
 	}
 }
 
+//#endregion
+//#region src/commands/dashboard/deploy.ts
+const APP_URL$3 = process.env.BON_APP_URL || "https://app.bonnard.dev";
+/**
+* Extract <title> content from HTML string
+*/
+function extractHtmlTitle(html) {
+	const match = html.match(/<title[^>]*>(.*?)<\/title>/is);
+	return match ? match[1].trim() : null;
+}
+/**
+* Extract title from YAML frontmatter in markdown
+*/
+function extractFrontmatterTitle(content) {
+	const match = content.match(/^---\n([\s\S]*?)\n---/);
+	if (!match) return null;
+	const titleMatch = match[1].match(/^title:\s*["']?(.+?)["']?\s*$/m);
+	return titleMatch ? titleMatch[1] : null;
+}
+/**
+* Derive slug from filename: strip extension, lowercase, replace non-alphanumeric with hyphens
+*/
+function slugFromFilename(filename) {
+	return path.basename(filename, path.extname(filename)).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+async function dashboardDeployCommand(file, options) {
+	const filePath = path.resolve(file);
+	if (!fs.existsSync(filePath)) {
+		console.error(pc.red(`File not found: ${file}`));
+		process.exit(1);
+	}
+	const content = fs.readFileSync(filePath, "utf-8");
+	if (content.length > 2 * 1024 * 1024) {
+		console.error(pc.red("File exceeds 2MB limit."));
+		process.exit(1);
+	}
+	const format = path.extname(filePath).toLowerCase() === ".md" ? "markdown" : "html";
+	const slug = options.slug || slugFromFilename(file);
+	const title = options.title || (format === "markdown" ? extractFrontmatterTitle(content) || slug : extractHtmlTitle(content) || slug);
+	console.log(pc.dim(`Deploying ${format} dashboard "${slug}"...`));
+	try {
+		const dashboard = (await post("/api/dashboards", {
+			slug,
+			title,
+			content,
+			format
+		})).dashboard;
+		const url = `${APP_URL$3}/d/${dashboard.org_slug}/${dashboard.slug}`;
+		console.log(pc.green(`Dashboard deployed successfully`));
+		console.log();
+		console.log(`  ${pc.bold("Slug")}     ${dashboard.slug}`);
+		console.log(`  ${pc.bold("Title")}    ${dashboard.title}`);
+		console.log(`  ${pc.bold("Format")}   ${format}`);
+		console.log(`  ${pc.bold("Version")}  ${dashboard.version}`);
+		console.log(`  ${pc.bold("URL")}      ${url}`);
+	} catch (err) {
+		console.error(pc.red(`Deploy failed: ${err instanceof Error ? err.message : err}`));
+		process.exit(1);
+	}
+}
+
+//#endregion
+//#region src/commands/dashboard/list.ts
+const APP_URL$2 = process.env.BON_APP_URL || "https://app.bonnard.dev";
+async function dashboardListCommand() {
+	try {
+		const dashboards = (await get("/api/dashboards")).dashboards;
+		if (dashboards.length === 0) {
+			console.log(pc.dim("No dashboards deployed yet. Run `bon dashboard deploy <file>` to publish."));
+			return;
+		}
+		const slugWidth = Math.max(4, ...dashboards.map((d) => d.slug.length));
+		const titleWidth = Math.max(5, ...dashboards.map((d) => d.title.length));
+		const versionWidth = 7;
+		const dateWidth = 10;
+		const header = [
+			"SLUG".padEnd(slugWidth),
+			"TITLE".padEnd(titleWidth),
+			"VERSION".padEnd(versionWidth),
+			"UPDATED".padEnd(dateWidth),
+			"URL"
+		].join("  ");
+		console.log(pc.dim(header));
+		for (const d of dashboards) {
+			const url = `${APP_URL$2}/d/${d.org_slug}/${d.slug}`;
+			const date = new Date(d.updated_at).toLocaleDateString();
+			const row = [
+				d.slug.padEnd(slugWidth),
+				d.title.padEnd(titleWidth),
+				`v${d.version}`.padEnd(versionWidth),
+				date.padEnd(dateWidth),
+				url
+			].join("  ");
+			console.log(row);
+		}
+	} catch (err) {
+		console.error(pc.red(`Failed to list dashboards: ${err instanceof Error ? err.message : err}`));
+		process.exit(1);
+	}
+}
+
+//#endregion
+//#region src/commands/dashboard/remove.ts
+async function confirm(message) {
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	return new Promise((resolve) => {
+		rl.question(`${message} (y/N) `, (answer) => {
+			rl.close();
+			resolve(answer.toLowerCase() === "y");
+		});
+	});
+}
+async function dashboardRemoveCommand(slug, options) {
+	if (!options.force) {
+		if (!await confirm(`Remove dashboard "${slug}"? This cannot be undone.`)) {
+			console.log(pc.dim("Cancelled."));
+			return;
+		}
+	}
+	try {
+		await del(`/api/dashboards/${encodeURIComponent(slug)}`);
+		console.log(pc.green(`Dashboard "${slug}" removed.`));
+	} catch (err) {
+		console.error(pc.red(`Failed to remove dashboard: ${err instanceof Error ? err.message : err}`));
+		process.exit(1);
+	}
+}
+
+//#endregion
+//#region src/commands/dashboard/open.ts
+const APP_URL$1 = process.env.BON_APP_URL || "https://app.bonnard.dev";
+async function dashboardOpenCommand(slug) {
+	try {
+		const result = await get(`/api/dashboards/${encodeURIComponent(slug)}`);
+		const url = `${APP_URL$1}/d/${result.dashboard.org_slug}/${result.dashboard.slug}`;
+		console.log(pc.dim(`Opening ${url}`));
+		await open(url);
+	} catch (err) {
+		console.error(pc.red(`Failed to open dashboard: ${err instanceof Error ? err.message : err}`));
+		process.exit(1);
+	}
+}
+
+//#endregion
+//#region src/commands/dashboard/dev.ts
+const APP_URL = process.env.BON_APP_URL || "https://app.bonnard.dev";
+function loadViewer() {
+	const dir = path.dirname(fileURLToPath(import.meta.url));
+	const viewerPath = path.resolve(dir, "..", "viewer.html");
+	if (!fs.existsSync(viewerPath)) {
+		console.error(pc.red("Viewer not found. Rebuild the CLI with `pnpm build`."));
+		process.exit(1);
+	}
+	return fs.readFileSync(viewerPath, "utf-8");
+}
+async function dashboardDevCommand(file, options) {
+	const filePath = path.resolve(file);
+	if (!fs.existsSync(filePath)) {
+		console.error(pc.red(`File not found: ${file}`));
+		process.exit(1);
+	}
+	const creds = loadCredentials();
+	if (!creds) {
+		console.error(pc.red("Not logged in. Run `bon login` first."));
+		process.exit(1);
+	}
+	const viewerHtml = loadViewer();
+	const sseClients = /* @__PURE__ */ new Set();
+	let debounce = null;
+	fs.watch(filePath, () => {
+		if (debounce) clearTimeout(debounce);
+		debounce = setTimeout(() => {
+			for (const client of sseClients) client.write("data: reload\n\n");
+		}, 50);
+	});
+	const server = http.createServer((req, res) => {
+		const url = req.url || "/";
+		if (url === "/") {
+			res.writeHead(200, { "Content-Type": "text/html" });
+			res.end(viewerHtml);
+			return;
+		}
+		if (url === "/__bon/content") {
+			res.writeHead(200, {
+				"Content-Type": "text/plain",
+				"Cache-Control": "no-cache"
+			});
+			res.end(fs.readFileSync(filePath, "utf-8"));
+			return;
+		}
+		if (url === "/__bon/config") {
+			res.writeHead(200, {
+				"Content-Type": "application/json",
+				"Cache-Control": "no-cache"
+			});
+			res.end(JSON.stringify({
+				token: creds.token,
+				baseUrl: APP_URL
+			}));
+			return;
+		}
+		if (url === "/__bon/events") {
+			res.writeHead(200, {
+				"Content-Type": "text/event-stream",
+				"Cache-Control": "no-cache",
+				Connection: "keep-alive"
+			});
+			sseClients.add(res);
+			req.on("close", () => sseClients.delete(res));
+			return;
+		}
+		res.writeHead(404);
+		res.end();
+	});
+	const port = options.port ? parseInt(options.port, 10) : 0;
+	server.listen(port, () => {
+		const url = `http://localhost:${server.address().port}`;
+		console.log(pc.green(`Dashboard preview running at ${pc.bold(url)}`));
+		console.log(pc.dim(`Watching ${path.basename(filePath)} for changes...\n`));
+		open(url);
+	});
+}
+
 //#endregion
 //#region src/bin/bon.ts
 const { version } = createRequire(import.meta.url)("../../package.json");
 program.name("bon").description("Bonnard semantic layer CLI").version(version);
-program.command("init").description("Create bon.yaml, bonnard/cubes/, bonnard/views/, .bon/, and agent templates (.claude/, .cursor/)").action(initCommand);
+program.command("init").description("Create bon.yaml, bonnard/cubes/, bonnard/views/, .bon/, and agent templates (.claude/, .cursor/)").option("--update", "Update agent templates to match installed CLI version").action(initCommand);
 program.command("login").description("Authenticate with Bonnard via your browser").action(loginCommand);
 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);
@@ -3895,6 +4241,12 @@ const keys = program.command("keys").description("Manage API keys for the Bonnar
 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 dashboard = program.command("dashboard").description("Manage hosted dashboards");
+dashboard.command("dev").description("Preview a markdown dashboard locally with live reload").argument("<file>", "Path to dashboard .md file").option("--port <port>", "Server port (default: random available port)").action(dashboardDevCommand);
+dashboard.command("deploy").description("Deploy an HTML or markdown file as a hosted dashboard").argument("<file>", "Path to HTML or markdown file").option("--slug <slug>", "Dashboard slug (defaults to filename)").option("--title <title>", "Dashboard title (defaults to <title> tag or slug)").action(dashboardDeployCommand);
+dashboard.command("list").description("List deployed dashboards").action(dashboardListCommand);
+dashboard.command("remove").description("Remove a deployed dashboard").argument("<slug>", "Dashboard slug to remove").option("--force", "Skip confirmation prompt").action(dashboardRemoveCommand);
+dashboard.command("open").description("Open a deployed dashboard in the browser").argument("<slug>", "Dashboard slug to open").action(dashboardOpenCommand);
 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.md

@@ -6,7 +6,7 @@
 
 Dashboards let your team track key metrics without leaving the Bonnard app. Define queries once in markdown, deploy them, and every viewer gets live, governed data — no separate BI tool needed. Filters, formatting, and layout are all declared in the same file.
 
-A dashboard is a markdown file with YAML frontmatter, query blocks, and chart components. Write it as a `.md` file, deploy with `bon dashboard deploy`, and view it in the Bonnard web app.
+A dashboard is a markdown file with YAML frontmatter, query blocks, and chart components. Write it as a `.md` file, preview locally with `bon dashboard dev`, and deploy with `bon dashboard deploy`.
 
 ## Format
 
@@ -48,7 +48,6 @@ The YAML frontmatter is required and must include `title`:
 ---
 title: Revenue Dashboard        # Required
 description: Monthly trends     # Optional
-slug: revenue-dashboard         # Optional (derived from title if omitted)
 ---
 ```
 
@@ -56,49 +55,47 @@ slug: revenue-dashboard         # Optional (derived from title if omitted)
 |-------|----------|-------------|
 | `title` | Yes | Dashboard title displayed in the viewer and listings |
 | `description` | No | Short description shown in dashboard listings |
-| `slug` | No | URL-safe identifier. Auto-derived from title if omitted |
+
+## Local Preview
+
+Preview a dashboard locally with live reload before deploying. Requires `bon login`.
+
+```bash
+bon dashboard dev revenue.md
+```
+
+This starts a local server, opens your browser, and auto-reloads when you save changes. Queries run against your deployed semantic layer using your own credentials — governance policies apply.
 
 ## Deployment
 
 Deploy from the command line or via MCP tools. Each deploy auto-versions the dashboard so you can roll back if needed.
 
 ```bash
-# Deploy a single dashboard
+# Deploy a markdown dashboard
 bon dashboard deploy revenue.md
 
-# Deploy all dashboards in a directory
-bon dashboard deploy dashboards/
-
 # List deployed dashboards
 bon dashboard list
 
+# Open in browser
+bon dashboard open revenue
+
 # Remove a dashboard
-bon dashboard remove revenue-dashboard
+bon dashboard remove revenue
 ```
 
+Options:
+- `--slug <slug>` — custom URL slug (default: derived from filename)
+- `--title <title>` — dashboard title (default: from frontmatter)
+
 Via MCP tools, agents can use `deploy_dashboard` with the markdown content as a string.
 
 ## Versioning
 
-Every deployment auto-increments the version number and saves a snapshot. You can view version history and restore previous versions:
-
-```bash
-# Via MCP tools:
-# get_dashboard with version parameter to fetch a specific version
-# deploy_dashboard with slug + restore_version to roll back
-```
+Every deployment auto-increments the version number and saves a snapshot. You can view version history and restore previous versions via MCP tools (`get_dashboard` with version parameter, `deploy_dashboard` with `restore_version`).
 
 Restoring a version creates a new version (e.g. restoring v2 from v5 creates v6 with v2's content). Version history is never deleted — only `remove_dashboard` deletes all history.
 
-## Sharing
-
-Dashboard viewers include a **Share** menu in the header with:
-
-- **Copy link** — copies the current URL including any active filter state
-- **Print to PDF** — opens the browser print dialog for PDF export
-
-Filter state (DateRange presets, Dropdown selections) is encoded in URL query params, so shared links preserve the exact filtered view the sender was looking at.
-
 ## Governance
 
 Dashboard queries respect the same governance policies as all other queries. When a user views a dashboard: