@metabase/cli 0.1.0-alpha.workspaces-commands.c1d5eea → 0.1.0-alpha.workspaces-commands.d9c31ec

package/README.md

@@ -271,39 +271,42 @@ metabase transform-job delete 1 --yes
 
 ## Databases
 
-Read warehouse metadata from `/api/database`. The `db` group exposes the full database list, the per-database record, hydrated metadata (tables + fields rolled up in one response), schema and table inspection, and the two manual-sync triggers.
+Read warehouse metadata from `/api/database`. The `db` group exposes the full database list, the per-database record, schema and table inspection, the two manual-sync triggers, and (rarely useful) full-warehouse rollup endpoints.
 
 `db` is aliased to `database`.
 
+> **Agent traversal:** prefer the granular path — `db list` → `db schemas <db-id>` → `db schema-tables <db-id> <schema>` → `table get <table-id> --include fields`. On a real warehouse (dozens of schemas, hundreds of tables, dozens of fields per table) the rollup commands (`db metadata`, `db get --include tables.fields`, `db list --include tables`) return megabytes of JSON and exhaust the agent context. Reach for them only on small/dev warehouses where you know the size up front.
+
 ### `metabase db list`
 
 ```sh
 metabase db list
 metabase db list --json
-metabase db list --include tables --full --json
 metabase db list --saved --json
+metabase db list --include tables --full --json   # rollup: every db with its full table list
 ```
 
-| Flag                | Description                                                                                                   |
-| ------------------- | ------------------------------------------------------------------------------------------------------------- |
-| `--include <which>` | Hydrate related entities. Currently only `tables` is supported (each database is returned with its `tables`). |
-| `--saved`           | Include the Saved Questions virtual database in the list. The virtual db has id `-1337` and no `engine`.      |
+| Flag                | Description                                                                                                                                                                                                          |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--include <which>` | Hydrate related entities. Currently only `tables` is supported (each database is returned with its `tables`). On real warehouses this returns hundreds of table records per db — use the granular traversal instead. |
+| `--saved`           | Include the Saved Questions virtual database in the list. The virtual db has id `-1337` and no `engine`.                                                                                                             |
 
 ### `metabase db get <id>`
 
 ```sh
 metabase db get 1
 metabase db get 1 --json
-metabase db get 1 --include tables.fields --full --json
+metabase db get 1 --include tables --full --json          # rollup: db + every table (compact)
+metabase db get 1 --include tables.fields --full --json   # rollup: db + every table + every field
 ```
 
-| Flag                | Description                                                   |
-| ------------------- | ------------------------------------------------------------- |
-| `--include <which>` | Hydrate related entities. One of `tables` or `tables.fields`. |
+| Flag                | Description                                                                                                                                                                                                                                                                       |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--include <which>` | Hydrate related entities. One of `tables` or `tables.fields`. `tables.fields` returns every column of every table in the database in one response — only safe on small/dev warehouses. For a real warehouse use `db schemas` → `db schema-tables` → `table get --include fields`. |
 
 ### `metabase db metadata <id>`
 
-Equivalent to `GET /api/database/:id/metadata`: a single database with all its tables and fields rolled up in one response. Use this when an agent needs a one-shot warehouse introspection rather than the per-table `metabase table get --full`.
+Equivalent to `GET /api/database/:id/metadata`: a single database with all its tables and fields rolled up in one response. This is the largest read in the `db` group — on a real warehouse the response will exceed the agent context. Use only when you know the database is small (a seeded dev instance, a sample db, a freshly-bootstrapped test fixture). For agent-driven introspection on a real warehouse, walk `db schemas` → `db schema-tables` → `table get --include fields` instead.
 
 ```sh
 metabase db metadata 1 --json --full --max-bytes 0
@@ -311,7 +314,7 @@ metabase db metadata 1 --json --full --max-bytes 0
 
 ### `metabase db schemas <id>`
 
-List the schemas in a database. Schemas with no tables are excluded.
+List the schemas in a database. Schemas with no tables are excluded. Cheap and bounded — this is the right entry point for an agent walking a warehouse.
 
 ```sh
 metabase db schemas 1
@@ -320,7 +323,7 @@ metabase db schemas 1 --json
 
 ### `metabase db schema-tables <id> <schema>`
 
-List the tables in a given schema, sorted by display name.
+List the tables in one schema, sorted by display name. Returns compact projections without fields — pair with `table get --include fields` (or `table fields <id>`) per table you actually need to introspect.
 
 ```sh
 metabase db schema-tables 1 public
@@ -347,10 +350,12 @@ metabase db rescan-values 1 --json
 
 ## Tables
 
-Inspect and edit warehouse tables via `/api/table`.
+Inspect and edit warehouse tables via `/api/table`. For agent-driven field introspection, `table get --include fields` is the default — it returns the table plus its columns in a single bounded response.
 
 ### `metabase table list`
 
+Returns every table in the chosen database (or across all databases) as a flat compact list — no fields, no per-table hydration. On a real warehouse with hundreds of tables this is still bounded (kilobytes), but `db schema-tables <db-id> <schema>` is the better starting point when you know the schema.
+
 ```sh
 metabase table list
 metabase table list --db-id 1 --json
@@ -362,28 +367,33 @@ metabase table list --db-id 1 --json
 
 ### `metabase table get <id>`
 
-Returns the basic table record (no fields). Use `metabase table metadata <id>` when you want the rollup with fields/FKs/dimensions hydrated.
+Returns the basic table record (no fields). Pass `--include fields` to route through `/api/table/:id/query_metadata` so the response carries the table's columns compact-projected as `fields` — this is the default agent path for field introspection. Use `metabase table fields <id>` if you only want the fields as a list envelope, or `metabase table metadata <id>` when you also need FKs and dimensions hydrated.
 
 ```sh
 metabase table get 42
 metabase table get 42 --json
+metabase table get 42 --include fields --json
 ```
 
-### `metabase table metadata <id>`
+| Flag                | Description                                                                                         |
+| ------------------- | --------------------------------------------------------------------------------------------------- |
+| `--include <which>` | Hydrate related entities. Currently only `fields` is supported (bundles compact-projected columns). |
 
-`GET /api/table/:id/query_metadata`: the table with its fields, FKs, and dimensions hydrated. The agent-facing one-shot introspection for a single table.
+### `metabase table fields <id>`
+
+List the fields on a table (a thin projection over `query_metadata.fields`). Use this when you want just the field array without the surrounding table metadata.
 
 ```sh
-metabase table metadata 42 --json --full --max-bytes 0
+metabase table fields 42
+metabase table fields 42 --json
 ```
 
-### `metabase table fields <id>`
+### `metabase table metadata <id>`
 
-List the fields on a table (a thin projection over `query_metadata.fields`).
+`GET /api/table/:id/query_metadata`: the table with its fields, FKs, dimensions, segments, and measures all hydrated. Heavier than `table get --include fields` — reach for it only when you actually need the FK / dimension / segment / measure data.
 
 ```sh
-metabase table fields 42
-metabase table fields 42 --json
+metabase table metadata 42 --json --full --max-bytes 0
 ```
 
 ### `metabase table update <id>`
@@ -685,29 +695,33 @@ metabase segment get 1 --json --full
 ```sh
 cat segment.json | metabase segment create
 metabase segment create --file segment.json
+metabase segment create --file segment.json --skip-validate
 ```
 
-| Flag            | Description             |
-| --------------- | ----------------------- |
-| `--body <json>` | Inline JSON body.       |
-| `--file <path>` | Path to JSON body file. |
+| Flag              | Description                                                                                                                                            |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `--body <json>`   | Inline JSON body.                                                                                                                                      |
+| `--file <path>`   | Path to JSON body file.                                                                                                                                |
+| `--skip-validate` | Skip the local MBQL 5 pre-flight validation; let the server be the authority. Use only when the bundled schema disagrees with what the server accepts. |
 
-Body fields: `name` (required), `table_id` (required positive integer), `definition` (required MBQL filter object), `description` (optional).
+Body fields: `name` (required), `table_id` (required positive integer), `definition` (required MBQL filter object), `description` (optional). If `definition` is MBQL 5 (`lib/type: "mbql/query"`) it goes through the same pre-flight validation as `card create` and `metabase query`; pass `--skip-validate` to bypass.
 
 ### `metabase segment update <id>`
 
-Patch a segment. The body MUST include `revision_message`. Other keys are partial: `name`, `definition`, `archived`, `description`, `caveats`, `points_of_interest`, `show_in_getting_started`.
+Patch a segment. The body MUST include `revision_message`. Other keys are partial: `name`, `definition`, `archived`, `description`, `caveats`, `points_of_interest`, `show_in_getting_started`. If `definition` is MBQL 5 (`lib/type: "mbql/query"`) it goes through the same pre-flight validation as `segment create`; pass `--skip-validate` to bypass.
 
 ```sh
 cat patch.json | metabase segment update 1
 metabase segment update 1 --file patch.json
 metabase segment update 1 --body '{"name":"renamed","revision_message":"rename"}'
+metabase segment update 1 --file patch.json --skip-validate
 ```
 
-| Flag            | Description             |
-| --------------- | ----------------------- |
-| `--body <json>` | Inline JSON body.       |
-| `--file <path>` | Path to JSON body file. |
+| Flag              | Description                                                                                                                                            |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `--body <json>`   | Inline JSON body.                                                                                                                                      |
+| `--file <path>`   | Path to JSON body file.                                                                                                                                |
+| `--skip-validate` | Skip the local MBQL 5 pre-flight validation; let the server be the authority. Use only when the bundled schema disagrees with what the server accepts. |
 
 ### `metabase segment archive <id>`
 
@@ -745,29 +759,33 @@ metabase measure get 1 --json --full
 ```sh
 cat measure.json | metabase measure create
 metabase measure create --file measure.json
+metabase measure create --file measure.json --skip-validate
 ```
 
-| Flag            | Description             |
-| --------------- | ----------------------- |
-| `--body <json>` | Inline JSON body.       |
-| `--file <path>` | Path to JSON body file. |
+| Flag              | Description                                                                                                                                            |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `--body <json>`   | Inline JSON body.                                                                                                                                      |
+| `--file <path>`   | Path to JSON body file.                                                                                                                                |
+| `--skip-validate` | Skip the local MBQL 5 pre-flight validation; let the server be the authority. Use only when the bundled schema disagrees with what the server accepts. |
 
-Body fields: `name` (required), `table_id` (required positive integer), `definition` (required MBQL aggregation object), `description` (optional).
+Body fields: `name` (required), `table_id` (required positive integer), `definition` (required MBQL aggregation object), `description` (optional). If `definition` is MBQL 5 (`lib/type: "mbql/query"`) it goes through the same pre-flight validation as `card create` and `metabase query`; pass `--skip-validate` to bypass.
 
 ### `metabase measure update <id>`
 
-Patch a measure. The body MUST include `revision_message`. Other keys are partial: `name`, `definition`, `archived`, `description`.
+Patch a measure. The body MUST include `revision_message`. Other keys are partial: `name`, `definition`, `archived`, `description`. If `definition` is MBQL 5 (`lib/type: "mbql/query"`) it goes through the same pre-flight validation as `measure create`; pass `--skip-validate` to bypass.
 
 ```sh
 cat patch.json | metabase measure update 1
 metabase measure update 1 --file patch.json
 metabase measure update 1 --body '{"name":"renamed","revision_message":"rename"}'
+metabase measure update 1 --file patch.json --skip-validate
 ```
 
-| Flag            | Description             |
-| --------------- | ----------------------- |
-| `--body <json>` | Inline JSON body.       |
-| `--file <path>` | Path to JSON body file. |
+| Flag              | Description                                                                                                                                            |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `--body <json>`   | Inline JSON body.                                                                                                                                      |
+| `--file <path>`   | Path to JSON body file.                                                                                                                                |
+| `--skip-validate` | Skip the local MBQL 5 pre-flight validation; let the server be the authority. Use only when the bundled schema disagrees with what the server accepts. |
 
 ### `metabase measure archive <id>`
 
@@ -914,73 +932,73 @@ metabase search products --archived
 | `--table-db-id`  | Restrict to items on a given database id.                                                                                                                 |
 | `--verified`     | Only verified content.                                                                                                                                    |
 
-## Sync
+## Remote Sync
 
-Drive Metabase Enterprise Remote Sync (`/api/ee/remote-sync`) — import / export Metabase content against a configured git remote, inspect dirty state, and manage branches. All sync commands require an active EE token and superuser credentials.
+Drive Metabase Enterprise Remote Sync (`/api/ee/remote-sync`) — import / export Metabase content against a configured git remote, inspect dirty state, and manage branches. All remote-sync commands require an active EE token and superuser credentials.
 
-### `metabase sync status`
+### `metabase remote-sync status`
 
 Roll up the current sync state in one call: configured branch, dirty flag, and the most recent sync task (or `null` if none has ever run).
 
 ```sh
-metabase sync status
-metabase sync status --json
+metabase remote-sync status
+metabase remote-sync status --json
 ```
 
-### `metabase sync is-dirty`
+### `metabase remote-sync is-dirty`
 
 Boolean check for whether any synced collection has unsynced local changes.
 
 ```sh
-metabase sync is-dirty --json
+metabase remote-sync is-dirty --json
 ```
 
-### `metabase sync has-remote-changes`
+### `metabase remote-sync has-remote-changes`
 
 Compare the latest version on the remote branch against the version Metabase last imported. Cached for a short TTL server-side; pass `--force-refresh` to bypass.
 
 ```sh
-metabase sync has-remote-changes
-metabase sync has-remote-changes --force-refresh --json
+metabase remote-sync has-remote-changes
+metabase remote-sync has-remote-changes --force-refresh --json
 ```
 
 | Flag              | Description                                         |
 | ----------------- | --------------------------------------------------- |
 | `--force-refresh` | Bypass the in-memory cache and re-check the remote. |
 
-### `metabase sync dirty`
+### `metabase remote-sync dirty`
 
 List every object that has unsynced local changes (compact list envelope; `--full` for the per-row payload).
 
 ```sh
-metabase sync dirty
-metabase sync dirty --json
+metabase remote-sync dirty
+metabase remote-sync dirty --json
 ```
 
-### `metabase sync current-task`
+### `metabase remote-sync current-task`
 
 Fetch the most recent sync task. Renders `{ status: "idle" }` when no task has ever run, otherwise the full task with its hydrated `status`.
 
 ```sh
-metabase sync current-task
-metabase sync current-task --json
+metabase remote-sync current-task
+metabase remote-sync current-task --json
 ```
 
-### `metabase sync cancel-task`
+### `metabase remote-sync cancel-task`
 
 Cancel the currently running sync task. Fails with HTTP 400 if no task is running.
 
 ```sh
-metabase sync cancel-task --json
+metabase remote-sync cancel-task --json
 ```
 
-### `metabase sync wait`
+### `metabase remote-sync wait`
 
 Poll `/current-task` until it reaches a terminal status (`successful`, `errored`, `cancelled`, `timed-out`, `conflict`). Exits 0 on `successful` or `cancelled`; exits 1 on `errored` / `timed-out` / `conflict`. Returns immediately with `{ status: "idle" }` if no task is running.
 
 ```sh
-metabase sync wait
-metabase sync wait --timeout 300000 --json
+metabase remote-sync wait
+metabase remote-sync wait --timeout 300000 --json
 ```
 
 | Flag              | Description                             |
@@ -988,14 +1006,14 @@ metabase sync wait --timeout 300000 --json
 | `--timeout <ms>`  | Polling timeout in ms (default 600000). |
 | `--interval <ms>` | Polling interval in ms (default 2000).  |
 
-### `metabase sync import`
+### `metabase remote-sync import`
 
 Import content from the configured git remote into Metabase (repo → Metabase). Auto-polls until the resulting task reaches a terminal status; pass `--no-wait` to return immediately after kickoff.
 
 ```sh
-metabase sync import
-metabase sync import --branch main --json
-metabase sync import --force --no-wait
+metabase remote-sync import
+metabase remote-sync import --branch main --json
+metabase remote-sync import --force --no-wait
 ```
 
 | Flag                    | Description                                                           |
@@ -1006,14 +1024,14 @@ metabase sync import --force --no-wait
 | `--timeout <ms>`        | Polling timeout in ms (default 600000). Used with `--wait`.           |
 | `--interval <ms>`       | Polling interval in ms (default 2000). Used with `--wait`.            |
 
-### `metabase sync export`
+### `metabase remote-sync export`
 
 Export Metabase changes back to the configured git remote (Metabase → repo). Auto-polls by default.
 
 ```sh
-metabase sync export -m "update dashboards"
-metabase sync export --branch main --json
-metabase sync export --no-wait
+metabase remote-sync export -m "update dashboards"
+metabase remote-sync export --branch main --json
+metabase remote-sync export --no-wait
 ```
 
 | Flag                    | Description                                                         |
@@ -1025,13 +1043,13 @@ metabase sync export --no-wait
 | `--timeout <ms>`        | Polling timeout in ms (default 600000). Used with `--wait`.         |
 | `--interval <ms>`       | Polling interval in ms (default 2000). Used with `--wait`.          |
 
-### `metabase sync stash`
+### `metabase remote-sync stash`
 
 Export the current Metabase state to a NEW branch on the remote and switch sync to it. Requires `remote-sync-type` to be `read-write`.
 
 ```sh
-metabase sync stash --new-branch wip
-metabase sync stash --new-branch wip -m "work in progress" --json
+metabase remote-sync stash --new-branch wip
+metabase remote-sync stash --new-branch wip -m "work in progress" --json
 ```
 
 | Flag                    | Description                                                    |
@@ -1042,41 +1060,41 @@ metabase sync stash --new-branch wip -m "work in progress" --json
 | `--timeout <ms>`        | Polling timeout in ms. Used with `--wait`.                     |
 | `--interval <ms>`       | Polling interval in ms. Used with `--wait`.                    |
 
-### `metabase sync branches`
+### `metabase remote-sync branches`
 
 List branches available on the configured git remote.
 
 ```sh
-metabase sync branches --json
+metabase remote-sync branches --json
 ```
 
-### `metabase sync create-branch <name>`
+### `metabase remote-sync create-branch <name>`
 
 Create a new branch on the git remote (from the last imported version) and switch sync to it.
 
 ```sh
-metabase sync create-branch feat/dashboards
-metabase sync create-branch feat/x --json
+metabase remote-sync create-branch feat/dashboards
+metabase remote-sync create-branch feat/x --json
 ```
 
-### `metabase sync add-collection <id>`
+### `metabase remote-sync add-collection <id>`
 
 Mark a collection as remote-synced. The toggle cascades to every descendant by `location` prefix, so flagging a parent flags the whole subtree. Returns `{ success, task_id? }`; `task_id` only appears when the toggle triggers a follow-up task (e.g. a finalization import after switching to read-only mode).
 
 ```sh
-metabase sync add-collection 12
-metabase sync add-collection 12 --json --profile prod
+metabase remote-sync add-collection 12
+metabase remote-sync add-collection 12 --json --profile prod
 ```
 
 The server rejects toggles while `remote-sync-type` is `read-only` (the install default). Switch first with `metabase setting set remote-sync-type '"read-write"'`.
 
-### `metabase sync remove-collection <id>`
+### `metabase remote-sync remove-collection <id>`
 
 Unmark a collection as remote-synced. Same cascade and same `read-only` precondition as `add-collection`.
 
 ```sh
-metabase sync remove-collection 12
-metabase sync remove-collection 12 --json --profile prod
+metabase remote-sync remove-collection 12
+metabase remote-sync remove-collection 12 --json --profile prod
 ```
 
 ## Workspaces
@@ -1322,25 +1340,20 @@ metabase eid translate --body '{"entity_ids":{"card":["abc123XYZ"]}}'
 
 Run an MBQL 5 query with built-in schema validation. Three modes — discover the schema (`--print-schema`), validate without sending (`--dry-run`), run.
 
-Two MBQL flavors:
-
-- **Internal MBQL** (default) — numeric IDs (`database: 1`, `source-table: 7`). POSTs to `/api/dataset`. This is what every existing Metabase API endpoint accepts.
-- **External MBQL** (`--external`) — string-id FKs (`database: "My DB"`, `source-table: ["My DB", null, "orders"]`). POSTs to `/api/dataset/external` (forward-looking representations endpoint).
-
-External and internal MBQL are structurally identical; only the ID types differ. The bundled query schema is synced from `@metabase/representations`; the internal validator overrides `id.yaml` to require positive integers for every ID `$def`.
+MBQL 5 bodies use numeric IDs (`database: 1`, `source-table: 7`) and POST to `/api/dataset`. The bundled query schema is synced from `@metabase/representations`; `id.yaml` is overridden to require positive integers for every ID `$def`.
 
 ```sh
-metabase query --print-schema                     # internal JSON Schema bundle
-metabase query --print-schema --external          # string-FK variant
+metabase query --print-schema                     # JSON Schema bundle
 cat q.json | metabase query --dry-run             # validate, no network
 metabase query --file q.json
-metabase query --file q.json --external
 metabase query --file q.json --skip-validate      # bypass pre-flight; let server reject
 ```
 
 Body sources: `--file`, `--body`, or stdin (exactly one). Body is JSON.
 
-`--skip-validate` is an escape hatch when the bundled schema disagrees with what the server actually accepts (drift, false negative, edge case). Validation is skipped entirely and the body is sent as-is. Mutually exclusive with `--dry-run` (which is itself the validation mode).
+Any non-MBQL 5 body skips pre-flight automatically — legacy MBQL 4 (`{ "type": "query", "database": N, "query": { "source-table": T, ... } }`), legacy native (`{ "type": "native", "database": N, "native": { "query": "..." } }`), or any other shape that doesn't carry `"lib/type": "mbql/query"`. The bundled schema only models MBQL 5; `/api/dataset` normalizes the rest server-side via `lib-be/normalize-query` (the same normalizer that backs `card create` / `transform create`), so behavior is symmetric across endpoints. `--dry-run` on a non-MBQL 5 body emits `{ ok: true, errors: [] }` (no schema applies). The double-wrap footgun — an MBQL 5 query nested inside a `{type:"query", query:…}` envelope — is still rejected with a `ConfigError` before send.
+
+`--skip-validate` is an escape hatch when the bundled schema disagrees with what the server actually accepts (drift, false negative, edge case) for MBQL 5 bodies. Validation is skipped entirely and the body is sent as-is. Mutually exclusive with `--dry-run` (which is itself the validation mode).
 
 Exit codes:
 
@@ -1350,21 +1363,29 @@ Exit codes:
 
 Output by mode:
 
-- `--print-schema` — `{ mode, schema, defs: { "id.yaml", "parameter.yaml", "ref.yaml", "temporal_bucketing.yaml" } }`. The query schema's `$ref`s point into the `defs` namespace by file path; an agent can either feed the bundle directly into Ajv (`addSchema(defs["id.yaml"], "id.yaml")` etc., then `compile(schema)`) or read it as documentation.
+- `--print-schema` — `{ schema, defs: { "id.yaml", "parameter.yaml", "ref.yaml", "temporal_bucketing.yaml" } }`. The query schema's `$ref`s point into the `defs` namespace by file path; an agent can either feed the bundle directly into Ajv (`addSchema(defs["id.yaml"], "id.yaml")` etc., then `compile(schema)`) or read it as documentation.
 - `--dry-run` — `{ ok: boolean, errors: { path: string, message: string }[] }`. `path` is a JSON Pointer into the body, `message` is the Ajv error string.
 - Run failure (no `--dry-run`) — same `{ ok, errors }` envelope on stdout, exit 2, no request made.
 - Run success — the streamed `CardQueryResult`.
 
-### MBQL 5 pre-flight in `card create`/`update` and `transform create`/`update`
+### MBQL 5 pre-flight in `card create`/`update`, `transform create`/`update`, `measure create`/`update`, and `segment create`/`update`
 
-When the embedded query (`card.dataset_query`, or `transform.source.query` for `source.type: "query"`) is MBQL 5 (`lib/type: "mbql/query"`), it is pre-flight-validated against the same schema as `metabase query`. Validation failure: `{ ok, errors }` envelope on stdout, exit 2, request not made. MBQL 4 (legacy) bodies and Python transform sources skip validation — they're still accepted by the server and we don't ship a schema for them.
+When the embedded query (`card.dataset_query`, `transform.source.query` for `source.type: "query"`, or `measure.definition` / `segment.definition`) is MBQL 5 (`lib/type: "mbql/query"`), it is pre-flight-validated against the same schema as `metabase query`. Validation failure: `{ ok, errors }` envelope on stdout, exit 2, request not made. MBQL 4 (legacy) bodies and Python transform sources skip validation — they're still accepted by the server and we don't ship a schema for them.
 
-Pass `--skip-validate` to bypass the pre-flight on `card create`, `card update`, `transform create`, or `transform update` — the body is sent as-is and the server is the authority. Same escape hatch as on `metabase query`; use only when the bundled schema disagrees with what the server actually accepts.
+Pass `--skip-validate` to bypass the pre-flight on any of `card create`, `card update`, `transform create`, `transform update`, `measure create`, `measure update`, `segment create`, or `segment update` — the body is sent as-is and the server is the authority. Same escape hatch as on `metabase query`; use only when the bundled schema disagrees with what the server actually accepts.
 
-Agent discovery path: `metabase __manifest` lists every command's args and description; the description for `card create`/`update` and `transform create`/`update` references `metabase query --print-schema` so an agent can fetch the validating schema directly.
+Agent discovery path: `metabase __manifest` lists every command's args and description; the description for `card create`/`update`, `transform create`/`update`, `measure create`/`update`, and `segment create`/`update` references `metabase query --print-schema` so an agent can fetch the validating schema directly.
 
 The bundled query schema is synced from a pinned `@metabase/representations` release via `bun run sync:representations`; CI guards against drift.
 
+### Card-reference pre-flight in `dashboard create` / `dashboard update`
+
+Before either command sends anything, every positive `card_id` referenced from the body's `dashcards` array is checked against `GET /api/card/:id` in parallel (de-duplicated per id). Cards that don't exist, are archived, or aren't readable fail pre-flight: the CLI writes a `{ ok: false, errors: [{ path, message }] }` envelope to stdout (one entry per offending dashcard, `path` is a JSON pointer like `/dashcards/3/card_id`) and exits **2** with `dashboard card-reference pre-flight failed: N error(s) — fix the dashcard card_id values listed above` on stderr. No dashboard is created or modified on a pre-flight miss — this is the contract that prevents orphan dashboards when a stale spec references an archived or missing card.
+
+There is no `--skip-validate` escape hatch here. The pre-flight queries live server state (no bundled schema to drift from), so the only legitimate path on a pre-flight miss is to fix the input.
+
+If the chained `PUT /api/dashboard/:id` fails _after_ the create has already inserted the row (rare with pre-flight in place, but possible on a permission / 5xx / network failure mid-flight), the user-facing error is rewritten to `dashboard <id> created but follow-up PUT /api/dashboard/<id> failed: <reason>; dashcards not applied`, so the caller knows the orphan exists. Recovery: `dashboard update <id> --body '{"dashcards":[...]}'` to retry the dashcards, or `dashboard update <id> --body '{"archived":true}'` to archive the orphan.
+
 ## UUIDs
 
 ### `metabase uuid`

package/dist/{add-collection-Dsju7qPh.mjs → add-collection-8GuI25VU.mjs}

@@ -1,10 +1,10 @@
-import { renderItem } from "./render-BblMa0Cg.mjs";
-import { connectionFlags, defineMetabaseCommand, outputFlags, profileFlag } from "./runtime-DcczfJol.mjs";
-import { parseId } from "./parse-id-BgFi3UCN.mjs";
-import { REMOTE_SYNC_PATHS } from "./poll-task-BP37zYAf.mjs";
+import { renderItem } from "./render-DXv-D6fU.mjs";
+import { connectionFlags, defineMetabaseCommand, outputFlags, profileFlag } from "./runtime-BY0yq43g.mjs";
+import { parseId } from "./parse-id-Di-wVtcP.mjs";
+import { REMOTE_SYNC_PATHS } from "./poll-task-CQ0jyN9p.mjs";
 import { z } from "zod";
 
-//#region src/commands/sync/add-collection.ts
+//#region src/commands/remote-sync/add-collection.ts
 const SyncSettingsUpdateResult = z.object({
 	success: z.boolean(),
 	task_id: z.number().int().positive().optional()
@@ -41,7 +41,7 @@ var add_collection_default = defineMetabaseCommand({
 		}
 	},
 	outputSchema: SyncSettingsUpdateResult,
-	examples: ["metabase sync add-collection 12", "metabase sync add-collection 12 --json --profile prod"],
+	examples: ["metabase remote-sync add-collection 12", "metabase remote-sync add-collection 12 --json --profile prod"],
 	async run({ args, ctx, getClient }) {
 		const collectionId = parseId(args.id, "id");
 		const client = await getClient();

package/dist/add-collection-Dy0OMhKh.mjs

@@ -0,0 +1,11 @@
+import "./package-DwhGofpM.mjs";
+import "./command-augment-D9pI9Vbh.mjs";
+import "./render-DXv-D6fU.mjs";
+import "./predicates-DiIiS3k7.mjs";
+import "./runtime-BY0yq43g.mjs";
+import "./parse-id-Di-wVtcP.mjs";
+import "./poll-task-CQ0jyN9p.mjs";
+import "./poll-BHFOOAGq.mjs";
+import { SyncSettingsUpdateResult, add_collection_default, setCollectionRemoteSynced, syncSettingsUpdateView } from "./add-collection-8GuI25VU.mjs";
+
+export { add_collection_default as default };

package/dist/{api-key-BU8wdQsz.mjs → api-key-bpZ0_40D.mjs}

@@ -6,7 +6,7 @@ var api_key_default = defineCommand({
 		name: "api-key",
 		description: "Manage Metabase API keys"
 	},
-	subCommands: { create: () => import("./create-DbCWjP7O.mjs").then((mod) => mod.default) }
+	subCommands: { create: () => import("./create-1MX0T09Q.mjs").then((mod) => mod.default) }
 });
 
 //#endregion

package/dist/{archive-Dc8Ob7X2.mjs → archive-BAaYDw3P.mjs}

@@ -1,10 +1,10 @@
-import "./package-CbQKObcX.mjs";
+import "./package-DwhGofpM.mjs";
 import "./command-augment-D9pI9Vbh.mjs";
-import { renderItem } from "./render-BblMa0Cg.mjs";
-import "./errors-CkVGRHrW.mjs";
-import { connectionFlags, defineMetabaseCommand, outputFlags, profileFlag } from "./runtime-DcczfJol.mjs";
-import { parseId } from "./parse-id-BgFi3UCN.mjs";
-import { Snippet, snippetView } from "./snippet-DRTklDg3.mjs";
+import { renderItem } from "./render-DXv-D6fU.mjs";
+import "./predicates-DiIiS3k7.mjs";
+import { connectionFlags, defineMetabaseCommand, outputFlags, profileFlag } from "./runtime-BY0yq43g.mjs";
+import { parseId } from "./parse-id-Di-wVtcP.mjs";
+import { Snippet, snippetView } from "./snippet-Dw0Sjzkr.mjs";
 
 //#region src/commands/snippet/archive.ts
 var archive_default = defineMetabaseCommand({

package/dist/{archive-C9nd1_nR.mjs → archive-BhqpKCm3.mjs}

@@ -1,11 +1,11 @@
-import "./package-CbQKObcX.mjs";
+import "./package-DwhGofpM.mjs";
 import "./command-augment-D9pI9Vbh.mjs";
-import { renderItem } from "./render-BblMa0Cg.mjs";
-import "./errors-CkVGRHrW.mjs";
-import { connectionFlags, defineMetabaseCommand, outputFlags, profileFlag } from "./runtime-DcczfJol.mjs";
-import { parseId } from "./parse-id-BgFi3UCN.mjs";
-import { Measure, measureView } from "./measure-B1GKcZxO.mjs";
-import { revisionMessageFlag } from "./revision-message-flag-BJiGjb5m.mjs";
+import { renderItem } from "./render-DXv-D6fU.mjs";
+import "./predicates-DiIiS3k7.mjs";
+import { connectionFlags, defineMetabaseCommand, outputFlags, profileFlag } from "./runtime-BY0yq43g.mjs";
+import { parseId } from "./parse-id-Di-wVtcP.mjs";
+import { Measure, measureView } from "./measure-jbc7fsCs.mjs";
+import { revisionMessageFlag } from "./revision-message-flag-D4E1lKE5.mjs";
 
 //#region src/commands/measure/archive.ts
 var archive_default = defineMetabaseCommand({

package/dist/{archive-CT0qt-5r.mjs → archive-C17bfUgD.mjs}

@@ -1,10 +1,10 @@
-import "./package-CbQKObcX.mjs";
+import "./package-DwhGofpM.mjs";
 import "./command-augment-D9pI9Vbh.mjs";
-import { renderItem } from "./render-BblMa0Cg.mjs";
-import "./errors-CkVGRHrW.mjs";
-import { connectionFlags, defineMetabaseCommand, outputFlags, profileFlag } from "./runtime-DcczfJol.mjs";
-import { parseId } from "./parse-id-BgFi3UCN.mjs";
-import { Card, cardView } from "./card-BOGKT258.mjs";
+import { renderItem } from "./render-DXv-D6fU.mjs";
+import "./predicates-DiIiS3k7.mjs";
+import { connectionFlags, defineMetabaseCommand, outputFlags, profileFlag } from "./runtime-BY0yq43g.mjs";
+import { parseId } from "./parse-id-Di-wVtcP.mjs";
+import { Card, cardView } from "./card-B2ZlGpQP.mjs";
 
 //#region src/commands/card/archive.ts
 var archive_default = defineMetabaseCommand({

package/dist/{archive-coFyGzcm.mjs → archive-Ci_l9wTo.mjs}

@@ -1,11 +1,11 @@
-import "./package-CbQKObcX.mjs";
+import "./package-DwhGofpM.mjs";
 import "./command-augment-D9pI9Vbh.mjs";
-import { renderItem } from "./render-BblMa0Cg.mjs";
-import "./errors-CkVGRHrW.mjs";
-import { connectionFlags, defineMetabaseCommand, outputFlags, profileFlag } from "./runtime-DcczfJol.mjs";
-import { parseId } from "./parse-id-BgFi3UCN.mjs";
-import { revisionMessageFlag } from "./revision-message-flag-BJiGjb5m.mjs";
-import { Segment, segmentView } from "./segment-CQ5w3M_W.mjs";
+import { renderItem } from "./render-DXv-D6fU.mjs";
+import "./predicates-DiIiS3k7.mjs";
+import { connectionFlags, defineMetabaseCommand, outputFlags, profileFlag } from "./runtime-BY0yq43g.mjs";
+import { parseId } from "./parse-id-Di-wVtcP.mjs";
+import { revisionMessageFlag } from "./revision-message-flag-D4E1lKE5.mjs";
+import { Segment, segmentView } from "./segment-BMrUBz94.mjs";
 
 //#region src/commands/segment/archive.ts
 var archive_default = defineMetabaseCommand({