@metabase/cli 0.5.6 → 0.5.7

package/skill-data/data-action/SKILL.md

@@ -1,16 +1,21 @@
 ---
 name: data-action
-description: Author and run Metabase data actions with the `mb` CLI — saved, parameterized native SQL writes (INSERT, UPDATE, DELETE) filed in a collection and run with values. Covers enabling them on a database, the collection they go in, the body, mapping template tags to parameters, running, and the lifecycle. Triggers — "add a data action", "let users update a row", "a button that inserts a record", "run a write query", "a form that saves to the database", "delete rows from Metabase". Inside a data app, start with `data-app-actions`.
+description: Author and run Metabase data actions with the `mb` CLI — table actions that insert, update or delete one row of a table, and query actions that run a parameterized native SQL write (INSERT, UPDATE, DELETE), filed in a collection and run with values. Covers enabling them on a database, picking the type, the collection they go in, each type's body and parameters, running, and the lifecycle. Triggers — "add a data action", "let users update a row", "a button that inserts a record", "add a record to a table", "run a write query", "a form that saves to the database", "delete rows from Metabase". Inside a data app, start with `data-app-actions`.
 allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
 requires: [dataActionsWithoutModel]
 ---
 
 # Data actions
 
-A **data action** is one native SQL statement that writes — `INSERT`, `UPDATE` or `DELETE` — with named inputs. It lives in a collection, and dashboards, apps and `mb data-action execute` run it with values.
+A **data action** writes to a database with named inputs. A **table action** (`type: "implicit"`) inserts, updates or deletes one row of a table; a **query action** (`type: "query"`) runs one native SQL statement — `INSERT`, `UPDATE` or `DELETE`. Either lives in a collection, and dashboards, apps and `mb data-action execute` run it with values.
 
 Flag conventions and `./.scratch` are in `core`; the native query and its template tags follow `native-sql`. This skill covers what a data action adds.
 
+## Pick the type
+
+- **Table action** (_Table actions_) for a write of one row by its primary key: insert a row, change some of its columns, delete it. There is no SQL to write.
+- **Query action** (_Query actions_) for anything else: a computed value (`now()`), several rows or tables, rows matched by another column, a table without exactly one primary key, or setting a column to `NULL`.
+
 ## Check the database first
 
 Data actions are off on every database until an admin turns on **Data actions** for it ("Allow data actions that use this database to be run", Admin → Databases → the database). That toggle is the database setting `database-enable-actions`.
@@ -30,7 +35,7 @@ A data action goes in a data actions collection, a data app collection, or the d
 mb collection create --namespace data-actions --body '{"name":"Order actions"}' --json
 ```
 
-## The body
+## Query actions
 
 Mint one template-tag `id` per tag with `mb uuid --count <n> --format text`.
 
@@ -38,7 +43,6 @@ Mint one template-tag `id` per tag with `mb uuid --count <n> --format text`.
 {
   "name": "Set order note",
   "type": "query",
-  "database_id": 1,
   "collection_id": 12,
   "dataset_query": {
     "lib/type": "mbql/query",
@@ -87,12 +91,12 @@ Mint one template-tag `id` per tag with `mb uuid --count <n> --format text`.
 }
 ```
 
-- `type` is always `"query"`. Never set `model_id` or `type: "implicit"`; `mb data-action create` refuses both.
-- `database_id` and `dataset_query.database` are the same id (`mb db list`). `collection_id` is the data actions collection (here `12`); omit it for the data actions root.
+- Never set `model_id`; `mb data-action create` refuses it.
+- `dataset_query.database` is the database the action writes to (`mb db list`); Metabase takes the action's `database_id` from it. `collection_id` is the data actions collection (here `12`); omit it for the data actions root.
 - A template tag's `id` is a UUID, unique among the tags: the representation schema requires one.
 - One statement, no `;`. `create` and `update` validate `dataset_query` as `native-sql` does.
 
-## Parameters: one per template tag
+### Parameters: one per template tag
 
 Each `{{name}}` needs a `template-tags` entry and a `parameters` entry, all using the same name:
 
@@ -108,26 +112,54 @@ Each `{{name}}` needs a `template-tags` entry and a `parameters` entry, all usin
 - Set `required: true` on every input the statement cannot run without (`WHERE` keys, `NOT NULL` columns).
 - Wrap an optional input in `[[ … ]]` with `required: false`; the clause drops out when no value is given. This makes one action do partial updates: `UPDATE orders SET updated_at = now() [[, note = {{note}}]] [[, status = {{status}}]] WHERE id = {{order_id}}`.
 
+## Table actions
+
+```json
+{
+  "name": "Add customer",
+  "type": "implicit",
+  "kind": "row/create",
+  "table_id": 7,
+  "collection_id": 12
+}
+```
+
+- `kind` is `row/create`, `row/update` or `row/delete`; `table_id` comes from `mb table list --db-id <id>`. The table needs exactly one primary key, or create answers `An implicit action needs a table with exactly one primary key.`
+- In a data app's collection the table must also be published to the Library (`mb library publish`), or create answers `An implicit action in a data app's collection can write only to a table published to the Library.`
+- The body has no `dataset_query` or `parameters`: Metabase derives the parameters from the table's columns, without sensitive and retired ones. Each parameter `id` is its column name, slugified; `mb data-action get <id> --full --json` lists them.
+
+| `kind`       | Parameters                             | Answers                                                                 |
+| ------------ | -------------------------------------- | ----------------------------------------------------------------------- |
+| `row/create` | every column but an auto-increment key | `{"created-row": {...}}`: the new row's parameter columns, key included |
+| `row/update` | the key and every other column         | `{"rows-updated": 1}`                                                   |
+| `row/delete` | the key                                | `{"rows-deleted": 1}`                                                   |
+
+- `required` marks each `NOT NULL` column without a default, and the key of an update or delete. Execution itself checks only that an update or delete has the key; an insert without a `NOT NULL` column fails in the database.
+- An update writes only the columns given a value. A `null` value is dropped, so an update can't clear a column. A key that matches no row is refused: `Sorry, the row you're trying to update doesn't exist` (or `delete`).
+- `visualization_settings.fields.<parameter id>.hidden: true` hides a parameter: execution refuses a value for it, and a data app's `src/metabase.ts` leaves it out. Hide a column an insert needs only when the same field has a `defaultValue`.
+- A patch (_Lifecycle_) changes a query action's `dataset_query` or a table action's `kind` and `table_id`, never both.
+
 ## Run it
 
 ```bash
 mb data-action execute <id> --body '{"parameters":{"order_id":1042,"note":"rush delivery"}}'
 ```
 
-`parameters` is keyed by parameter `id`. The result is `{"rows-affected": <n>}`. A missing required value is refused. A run cannot be undone, so confirm with the user before running against data that matters, and test a new action on a row created for the purpose.
+`parameters` is keyed by parameter `id`. A query action refuses a missing required value and answers `{"rows-affected": <n>}`; a table action answers as _Table actions_ shows. A run cannot be undone, so confirm with the user before running against data that matters, and test a new action on a row created for the purpose.
 
 ## Lifecycle
 
-| Task                     | Command                                                                                  |
-| ------------------------ | ---------------------------------------------------------------------------------------- |
-| Find                     | `mb data-action list` (unarchived only), `mb search --models action <text>`              |
-| Inspect                  | `mb data-action get <id> --full --json`                                                  |
-| Change SQL, inputs, name | `mb data-action update <id> --file patch.json` (changed fields only)                     |
-| Move                     | `mb data-action update <id> --body '{"collection_id":<id>}'`                             |
-| Archive / restore        | `mb data-action archive <id>` / `mb data-action update <id> --body '{"archived":false}'` |
-| Delete                   | `mb data-action delete <id> --yes` (also removes the dashboard buttons that run it)      |
-
-Archiving or deleting a collection archives or deletes its data actions. Existing model-bound or implicit data actions still list, run and archive; leave them as they are.
+| Task                  | Command                                                                                  |
+| --------------------- | ---------------------------------------------------------------------------------------- |
+| Find                  | `mb data-action list` (unarchived only), `mb search --models action <text>`              |
+| Inspect               | `mb data-action get <id> --full --json`                                                  |
+| Change a query action | `mb data-action update <id> --file patch.json` (changed fields only)                     |
+| Change a table action | `mb data-action update <id> --body '{"kind":"row/update"}'` (or `table_id`)              |
+| Move                  | `mb data-action update <id> --body '{"collection_id":<id>}'`                             |
+| Archive / restore     | `mb data-action archive <id>` / `mb data-action update <id> --body '{"archived":false}'` |
+| Delete                | `mb data-action delete <id> --yes` (also removes the dashboard buttons that run it)      |
+
+Archiving or deleting a collection archives or deletes its data actions. Existing data actions of a model still list, run and archive; leave them as they are.
 
 ## Don't
 

package/skill-data/data-app-actions/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: data-app-actions
-description: Make a Metabase data app write data — an action in the app's collection, its typed definition in `src/metabase.ts`, and the `useAction` hook from `@metabase/embedding-sdk-react/data-app` behind a form or a button, with inputs typed from each parameter, the server's error shown as it comes, and every affected query refreshed. Triggers — "a form that saves a row", "a button that updates a record", "delete an entry from the app", "submit doesn't refresh the list", "the action fails in the app". Creating the action itself is `data-action`; reads are `data-app-data`.
+description: Make a Metabase data app write data — an action in the app's collection (a table action that inserts, updates or deletes a row, or a SQL query action), its typed definition in `src/metabase.ts`, and the `useAction` hook from `@metabase/embedding-sdk-react/data-app` behind a form or a button, with inputs typed from each parameter, the server's error shown as it comes, and every affected query refreshed. Triggers — "a form that saves a row", "a button that updates a record", "delete an entry from the app", "submit doesn't refresh the list", "the action fails in the app". Creating the action itself is `data-action`; reads are `data-app-data`.
 allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
 requires: [dataApps]
 ---
 
 # Writes in a data app
 
-An **action** is a saved, parameterized SQL write — `INSERT`, `UPDATE` or `DELETE`. A data app runs only the actions in **the app's collection** (`data-app`, _Create the app_).
+An **action** is a table action, which inserts, updates or deletes one row of a table, or a query action, a saved SQL write (`data-action`). A data app runs only the actions in **the app's collection** (`data-app`, _Create the app_).
 
-1. Draft the action as `data-action` describes — the database must allow actions — with `collection_id` the app's collection. Show the user its SQL and parameters, and create it once they agree.
+1. Draft the action as `data-action` describes, with `collection_id` the app's collection: the database must allow actions, and a table action's table must be published to the Library, as every table the app reads is. Pick the type as `data-action`, _Pick the type_, says. Show the user the table and kind, or the SQL, and the parameters; create it once they agree.
 2. Regenerate `src/metabase.ts` (`data-app-data`).
 3. Pass `actions.<name>` from it to `useAction`.
 
@@ -29,7 +29,7 @@ const { execute, isExecuting, result, error, reset } = useAction(actions.setOrde
 - **Import it from `/data-app`.** The main `@metabase/embedding-sdk-react` entry exports the general SDK `useAction`, which takes raw ids and isn't typed from the definition. Write no generics: the definition types `execute`'s keys and values.
 - `execute(params)` resolves to the response body; on failure it both throws and sets `error`. It resolves to `null` without sending anything while the SDK is still starting, so guard a call that can happen at mount. It never runs on its own and has no `enabled`: return early in the handler to skip it.
 - `isExecuting` is true until it settles: disable the trigger and show progress, so a double click can't send twice.
-- `result` is the last response, `null` before the first call; `result?.["rows-affected"]` is a quick confirmation. `reset()` clears `result` and `error`, for example when the user dismisses a message.
+- `result` is the last response, `null` before the first call; a query action answers `{"rows-affected": <n>}`, a table action `rows-updated`, `rows-deleted` or `created-row` (`data-action`, _Table actions_). `reset()` clears `result` and `error`, for example when the user dismisses a message.
 
 ## A form
 
@@ -76,9 +76,15 @@ export function NoteForm({ orderId, onSaved }: { orderId: number; onSaved: () =>
 | `Date`    | `type="date"`, or `datetime-local` when a time is expected |
 | `unknown` | `type="text"`, converted at the call                       |
 
+**Table actions.** The parameter slugs are the table's column names, slugified.
+
+- **Insert** (`row/create`): every column but an auto-increment key. `result["created-row"]` holds the new row's parameter columns, its key among them.
+- **Update** (`row/update`): the key and every other column, `required` on each `NOT NULL` one without a default. Start the form from the row's current values, read by the query on screen, and send them all. A `null` is dropped, so an update can't clear a column.
+- **Delete** (`row/delete`): the key only. Ask the viewer to confirm first.
+
 **Validation** is `required` on each required parameter and nothing else — no length, range or format checks of your own. Disable submit from the browser's verdict, `form.checkValidity()`, never from hand-rolled checks. Anything stricter comes back from the server.
 
-**Errors.** `error` is `{ status?, data: { message?, errors? }, isCancelled }` — read it without a cast. A failing SQL action comes back as a 500 whose `data.message` wraps the driver's text (`Error executing Action: …`): show it as it comes, in a `white-space: pre-wrap` element, since driver messages span lines — never "Something went wrong", `String(error)` or a friendlier paraphrase. `error.data.errors?.[parameterSlug]`, when present, goes beside its field (`aria-invalid` on the input).
+**Errors.** `error` is `{ status?, data: { message?, errors? }, isCancelled }` — read it without a cast. A failing query action comes back as a 500 whose `data.message` wraps the driver's text (`Error executing Action: …`): show it as it comes, in a `white-space: pre-wrap` element, since driver messages span lines — never "Something went wrong", `String(error)` or a friendlier paraphrase. A table action's refusals and constraint errors are 400s, shown the same way (`Sorry, the row you're trying to update doesn't exist`). `error.data.errors?.[parameterSlug]`, when present, goes beside its field (`aria-invalid` on the input).
 
 ## Refresh
 

package/dist/git-sync-Dje-mnMh.mjs

@@ -1,29 +0,0 @@
-import { t as defineCommandGroup } from "./group--6adAsqG.mjs";
-//#region src/commands/git-sync/index.ts
-var git_sync_default = defineCommandGroup({
-	name: "git-sync",
-	description: "Sync Metabase content with a git remote",
-	skills: [{
-		skill: "git-sync",
-		purpose: "import/export round-trip and dirty checks"
-	}],
-	subCommands: {
-		status: () => import("./status-4ewKKM1J.mjs").then((mod) => mod.default),
-		"is-dirty": () => import("./is-dirty-BRdzj548.mjs").then((mod) => mod.default),
-		"has-remote-changes": () => import("./has-remote-changes-DUCn8d5k.mjs").then((mod) => mod.default),
-		dirty: () => import("./dirty-BnuuGVxz.mjs").then((mod) => mod.default),
-		"current-task": () => import("./current-task-CpPUJYbQ.mjs").then((mod) => mod.default),
-		"cancel-task": () => import("./cancel-task-DMlaD81O.mjs").then((mod) => mod.default),
-		wait: () => import("./wait-DrOL01Y_.mjs").then((mod) => mod.default),
-		import: () => import("./import-Bnun0H8L.mjs").then((mod) => mod.default),
-		export: () => import("./export-C_G6D1MF.mjs").then((mod) => mod.default),
-		"export-preflight": () => import("./export-preflight-DeqCCYP0.mjs").then((mod) => mod.default),
-		stash: () => import("./stash-BMitlOt0.mjs").then((mod) => mod.default),
-		branches: () => import("./branches-iu9tRXr6.mjs").then((mod) => mod.default),
-		"create-branch": () => import("./create-branch-D56lVQNd.mjs").then((mod) => mod.default),
-		"add-collection": () => import("./add-collection-C_PXX4ls.mjs").then((mod) => mod.default),
-		"remove-collection": () => import("./remove-collection-p9OgcXQ0.mjs").then((mod) => mod.default)
-	}
-});
-//#endregion
-export { git_sync_default as default };

package/dist/table-BAOSPOlO.mjs

@@ -1,26 +0,0 @@
-import { t as defineCommandGroup } from "./group--6adAsqG.mjs";
-//#region src/commands/table/index.ts
-var table_default = defineCommandGroup({
-	name: "table",
-	description: "Manage Metabase tables",
-	skills: [{
-		skill: "metadata",
-		purpose: "table and column metadata, semantic types, visibility"
-	}],
-	subCommands: {
-		list: () => import("./list-D7oLTX1F.mjs").then((m) => m.default),
-		get: () => import("./get-BB0b96ox.mjs").then((m) => m.default),
-		fields: () => import("./fields-Ds2PnxA7.mjs").then((m) => m.default),
-		fks: () => import("./fks-CCKTcQ4c.mjs").then((m) => m.default),
-		update: () => import("./update-DRH78xMc.mjs").then((m) => m.default),
-		"sync-schema": () => import("./sync-schema-Dt0zekZR.mjs").then((m) => m.default),
-		"rescan-values": () => import("./rescan-values-DgUwDmwZ.mjs").then((m) => m.default),
-		"discard-values": () => import("./discard-values-CXyBp5pq.mjs").then((m) => m.default),
-		"bulk-edit": () => import("./bulk-edit-vWzm2uEj.mjs").then((m) => m.default),
-		"bulk-sync-schema": () => import("./bulk-sync-schema-neL4AxaB.mjs").then((m) => m.default),
-		"bulk-rescan-values": () => import("./bulk-rescan-values-qTNZkMRH.mjs").then((m) => m.default),
-		"bulk-discard-values": () => import("./bulk-discard-values-Bsdq0Aid.mjs").then((m) => m.default)
-	}
-});
-//#endregion
-export { table_default as default };

package/dist/transform-C8ZiOTWq.mjs

@@ -1,28 +0,0 @@
-import { t as defineCommandGroup } from "./group--6adAsqG.mjs";
-//#region src/commands/transform/index.ts
-var transform_default = defineCommandGroup({
-	name: "transform",
-	description: "Manage Metabase transforms",
-	skills: [{
-		skill: "transform",
-		purpose: "body shape, run-with-wait, iterate"
-	}, {
-		skill: "mbql",
-		purpose: "MBQL source.query bodies"
-	}],
-	subCommands: {
-		list: () => import("./list-jPZgEqWH.mjs").then((mod) => mod.default),
-		get: () => import("./get-R4_vq3U9.mjs").then((mod) => mod.default),
-		dependencies: () => import("./dependencies-CKT460jf.mjs").then((mod) => mod.default),
-		create: () => import("./create-DDEKafSb2.mjs").then((mod) => mod.default),
-		update: () => import("./update-D_9HdXGt.mjs").then((mod) => mod.default),
-		delete: () => import("./delete-DXL1orAc.mjs").then((mod) => mod.default),
-		"delete-table": () => import("./delete-table-RAznoioi.mjs").then((mod) => mod.default),
-		run: () => import("./run-BtRi59Hd.mjs").then((mod) => mod.default),
-		cancel: () => import("./cancel-DsyTp_jV.mjs").then((mod) => mod.default),
-		"get-run": () => import("./get-run-Ds50O2Rn.mjs").then((mod) => mod.default),
-		runs: () => import("./runs-hulvKxUw.mjs").then((mod) => mod.default)
-	}
-});
-//#endregion
-export { transform_default as default };

package/dist/transform-job-BKX10IUY.mjs

@@ -1,22 +0,0 @@
-import { t as defineCommandGroup } from "./group--6adAsqG.mjs";
-//#region src/commands/transform-job/index.ts
-var transform_job_default = defineCommandGroup({
-	name: "transform-job",
-	description: "Manage Metabase transform jobs",
-	skills: [{
-		skill: "transform",
-		purpose: "tag-driven job schedules"
-	}],
-	subCommands: {
-		list: () => import("./list-uDe8e-8m.mjs").then((mod) => mod.default),
-		get: () => import("./get-D3k4Pyfn.mjs").then((mod) => mod.default),
-		create: () => import("./create-C1DBXOxh.mjs").then((mod) => mod.default),
-		update: () => import("./update-eL6rSQvo2.mjs").then((mod) => mod.default),
-		delete: () => import("./delete-DHJ3ea0o.mjs").then((mod) => mod.default),
-		run: () => import("./run-qAs_RthF.mjs").then((mod) => mod.default),
-		transforms: () => import("./transforms-yuckjEH-.mjs").then((mod) => mod.default),
-		"set-active": () => import("./set-active-DaGUZCbh.mjs").then((mod) => mod.default)
-	}
-});
-//#endregion
-export { transform_job_default as default };