@bonnard/cli 0.2.16 → 0.3.1

package/README.md

@@ -174,6 +174,13 @@ Handles automatic datasource synchronisation and skips interactive prompts. Fits
 | `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 |

package/dist/bin/bon.mjs

@@ -557,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}`);
-			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
+		});
+	}
+}
+/**
+* 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}`);
+			results.push({
+				action: "appended",
+				path: relativePath
+			});
+		}
+	} else {
+		fs.writeFileSync(targetPath, content);
+		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
+		});
 	}
 }
 /**
@@ -603,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");
@@ -614,35 +698,64 @@ function createAgentTemplates(cwd, env) {
 	fs.mkdirSync(path.join(claudeSkillsDir, "bonnard-metabase-migrate"), { recursive: true });
 	fs.mkdirSync(path.join(claudeSkillsDir, "bonnard-design-guide"), { recursive: true });
 	fs.mkdirSync(path.join(claudeSkillsDir, "bonnard-build-dashboard"), { 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);
-	writeTemplateFile(loadTemplate("claude/skills/bonnard-build-dashboard/SKILL.md"), path.join(claudeSkillsDir, "bonnard-build-dashboard", "SKILL.md"), createdFiles);
-	mergeSettingsJson(loadJsonTemplate("claude/settings.json"), path.join(cwd, ".claude", "settings.json"), createdFiles);
+	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(loadTemplate("cursor/rules/bonnard-build-dashboard.mdc"), path.join(cursorRulesDir, "bonnard-build-dashboard.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 });
 	fs.mkdirSync(path.join(codexSkillsDir, "bonnard-build-dashboard"), { 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);
-	writeTemplateFile(loadTemplate("claude/skills/bonnard-build-dashboard/SKILL.md"), path.join(codexSkillsDir, "bonnard-build-dashboard", "SKILL.md"), createdFiles);
-	return createdFiles;
-}
-async function initCommand() {
+	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(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);
@@ -665,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();
@@ -677,12 +790,12 @@ async function initCommand() {
 
 //#endregion
 //#region src/commands/login.ts
-const APP_URL$3 = 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$3}/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);
@@ -3879,15 +3992,24 @@ async function keysRevokeCommand(nameOrPrefix) {
 
 //#endregion
 //#region src/commands/dashboard/deploy.ts
-const APP_URL$2 = process.env.BON_APP_URL || "https://app.bonnard.dev";
+const APP_URL$3 = process.env.BON_APP_URL || "https://app.bonnard.dev";
 /**
 * Extract <title> content from HTML string
 */
-function extractTitle(html) {
+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) {
@@ -3904,20 +4026,23 @@ async function dashboardDeployCommand(file, options) {
 		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 || extractTitle(content) || slug;
-	console.log(pc.dim(`Deploying dashboard "${slug}"...`));
+	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
+			content,
+			format
 		})).dashboard;
-		const url = `${APP_URL$2}/d/${dashboard.org_slug}/${dashboard.slug}`;
+		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) {
@@ -3928,7 +4053,7 @@ async function dashboardDeployCommand(file, options) {
 
 //#endregion
 //#region src/commands/dashboard/list.ts
-const APP_URL$1 = process.env.BON_APP_URL || "https://app.bonnard.dev";
+const APP_URL$2 = process.env.BON_APP_URL || "https://app.bonnard.dev";
 async function dashboardListCommand() {
 	try {
 		const dashboards = (await get("/api/dashboards")).dashboards;
@@ -3949,7 +4074,7 @@ async function dashboardListCommand() {
 		].join("  ");
 		console.log(pc.dim(header));
 		for (const d of dashboards) {
-			const url = `${APP_URL$1}/d/${d.org_slug}/${d.slug}`;
+			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),
@@ -3998,11 +4123,11 @@ async function dashboardRemoveCommand(slug, options) {
 
 //#endregion
 //#region src/commands/dashboard/open.ts
-const APP_URL = process.env.BON_APP_URL || "https://app.bonnard.dev";
+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}/d/${result.dashboard.org_slug}/${result.dashboard.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) {
@@ -4011,11 +4136,91 @@ async function dashboardOpenCommand(slug) {
 	}
 }
 
+//#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);
@@ -4036,8 +4241,9 @@ 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 HTML dashboards");
-dashboard.command("deploy").description("Deploy an HTML file as a hosted dashboard").argument("<file>", "Path to HTML file").option("--slug <slug>", "Dashboard slug (defaults to filename)").option("--title <title>", "Dashboard title (defaults to <title> tag or slug)").action(dashboardDeployCommand);
+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);