@metabase/cli 0.1.9 → 0.1.10

package/skill-data/document/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: document
+description: Author and edit Metabase documents via `mb` — the TipTap (ProseMirror) JSON body shape, the node-type inventory (paragraphs, headings, lists, plus the Metabase-custom `cardEmbed` / `smartLink` / `flexContainer` / `resizeNode`), the per-node-type `_id` requirement, embedding existing or brand-new cards, and the list/get/create/update/archive verbs. Load when the user touches documents — "create a document", "add a card to a document", "edit a document", "list documents", or anything `mb document …`.
+allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
+---
+
+# Documents
+
+A **document** is a Metabase rich-text page (a "report" / notebook) that mixes prose with embedded saved questions and links to other Metabase entities. The body is a **TipTap** JSON tree (TipTap is the editor; the wire format is ProseMirror JSON, and the server stores it under `content_type: "application/json+vnd.prose-mirror"`).
+
+This skill covers authoring the body and driving the verbs. General flag conventions, body-input precedence, and output flags live in the `core` skill (`mb skills get core`).
+
+## Command surface
+
+```bash
+mb document list --profile <name> --json                 # non-archived docs visible to you
+mb document get <id> --profile <name> --full --json      # one doc incl. its TipTap body
+mb document create --file doc.json --profile <name> --json
+mb document update <id> --file patch.json --profile <name> --json   # PATCH semantics
+mb document archive <id> --profile <name> --json         # soft-delete (PUT archived:true)
+```
+
+- `list` returns the standard envelope (`{data, returned, total}`). The compact item is `{id, name, collection_id, archived, creator_id, can_write}` — it does **not** include the (potentially huge) `document` body. Pull the body with `get --full`.
+- `archive` is the only delete, mirroring `card` / `dashboard`. **Unarchive** with `mb document update <id> --body '{"archived":false}'`.
+- `update` is PATCH — send only the keys you want to change (`name`, `document`, `collection_id`, `collection_position`, `archived`). Replacing `document` replaces the **whole** body; there is no partial-node patch.
+
+## Node ids (`_id`)
+
+The editor anchors only these node types with an `_id` (a UUID): `paragraph`, `heading`, `codeBlock`, `orderedList`, `bulletList`, `blockquote`, `cardEmbed`, `supportingText`. **`create`/`update` require a non-empty `_id` on every node of those types** and reject a body missing any; other node types (`doc`, `text`, `listItem`, `resizeNode`, `flexContainer`, …) don't take an `_id` and are left alone. Mint the ids with the bundled `uuid` command — one per id-bearing node:
+
+```bash
+mb uuid --count 5 --json     # → ["…", …]   one UUID per id-bearing node
+```
+
+Set each as that node's `attrs._id`. Without them the editor backfills ids when the document opens, which makes a freshly-saved document show a spurious "unsaved changes" prompt.
+
+## Body shape (create / update)
+
+The create body is `{name, document, collection_id?, collection_position?}`. `name` and `document` are required on create; everything is optional on update.
+
+`document` is the TipTap tree — a root `doc` node whose `content` is an array of block nodes (replace each `<uuid-N>` with an `mb uuid` value):
+
+```json
+{
+  "name": "Weekly report",
+  "collection_id": 12,
+  "document": {
+    "type": "doc",
+    "content": [
+      {
+        "type": "heading",
+        "attrs": { "level": 1, "_id": "<uuid-1>" },
+        "content": [{ "type": "text", "text": "Weekly report" }]
+      },
+      {
+        "type": "paragraph",
+        "attrs": { "_id": "<uuid-2>" },
+        "content": [{ "type": "text", "text": "Orders trended up this week." }]
+      }
+    ]
+  }
+}
+```
+
+`collection_id: null` (or omitted) files the document in "Our analytics" (the root). `collection_id` accepts any normal analytics collection id (unlike transforms, documents are not namespace-restricted).
+
+## Node inventory
+
+Every node is `{ "type": string, "attrs"?: object, "content"?: [nodes], "text"?: string, "marks"?: [marks] }`. The id-bearing types listed above carry `attrs._id`; the rest don't.
+
+**Standard text nodes** (TipTap StarterKit):
+
+- `doc` — the root; `content` holds block nodes.
+- `paragraph` — `content` is inline nodes (usually `text`). An empty paragraph (`{ "type": "paragraph", "attrs": { "_id": "<uuid>" } }`) is a blank line.
+- `text` — a leaf with `text` and optional `marks` (no `_id`).
+- `heading` — `attrs.level` 1–6.
+- `bulletList` / `orderedList` — `content` is `listItem` nodes (no `_id`); each `listItem` wraps `paragraph`(s).
+- `blockquote`, `codeBlock`, `horizontalRule`, `hardBreak`, `image`.
+
+**Marks** on `text` (the `marks` array): `bold`, `italic`, `strike`, `code`, plus `link` (`attrs.href`). Example: `{ "type": "text", "text": "important", "marks": [{ "type": "bold" }] }`.
+
+**Metabase-custom nodes** (the reason a document is more than a wiki page):
+
+- **`cardEmbed`** — an embedded saved question. Block, atomic, id-bearing. `attrs: { "id": <card-id>, "name": <string|null>, "_id": "<uuid>" }`. `name` overrides the displayed title (`null` = use the card's own name). Card embeds are commonly wrapped in a `resizeNode` to give them a fixed height.
+- **`resizeNode`** — wraps a single `cardEmbed` or `flexContainer` to make it resizable (no `_id`). `attrs: { "height": <px>, "minHeight": <px> }`, `content` is exactly one `cardEmbed`/`flexContainer`.
+- **`flexContainer`** — a horizontal row of 1–3 `cardEmbed` / `supportingText` cells side by side (no `_id`). `attrs.columnWidths` is an array of width percentages.
+- **`supportingText`** — a text column that sits next to a card inside a `flexContainer` (id-bearing); `content` is the usual block nodes (`paragraph`, `heading`, lists, …).
+- **`smartLink`** — an inline reference to a Metabase entity (renders as a live chip). Inline, atomic, no `_id`. `attrs: { "entityId": <id>, "model": <model>, "label": <string|null>, "href": <relative-path> }`. `model` ∈ `card`, `dataset`, `metric`, `dashboard`, `collection`, `table`, `database`, `document`, `transform`, `segment`, `measure`, `user`, `action`, `indexed-entity`.
+- **`metabot`** — an inline Metabot prompt block.
+
+## Embedding an existing card
+
+A document embedding an existing card (id 114) under a heading (only the id-bearing nodes carry `_id`):
+
+```json
+{
+  "type": "doc",
+  "content": [
+    {
+      "type": "heading",
+      "attrs": { "level": 2, "_id": "<uuid-1>" },
+      "content": [{ "type": "text", "text": "Orders" }]
+    },
+    {
+      "type": "resizeNode",
+      "attrs": { "height": 400, "minHeight": 200 },
+      "content": [{ "type": "cardEmbed", "attrs": { "id": 114, "name": null, "_id": "<uuid-2>" } }]
+    },
+    { "type": "paragraph", "attrs": { "_id": "<uuid-3>" } }
+  ]
+}
+```
+
+To embed an existing card, find its id with `mb card list --profile <name> --json` (or `mb search --models card "<text>"`), then reference it in a `cardEmbed`.
+
+## Creating brand-new cards inline with the document
+
+You can create cards atomically with the document instead of pre-creating them. Reference each new card by a **negative** id in its `cardEmbed.attrs.id`, then supply the card definitions in a top-level `cards` map keyed by the same negative ids. The server creates the real cards and rewrites the negative ids to the real positive ids in the stored body.
+
+```json
+{
+  "name": "Auto report",
+  "document": {
+    "type": "doc",
+    "content": [
+      { "type": "cardEmbed", "attrs": { "id": -1, "name": null, "_id": "<uuid-1>" } },
+      { "type": "paragraph", "attrs": { "_id": "<uuid-2>" } }
+    ]
+  },
+  "cards": {
+    "-1": {
+      "name": "Order count",
+      "display": "scalar",
+      "dataset_query": { "...": "an MBQL or native query — see the mbql skill" },
+      "visualization_settings": {}
+    }
+  }
+}
+```
+
+Each entry in `cards` needs at least `{name, dataset_query, display, visualization_settings}` (these are card definitions, not TipTap nodes, so they take no `_id`). Author the `dataset_query` with the `mbql` skill (`mb skills get mbql`) and the `visualization_settings` with the `viz` skill. For most edits, prefer embedding cards that already exist (a plain positive `id` in `cardEmbed`) — inline creation is for "build the report and its questions in one shot".
+
+## Iterating on a document
+
+`update` replaces the whole `document` body, so the safe loop is **read → edit → write**. A fetched body already carries `_id`s on its id-bearing nodes, so preserve them — only mint new ones for id-bearing nodes you add:
+
+```bash
+mb document get <id> --full --profile <name> --json | jq '.document' > /tmp/body.json
+# edit /tmp/body.json (add nodes — give each new id-bearing node a fresh `mb uuid` _id) …
+jq -n --slurpfile d /tmp/body.json '{document: $d[0]}' > /tmp/patch.json
+mb document update <id> --file /tmp/patch.json --profile <name> --json
+```
+
+Don't hand-merge a partial node tree into a live document — pull the current `document`, mutate the array, and PUT the whole thing back. To rename without touching the body, patch only `name`: `mb document update <id> --body '{"name":"New title"}'`.
+
+## Don't
+
+- Don't omit `_id` on an id-bearing node (`paragraph`, `heading`, `codeBlock`, `orderedList`, `bulletList`, `blockquote`, `cardEmbed`, `supportingText`) — `create`/`update` reject the body ("did not match expected schema"). Mint ids with `mb uuid`.
+- Don't paste a whole `document get` response into `update` — `update` only accepts `name`, `document`, `collection_id`, `collection_position`, `archived`. Send the body under the `document` key, not the full record.
+- Don't put the full `document` body in `list` expectations — `list` is compact and omits it by design; use `get --full`.
+- Don't invent node types. Stick to the inventory above; unknown block types render as empty/broken in the editor even though the response schema is lenient.
+- Don't author a card's `dataset_query` or `visualization_settings` from this skill alone — load `mbql` and `viz`.

package/dist/add-collection-EPp89tcs.mjs

@@ -1,10 +0,0 @@
-import "./command-augment-BH9qgQ5u.mjs";
-import "./error-BndUmcwS.mjs";
-import "./runtime-Ck8KKQe-.mjs";
-import "./capabilities-7L9GVMd_.mjs";
-import "./parse-id-Boqc4wn4.mjs";
-import "./poll-BMjCkDaj.mjs";
-import "./poll-task-CiRA0ER9.mjs";
-import { SyncSettingsUpdateResult, add_collection_default, setCollectionRemoteSynced, syncSettingsUpdateView } from "./add-collection-CoP-6FZR.mjs";
-
-export { add_collection_default as default };

package/dist/auth-CCUDM9Sv.mjs

@@ -1,19 +0,0 @@
-import { defineCommand } from "citty";
-
-//#region src/commands/auth/index.ts
-var auth_default = defineCommand({
-	meta: {
-		name: "auth",
-		description: "Authenticate against a Metabase instance"
-	},
-	default: "login",
-	subCommands: {
-		login: () => import("./login-BMKBmgeQ.mjs").then((m) => m.default),
-		status: () => import("./status-AnPzI1f7.mjs").then((m) => m.default),
-		list: () => import("./list-D2D5Mw1E.mjs").then((m) => m.default),
-		logout: () => import("./logout-C5pod937.mjs").then((m) => m.default)
-	}
-});
-
-//#endregion
-export { auth_default as default };

package/dist/card-UwczcLjq.mjs

@@ -1,20 +0,0 @@
-import { defineCommand } from "citty";
-
-//#region src/commands/card/index.ts
-var card_default = defineCommand({
-	meta: {
-		name: "card",
-		description: "Manage Metabase cards (questions, models, metrics)"
-	},
-	subCommands: {
-		list: () => import("./list-Cj3v4Lgv.mjs").then((mod) => mod.default),
-		get: () => import("./get-BIH72g0v.mjs").then((mod) => mod.default),
-		query: () => import("./query-B8JzsQ_I.mjs").then((mod) => mod.default),
-		create: () => import("./create-BsOdn1Q1.mjs").then((mod) => mod.default),
-		update: () => import("./update-DykqQLfo.mjs").then((mod) => mod.default),
-		archive: () => import("./archive-BxwGVDpd.mjs").then((mod) => mod.default)
-	}
-});
-
-//#endregion
-export { card_default as default };

package/dist/collection-Cexywhlj.mjs

@@ -1,20 +0,0 @@
-import { defineCommand } from "citty";
-
-//#region src/commands/collection/index.ts
-var collection_default = defineCommand({
-	meta: {
-		name: "collection",
-		description: "Manage Metabase collections"
-	},
-	subCommands: {
-		list: () => import("./list-jcgK0thu.mjs").then((mod) => mod.default),
-		get: () => import("./get-Bk81meka.mjs").then((mod) => mod.default),
-		items: () => import("./items-Kr0oN2V7.mjs").then((mod) => mod.default),
-		tree: () => import("./tree-BlYgJOn9.mjs").then((mod) => mod.default),
-		create: () => import("./create-dVmIemXi.mjs").then((mod) => mod.default),
-		archive: () => import("./archive-BeslLaal.mjs").then((mod) => mod.default)
-	}
-});
-
-//#endregion
-export { collection_default as default };

package/dist/dashboard-B_CuVbMX.mjs

@@ -1,21 +0,0 @@
-import { defineCommand } from "citty";
-
-//#region src/commands/dashboard/index.ts
-var dashboard_default = defineCommand({
-	meta: {
-		name: "dashboard",
-		description: "Manage Metabase dashboards"
-	},
-	subCommands: {
-		list: () => import("./list-Ccj8-vb5.mjs").then((mod) => mod.default),
-		get: () => import("./get-LI2xsRoT.mjs").then((mod) => mod.default),
-		cards: () => import("./cards-6MTreYAo.mjs").then((mod) => mod.default),
-		create: () => import("./create-DcoF52Kx.mjs").then((mod) => mod.default),
-		update: () => import("./update-B0z-2zqC.mjs").then((mod) => mod.default),
-		"update-dashcard": () => import("./update-dashcard-DZ8oV8up.mjs").then((mod) => mod.default),
-		archive: () => import("./archive-BY8nrgnq.mjs").then((mod) => mod.default)
-	}
-});
-
-//#endregion
-export { dashboard_default as default };

package/dist/db-DULi5MOr.mjs

@@ -1,22 +0,0 @@
-import { defineCommand } from "citty";
-
-//#region src/commands/db/index.ts
-var db_default = defineCommand({
-	meta: {
-		name: "db",
-		description: "Inspect and sync Metabase databases",
-		alias: "database"
-	},
-	subCommands: {
-		list: () => import("./list-tklIxo38.mjs").then((m) => m.default),
-		get: () => import("./get-w-WqpjKy.mjs").then((m) => m.default),
-		metadata: () => import("./metadata-DIEbyQeS.mjs").then((m) => m.default),
-		schemas: () => import("./schemas-CyzplnXl.mjs").then((m) => m.default),
-		"schema-tables": () => import("./schema-tables-izDPI4f5.mjs").then((m) => m.default),
-		"sync-schema": () => import("./sync-schema-BGQVq2JA.mjs").then((m) => m.default),
-		"rescan-values": () => import("./rescan-values-DuHBnFjK.mjs").then((m) => m.default)
-	}
-});
-
-//#endregion
-export { db_default as default };

package/dist/field-CfrrLetM.mjs

@@ -1,18 +0,0 @@
-import { defineCommand } from "citty";
-
-//#region src/commands/field/index.ts
-var field_default = defineCommand({
-	meta: {
-		name: "field",
-		description: "Manage Metabase fields"
-	},
-	subCommands: {
-		get: () => import("./get-6Cj360cH.mjs").then((m) => m.default),
-		values: () => import("./values-oD72EtRq.mjs").then((m) => m.default),
-		summary: () => import("./summary-DDed1LOz.mjs").then((m) => m.default),
-		update: () => import("./update-CdfAogO2.mjs").then((m) => m.default)
-	}
-});
-
-//#endregion
-export { field_default as default };

package/dist/git-sync-BpRstrZo.mjs

@@ -1,28 +0,0 @@
-import { defineCommand } from "citty";
-
-//#region src/commands/git-sync/index.ts
-var git_sync_default = defineCommand({
-	meta: {
-		name: "git-sync",
-		description: "Sync Metabase content with a git remote"
-	},
-	subCommands: {
-		status: () => import("./status-DHFYn9kO.mjs").then((mod) => mod.default),
-		"is-dirty": () => import("./is-dirty-DuWCgrz2.mjs").then((mod) => mod.default),
-		"has-remote-changes": () => import("./has-remote-changes-DcpW1_KX.mjs").then((mod) => mod.default),
-		dirty: () => import("./dirty-DGCa6W1F.mjs").then((mod) => mod.default),
-		"current-task": () => import("./current-task-BN_XEFSX.mjs").then((mod) => mod.default),
-		"cancel-task": () => import("./cancel-task-DoL2bqs1.mjs").then((mod) => mod.default),
-		wait: () => import("./wait-BtzuqQC3.mjs").then((mod) => mod.default),
-		import: () => import("./import-CTQT1atq.mjs").then((mod) => mod.default),
-		export: () => import("./export-BIZ-UR_M.mjs").then((mod) => mod.default),
-		stash: () => import("./stash-DLtVf4_D.mjs").then((mod) => mod.default),
-		branches: () => import("./branches-Vlu44J51.mjs").then((mod) => mod.default),
-		"create-branch": () => import("./create-branch-40Xm4DN7.mjs").then((mod) => mod.default),
-		"add-collection": () => import("./add-collection-EPp89tcs.mjs").then((mod) => mod.default),
-		"remove-collection": () => import("./remove-collection-Clwz3EHQ.mjs").then((mod) => mod.default)
-	}
-});
-
-//#endregion
-export { git_sync_default as default };

package/dist/is-dirty-DuWCgrz2.mjs

@@ -1,9 +0,0 @@
-import "./command-augment-BH9qgQ5u.mjs";
-import "./error-BndUmcwS.mjs";
-import "./runtime-Ck8KKQe-.mjs";
-import "./capabilities-7L9GVMd_.mjs";
-import "./poll-BMjCkDaj.mjs";
-import "./poll-task-CiRA0ER9.mjs";
-import { IsDirtyResult, is_dirty_default } from "./is-dirty-DGrmt1ss.mjs";
-
-export { is_dirty_default as default };

package/dist/measure-BkwFsP44.mjs

@@ -1,19 +0,0 @@
-import { defineCommand } from "citty";
-
-//#region src/commands/measure/index.ts
-var measure_default = defineCommand({
-	meta: {
-		name: "measure",
-		description: "Manage Metabase measures"
-	},
-	subCommands: {
-		list: () => import("./list-zRQsvrH6.mjs").then((mod) => mod.default),
-		get: () => import("./get-DlGlnciR.mjs").then((mod) => mod.default),
-		create: () => import("./create-k59K2qf1.mjs").then((mod) => mod.default),
-		update: () => import("./update-CilTW98H.mjs").then((mod) => mod.default),
-		archive: () => import("./archive-Blt0TxxA.mjs").then((mod) => mod.default)
-	}
-});
-
-//#endregion
-export { measure_default as default };

package/dist/segment-ChYmSM0p.mjs

@@ -1,19 +0,0 @@
-import { defineCommand } from "citty";
-
-//#region src/commands/segment/index.ts
-var segment_default = defineCommand({
-	meta: {
-		name: "segment",
-		description: "Manage Metabase segments"
-	},
-	subCommands: {
-		list: () => import("./list-DNmekF2B.mjs").then((mod) => mod.default),
-		get: () => import("./get-CHaIVT6Y.mjs").then((mod) => mod.default),
-		create: () => import("./create-C_Z3IDrW.mjs").then((mod) => mod.default),
-		update: () => import("./update-DqSG5_Ie.mjs").then((mod) => mod.default),
-		archive: () => import("./archive-C17qIvFW.mjs").then((mod) => mod.default)
-	}
-});
-
-//#endregion
-export { segment_default as default };

package/dist/snippet-De70ayL1.mjs

@@ -1,19 +0,0 @@
-import { defineCommand } from "citty";
-
-//#region src/commands/snippet/index.ts
-var snippet_default = defineCommand({
-	meta: {
-		name: "snippet",
-		description: "Manage Metabase native query snippets"
-	},
-	subCommands: {
-		list: () => import("./list-Bz2ej0Cl.mjs").then((mod) => mod.default),
-		get: () => import("./get-BuM6QPjZ.mjs").then((mod) => mod.default),
-		create: () => import("./create-BZRA7nPu.mjs").then((mod) => mod.default),
-		update: () => import("./update-BHtliIr_.mjs").then((mod) => mod.default),
-		archive: () => import("./archive-CPLXsrzD.mjs").then((mod) => mod.default)
-	}
-});
-
-//#endregion
-export { snippet_default as default };

package/dist/table-C_bP2ao-.mjs

@@ -1,19 +0,0 @@
-import { defineCommand } from "citty";
-
-//#region src/commands/table/index.ts
-var table_default = defineCommand({
-	meta: {
-		name: "table",
-		description: "Manage Metabase tables"
-	},
-	subCommands: {
-		list: () => import("./list-CLvlEVQo.mjs").then((m) => m.default),
-		get: () => import("./get-BSJN5TwW.mjs").then((m) => m.default),
-		metadata: () => import("./metadata-CG4VZ5NW.mjs").then((m) => m.default),
-		fields: () => import("./fields-9lOrO8UH.mjs").then((m) => m.default),
-		update: () => import("./update-DBN7yfAk.mjs").then((m) => m.default)
-	}
-});
-
-//#endregion
-export { table_default as default };

package/dist/transform-B4RZfm6A.mjs

@@ -1,24 +0,0 @@
-import { defineCommand } from "citty";
-
-//#region src/commands/transform/index.ts
-var transform_default = defineCommand({
-	meta: {
-		name: "transform",
-		description: "Manage Metabase transforms"
-	},
-	subCommands: {
-		list: () => import("./list-Cl_O4_U4.mjs").then((mod) => mod.default),
-		get: () => import("./get-DFe2WoJ2.mjs").then((mod) => mod.default),
-		create: () => import("./create-BWD8H6yw.mjs").then((mod) => mod.default),
-		update: () => import("./update-CgOPxKXK.mjs").then((mod) => mod.default),
-		delete: () => import("./delete-tPjicYO4.mjs").then((mod) => mod.default),
-		"delete-table": () => import("./delete-table-CDj19Qn6.mjs").then((mod) => mod.default),
-		run: () => import("./run-JXRivkfH.mjs").then((mod) => mod.default),
-		cancel: () => import("./cancel-D0aBPUhs.mjs").then((mod) => mod.default),
-		"get-run": () => import("./get-run-hCZaw8-h.mjs").then((mod) => mod.default),
-		runs: () => import("./runs-FxgbXvax.mjs").then((mod) => mod.default)
-	}
-});
-
-//#endregion
-export { transform_default as default };

package/dist/transform-job-C4pZcrIF.mjs

@@ -1,19 +0,0 @@
-import { defineCommand } from "citty";
-
-//#region src/commands/transform-job/index.ts
-var transform_job_default = defineCommand({
-	meta: {
-		name: "transform-job",
-		description: "Manage Metabase transform jobs"
-	},
-	subCommands: {
-		list: () => import("./list-DaESiI72.mjs").then((mod) => mod.default),
-		get: () => import("./get-CRa-h69C.mjs").then((mod) => mod.default),
-		create: () => import("./create-DNYFXAsy.mjs").then((mod) => mod.default),
-		update: () => import("./update-CoVvsU-I.mjs").then((mod) => mod.default),
-		delete: () => import("./delete-DEFgs5LE.mjs").then((mod) => mod.default)
-	}
-});
-
-//#endregion
-export { transform_job_default as default };