Update template and instructions for creating/updating reports

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+### Updated
+
+Document new `key` value for `tiles` available when creating and updating reports via `dx studio reports`.
+
 ## 0.5.3 - 2026-06-26
 
 ### Updated

skills/dx-cli/references/report-creation.md

@@ -87,7 +87,8 @@ viewer_emails: []
 edit_access_type: read_only
 editor_emails: []
 tiles:
-  - title: "Table"
+  - key: "tile1"
+    title: "Table"
     sql: |-
       SELECT 1 AS value
     chart_type: table
@@ -115,6 +116,8 @@ Provide `editor_emails` only when `edit_access_type` is `specific_users`.
 
 ### Tiles
 
+Each tile `key` must be unique for the report.
+
 Supported tile `chart_type` values are `line`, `pie`, `stacked_bar`, `scatter`, and `table`.
 
 `line`, `stacked_bar`, and `scatter` chart configs require `xAxis` and `yAxes`; `pie` chart configs require `labelColumn` and `valueColumn`; `table` chart configs can be `{}`.

src/commands/studio/report-blank-template.yaml

@@ -23,7 +23,8 @@ editor_emails: []
 
 # Supported chart_type values: line, pie, stacked_bar, scatter, table
 tiles:
-  - title: ""
+  - key: "tile1"
+    title: ""
     sql: |-
       SELECT 1 AS value
     chart_type: table

src/commands/studio/reports.test.ts

@@ -83,6 +83,7 @@ describe("studio reports command", () => {
     tiles: [
       {
         id: "tile_line",
+        key: "tile1",
         title: "Weekly deploys",
         sql: "SELECT week_start, deploys FROM deployments",
         chart_type: "line",
@@ -93,6 +94,7 @@ describe("studio reports command", () => {
       },
       {
         id: "tile_table",
+        key: "tile2",
         title: "Recent deploys",
         sql: "SELECT * FROM deployments LIMIT 10",
         chart_type: "table",

src/commands/studio/reports.ts

@@ -309,6 +309,7 @@ export function reportsCommand() {
 
 type StudioReportTile = {
   id: string;
+  key: string;
   title: string | null;
   sql: string | null;
   chart_type: string;
@@ -336,6 +337,7 @@ type StudioReport = {
 };
 
 type StudioReportTilePayload = {
+  key: string;
   title: string | null;
   sql: string | null;
   chart_type: string;
@@ -624,6 +626,7 @@ function studioReportToYaml(report: StudioReport): string {
     edit_access_type: report.edit_access_type,
     editor_emails: [],
     tiles: report.tiles.map((tile) => ({
+      key: tile.key,
       title: tile.title,
       sql: tile.sql,
       chart_type: tile.chart_type,