@metabase/cli 0.1.17 → 0.2.0

package/dist/{update-Bos8nnv0.mjs → update-CTZg2Lia.mjs}

@@ -1,16 +1,14 @@
-import "./notice-DyVl5aYB.mjs";
-import { connectionFlags, outputFlags, profileFlag } from "./error-5H_tcfL8.mjs";
-import "./command-augment-DdZIfx1V.mjs";
-import { defineMetabaseCommand } from "./runtime-BJtuxWM8.mjs";
-import { renderSummary } from "./capabilities-N0jo5U7S.mjs";
-import "./input-7Sj85_K7.mjs";
-import { parseId } from "./parse-id-D4LeTUsP.mjs";
-import { readBody } from "./body-IcJ5kFtk.mjs";
-import { bodyInputFlags } from "./body-flags-DWTTxJpP.mjs";
-import "./validate-BqNW4Sk1.mjs";
-import { TRANSFORM_SOURCE_QUERY_LABELS, preflightMbql5Query, skipValidateFlag } from "./validate-query-CcZVKYPV.mjs";
-import { Transform, TransformUpdateInput, transformView } from "./transform-DEF38FWe.mjs";
-import { enrichTransformCollectionError } from "./collection-namespace-CsaxEqOb.mjs";
+import { connectionFlags, outputFlags, profileFlag, renderSummary } from "./capabilities-DrDJo_ng.mjs";
+import "./command-augment-D9pI9Vbh.mjs";
+import { defineMetabaseCommand } from "./runtime-B-c-Fc2i.mjs";
+import "./input-m9ctfLxZ.mjs";
+import { parseId } from "./parse-id-DfY0Lugw.mjs";
+import { readBody } from "./body-C1_AaTS4.mjs";
+import { bodyInputFlags } from "./body-flags-CgHgJBRC.mjs";
+import "./validate-clAWO3X-.mjs";
+import { TRANSFORM_SOURCE_QUERY_LABELS, preflightMbql5Query, skipValidateFlag } from "./validate-query-CsK2_2_u.mjs";
+import { Transform, TransformUpdateInput, transformView } from "./transform-JQel7e5H.mjs";
+import { enrichTransformCollectionError } from "./collection-namespace-DqPNrCdQ.mjs";
 
 //#region src/commands/transform/update.ts
 var update_default = defineMetabaseCommand({
@@ -18,7 +16,7 @@ var update_default = defineMetabaseCommand({
 		name: "update",
 		description: "Update a transform by id (partial)"
 	},
-	details: "Patches only the fields you send (any of `name`, `source`, `target`, `tag_ids`, …). When a new `source.query` is an MBQL 5 query it is checked against a bundled JSON Schema before sending; pass --skip-validate to bypass.",
+	details: "Patches only the fields you send (any of `name`, `source`, `target`, `tag_ids`, …). When a new `source.query` is an MBQL 5 query it is checked against a bundled JSON Schema (print it with `mb query --print-schema`) before sending; pass --skip-validate to bypass.",
 	skills: [{
 		skill: "mbql",
 		purpose: "MBQL source.query bodies"
@@ -36,6 +34,7 @@ var update_default = defineMetabaseCommand({
 		},
 		...skipValidateFlag
 	},
+	inputSchema: TransformUpdateInput,
 	outputSchema: Transform,
 	examples: [
 		"cat patch.json | mb transform update 1",

package/dist/{update-DV7IY7IQ.mjs → update-DJDuIhYG.mjs}

@@ -1,13 +1,11 @@
-import "./notice-DyVl5aYB.mjs";
-import { connectionFlags, outputFlags, profileFlag } from "./error-5H_tcfL8.mjs";
-import "./command-augment-DdZIfx1V.mjs";
-import { defineMetabaseCommand } from "./runtime-BJtuxWM8.mjs";
-import { renderSummary } from "./capabilities-N0jo5U7S.mjs";
-import "./input-7Sj85_K7.mjs";
-import { parseId } from "./parse-id-D4LeTUsP.mjs";
-import { readBody } from "./body-IcJ5kFtk.mjs";
-import { bodyInputFlags } from "./body-flags-DWTTxJpP.mjs";
-import { TransformJob, TransformJobUpdateInput, transformJobView } from "./transform-job-CtixL4An.mjs";
+import { connectionFlags, outputFlags, profileFlag, renderSummary } from "./capabilities-DrDJo_ng.mjs";
+import "./command-augment-D9pI9Vbh.mjs";
+import { defineMetabaseCommand } from "./runtime-B-c-Fc2i.mjs";
+import "./input-m9ctfLxZ.mjs";
+import { parseId } from "./parse-id-DfY0Lugw.mjs";
+import { readBody } from "./body-C1_AaTS4.mjs";
+import { bodyInputFlags } from "./body-flags-CgHgJBRC.mjs";
+import { TransformJob, TransformJobUpdateInput, transformJobView } from "./transform-job-CtVziW85.mjs";
 
 //#region src/commands/transform-job/update.ts
 var update_default = defineMetabaseCommand({
@@ -27,6 +25,7 @@ var update_default = defineMetabaseCommand({
 			required: true
 		}
 	},
+	inputSchema: TransformJobUpdateInput,
 	outputSchema: TransformJob,
 	examples: [
 		"cat patch.json | mb transform-job update 1",

package/dist/{update-Dxa_6H2A.mjs → update-HxYcvpSq.mjs}

@@ -1,17 +1,16 @@
-import "./notice-DyVl5aYB.mjs";
-import { connectionFlags, outputFlags, profileFlag } from "./error-5H_tcfL8.mjs";
-import "./command-augment-DdZIfx1V.mjs";
-import { defineMetabaseCommand } from "./runtime-BJtuxWM8.mjs";
-import { renderSummary } from "./capabilities-N0jo5U7S.mjs";
-import "./input-7Sj85_K7.mjs";
-import "./field-CMY_LWUe.mjs";
-import "./parameter-CiJ4CwWE.mjs";
-import { Card, CardUpdateInput, cardView } from "./card-DEmcRlNO.mjs";
-import { parseId } from "./parse-id-D4LeTUsP.mjs";
-import { readBody } from "./body-IcJ5kFtk.mjs";
-import { bodyInputFlags } from "./body-flags-DWTTxJpP.mjs";
-import "./validate-BqNW4Sk1.mjs";
-import { CARD_DATASET_QUERY_LABELS, preflightMbql5Query, skipValidateFlag } from "./validate-query-CcZVKYPV.mjs";
+import { connectionFlags, outputFlags, profileFlag, renderSummary } from "./capabilities-DrDJo_ng.mjs";
+import "./command-augment-D9pI9Vbh.mjs";
+import { defineMetabaseCommand } from "./runtime-B-c-Fc2i.mjs";
+import "./input-m9ctfLxZ.mjs";
+import "./embedding-CKdw8q7p.mjs";
+import "./field-DsXTeqBy.mjs";
+import "./parameter-BZ6y-Gfs.mjs";
+import { Card, CardUpdateInput, cardView } from "./card-B8G5jQQT.mjs";
+import { parseId } from "./parse-id-DfY0Lugw.mjs";
+import { readBody } from "./body-C1_AaTS4.mjs";
+import { bodyInputFlags } from "./body-flags-CgHgJBRC.mjs";
+import "./validate-clAWO3X-.mjs";
+import { CARD_DATASET_QUERY_LABELS, preflightMbql5Query, skipValidateFlag } from "./validate-query-CsK2_2_u.mjs";
 
 //#region src/commands/card/update.ts
 var update_default = defineMetabaseCommand({
@@ -19,7 +18,7 @@ var update_default = defineMetabaseCommand({
 		name: "update",
 		description: "Update a card by id (partial)"
 	},
-	details: "Patches only the fields you send (any of `name`, `display`, `dataset_query`, `collection_id`, `archived`, …). When `dataset_query` is an MBQL 5 query it is checked against a bundled JSON Schema before sending; pass --skip-validate to bypass.",
+	details: "Patches only the fields you send (any of `name`, `display`, `dataset_query`, `collection_id`, `archived`, …). When `dataset_query` is an MBQL 5 query it is checked against a bundled JSON Schema (print it with `mb query --print-schema`) before sending; pass --skip-validate to bypass.",
 	skills: [{
 		skill: "mbql",
 		purpose: "author the dataset_query"
@@ -40,6 +39,7 @@ var update_default = defineMetabaseCommand({
 			required: true
 		}
 	},
+	inputSchema: CardUpdateInput,
 	outputSchema: Card,
 	examples: [
 		"cat patch.json | mb card update 1",

package/dist/{update-Ck0Kxv8u.mjs → update-Sz0QRGWB.mjs}

@@ -1,13 +1,11 @@
-import "./notice-DyVl5aYB.mjs";
-import { connectionFlags, outputFlags, profileFlag } from "./error-5H_tcfL8.mjs";
-import "./command-augment-DdZIfx1V.mjs";
-import { defineMetabaseCommand } from "./runtime-BJtuxWM8.mjs";
-import { renderSummary } from "./capabilities-N0jo5U7S.mjs";
-import "./input-7Sj85_K7.mjs";
-import { parseId } from "./parse-id-D4LeTUsP.mjs";
-import { readBody } from "./body-IcJ5kFtk.mjs";
-import { bodyInputFlags } from "./body-flags-DWTTxJpP.mjs";
-import { Snippet, SnippetUpdateInput, snippetView } from "./snippet-CtA2Pkoa.mjs";
+import { connectionFlags, outputFlags, profileFlag, renderSummary } from "./capabilities-DrDJo_ng.mjs";
+import "./command-augment-D9pI9Vbh.mjs";
+import { defineMetabaseCommand } from "./runtime-B-c-Fc2i.mjs";
+import "./input-m9ctfLxZ.mjs";
+import { parseId } from "./parse-id-DfY0Lugw.mjs";
+import { readBody } from "./body-C1_AaTS4.mjs";
+import { bodyInputFlags } from "./body-flags-CgHgJBRC.mjs";
+import { Snippet, SnippetUpdateInput, snippetView } from "./snippet-DWiXNy4T.mjs";
 
 //#region src/commands/snippet/update.ts
 var update_default = defineMetabaseCommand({
@@ -27,6 +25,7 @@ var update_default = defineMetabaseCommand({
 			required: true
 		}
 	},
+	inputSchema: SnippetUpdateInput,
 	outputSchema: Snippet,
 	examples: [
 		"cat patch.json | mb snippet update 1",

package/dist/{update-dashcard-CZUWZhal.mjs → update-dashcard-CfDpy7Lz.mjs}

@@ -1,14 +1,13 @@
-import { ConfigError } from "./notice-DyVl5aYB.mjs";
-import { connectionFlags, outputFlags, profileFlag } from "./error-5H_tcfL8.mjs";
-import "./command-augment-DdZIfx1V.mjs";
-import { defineMetabaseCommand } from "./runtime-BJtuxWM8.mjs";
-import { renderSummary } from "./capabilities-N0jo5U7S.mjs";
-import "./input-7Sj85_K7.mjs";
-import "./parameter-CiJ4CwWE.mjs";
-import { parseId } from "./parse-id-D4LeTUsP.mjs";
-import { readBody } from "./body-IcJ5kFtk.mjs";
-import { bodyInputFlags } from "./body-flags-DWTTxJpP.mjs";
-import { DashboardDetail, Dashcard, DashcardPatchInput, dashcardView } from "./dashboard-DOplbKyQ.mjs";
+import { ConfigError, connectionFlags, outputFlags, profileFlag, renderSummary } from "./capabilities-DrDJo_ng.mjs";
+import "./command-augment-D9pI9Vbh.mjs";
+import { defineMetabaseCommand } from "./runtime-B-c-Fc2i.mjs";
+import "./input-m9ctfLxZ.mjs";
+import "./embedding-CKdw8q7p.mjs";
+import "./parameter-BZ6y-Gfs.mjs";
+import { parseId } from "./parse-id-DfY0Lugw.mjs";
+import { readBody } from "./body-C1_AaTS4.mjs";
+import { bodyInputFlags } from "./body-flags-CgHgJBRC.mjs";
+import { DashboardDetail, Dashcard, DashcardPatchInput, dashcardView } from "./dashboard-B-MTpfeS.mjs";
 
 //#region src/commands/dashboard/update-dashcard.ts
 var update_dashcard_default = defineMetabaseCommand({
@@ -33,6 +32,7 @@ var update_dashcard_default = defineMetabaseCommand({
 			required: true
 		}
 	},
+	inputSchema: DashcardPatchInput,
 	outputSchema: Dashcard,
 	examples: [
 		"mb dashboard update-dashcard 1 5 --body '{\"row\":2,\"col\":0}'",

package/dist/{update-7DacwIvi.mjs → update-zfLbmC-H.mjs}

@@ -1,13 +1,11 @@
-import "./notice-DyVl5aYB.mjs";
-import { connectionFlags, outputFlags, profileFlag } from "./error-5H_tcfL8.mjs";
-import "./command-augment-DdZIfx1V.mjs";
-import { defineMetabaseCommand } from "./runtime-BJtuxWM8.mjs";
-import { renderSummary } from "./capabilities-N0jo5U7S.mjs";
-import "./input-7Sj85_K7.mjs";
-import { parseId } from "./parse-id-D4LeTUsP.mjs";
-import { readBody } from "./body-IcJ5kFtk.mjs";
-import { bodyInputFlags } from "./body-flags-DWTTxJpP.mjs";
-import { TransformTag, TransformTagUpdateInput, transformTagView } from "./transform-tag-rsIrckCM.mjs";
+import { connectionFlags, outputFlags, profileFlag, renderSummary } from "./capabilities-DrDJo_ng.mjs";
+import "./command-augment-D9pI9Vbh.mjs";
+import { defineMetabaseCommand } from "./runtime-B-c-Fc2i.mjs";
+import "./input-m9ctfLxZ.mjs";
+import { parseId } from "./parse-id-DfY0Lugw.mjs";
+import { readBody } from "./body-C1_AaTS4.mjs";
+import { bodyInputFlags } from "./body-flags-CgHgJBRC.mjs";
+import { TransformTag, TransformTagUpdateInput, transformTagView } from "./transform-tag-wFiWmiyO.mjs";
 
 //#region src/commands/transform-tag/update.ts
 var update_default = defineMetabaseCommand({
@@ -27,6 +25,7 @@ var update_default = defineMetabaseCommand({
 			required: true
 		}
 	},
+	inputSchema: TransformTagUpdateInput,
 	outputSchema: TransformTag,
 	examples: [
 		"mb transform-tag update 5 --body '{\"name\":\"renamed\"}'",

package/dist/{upgrade-CBW8V9qZ.mjs → upgrade-BWl0VjMK.mjs}

@@ -1,10 +1,8 @@
-import { AbortError, NetworkError, TimeoutError, UnknownError, errorMessage } from "./notice-DyVl5aYB.mjs";
-import { outputFlags, package_default } from "./error-5H_tcfL8.mjs";
-import "./command-augment-DdZIfx1V.mjs";
-import { HttpError, USER_AGENT, combineAborts, defineMetabaseCommand, parseJson, throwIfAborted } from "./runtime-BJtuxWM8.mjs";
-import { renderItem, writeText } from "./capabilities-N0jo5U7S.mjs";
-import { promptConfirm } from "./prompt-C85xd9HR.mjs";
-import { streamProcess } from "./process-j8UHMHc2.mjs";
+import { AbortError, NetworkError, TimeoutError, UnknownError, errorMessage, outputFlags, package_default, renderItem, writeText } from "./capabilities-DrDJo_ng.mjs";
+import "./command-augment-D9pI9Vbh.mjs";
+import { HttpError, USER_AGENT, combineAborts, defineMetabaseCommand, parseJson, throwIfAborted } from "./runtime-B-c-Fc2i.mjs";
+import { promptConfirm } from "./prompt-ZG9Drin_.mjs";
+import { streamProcess } from "./process-D5HN1wpT.mjs";
 import { z } from "zod";
 import { realpathSync } from "node:fs";
 import { compare, valid } from "semver";

package/dist/upload-CPzOhGeX.mjs

@@ -0,0 +1,16 @@
+import "./command-augment-D9pI9Vbh.mjs";
+import { defineCommandGroup } from "./group-CILtQqCL.mjs";
+
+//#region src/commands/upload/index.ts
+var upload_default = defineCommandGroup({
+	name: "upload",
+	description: "Upload CSV files into Metabase",
+	subCommands: {
+		csv: () => import("./csv-T6_vlLJS.mjs").then((m) => m.default),
+		append: () => import("./append-DY1-O789.mjs").then((m) => m.default),
+		replace: () => import("./replace-CFzqkZXs.mjs").then((m) => m.default)
+	}
+});
+
+//#endregion
+export { upload_default as default };

package/dist/{uuid-D6JVJ-R1.mjs → uuid-D_YeqDui.mjs}

@@ -1,8 +1,6 @@
-import { ConfigError } from "./notice-DyVl5aYB.mjs";
-import { outputFlags } from "./error-5H_tcfL8.mjs";
-import "./command-augment-DdZIfx1V.mjs";
-import { defineMetabaseCommand, parseInteger } from "./runtime-BJtuxWM8.mjs";
-import { writeJson, writeText } from "./capabilities-N0jo5U7S.mjs";
+import { ConfigError, outputFlags, writeJson, writeText } from "./capabilities-DrDJo_ng.mjs";
+import "./command-augment-D9pI9Vbh.mjs";
+import { defineMetabaseCommand, parseInteger } from "./runtime-B-c-Fc2i.mjs";
 import { z } from "zod";
 import { randomUUID } from "node:crypto";
 

package/dist/{validate-BqNW4Sk1.mjs → validate-clAWO3X-.mjs}

@@ -1,5 +1,4 @@
-import { ConfigError, escapeJsonPointerSegment } from "./notice-DyVl5aYB.mjs";
-import { isPlainObject } from "./capabilities-N0jo5U7S.mjs";
+import { ConfigError, escapeJsonPointerSegment, isPlainObject } from "./capabilities-DrDJo_ng.mjs";
 import { z } from "zod";
 import Ajv2020 from "ajv/dist/2020.js";
 import addFormats from "ajv-formats";

package/dist/{validate-query-CcZVKYPV.mjs → validate-query-CsK2_2_u.mjs}

@@ -1,6 +1,5 @@
-import { ConfigError } from "./notice-DyVl5aYB.mjs";
-import { writeJson } from "./capabilities-N0jo5U7S.mjs";
-import { assertNotLegacyEnvelopeWrappingMbql5, isMbql5Query, validateQuery } from "./validate-BqNW4Sk1.mjs";
+import { ConfigError, writeJson } from "./capabilities-DrDJo_ng.mjs";
+import { assertNotLegacyEnvelopeWrappingMbql5, isMbql5Query, validateQuery } from "./validate-clAWO3X-.mjs";
 
 //#region src/commands/validate-query.ts
 const skipValidateFlag = { "skip-validate": {

package/dist/{values-DBvuGnnA.mjs → values-DSk8ZJ3B.mjs}

@@ -1,10 +1,8 @@
-import "./notice-DyVl5aYB.mjs";
-import { connectionFlags, outputFlags, profileFlag } from "./error-5H_tcfL8.mjs";
-import "./command-augment-DdZIfx1V.mjs";
-import { defineMetabaseCommand } from "./runtime-BJtuxWM8.mjs";
-import { formatScalar, renderSummary } from "./capabilities-N0jo5U7S.mjs";
-import { FieldValues, fieldValuesView } from "./field-CMY_LWUe.mjs";
-import { parseId } from "./parse-id-D4LeTUsP.mjs";
+import { connectionFlags, formatScalar, outputFlags, profileFlag, renderSummary } from "./capabilities-DrDJo_ng.mjs";
+import "./command-augment-D9pI9Vbh.mjs";
+import { defineMetabaseCommand } from "./runtime-B-c-Fc2i.mjs";
+import { FieldValues, fieldValuesView } from "./field-DsXTeqBy.mjs";
+import { parseId } from "./parse-id-DfY0Lugw.mjs";
 
 //#region src/commands/field/values.ts
 var values_default = defineMetabaseCommand({

package/dist/{verify-LIShMNZ2.mjs → verify-DkQdLjf3.mjs}

@@ -1,5 +1,5 @@
-import { MetabaseError, NetworkError, TimeoutError, errorMessage } from "./notice-DyVl5aYB.mjs";
-import { HttpError, createClient, probeServer } from "./runtime-BJtuxWM8.mjs";
+import { MetabaseError, NetworkError, TimeoutError, errorMessage } from "./capabilities-DrDJo_ng.mjs";
+import { HttpError, createClient, probeServer } from "./runtime-B-c-Fc2i.mjs";
 import { z } from "zod";
 
 //#region src/domain/user.ts

package/dist/{wait-DUHze3_B.mjs → wait-DvSsMjea.mjs}

@@ -1,11 +1,9 @@
-import "./notice-DyVl5aYB.mjs";
-import { connectionFlags, outputFlags, profileFlag } from "./error-5H_tcfL8.mjs";
-import "./command-augment-DdZIfx1V.mjs";
-import { defineMetabaseCommand } from "./runtime-BJtuxWM8.mjs";
-import { renderSummary } from "./capabilities-N0jo5U7S.mjs";
-import { parseId } from "./parse-id-D4LeTUsP.mjs";
-import { DEFAULT_INTERVAL_MS, DEFAULT_TIMEOUT_MS } from "./poll-BpAJpvb-.mjs";
-import { SyncTaskOrIdle, formatSyncTask, pollSyncTask, syncTaskIdleView, syncTaskView, throwIfFailedTask } from "./poll-task-TilgciQn.mjs";
+import { connectionFlags, outputFlags, profileFlag, renderSummary } from "./capabilities-DrDJo_ng.mjs";
+import "./command-augment-D9pI9Vbh.mjs";
+import { defineMetabaseCommand } from "./runtime-B-c-Fc2i.mjs";
+import { parseId } from "./parse-id-DfY0Lugw.mjs";
+import { DEFAULT_INTERVAL_MS, DEFAULT_TIMEOUT_MS } from "./poll-D1Yg78c3.mjs";
+import { SyncTaskOrIdle, formatSyncTask, pollSyncTask, syncTaskIdleView, syncTaskView, throwIfFailedTask } from "./poll-task-DLUZaglY.mjs";
 
 //#region src/commands/git-sync/wait.ts
 const WaitResult = SyncTaskOrIdle;

package/dist/{wait-flags-Ybpt98PK.mjs → wait-flags-dXGThljd.mjs}

@@ -1,5 +1,5 @@
-import { parseId } from "./parse-id-D4LeTUsP.mjs";
-import { DEFAULT_INTERVAL_MS, DEFAULT_TIMEOUT_MS } from "./poll-BpAJpvb-.mjs";
+import { parseId } from "./parse-id-DfY0Lugw.mjs";
+import { DEFAULT_INTERVAL_MS, DEFAULT_TIMEOUT_MS } from "./poll-D1Yg78c3.mjs";
 
 //#region src/commands/wait-flags.ts
 const waitScheduleFlags = {

package/package.json

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

package/skill-data/core/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: core
-description: Foundations for driving Metabase from the terminal with the `mb` CLI — authentication and named profiles, the flag/output/`--json` conventions every command shares, JSON body input, command discovery via `mb __manifest`, and the per-resource footguns (db, table, field, card, dashboard, collection, segment, measure, library, setting, search, eid). Load first for any `mb` task; it routes to the specialized skills for deeper work.
+description: Foundations for driving Metabase from the terminal with the `mb` CLI — authentication and named profiles, the flag/output/`--json` conventions every command shares, JSON body input, command discovery via `--help` (add `--json` for machine-readable schemas), and the per-resource footguns (db, table, field, upload, card, dashboard, collection, segment, measure, library, setting, search, eid). Load first for any `mb` task; it routes to the specialized skills for deeper work.
 allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
 ---
 
@@ -11,11 +11,11 @@ The official Metabase CLI (`mb`) drives a Metabase instance over its REST API: a
 Top-level command groups (run `mb <group> --help` to discover verbs):
 
 ```
-auth | db | table | field | query | card | dashboard | snippet | segment | measure | collection | library
+auth | db | table | field | upload | query | card | dashboard | snippet | segment | measure | collection | library
 document | transform | transform-job | transform-tag | setting | search | git-sync | setup | eid | uuid | upgrade | skills
 ```
 
-The conventions below — auth, flags, output, body input — hold across **every** group. Per-command flags, examples, and output schemas live in `mb __manifest`. A few flows have their own skills (see "Specialized skills"). When a card needs a query, prefer MBQL over native SQL (portable, pre-flight-validated — load `mbql`); fall back to native SQL when MBQL can't express it.
+The conventions below — auth, flags, output, body input — hold across **every** group. Per-command flags and examples live in each command's `--help`; add `--json` for the machine-readable form with the output JSON Schema. A few flows have their own skills (see "Specialized skills"). When a card needs a query, prefer MBQL over native SQL (portable, pre-flight-validated — load `mbql`); fall back to native SQL when MBQL can't express it.
 
 ## Auth & profiles
 
@@ -59,22 +59,25 @@ Every list/get verb supports the same output flags:
 - `--json` — emit the full JSON envelope, safe for `jq`. Default is human-readable text.
 - `--full` — include every field (the compact projection is the default, and is the agent-facing contract).
 - `--fields a,b.c.d` — project specific dot-paths. Mutually exclusive with `--full`. **Paths are relative to each `data[]` item on list verbs, and to the root on single-item verbs.** So it's `--fields id,name` on `… list` / `database schema-tables` (`data.id` and `data[].id` both fail with `unknown field path: "data.id"`), and `--fields id,name,display` on `card get`, `--fields data.rows` on `mb query` (whose `data` is an object).
-- `--max-bytes <n>` — cap **list** output size (drops trailing items, sets `truncated`). Default 65536; `0` disables. Single-item commands (`get`, `metadata`) never truncate — when their output exceeds the cap they throw a `ConfigError` (exit 2: "output is N bytes, over the M-byte --max-bytes cap…"); raise `--max-bytes` or narrow with `--fields`.
+- `--max-bytes <n>` — cap **list** output size (drops trailing items, sets `truncated`). Default 24576 (sized to fit under agent-harness tool-output limits); `0` disables. Single-item commands (`get`) never truncate — when their output exceeds the cap they throw a `ConfigError` (exit 2: "output is N bytes, over the M-byte --max-bytes cap; …") whose tail names the remedy: on schema-shaped commands it is the exact narrower command to run instead — follow it rather than raising the cap.
+- JSON output is a single line when stdout is piped (pretty-printed only at a TTY) — always parse it, never scrape by line position.
 
-List envelope shape:
+List envelope shape (metadata first, so counts and the truncation marker survive if a consumer cuts the tail):
 
 ```json
 {
-  "data": [
-    /* items */
-  ],
   "returned": 10,
   "total": 42,
   "limit": 50,
-  "truncated": false
+  "truncated": { "reason": "max_bytes", "bytes": 123456 },
+  "data": [
+    /* items */
+  ]
 }
 ```
 
+`truncated` is present only when the cap dropped trailing items.
+
 `total` is best-effort and may be `null` (empty / permissions-filtered collections, or `--limit` early-stop); use `returned` for the count you got and `data.length` for the rendered slice.
 
 ## Body input (create / update / run)
@@ -99,28 +102,31 @@ Single-quoted `'EOF'` stops the shell interpolating `$vars` inside the JSON.
 
 Write working files to **`./.scratch`** in the current directory (`mkdir -p ./.scratch` first), never `/tmp` — better permissions, they persist across the session, and the user can review them.
 
-## Discover the full surface: `mb __manifest`
+## Discovering commands and schemas
+
+Cheapest source that answers the question wins:
 
-The canonical, machine-readable inventory of every command — name, description, per-command `details`, examples, every flag with type and default, and the output JSON Schema:
+- What groups/verbs exist? → `mb --help`, then `mb <group> --help`. Add `--json` for a machine-readable `{command, description}` index (`mb --help --json` lists every command).
+- What flags does a command take? → `mb <command> --help` — flags with enums and defaults, examples, ~1 KB.
+- Output JSON Schema before parsing, JSON-body input schema before authoring, machine-readable arg types, min server version? → `mb <command> --help --json` — that command's full entry (`inputSchema` is the exact validator the command runs on the body; `null` when it takes none).
 
 ```bash
-mb __manifest | jq -r '.commands[].command'                                                  # every command name
-mb __manifest | jq -r '.commands[] | select(.command | startswith("transform")) | .command'  # verbs under "transform"
-mb __manifest | jq '.commands[] | select(.command == "card query") | .args'                  # flags + types for a command
-mb __manifest | jq '.commands[] | select(.command == "card list") | .outputSchema'           # output schema before parsing
+mb card query --help                                    # flags, enums, defaults, examples
+mb card list --help --json | jq .outputSchema           # output schema before parsing
+mb card create --help --json | jq .inputSchema          # body schema before authoring
+mb transform --help --json | jq -r '.commands[].command'  # verbs under "transform"
 ```
 
-The leading `__` hides it from `--help`, but it's stable. Reach for it instead of per-command `--help` to enumerate verbs, validate flag names, or read an output schema before parsing.
-
 ## Resource quirks worth memorizing
 
-Routine verb shapes (list / get / create / update), every flag, and output schemas live in `mb __manifest`. Below is only what the manifest does _not_ tell you: footguns and non-obvious behaviors.
+Routine verb shapes (list / get / create / update), every flag, and output schemas live in each command's `--help` (add `--json` for output schemas). Below is only what help does _not_ tell you: footguns and non-obvious behaviors.
 
-- **db traversal vs. rollup.** Default to granular: `database list` → `database schemas <db-id>` → `database schema-tables <db-id> <schema>` → `table get <table-id> --include fields`. The rollup endpoints (`database get --include tables.fields`, `database metadata <db-id>`) pull megabytes and blow the context window on any real warehouse — use them only on a small/dev db. `sync-schema` / `rescan-values` queue async work and return `{status:"ok"}` immediately; `sync-schema --wait` blocks until `initial_sync_status: complete`.
-- **table fields.** `table get` never returns fields on its own — pass `--include fields` (compact) or use `table fields <id>` (list envelope). `table metadata <id>` adds FKs + dimensions (heavier). `table update` patches table-level metadata only; physical columns aren't editable.
+- **db traversal: the hydration ladder.** Start with `database get <db-id> --include tables` — the compact table map (id, name, schema, description per table), one call that fits most databases. Pick the relevant tables, then `table fields <table-id>` per table (bounded: fields are per-table). `--include tables.fields` is the full rollup — small databases only; when either outgrows the cap the error message names the next command down the ladder. Hundreds of tables? Traverse by schema (`database schemas <db-id>` → `database schema-tables <db-id> <schema>`) or look tables up by name (`search <term> --models table --db-id <db-id> --limit 10`). `sync-schema` / `rescan-values` queue async work and return `{status:"ok"}` immediately; `sync-schema --wait` blocks until `initial_sync_status: complete`.
+- **table fields.** `table get` never returns fields on its own — pass `--include fields` (compact; the underlying query_metadata response also carries FK targets and dimensions, visible under `--full`) or use `table fields <id>` (list envelope). `table update` patches table-level metadata only; physical columns aren't editable.
 - **field has no `list`.** Fields are per-table — get them via `table get <id> --include fields`. Never enumerate fields across a whole db (context blow-up). `field summary` is live cardinality `{field_id, count, distincts}`; `field values` is the cached distinct set (`has_more_values: true` ⇒ truncated cache). `field update` patches metadata only (`base_type` isn't editable) — this is where you set a column's `semantic_type` or foreign-key target.
+- **upload (CSV → tables).** `upload csv --file <path>` creates a new table + model (prints `{model_id, table_id}`); `upload append <table-id>` / `upload replace <table-id> --file <path>` add to / overwrite a table **previously created by upload** (columns must match). The destination db+schema is admin-configured, not per-call — check with `mb setting get uploads-settings --json` (`db_id: null` ⇒ uploads off/unconfigured; needs admin to read). `--collection <id|root>` only sets the model's collection. Max 50 MB. Errors: **"The uploads database is not configured."** = no db has uploads enabled; **"Uploads are not enabled."** = the append/replace target isn't an uploaded table.
 - **card.** `dataset_query` is the **flat** `mbql/query` value, not a legacy `{type:"query",query:…}` envelope (→ `mbql`). `--export-format csv|xlsx` streams the raw export (pipe to a file), bypassing the JSON envelope. `archive` is the only delete; unarchive with `update --body '{"archived":false}'`. `visualization_settings` keys are scoped by `display` and aren't pre-flighted — see `visualization`.
-- **dashboard.** Dashcards round-trip through `PUT /api/dashboard/:id` (no per-dashcard endpoint): `update-dashcard <dash-id> <dashcard-id>` patches one safely; `update --body '{"dashcards":[…]}'` replaces the whole set (omitted ids are deleted server-side; negative ids for new cards). `create` accepts the **same** `dashcards` array in its initial body — lay out the whole dashboard in one call: negative ids for new cards, and `card_id:null` plus a `visualization_settings.virtual_card` block (`{display:"text"|"heading"|"link"|…}`) for non-question cards. `create`/`update` pre-flight every positive `card_id` and exit **2** with `{ok:false,errors:[…]}` on a bad ref (non-bypassable). `dashboard get <id>` (or `--full`) hydrates dashcards/tabs; `list` omits them. **The grid is 24 columns wide:** each dashcard's `{col, row, size_x, size_y}` is in grid units — **full-width is `size_x: 24`** (`size_x: 12` is half a row, the usual cause of a card filling only half the width). Keep `col + size_x ≤ 24`, start a full-width stack's `col` at 0, and don't overlap (the server stores collisions as sent — no auto-fix).
+- **dashboard.** Dashcards round-trip through `PUT /api/dashboard/:id` (no per-dashcard endpoint): `update-dashcard <dash-id> <dashcard-id>` patches one safely; `update --body '{"dashcards":[…]}'` replaces the whole set (omitted ids are deleted server-side; negative ids for new cards). `create` accepts the **same** `dashcards` array in its initial body — lay out the whole dashboard in one call: negative ids for new cards, and `card_id:null` plus a `visualization_settings.virtual_card` block (`{display:"text"|"heading"|"link"|…}`) for non-question cards. `create`/`update` pre-flight every positive `card_id` and exit **2** with `{ok:false,errors:[…]}` on a bad ref (non-bypassable). `dashboard get <id>` (or `--full`) hydrates dashcards/tabs; `list` omits them. **The grid is 24 columns wide:** each dashcard's `{col, row, size_x, size_y}` is in grid units — **full-width is `size_x: 24`** (`size_x: 12` is half a row, the usual cause of a card filling only half the width). Keep `col + size_x ≤ 24`, start a full-width stack's `col` at 0, and don't overlap (the server stores collisions as sent — no auto-fix). Layout patterns and per-chart default sizes → the `dashboard` skill; load it before composing any `dashcards` array.
 - **dashboard parameters (filters).** A dashboard's `parameters` array holds its filter widgets; they're part of the dashboard record, so read them with `dashboard get <id> --fields parameters --json` (no separate verb). **Editing replaces the _whole_ array** (like dashcards), so it's a read-modify-write loop: pull the current set with `dashboard get <id> --fields parameters --json`, add/change entries, and send the full array back via `dashboard update --body '{"parameters":[…]}'` (or supply it in `create`). Omitting a parameter deletes it. Each parameter is `{id, type, …}`. **`id` is a descriptive slug-like string you pick (e.g. `order_status`), unique within this dashboard — Metabase stores any non-blank string verbatim. Do NOT invent a random/opaque id by guessing; reuse the `slug`. If you genuinely need an opaque id, mint one with `mb uuid` — never fabricate one.** `type` is a **closed enum**; an unlisted value is a hard parse error that echoes the full allowed set back to you: string ops `string/=` `string/!=` `string/contains` `string/does-not-contain` `string/starts-with` `string/ends-with`; number ops `number/=` `number/!=` `number/between` `number/>=` `number/<=`; date `date/single` `date/range` `date/relative` `date/month-year` `date/quarter-year` `date/all-options`; plus `category`, `id`, `boolean/=`, `temporal-unit`, and bare `number`/`text`/`date`/`boolean`. A parameter only filters a card once it is **mapped**: each dashcard's `parameter_mappings` is `[{parameter_id, target}]` where `parameter_id` must match a parameter's `id` exactly, and `target` is `["dimension", ["field", <field-id>, null]]` for an MBQL card column, `["dimension", ["template-tag", "<tag>"]]` for a native field-filter tag, or `["variable", ["template-tag", "<tag>"]]` for a native raw-value tag. Populate a dropdown with `values_source_type`: `"static-list"` + `values_source_config.values`, or `"card"` + `{card_id, value_field, label_field}`; omit it to pull live distinct values from the mapped field. `dashboard parameter-values <id> <parameter-id> [--query <substr>]` fetches those selectable values (`{values, has_more_values}`); `--query` is a case-insensitive substring search.
 - **snippet `--archived` is a swap, not a union** — list returns _either_ active _or_ archived rows, never both. (Same for `--filter archived` on dashboard/collection.)
 - **segment / measure.** `update` and `archive` require a non-blank `revision_message` (audit-logged); the CLI does not synthesize it on `update`. `archive` defaults to `"Archived via mb CLI"` — override with `--revision-message`. `definition` is a flat MBQL clause (→ `mbql`): segment = a filter, measure = exactly one aggregation.
@@ -131,14 +137,17 @@ Routine verb shapes (list / get / create / update), every flag, and output schem
 - **setup is one-shot.** `mb setup` walks `/api/setup` for a **fresh** instance only — errors against an already-configured one. Mostly for bootstrapping local / e2e instances.
 - **eid** translates a string entity id → numeric id: `mb eid --model <model> <eid1,eid2> --json`. Entity ids are NanoIDs that can start with `-`, which the positional form misreads as a flag (shell quotes don't help) — for those, use `--body '{"entity_ids":{"card":["-…"]}}'` (the id is a JSON string value, immune to flag parsing).
 - **library.** EE-only (`library` premium feature, v59+). The Library is a curated subtree (`library-data` "Data" + `library-metrics` "Metrics" under a `library` root): tables published to **Data** appear first in data pickers and rank up in search; metrics saved to **Metrics** are prioritized in nav, search, and the query builder — it's how you tell people (and agents) "start from these, they're trusted." `library get` shows the Library and its Data/Metrics collection ids; `library create` provisions it (idempotent). `library publish --table-ids/--db-ids/--schemas` publishes tables into Data — it **resolves the Data collection itself and creates the Library if absent** (no collection id to find); each `--schemas` entry is `<db-id>:<schema>` (e.g. `1:public`), not a bare name. `publish` cascades to upstream FK dependencies, `unpublish` to downstream dependents; both need **admin or data-analyst** (Curate alone won't publish) and exit **403** without write **and** query permission on every affected table. Publish status shows on the table: `table get`/`table list` carry `is_published` (`collection_id` under `--full`). Good candidates are finished, analysis-ready tables — clean/combine via transforms first, then publish the polished result.
-- **query / uuid.** `mb query` is the ad-hoc MBQL surface (`--print-schema` → `--dry-run` → run); `mb uuid --count <n>` mints the `lib/uuid` values every MBQL 5 clause needs. Both live in `mbql`.
+- **query / uuid.** `mb query` is the ad-hoc MBQL surface (`--print-schema` → `--dry-run` → run); `mb uuid --count <n>` mints the `lib/uuid` values MBQL clauses need. Both live in `mbql`.
 
 ## Specialized skills (load on demand)
 
 This file is enough for any single-command task. For anything deeper, load the relevant skill **proactively** — don't wing an MBQL body, a transform body, or the git-sync workflow from this overview. Load via `mb skills get <name>`.
 
 - **`mbql`** — authoring/fixing any MBQL query body (`mb query`, card `dataset_query`, transform `source.query`, measure/segment `definition`); reading `--dry-run` errors. The query-body reference.
+- **`native-sql`** — authoring a native SQL `dataset_query` with parameters: template tags, field filters vs. raw variables, snippets, card references, and wiring a tag to a dashboard filter. The SQL fallback when MBQL can't express it (`mbql` first).
 - **`visualization`** — choosing a card's `display` and authoring `visualization_settings`. The presentation counterpart to `mbql`.
+- **`dashboard`** — building interactive dashboards: wiring filters (parameters + mappings), linked/cascading filters, cross-filtering, click behavior, series, and tabs. Load beyond a plain card-layout task.
+- **`metadata`** — setting field/table metadata: semantic types, foreign-key targets, dropdown/scan behavior, and column visibility, and the downstream features each unlocks. Load when editing what a column _means_, not its data.
 - **`transform`** — transform body JSON, create + run-with-wait, run inspection, tags, jobs.
 - **`document`** — Metabase documents (TipTap body, embedding cards).
 - **`git-sync`** — round-tripping content to/from a git remote.