@metabase/cli 0.2.1 → 0.2.2-alpha.extract-api-client.27e2241

package/skill-data/git-sync/SKILL.md

@@ -1,12 +1,14 @@
 ---
 name: git-sync
-description: Round-trip Metabase content (cards, dashboards, transforms, snippets, collections) between an instance and a git remote via `mb git-sync …` — status, dirty / has-remote-changes checks, import, export (with branch guard), branches, stash, add/remove a collection from sync. Load when the user wants to "import the latest changes", "export to git", "git sync", "dirty check", "stash before pulling", "add a collection to sync", or anything `mb git-sync …`.
+description: Round-trip Metabase content (cards, dashboards, transforms, snippets, collections, Library-published table/field metadata) between an instance and a git remote via `mb git-sync …` — status, dirty / has-remote-changes checks, import, export (with branch guard), branches, stash, add/remove a collection from sync. Load when the user wants to "import the latest changes", "export to git", "push my changes to the repo", "open a PR with my Metabase changes", "git sync", "dirty check", "stash before pulling", "add a collection to sync", or anything `mb git-sync …`.
 allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
 ---
 
 # git-sync (representations ↔ instance)
 
-Metabase content (cards, dashboards, transforms, snippets, collections, …) can live in a git repo as YAML and round-trip in and out of a Metabase instance via the `git-sync` verbs. The instance is configured with a `remote-sync-*` settings block (URL, branch, token, type read-only/read-write); the CLI drives the sync tasks against `/api/ee/remote-sync/*`. Only collections flagged for sync serialize; everything else is local-only.
+Metabase content (cards, dashboards, transforms, snippets, collections, …) can live in a git repo as YAML and round-trip in and out of a Metabase instance via the `git-sync` verbs. The instance is configured with a `remote-sync-*` settings block (URL, branch, token, type read-only/read-write); the CLI drives the sync tasks against `/api/ee/remote-sync/*`. Only collections flagged for sync serialize; everything else is local-only. Table and field metadata round-trips too, for Library-published tables in a flagged collection — see "Published table metadata" below.
+
+The repo and the instance are two ends of the same state; what "push my changes" means depends on where the changes were made. If they were made **in the instance** (CLI verbs against a read-write instance — cards edited, transforms created, tables published, metadata written), "push my changes" / "save this to the repo" / "open a PR with these changes" means driving the instance's export to a branch (`stash` or `create-branch` + `export`) and opening the PR from that branch — not reconstructing the changes as files. If the workflow is **repo-first** (content YAML edited in the repo, the instance imports it), plain `git` against the repo is the way — but only in the serialized layout already there: files in paths or formats the serializer doesn't own are invisible to Metabase and never apply on import.
 
 This skill covers the import/export workflow. Flag conventions and auth setup live in `core` (`mb skills get core`). To author content YAML by hand: the per-resource clause and settings shapes mirror the API form — query bodies follow the `mbql` skill, `visualization_settings` follow the `visualization` skill — except the portable YAML uses **name-based** references (e.g. `[Sample Database, PUBLIC, ORDERS, TOTAL]`, and entity-ids for cross-entity FKs) where the API form uses numeric ids. For the on-disk folder layout, model new files on what the synced repo already contains.
 
@@ -126,13 +128,26 @@ mb setting set remote-sync-type '"read-write"' --profile <n>
 
 (`setting set` parses the value as strict JSON — mind the inner double quotes; see `core`.) The server also rejects switching to `:read-only` while the Remote Sync collection is dirty; export or `--force` import first if you're going the other way.
 
-**Verifying the result.** The CLI's `Collection` schema doesn't yet expose `is_remote_synced`, so `collection get --json` won't show the flag. The pragmatic confirmation paths are:
+**Verifying the result.** `mb git-sync status --profile <n> --json` lists the flagged collections under `synced_collections`, and `mb collection get <id> --json` shows the per-collection `is_remote_synced` flag.
+
+## Published table metadata (Library) and sync scope
+
+Table and field metadata — table/field descriptions, semantic types (`type/PK`, `type/FK`), FK targets, plus segments and measures on the table — serializes for **Library-published tables only**, under `databases/<db>/schemas/<schema>/tables/<table>/…` in the repo. Eligibility is two-gated: the table must be published (`mb library publish`), **and** the Library collection holding it must itself carry `is_remote_synced: true`. An ordinary warehouse table, or a transform's target table that isn't published, never serializes — a transform's YAML carries only the transform definition (query, target, description), not the output table's field metadata.
+
+The classic trap: publish tables, write field metadata, then `git-sync dirty` comes back empty and nothing lands in the repo. That does not mean git-sync can't carry table metadata — it means the Library collection isn't in the sync scope, so nothing was eligible for dirty-tracking when the writes happened. Check the scope (`synced_collections` in `status`), then:
+
+```bash
+mb library get --profile <n> --json                                # Library Data collection id
+mb git-sync add-collection <library-data-id> --profile <n>
+mb git-sync stash --new-branch <branch> -m "..." --profile <n>     # or create-branch + export
+```
 
-- `mb git-sync is-dirty --profile <n> --json` after editing a card in the now-synced collection — a `true` reading proves it's tracked.
-- The Metabase Admin UI's Remote Sync page renders the per-collection toggles.
+Flagging the collection records it for the next export, which serializes its current content — including already-published tables and their field metadata. `mb library publish` prints a reminder when the target collection is outside the sync scope on an instance with a configured remote.
 
 ## Don't (git-sync-specific)
 
+- Don't turn instance-side changes into hand-written repo files. When the changes were made against the instance, export them (`stash` / `create-branch` + `export`) and PR the exported branch; reconstructing them as YAML by hand — or pushing files in paths/formats the serializer doesn't own — produces content that never applies on import, and pushing behind Metabase's back races its own sync tasks. Hand-editing YAML belongs to the repo-first workflow, in the serialized layout the repo already uses.
+- Don't conclude from an empty `dirty` list that a change type isn't tracked. Dirty-tracking only records changes to _eligible_ objects; the usual cause is scope (the collection isn't flagged — see "Published table metadata"), not capability. Check `synced_collections` in `status` before concluding.
 - Don't run `git-sync import --force` or `git-sync export --force` without explicit user confirmation. Both are lossy — `--force` import discards instance-side work, `--force` export overwrites the remote branch.
 - Don't drive `git-sync` against a Metabase instance that doesn't have remote-sync configured — every verb returns an error pointing at the missing `remote-sync-*` settings. To check: `mb setting get remote-sync-url --profile <n> --json`.
 - Don't author content directly via `card create` / `transform create` and then assume `git-sync export` will commit it cleanly — the instance and repo can drift if you mix direct API writes with sync-tracked changes. If you do, follow direct writes immediately with `git-sync export -m "..."` to keep them in step.

package/skill-data/notification/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: notification
+description: Scheduled delivery of Metabase content by email, Slack, or webhook — question alerts (`mb alert …`, one card, fires on a send condition) and dashboard subscriptions (`mb subscription …`, one dashboard, fires on a schedule). Covers choosing between them, the two different schedule and recipient contracts, channel prerequisites, and testing a delivery. Load when the user wants to "alert me when X drops below Y", "email this dashboard every Monday", "send this question to Slack", "set up a subscription", "who gets this report", "add a recipient", "stop these emails", "post to a webhook when the number spikes", or anything `mb alert …` / `mb subscription …`.
+allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
+---
+
+# notification (alerts & subscriptions)
+
+Metabase delivers content on a schedule two different ways, and they share almost nothing under the hood:
+
+|            | `mb alert`                                           | `mb subscription`                           |
+| ---------- | ---------------------------------------------------- | ------------------------------------------- |
+| Delivers   | one **card**                                         | one **dashboard** (selected dashcards)      |
+| Fires      | on a **send condition** each time the schedule ticks | every time the schedule ticks               |
+| Schedule   | one **cron string**                                  | structured `schedule_type` + hour/day/frame |
+| Channels   | `channel/email`, `channel/slack`, `channel/http`     | `email`, `slack`, `http`                    |
+| Recipients | typed union (`user` / `group` / `raw-value`)         | `{id}` or `{email}`                         |
+| API        | `/api/notification`                                  | `/api/pulse`                                |
+
+Pick by **what is being delivered**, not by how often. A user asking to "get emailed when signups drop below 100" wants an alert (a condition on one card). A user asking to "email the exec dashboard every Monday" wants a subscription. If they want a whole dashboard _conditionally_, there is no such thing — the closest is a subscription with `skip_if_empty`, or an alert on the one card that carries the condition.
+
+Because the two bodies look superficially alike and are not, **never adapt one body shape into the other by hand.** Authoring a subscription's `schedule_type` inside an alert (or a `cron_schedule` inside a subscription) fails or, worse, silently drops the schedule.
+
+## Before you create anything: is the channel configured?
+
+A delivery to an unconfigured channel is accepted by the server and then never sends. This is the single most common "it doesn't work" report, and nothing in the create response hints at it. Check first:
+
+```bash
+mb setting get 'email-configured?'   --profile <n> --json | jq .value   # → true if SMTP is set up
+mb setting get 'slack-token-valid?'  --profile <n> --json | jq .value   # → true if the Slack app is connected
+```
+
+Quote the key — the trailing `?` is a shell glob character and an unquoted `email-configured?` will not reach the CLI.
+
+`false` means an **admin** must configure SMTP or the Slack app in Metabase before any delivery works. Say so and stop; do not create a notification that silently goes nowhere. Slack has a second trap: to post to a **private** channel, someone must invite the Metabase app to that channel (`@Metabase` in the channel) — it will not appear as a target until then.
+
+## Alerts (`mb alert`)
+
+An alert body has exactly three parts:
+
+```json
+{
+  "payload": { "card_id": 94, "send_condition": "has_result", "send_once": false },
+  "subscriptions": [{ "cron_schedule": "0 0 8 * * ? *" }],
+  "handlers": [
+    {
+      "channel_type": "channel/email",
+      "recipients": [
+        { "type": "notification-recipient/raw-value", "details": { "value": "team@example.com" } }
+      ]
+    }
+  ]
+}
+```
+
+**`send_condition`** is the whole point of an alert:
+
+| Value                       | Fires when                                                                                                                                                         |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `has_result`                | the card returns **any** row. The rare-event pattern: write the card so it returns rows _only_ when the thing you care about happened, then alert on `has_result`. |
+| `goal_above` / `goal_below` | the result crosses the card's goal line.                                                                                                                           |
+
+`goal_above` / `goal_below` **require a goal already set on the card's visualization** (`visualization_settings.graph.goal_value` — see the `visualization` skill). Without one the alert can never fire, and the failure is silent. Check with `mb card get <id> --fields visualization_settings --json` before choosing a goal condition; if there's no goal, either set one or reshape the card so `has_result` expresses the condition.
+
+`send_once: true` fires the alert at most once and then deactivates it — a one-shot "tell me when this finally happens."
+
+**`cron_schedule`** is a 7-field **Quartz** expression (`sec min hour day-of-month month day-of-week year`), not the 5-field Unix cron most people know. `0 0 8 * * ? *` is "every day at 08:00". The `?` in the day-of-week slot means "unspecified" and is mandatory when day-of-month is set (Quartz rejects `*` in both). The hour is evaluated in the **instance's report timezone**, not UTC and not yours — read it with `mb setting get report-timezone --json`, and say which zone you scheduled in when you report back to the user.
+
+**`handlers`** carry the delivery. The `channel_type` values are prefixed (`channel/email`, not `email` — that prefix is the subscription spelling). Recipients are a typed union:
+
+```text
+{ "type": "notification-recipient/user",      "user_id": 3 }                       a Metabase user
+{ "type": "notification-recipient/group",     "permissions_group_id": 5 }          everyone in a group
+{ "type": "notification-recipient/raw-value", "details": { "value": "a@b.com" } }  an external address
+```
+
+`channel/http` is a **webhook**, and it is alerts-only — dashboard subscriptions cannot post to a webhook. It needs a webhook channel configured server-side; pass its id as `channel_id`.
+
+**Verbs.** `mb alert list` hides archived alerts unless you pass `--include-inactive`; `mb card alerts <card-id>` is the same list scoped to one card. `mb alert archive <id>` deactivates (`active: false`) and stops delivery — it is not a delete, and `mb alert update <id> --body '{"active":true}'` brings it back. `mb alert send <id>` delivers **immediately**, ignoring both the schedule and the send condition — that's your end-to-end test that the channel really works. It sends to real recipients, so test with yourself as the only recipient first.
+
+## Subscriptions (`mb subscription`)
+
+```json
+{
+  "name": "Weekly orders",
+  "dashboard_id": 10,
+  "cards": [{ "id": 94, "dashboard_card_id": 87, "include_csv": false, "include_xls": false }],
+  "channels": [
+    {
+      "channel_type": "email",
+      "schedule_type": "weekly",
+      "schedule_hour": 8,
+      "schedule_day": "mon",
+      "recipients": [{ "email": "team@example.com" }]
+    }
+  ]
+}
+```
+
+**Each card needs two different ids.** `id` is the card id; `dashboard_card_id` is the id of the _placement_ of that card on that dashboard. Both come from `mb dashboard cards <dashboard-id> --json` — take them from the same row. Passing the card id in both slots is the most common subscription bug; it produces a subscription that sends the wrong content or nothing.
+
+**The schedule fields required depend on `schedule_type`:**
+
+| `schedule_type` | Also required                                                 | Meaning                                                                                                                                        |
+| --------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `hourly`        | —                                                             | every hour                                                                                                                                     |
+| `daily`         | `schedule_hour` (0–23)                                        | every day at that hour                                                                                                                         |
+| `weekly`        | `schedule_hour` + `schedule_day` (`mon`…`sun`)                | that weekday                                                                                                                                   |
+| `monthly`       | `schedule_hour` + `schedule_frame` (`first` / `mid` / `last`) | that point in the month. With `first` / `last` you may add `schedule_day` to mean e.g. "first Monday"; with `mid` a `schedule_day` is rejected |
+
+Recipients are `{"email": "a@b.com"}` for an external address or `{"id": <user-id>}` for a Metabase user. A Slack channel is **not** a recipient — it goes in `details`: `{"channel_type": "slack", "details": {"channel": "#general"}, …}`.
+
+**`skip_if_empty: true`** suppresses the send when the dashboard's questions return no rows — the way to build a "only tell me when something happened" dashboard report. **`parameters`** sets filter values for this subscription only, so one dashboard can feed several audiences a different slice (Pro/Enterprise). Its entries are dashboard parameter values — the parameter `id`s come from `mb dashboard get <id> --fields parameters --json` (see the `dashboard` skill).
+
+`mb subscription list --archived` is a **swap, not a union** — it returns archived subscriptions _instead of_ active ones, never both. `mb dashboard subscriptions <id>` is the list scoped to one dashboard. `mb subscription archive <id>` also disables every channel on it, so restoring takes two steps: `update --body '{"archived":false}'`, then re-send the `channels` array with `enabled: true`.
+
+## Updating: the lists replace wholesale
+
+On both nouns, the collection-valued fields are **replaced**, not merged:
+
+- alert — `subscriptions` and `handlers`
+- subscription — `cards` and `channels`
+
+So "add a recipient" is a read-modify-write, never a patch:
+
+```bash
+mb alert get 9 --json > ./.scratch/alert.json     # read the current handlers
+# edit ./.scratch/alert.json — add the recipient to the existing handlers array
+mb alert update 9 --body "$(jq -c '{handlers}' ./.scratch/alert.json)"
+```
+
+Sending a partial `handlers` array **deletes the recipients you left out.** The same holds for a subscription's `channels`: omit a channel and it's gone.
+
+Scalar fields _do_ merge, and inside an alert so does `payload` — `mb alert update 9 --body '{"payload":{"send_condition":"goal_above"}}'` keeps the card. An alert's `card_id` and a subscription's `dashboard_id` are fixed at creation; to point at different content, create a new one and archive the old.
+
+(Drive updates through `mb alert update` / `mb subscription update` only. Both endpoints have destructive raw-PUT semantics — the notification PUT is a spec-diff that will delete and recreate the row under a new id if the ids don't match, and the pulse PUT re-applies server defaults to omitted keys, silently un-archiving. The CLI's update verbs read-merge-write to neutralize both. A hand-rolled `curl` PUT will not.)
+
+## End-to-end recipe
+
+1. **Confirm the channel works** — `mb setting get 'email-configured?'` / `'slack-token-valid?'`. Stop and ask for an admin if `false`.
+2. **Find the content id.** Alert: the card id (`mb card list`, `mb search`). Subscription: the dashboard id _and_ the `{id, dashboard_card_id}` pairs from `mb dashboard cards <id> --json`.
+3. **Check the condition is expressible.** Goal alert → the card must have a goal. Otherwise reshape toward `has_result`.
+4. **Confirm the recipients with the user before creating.** A wrong address means real mail to a real person, and the fix is a full read-modify-write.
+5. **Create** from a file in `./.scratch` (see `core` for body input).
+6. **Test the delivery** — `mb alert send <id>`. There is no equivalent for subscriptions; verify those by reading back `mb subscription get <id>` and waiting for the schedule.
+7. **Report the schedule in the instance's timezone**, not the user's assumed one.
+
+## Don't
+
+- Don't create a notification against an unconfigured channel and call it done — it will never send, and nothing errors.
+- Don't set a `goal_above` / `goal_below` alert on a card with no goal line.
+- Don't reuse the card id as `dashboard_card_id`.
+- Don't send a partial `handlers` / `channels` / `cards` / `subscriptions` array — you will delete the entries you omitted.
+- Don't use `mb alert send` to "check it looks right" on an alert with real recipients — it emails all of them, immediately. To preview the content, run the card itself (`mb card query <card-id>`), which delivers nothing. To rehearse the delivery, create the alert with yourself as the only recipient, `mb alert send` it, then add the real recipients via the read-modify-write above.
+- Don't mix the spellings: `channel/email` is an alert, `email` is a subscription.
+
+Cross-links: `core` (auth, `--json`, body input), `dashboard` (dashcards and the `parameters` a subscription can override), `visualization` (the `graph.goal_value` a goal alert depends on).

package/skill-data/transform/SKILL.md

@@ -74,7 +74,7 @@ Columns and types are inferred from the result set; change the SELECT shape and
 ## Inspect runs and cancel an in-flight run
 
 ```bash
-# Recent runs across all transforms (drains all pages by default; cap with --limit):
+# Recent runs across all transforms (server-paged; continue with --offset <next_offset>):
 mb transform runs --profile <name> --json
 mb transform runs --transform-id <id> --limit 10 --profile <name> --json
 

package/.claude-plugin/marketplace.json

@@ -1,19 +0,0 @@
-{
-  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
-  "name": "metabase",
-  "description": "Official Metabase tooling for Claude Code",
-  "owner": {
-    "name": "Metabase",
-    "email": "support@metabase.com"
-  },
-  "plugins": [
-    {
-      "name": "metabase-cli",
-      "description": "Be your data analyst / data engineer for Metabase, from the terminal via the `mb` CLI. Go from raw data to something a non-technical person can use: clean tables, reusable metrics, dashboards, and written answers. Use when someone wants to \"make sense of my data\", \"build a data model\", \"go from raw data to a dashboard\", \"answer questions about my data\", \"report on who registered / signed up / responded\", or \"set up analytics for X\". Also full CRUD on every Metabase resource (cards, dashboards, transforms, queries), git-sync content to and from a remote, and on-demand workflow skills served by `mb skills get`.",
-      "source": "./",
-      "strict": false,
-      "skills": ["./skills/metabase-cli"],
-      "category": "development"
-    }
-  ]
-}

package/dist/add-collection-C8ZTPlIE.mjs

@@ -1,9 +0,0 @@
-import "./capabilities-DOTcPraV.mjs";
-import "./command-augment-D9pI9Vbh.mjs";
-import "./runtime-Ab96yYlM.mjs";
-import "./parse-id-CD54Chc5.mjs";
-import "./poll-DVF9EnEb.mjs";
-import "./poll-task-CpHGQOd5.mjs";
-import { SyncSettingsUpdateResult, add_collection_default, setCollectionRemoteSynced, syncSettingsUpdateView } from "./add-collection-CUBn11d4.mjs";
-
-export { add_collection_default as default };

package/dist/add-collection-CUBn11d4.mjs

@@ -1,60 +0,0 @@
-import { connectionFlags, outputFlags, profileFlag, renderSummary } from "./capabilities-DOTcPraV.mjs";
-import { defineMetabaseCommand } from "./runtime-Ab96yYlM.mjs";
-import { parseId } from "./parse-id-CD54Chc5.mjs";
-import { REMOTE_SYNC_PATHS } from "./poll-task-CpHGQOd5.mjs";
-import { z } from "zod";
-
-//#region src/commands/git-sync/add-collection.ts
-const SyncSettingsUpdateResult = z.object({
-	success: z.boolean(),
-	task_id: z.number().int().positive().optional()
-});
-const syncSettingsUpdateView = {
-	compactPick: SyncSettingsUpdateResult,
-	tableColumns: [{
-		key: "success",
-		label: "Success"
-	}, {
-		key: "task_id",
-		label: "Task ID"
-	}]
-};
-async function setCollectionRemoteSynced(client, collectionId, synced) {
-	return await client.requestParsed(SyncSettingsUpdateResult, REMOTE_SYNC_PATHS.settings, {
-		method: "PUT",
-		body: { collections: { [collectionId]: synced } }
-	});
-}
-var add_collection_default = defineMetabaseCommand({
-	meta: {
-		name: "add-collection",
-		description: "Mark a collection as git-synced; cascades to descendants by location prefix"
-	},
-	capabilities: {
-		minVersion: 60,
-		tokenFeature: "remote_sync"
-	},
-	args: {
-		...outputFlags,
-		...profileFlag,
-		...connectionFlags,
-		id: {
-			type: "positional",
-			description: "Collection id (positive integer)",
-			required: true
-		}
-	},
-	outputSchema: SyncSettingsUpdateResult,
-	examples: ["mb git-sync add-collection 12", "mb git-sync add-collection 12 --json --profile prod"],
-	async run({ args, ctx, getClient }) {
-		const collectionId = parseId(args.id, "id");
-		const client = await getClient();
-		const result = await setCollectionRemoteSynced(client, collectionId, true);
-		const taskPart = result.task_id !== void 0 ? ` (task #${result.task_id})` : "";
-		const message = result.success ? `Collection ${collectionId} is now git-synced${taskPart}.` : `Could not update git-sync setting for collection ${collectionId}.`;
-		renderSummary(result, syncSettingsUpdateView, message, ctx);
-	}
-});
-
-//#endregion
-export { SyncSettingsUpdateResult, add_collection_default, setCollectionRemoteSynced, syncSettingsUpdateView };

package/dist/auth-hgAnMUfi.mjs

@@ -1,22 +0,0 @@
-import "./command-augment-D9pI9Vbh.mjs";
-import { defineCommandGroup } from "./group-CILtQqCL.mjs";
-
-//#region src/commands/auth/index.ts
-var auth_default = defineCommandGroup({
-	name: "auth",
-	description: "Authenticate against a Metabase instance",
-	defaultCommand: "login",
-	skills: [{
-		skill: "core",
-		purpose: "authentication and named profiles"
-	}],
-	subCommands: {
-		login: () => import("./login-jy9rbYev.mjs").then((m) => m.default),
-		status: () => import("./status-B5ar0uXc.mjs").then((m) => m.default),
-		list: () => import("./list-De82cXvn.mjs").then((m) => m.default),
-		logout: () => import("./logout-CRbk1SuY.mjs").then((m) => m.default)
-	}
-});
-
-//#endregion
-export { auth_default as default };