@bonnard/cli 0.2.14 → 0.2.15

package/dist/bin/bon.mjs

@@ -1908,6 +1908,30 @@ async function annotateCommand(id, options = {}) {
 	}
 }
 
+//#endregion
+//#region src/commands/pull.ts
+async function pullCommand() {
+	const paths = getProjectPaths(process.cwd());
+	console.log(pc.dim("Downloading deployed models..."));
+	try {
+		const files = (await get("/api/deploy/files")).files;
+		const fileKeys = Object.keys(files);
+		if (fileKeys.length === 0) {
+			console.log(pc.yellow("No deployed files found. Have you run `bon deploy` yet?"));
+			return;
+		}
+		for (const [relativePath, content] of Object.entries(files)) {
+			const fullPath = path.join(paths.root, relativePath);
+			fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+			fs.writeFileSync(fullPath, content, "utf-8");
+		}
+		console.log(pc.green(`Pulled ${fileKeys.length} file(s) to bonnard/`));
+	} catch (err) {
+		console.log(pc.red(`Pull failed: ${err instanceof Error ? err.message : err}`));
+		process.exit(1);
+	}
+}
+
 //#endregion
 //#region src/commands/diff.ts
 async function diffCommand(id, options = {}) {
@@ -3860,6 +3884,7 @@ datasource.command("list").description("List data sources (shows both local and
 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);
 program.command("deploy").description("Deploy cubes and views to Bonnard. Requires login, validates, syncs datasources").option("--ci", "Non-interactive mode").requiredOption("-m, --message <text>", "Deploy message describing your changes").action(deployCommand);
+program.command("pull").description("Download deployed cubes and views from Bonnard").action(pullCommand);
 program.command("deployments").description("List deployment history").option("--all", "Show all deployments (default: last 10)").option("--format <format>", "Output format: table or json", "table").action(deploymentsCommand);
 program.command("diff").description("Show changes in a deployment").argument("<id>", "Deployment ID").option("--format <format>", "Output format: table or json", "table").option("--breaking", "Show only breaking changes").action(diffCommand);
 program.command("annotate").description("Annotate deployment changes with reasoning").argument("<id>", "Deployment ID").option("--data <json>", "Annotations JSON").action(annotateCommand);

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

@@ -172,6 +172,25 @@ Wrap components in a `<Grid>` tag to arrange them in columns:
 |------|------|---------|-------------|
 | `cols` | string | `"2"` | Number of columns in the grid |
 
+### Layout Best Practices
+
+**Use `##` for sections, not `#`.** The `#` heading renders very large and wastes vertical space. Use `##` for section titles and `###` for subsections. Reserve `#` for the dashboard title only (which is set in frontmatter, not in the body).
+
+**Group related charts side by side.** Wrap pairs of charts in `<Grid cols="2">` to avoid long vertical scrolling:
+
+```markdown
+<Grid cols="2">
+<BarChart data={by_channel} x="orders.channel" y="orders.total_revenue" title="By Channel" />
+<BarChart data={by_city} x="orders.city" y="orders.total_revenue" title="By City" horizontal />
+</Grid>
+```
+
+**Start each section with KPIs.** Place `<BigValue>` cards at the top of a section for at-a-glance metrics, then follow with charts for detail.
+
+**Only Grid together components of similar height.** Don't mix a `<BigValue>` with a chart in the same `<Grid>` row — the grid stretches both cells to the tallest item, leaving the BigValue card with a large empty area. Instead, place KPIs in their own row (consecutive BigValues auto-group) and pair charts with other charts of similar size.
+
+**Keep it compact.** A good dashboard fits key information in 2-3 screens of scrolling. Use Grids, concise titles, and avoid unnecessary headings between every chart.
+
 ## Formatting
 
 Values are auto-formatted by default — numbers get locale grouping (1,234.56), dates display as "13 Jan 2025", and nulls show as "—". Override with named presets for common currencies and percentages, or use raw Excel format codes for full control.

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

@@ -252,16 +252,89 @@ limit: 10
 
 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.
 
+## Compact Multi-Section Dashboard
+
+A dashboard with multiple sections, side-by-side charts, and compact layout. Uses `##` headings (not `#`), `<Grid>` for horizontal grouping, and keeps all queries near the components that use them.
+
+```markdown
+---
+title: Operations Overview
+description: KPIs, trends, and breakdowns across channels and cities
+---
+
+<DateRange name="period" default="last-30-days" label="Period" />
+
+` ``query channels
+dimensions: [orders.channel]
+` ``
+
+<Dropdown name="channel" dimension="orders.channel" data={channels} queries="kpis,trend,by_city" label="Channel" />
+
+## Key Metrics
+
+` ``query kpis
+measures: [orders.total_revenue, orders.count, orders.avg_order_value]
+` ``
+
+<BigValue data={kpis} value="orders.total_revenue" title="Revenue" fmt="eur" />
+<BigValue data={kpis} value="orders.count" title="Orders" fmt="num0" />
+<BigValue data={kpis} value="orders.avg_order_value" title="Avg Order" fmt="eur2" />
+
+## Trends & Breakdown
+
+` ``query trend
+measures: [orders.total_revenue]
+timeDimension:
+  dimension: orders.created_at
+  granularity: week
+` ``
+
+` ``query by_channel
+measures: [orders.total_revenue]
+dimensions: [orders.channel]
+orderBy:
+  orders.total_revenue: desc
+` ``
+
+<Grid cols="2">
+<LineChart data={trend} x="orders.created_at" y="orders.total_revenue" title="Weekly Revenue" yFmt="eur" />
+<BarChart data={by_channel} x="orders.channel" y="orders.total_revenue" title="By Channel" yFmt="eur" />
+</Grid>
+
+## Top Cities
+
+` ``query by_city
+measures: [orders.total_revenue, orders.count]
+dimensions: [orders.city]
+orderBy:
+  orders.total_revenue: desc
+limit: 10
+` ``
+
+<Grid cols="2">
+<BarChart data={by_city} x="orders.city" y="orders.total_revenue" title="Revenue by City" horizontal yFmt="eur" />
+<DataTable data={by_city} fmt="orders.total_revenue:eur,orders.count:num0" />
+</Grid>
+```
+
+Key patterns:
+- **`##` headings** for sections — compact, no oversized H1s
+- **Consecutive `<BigValue>`** auto-groups into a row (no Grid needed)
+- **`<Grid cols="2">`** pairs a chart with a table or two charts side by side
+- **Queries defined before their Grid** — keeps the layout clean and components grouped
+
 ## Tips
 
-- **Start with KPIs**: Use `BigValue` in a `Grid` at the top for key metrics
+- **Start with KPIs**: Use `BigValue` at the top for key metrics — consecutive BigValues auto-group into a row
 - **One query per chart**: Each component gets its own query — keep them focused
+- **Use `##` headings**: Reserve `#` for the dashboard title (in frontmatter). Use `##` for sections
 - **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="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
+- **Side-by-side charts**: Wrap pairs in `<Grid cols="2">` to reduce vertical scrolling
 
 ## See Also
 

package/package.json

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