@metabase/cli 0.1.6 → 0.1.8

package/dist/{uuid-CMKnS8-z.mjs → uuid-BWCaWG4O.mjs}

@@ -1,8 +1,8 @@
 import { ConfigError } from "./command-augment-BH9qgQ5u.mjs";
-import { outputFlags } from "./error-C9S6PN3-.mjs";
-import { defineMetabaseCommand, parseInteger } from "./runtime-Dmv5VtUK.mjs";
+import { outputFlags } from "./error-CTVL5CdB.mjs";
+import { defineMetabaseCommand, parseInteger } from "./runtime-B40L_bj8.mjs";
 import "./capabilities-7e9MgquN.mjs";
-import { writeJson, writeText } from "./render-CfznwleY.mjs";
+import { writeJson, writeText } from "./render-0_GsapXa.mjs";
 import { z } from "zod";
 import { randomUUID } from "node:crypto";
 

package/dist/{validate-query-Cw6WE5Y8.mjs → validate-query-CYvOP8Ld.mjs}

@@ -1,5 +1,5 @@
 import { ConfigError } from "./command-augment-BH9qgQ5u.mjs";
-import { writeJson } from "./render-CfznwleY.mjs";
+import { writeJson } from "./render-0_GsapXa.mjs";
 import { assertNotLegacyEnvelopeWrappingMbql5, isMbql5Query, validateQuery } from "./validate-dPEOnOf8.mjs";
 
 //#region src/commands/validate-query.ts

package/dist/{values-BfSTAbzc.mjs → values-D_wycrcr.mjs}

@@ -1,10 +1,10 @@
 import "./command-augment-BH9qgQ5u.mjs";
-import { connectionFlags, outputFlags, profileFlag } from "./error-C9S6PN3-.mjs";
-import { defineMetabaseCommand } from "./runtime-Dmv5VtUK.mjs";
+import { connectionFlags, outputFlags, profileFlag } from "./error-CTVL5CdB.mjs";
+import { defineMetabaseCommand } from "./runtime-B40L_bj8.mjs";
 import "./capabilities-7e9MgquN.mjs";
-import { renderItem } from "./render-CfznwleY.mjs";
-import { FieldValues, fieldValuesView } from "./field-yomXlkvl.mjs";
-import { parseId } from "./parse-id-lk_K-CEF.mjs";
+import { formatScalar, renderSummary } from "./render-0_GsapXa.mjs";
+import { FieldValues, fieldValuesView } from "./field-E0IBy4Uw.mjs";
+import { parseId } from "./parse-id-D1LTTt9L.mjs";
 
 //#region src/commands/field/values.ts
 var values_default = defineMetabaseCommand({
@@ -29,7 +29,15 @@ var values_default = defineMetabaseCommand({
 		const id = parseId(args.id);
 		const client = await getClient();
 		const values = await client.requestParsed(FieldValues, `/api/field/${id}/values`);
-		renderItem(values, fieldValuesView, ctx);
+		const fieldId = values.field_id ?? id;
+		const count = values.values.length;
+		renderSummary(values, fieldValuesView, () => {
+			if (count === 0) return `Field ${fieldId} has no cached values.`;
+			const more = values.has_more_values === true ? " (more available; rescan for the full set)" : "";
+			const header = `Field ${fieldId} has ${count} cached value${count === 1 ? "" : "s"}${more}:`;
+			const lines = values.values.map((row) => `  ${formatScalar(row[0])}`);
+			return [header, ...lines].join("\n");
+		}, ctx);
 	}
 });
 

package/dist/{verify-D5YtTqqp.mjs → verify-D7hb6VMy.mjs}

@@ -1,5 +1,5 @@
 import { MetabaseError, NetworkError, TimeoutError, errorMessage } from "./command-augment-BH9qgQ5u.mjs";
-import { HttpError, createClient, probeServer } from "./runtime-Dmv5VtUK.mjs";
+import { HttpError, createClient, probeServer } from "./runtime-B40L_bj8.mjs";
 import { z } from "zod";
 
 //#region src/domain/user.ts

package/dist/{wait-Bv3Tsnv4.mjs → wait-B5IpNFCG.mjs}

@@ -1,11 +1,11 @@
 import "./command-augment-BH9qgQ5u.mjs";
-import { connectionFlags, outputFlags, profileFlag } from "./error-C9S6PN3-.mjs";
-import { defineMetabaseCommand } from "./runtime-Dmv5VtUK.mjs";
+import { connectionFlags, outputFlags, profileFlag } from "./error-CTVL5CdB.mjs";
+import { defineMetabaseCommand } from "./runtime-B40L_bj8.mjs";
 import "./capabilities-7e9MgquN.mjs";
-import { renderItem } from "./render-CfznwleY.mjs";
-import { parseId } from "./parse-id-lk_K-CEF.mjs";
-import { SyncTaskOrIdle, pollSyncTask, syncTaskIdleView, syncTaskView, throwIfFailedTask } from "./poll-task-Cooi0lQV.mjs";
-import { DEFAULT_INTERVAL_MS, DEFAULT_TIMEOUT_MS } from "./poll-DHKDpCiq.mjs";
+import { renderSummary } from "./render-0_GsapXa.mjs";
+import { parseId } from "./parse-id-D1LTTt9L.mjs";
+import { SyncTaskOrIdle, formatSyncTask, pollSyncTask, syncTaskIdleView, syncTaskView, throwIfFailedTask } from "./poll-task-D8mG49IN.mjs";
+import { DEFAULT_INTERVAL_MS, DEFAULT_TIMEOUT_MS } from "./poll-DxpnK1wW.mjs";
 
 //#region src/commands/git-sync/wait.ts
 const WaitResult = SyncTaskOrIdle;
@@ -45,10 +45,10 @@ var wait_default = defineMetabaseCommand({
 		});
 		if (final === null) {
 			const idle = { status: "idle" };
-			renderItem(idle, syncTaskIdleView, ctx);
+			renderSummary(idle, syncTaskIdleView, "No git-sync task is running.", ctx);
 			return;
 		}
-		renderItem(final, syncTaskView, ctx);
+		renderSummary(final, syncTaskView, formatSyncTask(final), ctx);
 		throwIfFailedTask(final, "task");
 	}
 });

package/dist/{wait-8yV9_WIo.mjs → wait-DHjXk3jD.mjs}

@@ -1,5 +1,5 @@
-import { pollUntil } from "./poll-DHKDpCiq.mjs";
-import { Workspace } from "./workspace-BBXJczJK.mjs";
+import { pollUntil } from "./poll-DxpnK1wW.mjs";
+import { Workspace } from "./workspace-D8HtUN0y.mjs";
 
 //#region src/commands/workspace/database/wait.ts
 async function waitForDatabaseProvisioned(client, workspaceId, databaseId, schedule) {

package/dist/{wait-flags-Dzq9BGQY.mjs → wait-flags-CNIeSq0_.mjs}

@@ -1,5 +1,5 @@
-import { parseId } from "./parse-id-lk_K-CEF.mjs";
-import { DEFAULT_INTERVAL_MS, DEFAULT_TIMEOUT_MS } from "./poll-DHKDpCiq.mjs";
+import { parseId } from "./parse-id-D1LTTt9L.mjs";
+import { DEFAULT_INTERVAL_MS, DEFAULT_TIMEOUT_MS } from "./poll-DxpnK1wW.mjs";
 
 //#region src/commands/wait-flags.ts
 const waitScheduleFlags = {

package/dist/workspace-Bt8n3ojY.mjs

@@ -0,0 +1,25 @@
+import { defineCommand } from "citty";
+
+//#region src/commands/workspace/index.ts
+var workspace_default = defineCommand({
+	meta: {
+		name: "workspace",
+		description: "Manage Metabase workspaces (workspace-manager)"
+	},
+	subCommands: {
+		list: () => import("./list-evetBTcH.mjs").then((mod) => mod.default),
+		create: () => import("./create-C8gA-XP2.mjs").then((mod) => mod.default),
+		database: () => import("./database-BPT6BrmF.mjs").then((mod) => mod.default),
+		start: () => import("./start-B7ByBicB.mjs").then((mod) => mod.default),
+		stop: () => import("./stop-Cvexagxh.mjs").then((mod) => mod.default),
+		delete: () => import("./delete-CiV6f69N.mjs").then((mod) => mod.default),
+		logs: () => import("./logs-jx5b_YDk.mjs").then((mod) => mod.default),
+		url: () => import("./url-LMJZRDv4.mjs").then((mod) => mod.default),
+		credentials: () => import("./credentials-CFA9iGZG.mjs").then((mod) => mod.default),
+		ps: () => import("./ps-CpyHEvv7.mjs").then((mod) => mod.default),
+		license: () => import("./license-j0tDQLKI.mjs").then((mod) => mod.default)
+	}
+});
+
+//#endregion
+export { workspace_default as default };

package/dist/{workspace-credentials-BXpABsNZ.mjs → workspace-credentials-8CBMQJFz.mjs}

@@ -1,5 +1,5 @@
 import { ConfigError } from "./command-augment-BH9qgQ5u.mjs";
-import { parseYaml, stringifyYaml } from "./yaml-YTQiYJ9s.mjs";
+import { parseYaml, stringifyYaml } from "./yaml-Gv6wRFMF.mjs";
 import { z } from "zod";
 import { randomBytes } from "node:crypto";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metabase/cli",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Metabase CLI",
   "license": "AGPL-3.0",
   "repository": {

package/skill-data/visualization/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: visualization
+description: Pick the right `display` (chart type) for a card's data and author its `visualization_settings` via the `mb` CLI. Covers which chart fits which data shape, the required and optional settings per chart type, the rule that settings reference OUTPUT columns by name, minimum-viable settings per chart family, and the `column_settings` JSON-string-key footgun. The full per-chart key catalog lives in references. Load whenever choosing or shaping how a card renders — "what chart should I use for this", "create a bar chart", "make this a line chart", "turn this into a pie", "map this by state", "format this column as currency", "set the pie dimension and metric", "the card renders as a table instead of a chart", "add conditional formatting", or any `display` / `visualization_settings` work.
+allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
+---
+
+# Visualization: pick the chart, then set it
+
+A card has two presentation fields alongside its `dataset_query`:
+
+- **`display`** — the chart type (`bar`, `line`, `pie`, `scalar`, `map`, `table`, …). One closed set; pick from the enum below.
+- **`visualization_settings`** — a map whose keys are **namespaced by `display`** (`graph.*` for bar/line/area/combo, `pie.*` for pie, `table.*` for table, …). The server stores almost anything and **silently ignores keys that don't apply** to the chosen `display`.
+
+Nothing validates `visualization_settings` — there is no pre-flight to fail past. A `display` typo or a misnamed key is accepted by the API; the card just renders as a default table or drops the setting. So **the feedback loop is read-back, not pre-flight**: after `card create`/`update`, confirm with `mb card get <id> --full --json` (or open the card) that it rendered as intended.
+
+General flag conventions and body-input precedence live in the `core` skill (`mb skills get core`); the `dataset_query` itself is the `mbql` skill's job (`mb skills get mbql`). This skill is only about how the result is displayed.
+
+Two steps: **(1) pick the `display` that fits the data**, then **(2) bind the data columns and set options**.
+
+## Step 1 — pick the `display` for your data
+
+Decide which relationship in the data matters most, then pick the chart. The shape each one needs is in the per-display table further down.
+
+- **Single headline number** → `scalar` (one KPI). `smartscalar` when the story is the change vs the previous period. `gauge`/`progress` for one value against a target/goal.
+- **Compare a measure across categories** → `bar` (vertical). Use `row` (horizontal bar) when labels are long or there are many categories. Sort by value unless the dimension has a natural order.
+- **Change over time / trend** → `line` for a continuous series; `bar`/`area` for a few discrete periods. Two measures on unlike scales → `combo` (line + bar, dual-axis) — only when the metrics are genuinely related.
+- **Part-to-whole, one snapshot** → `pie`, but only for a meaningful whole with **≤5 slices**; beyond that use a sorted `bar`/`row`. Composition over time → stacked `area`/`bar`.
+- **Distribution / spread / outliers** → `boxplot` (especially comparing several groups).
+- **Correlation between two measures** → `scatter` (a third measure → bubble size).
+- **Sequential additive contributions** (start → +/− steps → total) → `waterfall`.
+- **Stage drop-off in an ordered, cumulative funnel** → `funnel`.
+- **Flow volume between nodes** (source → target + weight) → `sankey`.
+- **Geographic** → `map`: region/choropleth (a region dimension + a measure), pin (lat + long), or grid/heat (coordinates + measure).
+- **Precise values, many columns, mixed types, or no chart fits** → `table`; `pivot` for a cross-tab of two dimensions; `object` for a single record's detail.
+
+Closed `display` enum (card-level, non-hidden): `table`, `bar`, `line`, `area`, `row`, `pie`, `scalar`, `smartscalar`, `combo`, `pivot`, `funnel`, `map`, `scatter`, `waterfall`, `progress`, `gauge`, `object`, `sankey`, `boxplot`. (`scalar` **is** the "Number" viz — `display: number` is a legacy serialization alias, not a registered visualization; use `scalar`. `list` exists but is hidden — don't pick it. `heading`/`text`/`link`/`iframe`/`action` are dashcard virtuals, not standalone cards — see references.) An unknown `display` is accepted by the API but renders nothing — typos like `bargraph`/`linechart` are the most common "why is my chart blank" cause.
+
+## Step 2 — bind data columns and set options
+
+### Which chart for which data, and what to set
+
+**Use for** is the data shape each chart suits. **Required** is the minimum to set for it to render as a chart — omit it and the card falls back to a "which columns?" prompt. Everything else is optional (full keys in references). **Empty `"visualization_settings": {}` is valid**: for a simple aggregate the binding is auto-picked, so set keys only to pin or override.
+
+| `display`                   | Use for                                                   | Required                                                   |
+| --------------------------- | --------------------------------------------------------- | ---------------------------------------------------------- |
+| `scalar`                    | 1 row, 1 column                                           | — (`scalar.field` only if >1 column)                       |
+| `smartscalar`               | one value grouped by a single **time** field              | — (needs a time breakout; `scalar.field` auto)             |
+| `gauge`                     | 1 row, 1 numeric column                                   | — (`gauge.segments` auto)                                  |
+| `progress`                  | 1 row, ≥1 numeric column                                  | — (`progress.goal` defaults to 0)                          |
+| `bar` `line` `area` `combo` | >1 row, ≥2 cols, ≥1 dimension + ≥1 measure                | `graph.dimensions`, `graph.metrics`                        |
+| `row`                       | as bar; prefer for long/many category labels              | `graph.dimensions`, `graph.metrics`                        |
+| `scatter`                   | two numeric measures (correlation)                        | `graph.dimensions`, `graph.metrics` (`scatter.bubble` opt) |
+| `waterfall`                 | exactly 1 dimension + ≥1 measure; sequential              | `graph.dimensions` (1), `graph.metrics` (1)                |
+| `boxplot`                   | ≥3 cols, ≥2 dimensions, ≥1 measure                        | `graph.dimensions`, `graph.metrics`                        |
+| `pie`                       | ≥2 rows, ≥2 cols, ≥1 dimension + ≥1 measure; ≤~5 slices   | `pie.dimension`, `pie.metric`                              |
+| `funnel`                    | 2 columns (stage + value); ordered stages                 | `funnel.dimension`, `funnel.metric`                        |
+| `map` (region)              | a string/region dimension + a measure                     | `map.region`, `map.dimension`, `map.metric`                |
+| `map` (pin/grid)            | latitude + longitude columns                              | `map.latitude_column`, `map.longitude_column`              |
+| `sankey`                    | ≥3 cols, ≥2 non-date dimensions, ≥1 measure; acyclic flow | `sankey.source`, `sankey.target`, `sankey.value`           |
+| `pivot`                     | ≥2 cols, all aggregated/breakout                          | — (`pivot_table.column_split` auto)                        |
+| `table` `object`            | anything (table is the universal fallback)                | — (always renders)                                         |
+
+### The rule that trips everyone: settings name **output columns**, by name
+
+`graph.dimensions`, `graph.metrics`, `pie.dimension`, `pie.metric`, `scalar.field`, `funnel.metric`, `map.latitude_column`, `sankey.source`, … all take **output column-name strings** — the names the query _produces_, not field ids. A `count` aggregation outputs the column `count`; a breakout on a field outputs that field's name; a named aggregation outputs its `name`. These strings are **identical in the API form and the portable (git-sync) form** — no numeric-vs-name footgun here.
+
+So the names you put in `visualization_settings` come from the query's output, not from `mb field`/`mb table`. If you set `name` on an aggregation (see the `mbql` skill), use that same string here.
+
+## Minimum-viable settings per chart family (API form)
+
+Each block is the `visualization_settings` to pair with the given `display`. The `dataset_query` is elided — build it per the `mbql` skill. Output columns (`CATEGORY`, `count`, …) are whatever the query's breakout/aggregation produce.
+
+**Bar / line / area / combo** — one dimension on the x-axis, one or more metrics (the four share an identical key set; switch `display` freely):
+
+```json
+"display": "bar",
+"visualization_settings": { "graph.dimensions": ["CATEGORY"], "graph.metrics": ["count"] }
+```
+
+(Multiple metrics: `"graph.metrics": ["count","sum"]`. Stacked: add `"stackable.stack_type": "stacked"` — or `"normalized"` for 100%. A second dimension in `graph.dimensions` becomes a series breakout.)
+
+**Row** — same keys; axes are visually swapped (horizontal bars).
+
+**Pie** — one dimension, one metric:
+
+```json
+"display": "pie",
+"visualization_settings": { "pie.dimension": "CATEGORY", "pie.metric": "count" }
+```
+
+**Scalar** (single big number) — the field to surface (only needed if >1 column):
+
+```json
+"display": "scalar",
+"visualization_settings": { "scalar.field": "count" }
+```
+
+**Map (region/choropleth)** — region map + dimension + metric:
+
+```json
+"display": "map",
+"visualization_settings": { "map.type": "region", "map.region": "us_states", "map.dimension": "STATE", "map.metric": "count" }
+```
+
+**Table** — column order/visibility plus per-column formatting:
+
+```json
+"display": "table",
+"visualization_settings": {
+  "table.columns": [ { "name": "CATEGORY", "enabled": true }, { "name": "count", "enabled": true } ],
+  "column_settings": { "[\"name\",\"count\"]": { "column_title": "Orders" } }
+}
+```
+
+## `column_settings`: the JSON-string-key footgun
+
+`column_settings` is a map **whose keys are themselves JSON-encoded arrays** — so inside a JSON body the inner quotes must be escaped. The key is a _string_, never an object.
+
+- **Prefer the name form:** `["name", "<output column name>"]` → in a JSON body, `"[\"name\",\"count\"]"`. This is the canonical key Metabase writes, and it's **identical in API and portable form**. Use it unless you have a reason not to.
+- **Ref form (legacy order!):** `["ref", ["field", <id>, <opts>]]`. The inner field ref uses the **legacy MBQL-4 order** `["field", id, options]` (id **second**) — _not_ the MBQL-5 order you use in `dataset_query`. In the API form `<id>` is the numeric field id. Because the order differs, this form is easy to get wrong — reach for the name form instead.
+
+```json
+"column_settings": {
+  "[\"name\",\"TOTAL\"]": { "number_style": "currency", "currency": "USD", "decimals": 2 },
+  "[\"name\",\"CREATED_AT\"]": { "date_style": "MMMM D, YYYY" }
+}
+```
+
+The exhaustive per-column key list (number/date formatting, `view_as`, alignment, mini bars, click behavior) is in the references file.
+
+## Escape hatch: pull a real card instead of authoring from scratch
+
+For anything beyond a single dimension + metric — combo charts, conditional formatting, pivot splits, click behavior, series colors — the cheapest **correct** path is to build it once in the Metabase UI and copy the result:
+
+```bash
+mb card get <id> --full --json | jq '.visualization_settings'
+```
+
+Paste that block into your `card create`/`update` body. The server produced it, so it's valid for that `display`. This beats guessing keys from memory, and it's token-cheap.
+
+## Full per-visualization key catalog
+
+The body above covers the high-frequency 90%. The complete per-chart key tables — every key with its values and defaults, the data shape each chart suits, the full `column_settings` and `series_settings` vocabularies, conditional formatting, pivot splits, virtual cards (heading/text/link/iframe), and click behavior — live in the references file. Load on demand, not by default:
+
+```bash
+mb skills get visualization --full     # appends references/settings.md to this body
+mb skills path visualization           # → the skill dir; then Read references/settings.md
+```
+
+## Don't
+
+- Don't invent `display` values (`bargraph`, `linechart`, `histogram`) or use `number`/`list` — use the closed non-hidden enum; the API accepts a typo and renders nothing.
+- Don't put numeric field ids in `graph.dimensions`/`pie.metric`/`scalar.field`/`map.latitude_column` etc. — they take **output column-name strings**.
+- Don't reach for a `pie` with >5 slices, a `combo` of unrelated metrics, or a `pie`/`scalar` to show a trend — see Step 1.
+- Don't write a `column_settings` key as an object — it's a JSON **string** (`"[\"name\",\"COL\"]"`), inner quotes escaped.
+- Don't use the MBQL-5 field-ref order inside a `column_settings` `["ref", …]` key — that key uses the **legacy** `["field", id, opts]` order. Prefer the `["name", …]` form.
+- Don't expect a pre-flight to catch viz mistakes — there is none. Verify by reading the card back.
+- Don't hand-author complex charts when you can pull a working `visualization_settings` from a UI-built card.