@metabase/cli 0.1.18 → 0.2.1-alpha.bcm-ghy-4075-spawn-default-profile.eb120d1

package/README.md

@@ -52,16 +52,19 @@ Against a server older than v62 the CLI detects the missing OAuth support and fa
 
 On success the server is probed once — the rendered output shows the user, role (`Admin`/`User`), and Metabase version, and the same values are cached in `<configDir>/profiles.json` so later commands skip re-probing. Failure of either the auth probe (`/api/user/current`) or the server probe (`/api/session/properties`) rejects the login; an existing profile keeps its last-known-good credential and gains a `lastFailure` entry.
 
-| Flag                     | Description                                                                                                                                    |
-| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--url <url>`            | Metabase URL, including any subpath if the instance is hosted under one (`https://my.org.com/metabase`). Falls back to `MB_URL`, then prompts. |
-| `--api-key <value>`      | API key. Skips the browser flow. Visible in shell history — pipe on stdin instead.                                                             |
-| `--client-id <id>`       | Pre-registered OAuth client id (only needed when dynamic client registration is disabled on the server).                                       |
-| `--profile <name>`, `-p` | Profile to write to (default: `default`).                                                                                                      |
-| `--skip-verify`          | Save without contacting the server (no probe, no cache).                                                                                       |
+| Flag                     | Description                                                                                                                                                                                                                                                                                                     |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--url <url>`            | Metabase URL, including any subpath if the instance is hosted under one (`https://my.org.com/metabase`). Falls back to `MB_URL`, then prompts.                                                                                                                                                                  |
+| `--api-key <value>`      | API key. Skips the browser flow. Visible in shell history — pipe on stdin instead.                                                                                                                                                                                                                              |
+| `--client-id <id>`       | Pre-registered OAuth client id (only needed when dynamic client registration is disabled on the server).                                                                                                                                                                                                        |
+| `--profile <name>`, `-p` | Profile to write to (default: `default`).                                                                                                                                                                                                                                                                       |
+| `--skip-verify`          | Save without contacting the server (no probe, no cache).                                                                                                                                                                                                                                                        |
+| `--workspace`            | Request a workspace-manager-scoped login: the stored token can only manage workspaces — every other endpoint 403s server-side. Browser OAuth only (an API key cannot carry a scope), so it requires a TTY and refuses `--api-key`/`MB_API_KEY`. Requires a server advertising the `mb:workspace-manager` scope. |
 
 Non-interactive (non-TTY) login requires an API key; resolution order: `--api-key` → piped stdin → `MB_API_KEY` (first non-empty wins). Without one, non-interactive login fails rather than prompting.
 
+A workspace-scoped profile that hits a 403 on a content command gets an error naming the scope and the fix (re-login without `--workspace`, or use a workspace profile) instead of a bare "Forbidden."
+
 ```sh
 mb auth login                                            # interactive: browser or API key
 echo "$MB_KEY" | mb auth login --url https://m.example.com
@@ -328,11 +331,11 @@ mb transform-tag delete 5 --yes
 
 ## Databases
 
-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.
+Read warehouse metadata from `/api/database`. The `db` group exposes the full database list, the per-database record with optional table/field hydration, schema and table inspection, and the two manual-sync triggers.
 
 `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.
+> **Agent traversal — the hydration ladder:** start with `db 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 fetch fields per table with `table fields <table-id>` (bounded: a table has at most a few hundred fields). `--include tables.fields` is the full rollup — small databases only. When output outgrows the `--max-bytes` cap, the error message names the next command down the ladder. On warehouses with hundreds of tables, traverse by schema (`db schemas <db-id>` → `db schema-tables <db-id> <schema>`) or find tables by name (`mb search <term> --models table --db-id <db-id>`).
 
 ### `mb db list`
 
@@ -340,34 +343,26 @@ Read warehouse metadata from `/api/database`. The `db` group exposes the full da
 mb db list
 mb db list --json
 mb db list --saved --json
-mb db list --include tables --full --json   # rollup: every db with its full table list
+mb db list --include tables --json   # every db with its compact table map
 ```
 
-| 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`.                                                                                                             |
+| Flag                | Description                                                                                                                                                                             |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--include <which>` | Hydrate related entities. Currently only `tables` is supported (each database is returned with its compact `tables`). To map a single warehouse, prefer `db get <id> --include tables`. |
+| `--saved`           | Include the Saved Questions virtual database in the list. The virtual db has id `-1337` and no `engine`.                                                                                |
 
 ### `mb db get <id>`
 
 ```sh
 mb db get 1
 mb db get 1 --json
-mb db get 1 --include tables --full --json          # rollup: db + every table (compact)
-mb db get 1 --include tables.fields --full --json   # rollup: db + every table + every field
+mb db get 1 --include tables --json          # + compact table map (fits most databases)
+mb db get 1 --include tables.fields --json   # + every field of every table (small databases only)
 ```
 
-| 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`. |
-
-### `mb db metadata <id>`
-
-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
-mb db metadata 1 --json --full --max-bytes 0
-```
+| Flag                | Description                                                                                                                                                                                                                                                                                                     |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--include <which>` | Hydrate related entities. `tables` is the compact table map — the recommended first call for schema discovery. `tables.fields` is the full rollup and fits only small databases; on anything larger, take the map and fetch fields per table with `table fields <table-id>`, or traverse by schema (see above). |
 
 ### `mb db schemas <id>`
 
@@ -430,7 +425,7 @@ mb table list --db-id 1 --json
 
 ### `mb table get <id>`
 
-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 `mb table fields <id>` if you only want the fields as a list envelope, or `mb table metadata <id>` when you also need FKs and 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 (the response also carries FK targets and dimensions under `--full`). Use `mb table fields <id>` if you only want the fields as a list envelope.
 
 ```sh
 mb table get 42
@@ -451,14 +446,6 @@ mb table fields 42
 mb table fields 42 --json
 ```
 
-### `mb table metadata <id>`
-
-`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
-mb table metadata 42 --json --full --max-bytes 0
-```
-
 ### `mb table update <id>`
 
 Patch a table (`PUT /api/table/:id`). Body fields: `display_name`, `description`, `caveats`, `points_of_interest`, `entity_type`, `visibility_type`, `field_order`, `show_in_getting_started`. Pass the body via `--body`, `--file`, or stdin (exactly one).
@@ -508,6 +495,43 @@ mb field update 100 --body '{"description":"customer email","semantic_type":"typ
 mb field update 100 --file patch.json
 ```
 
+## Upload
+
+Load CSV/TSV data into the warehouse via `/api/upload`. Requires an uploads database configured on the server (Admin → Settings → Uploads); the destination db and schema are set there, not per-command. `append`/`replace` target a table created by a prior upload, and the CSV columns must match.
+
+### `mb upload csv`
+
+Create a new table plus a model over it from a CSV file. Prints the new model id and table id.
+
+```sh
+mb upload csv --file data.csv
+mb upload csv --file data.csv --collection 5
+mb upload csv --file data.csv --json
+```
+
+| Flag                | Description                                                            |
+| ------------------- | ---------------------------------------------------------------------- |
+| `--file <path>`     | Path to the CSV/TSV file to upload (required).                         |
+| `--collection <id>` | Target collection id for the created model, or `root` (default: root). |
+
+### `mb upload append <table-id>`
+
+Insert a CSV file's rows into an existing uploaded table.
+
+```sh
+mb upload append 42 --file more-rows.csv
+mb upload append 42 --file more-rows.csv --json
+```
+
+### `mb upload replace <table-id>`
+
+Replace an existing uploaded table's contents with a CSV file's rows.
+
+```sh
+mb upload replace 42 --file rows.csv
+mb upload replace 42 --file rows.csv --json
+```
+
 ## Cards
 
 CRUD plus query execution on `/api/card`. A "card" is a Metabase question, model, or metric. The `query` subcommand runs the card and either returns Metabase's JSON envelope or streams a raw CSV / XLSX export.
@@ -898,6 +922,157 @@ mb measure archive 1 --revision-message "deprecated"
 | --------------------------- | ------------------------------------------- |
 | `--revision-message <text>` | Audit-log message recorded with the change. |
 
+## Timelines
+
+CRUD on `/api/timeline`. A timeline is a named collection of dated events rendered as annotations on time-series charts. Timelines live in collections (`collection_id: null` = root) and carry an icon (`star`, `cake`, `mail`, `warning`, `bell`, `cloud`).
+
+### `mb timeline list`
+
+```sh
+mb timeline list
+mb timeline list --json
+mb timeline list --archived --json
+```
+
+| Flag         | Description                                     |
+| ------------ | ----------------------------------------------- |
+| `--archived` | Show archived timelines instead of active ones. |
+
+### `mb timeline get <id>`
+
+```sh
+mb timeline get 1
+mb timeline get 1 --json --full
+```
+
+### `mb timeline events <id>`
+
+List the events on a timeline. Archived events are excluded unless `--archived` is passed (which returns both).
+
+```sh
+mb timeline events 1
+mb timeline events 1 --archived --json
+```
+
+| Flag         | Description              |
+| ------------ | ------------------------ |
+| `--archived` | Include archived events. |
+
+### `mb timeline create`
+
+```sh
+mb timeline create --body '{"name":"Releases"}'
+cat timeline.json | mb timeline create
+mb timeline create --file timeline.json
+```
+
+| Flag            | Description             |
+| --------------- | ----------------------- |
+| `--body <json>` | Inline JSON body.       |
+| `--file <path>` | Path to JSON body file. |
+
+Body fields: `name` (required), `description` (optional), `icon` (optional, default `star`), `collection_id` (optional positive integer, omit for the root collection), `default` (optional boolean marking the collection's default timeline).
+
+### `mb timeline update <id>`
+
+Patch a timeline. Body is a partial subset of the create shape plus `archived`. Only the keys you send are touched. Changing `archived` cascades to every event on the timeline.
+
+```sh
+mb timeline update 1 --body '{"name":"Product releases"}'
+cat patch.json | mb timeline update 1
+mb timeline update 1 --file patch.json
+```
+
+| Flag            | Description             |
+| --------------- | ----------------------- |
+| `--body <json>` | Inline JSON body.       |
+| `--file <path>` | Path to JSON body file. |
+
+### `mb timeline archive <id>`
+
+Soft-delete a timeline (and, by server-side cascade, all its events) by setting `archived: true`. To unarchive use `mb timeline update <id> --body '{"archived":false}'`.
+
+```sh
+mb timeline archive 1
+mb timeline archive 1 --json
+```
+
+### `mb timeline delete <id>`
+
+Permanently delete a timeline and all its events. Irreversible — prefer `mb timeline archive` unless you mean it. Prompts for confirmation on a TTY; requires `--yes` otherwise.
+
+```sh
+mb timeline delete 1 --yes
+mb timeline delete 1
+```
+
+| Flag    | Description        |
+| ------- | ------------------ |
+| `--yes` | Skip confirmation. |
+
+## Timeline events
+
+CRUD on `/api/timeline-event`. An event is a dated annotation on a timeline. There is no server-side list endpoint — list events with `mb timeline events <id>`.
+
+### `mb timeline-event get <id>`
+
+```sh
+mb timeline-event get 1
+mb timeline-event get 1 --json --full
+```
+
+### `mb timeline-event create`
+
+```sh
+mb timeline-event create --body '{"name":"v2 launch","timestamp":"2026-07-01T00:00:00Z","timezone":"UTC","time_matters":false,"timeline_id":1}'
+cat event.json | mb timeline-event create
+mb timeline-event create --file event.json
+```
+
+| Flag            | Description             |
+| --------------- | ----------------------- |
+| `--body <json>` | Inline JSON body.       |
+| `--file <path>` | Path to JSON body file. |
+
+Body fields: `name` (required), `timestamp` (required, ISO 8601), `timezone` (required, IANA name like `UTC` or `America/New_York`), `time_matters` (required boolean — `true` when the time of day is significant, `false` when only the date is), `timeline_id` (required positive integer), `description` (optional), `icon` (optional, default: the timeline's icon).
+
+### `mb timeline-event update <id>`
+
+Patch an event. Body is a partial subset of the create shape plus `archived`. Only the keys you send are touched; `timeline_id` moves the event to another timeline.
+
+```sh
+mb timeline-event update 1 --body '{"name":"v2.1 launch"}'
+cat patch.json | mb timeline-event update 1
+mb timeline-event update 1 --file patch.json
+```
+
+| Flag            | Description             |
+| --------------- | ----------------------- |
+| `--body <json>` | Inline JSON body.       |
+| `--file <path>` | Path to JSON body file. |
+
+### `mb timeline-event archive <id>`
+
+Soft-delete an event by setting `archived: true`. To unarchive use `mb timeline-event update <id> --body '{"archived":false}'`.
+
+```sh
+mb timeline-event archive 1
+mb timeline-event archive 1 --json
+```
+
+### `mb timeline-event delete <id>`
+
+Permanently delete an event. Prompts for confirmation on a TTY; requires `--yes` otherwise.
+
+```sh
+mb timeline-event delete 1 --yes
+mb timeline-event delete 1
+```
+
+| Flag    | Description        |
+| ------- | ------------------ |
+| `--yes` | Skip confirmation. |
+
 ## Collections
 
 Read collections on `/api/collection`. Collections are the folders that contain cards, dashboards, and other collections. The list endpoint surfaces a virtual root collection (id `"root"`) alongside regular numeric ids; the get endpoint accepts only the numeric id.
@@ -1005,7 +1180,7 @@ mb library create --json
 
 ### `mb library publish`
 
-Publish tables (and their upstream dependencies) into the Library's Data collection (`POST /api/ee/data-studio/table/publish-tables`). The target Data collection is resolved automatically and the Library is created if it doesn't exist yet — there's no collection id to pass.
+Publish tables (and their upstream dependencies) into the Library's Data collection (`POST /api/ee/data-studio/table/publish-tables`). The target Data collection is resolved automatically and the Library is created if it doesn't exist yet — there's no collection id to pass. Publishing does not add the Data collection to the git-sync scope; on an instance with remote sync configured, the command warns on stderr with the `mb git-sync add-collection <id>` invocation that makes exports carry the published tables' metadata.
 
 ```sh
 mb library publish --table-ids 1,2,3
@@ -1156,7 +1331,7 @@ Drive Metabase Enterprise Remote Sync (`/api/ee/remote-sync`) — import / expor
 
 ### `mb git-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).
+Roll up the current sync state in one call: configured branch, dirty flag, the most recent sync task (or `null` if none has ever run), and the collections marked for sync.
 
 ```sh
 mb git-sync status
@@ -1315,6 +1490,64 @@ mb git-sync remove-collection 12
 mb git-sync remove-collection 12 --json --profile prod
 ```
 
+## Workspaces
+
+Lifecycle for EE workspaces via `/api/ee/workspace-manager` (Metabase v62+, `workspaces` premium feature). A workspace attaches databases and provisions warehouse isolation — a temporary schema + user per database — so work runs against real data without touching prod schemas. Alias: `mb ws`.
+
+### `mb workspace list`
+
+```sh
+mb workspace list
+mb workspace list --json
+```
+
+### `mb workspace get <id>`
+
+Includes per-database provisioning status (`unprovisioned` | `provisioning` | `provisioned` | `deprovisioning`), input schemas, and the isolated output namespace.
+
+```sh
+mb workspace get 1 --json
+```
+
+### `mb workspace create`
+
+Creates the workspace and provisions isolation for each database (blocking). Each database must be eligible for workspaces (driver support + the `database-enable-workspaces` database setting).
+
+```sh
+mb workspace create --name ws-reports --database-ids 1
+mb workspace create --name ws-etl --database-ids 1,2 --json
+mb workspace create --name transform-work --database-ids 1 --spawn
+```
+
+| Flag                   | Description                                                                                                                      |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `--name <name>`        | Workspace name.                                                                                                                  |
+| `--database-ids <ids>` | Database ids to attach, comma separated.                                                                                         |
+| `--spawn`              | Also spawn a workspace Metabase; the returned credential is saved to the `ws-<id>` profile (never printed) and made the default. |
+| `--keep-existing-auth` | Proceed despite broader same-server credentials in the profile store. Interactive only — refused in non-interactive contexts.    |
+
+Before creating, the profile store is swept for broader credentials against the same server: any API key profile, or any OAuth profile wider than `mb:workspace-manager`. Interactive runs offer to revoke the offenders (local clear + best-effort server-side token revocation; API keys must additionally be deleted in Admin settings); non-interactive runs hard-refuse so an agent can't proceed while a full-power credential is in reach.
+
+With `--spawn` the parent asks its instance manager for a workspace Metabase (`spawn_instance: true`) and the CLI consumes the returned `url` + `api_key`: the credential is written straight to the profile store as `ws-<id>` — never to stdout, `--json`, or an agent transcript — and that profile becomes the default, so bare `mb` targets the new workspace from then on (explicit `--profile`/`MB_PROFILE` still win). Destroying the workspace (or `mb auth logout` on the profile) unhooks the default again. Because an exported `MB_API_KEY` outranks stored profiles, `--spawn` refuses to run while it is set — it would silently shadow the profile it is about to install.
+
+### `mb workspace destroy <id>`
+
+Destroy is the only irreversible moment, so it closes the work-loss window first: when a local profile named `ws-<id>` exists, the child is checked for unsynced work (`remote-sync is-dirty`) and a dirty workspace is auto-exported to its target branch before teardown. `--discard` skips the check and the export; a machine without the workspace's profile warns and proceeds (destroy is the billing-stop lever — ops cleanup must work from anywhere), while a profile whose child can't be reached refuses without `--discard`.
+
+Then each provisioned database's warehouse isolation is torn down and the workspace removed; the matching local profile is dropped on success. Prompts unless `--yes`. Refuses (409) while any database is still provisioning/deprovisioning unless `--ignore-pending`, which removes the records and leaves those warehouse objects behind; unreachable-warehouse leftovers are reported as `orphaned_resources`.
+
+```sh
+mb workspace destroy 1 --yes
+mb workspace destroy 1 --yes --discard
+mb workspace destroy 1 --yes --ignore-pending
+```
+
+| Flag               | Description                                                             |
+| ------------------ | ----------------------------------------------------------------------- |
+| `--yes`            | Skip confirmation.                                                      |
+| `--discard`        | Destroy without exporting unsynced work (skips the is-dirty check).     |
+| `--ignore-pending` | Remove workspace records even while databases are mid-(de)provisioning. |
+
 ## Instance setup
 
 Bootstrapping a fresh, not-yet-configured Metabase instance.
@@ -1397,7 +1630,7 @@ When the embedded query (`card.dataset_query`, `transform.source.query` for `sou
 
 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 `mb query`; use only when the bundled schema disagrees with what the server actually accepts.
 
-Agent discovery path: `mb __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 `mb query --print-schema` so an agent can fetch the validating schema directly.
+Agent discovery path: `mb <command> --help --json` lists a command's args, JSON-body input schema, and output schema; the description for `card create`/`update`, `transform create`/`update`, `measure create`/`update`, and `segment create`/`update` references `mb 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.
 
@@ -1488,7 +1721,7 @@ mb skills path                              # absolute paths for direct Read
 mb skills path core                         # one path
 ```
 
-`mb skills get` honors the shared `--max-bytes` list cap. With the default 65 536 cap, `--all` will return only the first skill and emit a truncation notice — pass `--max-bytes 0` to dump every skill in one envelope.
+`mb skills get` honors the shared `--max-bytes` list cap. With the default 24 576 cap, `--all` will return only the first skill and emit a truncation notice — pass `--max-bytes 0` to dump every skill in one envelope.
 
 Bundled skills:
 
@@ -1515,7 +1748,7 @@ Exit codes: `0` success, `2` `ConfigError` (missing name, unknown name, `MB_SKIL
 | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `MB_URL`                 | Default URL for `auth login` and config resolution.                                                                                                                       |
 | `MB_API_KEY`             | Default API key (makes `auth login` non-interactive, skipping the browser flow; not stored).                                                                              |
-| `MB_PROFILE`             | Default profile when `--profile` is omitted. Falls back to `default`.                                                                                                     |
+| `MB_PROFILE`             | Default profile when `--profile` is omitted. Falls back to the stored default pointer (set by `workspace create --spawn`), then `default`.                                |
 | `MB_VERBOSE`             | When set to `1`, prints structured developer-detail JSON to stderr on failure.                                                                                            |
 | `MB_CLI_SKIP_PREFLIGHT`  | When set to `1`, bypasses the per-command server version / token-feature preflight check. Escape hatch for patched Metabase builds; can mask real compatibility problems. |
 | `MB_CLI_DISABLE_KEYRING` | When set to `1`, skips the OS keychain and stores credentials as plaintext in the profiles file.                                                                          |
@@ -1525,15 +1758,20 @@ The former `METABASE_`-prefixed names (`METABASE_URL`, `METABASE_API_KEY`, `META
 
 ## Agent integration
 
-### `mb __manifest`
+### `--help --json`
+
+Every node of the command tree answers `--help --json` with machine-readable help, mirroring what text help shows at that level:
 
-Hidden command that emits a machine-readable JSON manifest of every leaf command — name, description, examples, citty args, and the output Zod schema rendered as JSON Schema. Intended for agents that need typed capability discovery instead of scraping `--help`.
+- A leaf command emits its full entry — name, description, `details`, examples, citty args with types/defaults/enums, `capabilities` (min server version / token feature), and the input and output Zod schemas rendered as JSON Schema (`inputSchema` is the exact validator `readBody` enforces on the JSON body, `null` for commands that take none).
+- A command group (and the root) emits a flat `{ commands: [{ command, description }] }` index of every leaf in its subtree, with full-path names.
 
 ```sh
-mb __manifest | jq '.commands[].command'
+mb --help --json | jq -r '.commands[].command'    # every command
+mb card query --help --json | jq .outputSchema    # one command's output schema
+mb card create --help --json | jq .inputSchema    # the JSON-body contract it validates
 ```
 
-The manifest schema (`Manifest`) is exported from `src/runtime/manifest.ts`.
+The entry and index schemas (`CommandHelpEntry`, `CommandHelpIndex`) are exported from `src/runtime/command-help.ts`.
 
 ## Exit codes
 

package/dist/add-collection-CCpC-GUz.mjs

@@ -0,0 +1,9 @@
+import "./capabilities-CiaAfUgX.mjs";
+import "./command-augment-D9pI9Vbh.mjs";
+import "./runtime-C6ASrgVA.mjs";
+import "./parse-id-xS1tWJAq.mjs";
+import "./poll-CuTlWBwI.mjs";
+import "./poll-task-DhsYs8Hx.mjs";
+import { SyncSettingsUpdateResult, add_collection_default, setCollectionRemoteSynced, syncSettingsUpdateView } from "./add-collection-CLXfrgp4.mjs";
+
+export { add_collection_default as default };

package/dist/{add-collection-CRZAFCZy.mjs → add-collection-CLXfrgp4.mjs}

@@ -1,8 +1,7 @@
-import { connectionFlags, outputFlags, profileFlag } from "./error-BaBm-UrT.mjs";
-import { defineMetabaseCommand } from "./runtime-oxjmrYoP.mjs";
-import { renderSummary } from "./capabilities-N0jo5U7S.mjs";
-import { parseId } from "./parse-id-DlXnOcmP.mjs";
-import { REMOTE_SYNC_PATHS } from "./poll-task-NQNLT_aA.mjs";
+import { connectionFlags, outputFlags, profileFlag, renderSummary } from "./capabilities-CiaAfUgX.mjs";
+import { defineMetabaseCommand } from "./runtime-C6ASrgVA.mjs";
+import { parseId } from "./parse-id-xS1tWJAq.mjs";
+import { REMOTE_SYNC_PATHS } from "./poll-task-DhsYs8Hx.mjs";
 import { z } from "zod";
 
 //#region src/commands/git-sync/add-collection.ts

package/dist/append-DMcxP1LM.mjs

@@ -0,0 +1,42 @@
+import { connectionFlags, outputFlags, profileFlag, renderSummary } from "./capabilities-CiaAfUgX.mjs";
+import "./command-augment-D9pI9Vbh.mjs";
+import { defineMetabaseCommand } from "./runtime-C6ASrgVA.mjs";
+import "./input-BGyHn0Kr.mjs";
+import { parseId } from "./parse-id-xS1tWJAq.mjs";
+import { UploadUpdateResult, readCsvFile, requireUploadFilePath, updateTableFromCsv, uploadUpdateResultView } from "./requests-DYrDe-D0.mjs";
+
+//#region src/commands/upload/append.ts
+var append_default = defineMetabaseCommand({
+	meta: {
+		name: "append",
+		description: "Append a CSV file's rows to an existing uploaded table"
+	},
+	details: "Inserts the rows of the CSV into the table with the given id. The table must have been created by a CSV upload and the CSV columns must match.",
+	capabilities: { minVersion: 58 },
+	args: {
+		...outputFlags,
+		...profileFlag,
+		...connectionFlags,
+		file: {
+			type: "string",
+			description: "Path to the CSV/TSV file to upload"
+		},
+		id: {
+			type: "positional",
+			description: "Target table id",
+			required: true
+		}
+	},
+	outputSchema: UploadUpdateResult,
+	examples: ["mb upload append 42 --file more-rows.csv", "mb upload append 42 --file more-rows.csv --json"],
+	async run({ args, ctx, getClient }) {
+		const id = parseId(args.id);
+		const file = await readCsvFile(requireUploadFilePath(args.file));
+		const client = await getClient();
+		const result = await updateTableFromCsv(client, id, "append", file);
+		renderSummary(result, uploadUpdateResultView, `Appended "${file.filename}" into table ${id}.`, ctx);
+	}
+});
+
+//#endregion
+export { append_default as default };

package/dist/archive-4WqMsPWB.mjs

@@ -0,0 +1,38 @@
+import { connectionFlags, outputFlags, profileFlag, renderSummary } from "./capabilities-CiaAfUgX.mjs";
+import "./command-augment-D9pI9Vbh.mjs";
+import { defineMetabaseCommand } from "./runtime-C6ASrgVA.mjs";
+import { parseId } from "./parse-id-xS1tWJAq.mjs";
+import { Timeline, timelineView } from "./timeline-DEaiuB5V.mjs";
+
+//#region src/commands/timeline/archive.ts
+var archive_default = defineMetabaseCommand({
+	meta: {
+		name: "archive",
+		description: "Archive (soft-delete) a timeline and all its events by id"
+	},
+	capabilities: { minVersion: 58 },
+	args: {
+		...outputFlags,
+		...profileFlag,
+		...connectionFlags,
+		id: {
+			type: "positional",
+			description: "Timeline id",
+			required: true
+		}
+	},
+	outputSchema: Timeline,
+	examples: ["mb timeline archive 1", "mb timeline archive 1 --json"],
+	async run({ args, ctx, getClient }) {
+		const id = parseId(args.id);
+		const client = await getClient();
+		const updated = await client.requestParsed(Timeline, `/api/timeline/${id}`, {
+			method: "PUT",
+			body: { archived: true }
+		});
+		renderSummary(updated, timelineView, `Archived timeline ${updated.id} "${updated.name}".`, ctx);
+	}
+});
+
+//#endregion
+export { archive_default as default };

package/dist/{archive-De4yVEV8.mjs → archive-5inmbMDL.mjs}

@@ -1,10 +1,8 @@
-import "./notice-DyVl5aYB.mjs";
-import { connectionFlags, outputFlags, profileFlag } from "./error-BaBm-UrT.mjs";
-import "./command-augment-DdZIfx1V.mjs";
-import { defineMetabaseCommand } from "./runtime-oxjmrYoP.mjs";
-import { renderSummary } from "./capabilities-N0jo5U7S.mjs";
-import { parseId } from "./parse-id-DlXnOcmP.mjs";
-import { Collection, collectionView } from "./collection-DrLpA1SO.mjs";
+import { connectionFlags, outputFlags, profileFlag, renderSummary } from "./capabilities-CiaAfUgX.mjs";
+import "./command-augment-D9pI9Vbh.mjs";
+import { defineMetabaseCommand } from "./runtime-C6ASrgVA.mjs";
+import { parseId } from "./parse-id-xS1tWJAq.mjs";
+import { Collection, collectionView } from "./collection-C52Ndi_O.mjs";
 
 //#region src/commands/collection/archive.ts
 var archive_default = defineMetabaseCommand({

package/dist/{archive-3mEhK9_H.mjs → archive-BggM_AuL.mjs}

@@ -1,11 +1,9 @@
-import "./notice-DyVl5aYB.mjs";
-import { connectionFlags, outputFlags, profileFlag } from "./error-BaBm-UrT.mjs";
-import "./command-augment-DdZIfx1V.mjs";
-import { defineMetabaseCommand } from "./runtime-oxjmrYoP.mjs";
-import { renderSummary } from "./capabilities-N0jo5U7S.mjs";
-import { parseId } from "./parse-id-DlXnOcmP.mjs";
+import { connectionFlags, outputFlags, profileFlag, renderSummary } from "./capabilities-CiaAfUgX.mjs";
+import "./command-augment-D9pI9Vbh.mjs";
+import { defineMetabaseCommand } from "./runtime-C6ASrgVA.mjs";
+import { parseId } from "./parse-id-xS1tWJAq.mjs";
 import { revisionMessageFlag } from "./revision-message-flag-CHrJgFFx.mjs";
-import { Segment, segmentView } from "./segment-TXktTCfU.mjs";
+import { Segment, segmentView } from "./segment-CxRYEXeO.mjs";
 
 //#region src/commands/segment/archive.ts
 var archive_default = defineMetabaseCommand({

package/dist/{archive-Z8ZM-ilB.mjs → archive-BmhehbS0.mjs}

@@ -1,12 +1,11 @@
-import "./notice-DyVl5aYB.mjs";
-import { connectionFlags, outputFlags, profileFlag } from "./error-BaBm-UrT.mjs";
-import "./command-augment-DdZIfx1V.mjs";
-import { defineMetabaseCommand } from "./runtime-oxjmrYoP.mjs";
-import { renderSummary } from "./capabilities-N0jo5U7S.mjs";
-import "./field-CMY_LWUe.mjs";
-import "./parameter-CiJ4CwWE.mjs";
-import { Card, cardView } from "./card-DEmcRlNO.mjs";
-import { parseId } from "./parse-id-DlXnOcmP.mjs";
+import { connectionFlags, outputFlags, profileFlag, renderSummary } from "./capabilities-CiaAfUgX.mjs";
+import "./command-augment-D9pI9Vbh.mjs";
+import { defineMetabaseCommand } from "./runtime-C6ASrgVA.mjs";
+import "./embedding-CKdw8q7p.mjs";
+import "./field-DsXTeqBy.mjs";
+import "./parameter-BZ6y-Gfs.mjs";
+import { Card, cardView } from "./card-B8G5jQQT.mjs";
+import { parseId } from "./parse-id-xS1tWJAq.mjs";
 
 //#region src/commands/card/archive.ts
 var archive_default = defineMetabaseCommand({

package/dist/{archive-d74nDcp4.mjs → archive-BwIZzWGe.mjs}

@@ -1,10 +1,8 @@
-import "./notice-DyVl5aYB.mjs";
-import { connectionFlags, outputFlags, profileFlag } from "./error-BaBm-UrT.mjs";
-import "./command-augment-DdZIfx1V.mjs";
-import { defineMetabaseCommand } from "./runtime-oxjmrYoP.mjs";
-import { renderSummary } from "./capabilities-N0jo5U7S.mjs";
-import { parseId } from "./parse-id-DlXnOcmP.mjs";
-import { Document, documentView } from "./document-1W7NRaO_.mjs";
+import { connectionFlags, outputFlags, profileFlag, renderSummary } from "./capabilities-CiaAfUgX.mjs";
+import "./command-augment-D9pI9Vbh.mjs";
+import { defineMetabaseCommand } from "./runtime-C6ASrgVA.mjs";
+import { parseId } from "./parse-id-xS1tWJAq.mjs";
+import { Document, documentView } from "./document-D4zB-5a0.mjs";
 
 //#region src/commands/document/archive.ts
 var archive_default = defineMetabaseCommand({