primitive-admin 1.1.0-alpha.9 → 1.2.0-alpha.0

package/dist/src/commands/databases.js

@@ -1,13 +1,191 @@
+import { readFileSync, writeFileSync, appendFileSync, mkdirSync, existsSync, readdirSync } from "fs";
+import * as path from "path";
 import { ApiClient } from "../lib/api-client.js";
-import { getCurrentAppId } from "../lib/config.js";
-import { success, error, info, keyValue, formatTable, formatId, formatDate, json, } from "../lib/output.js";
-function resolveAppId(appId, options) {
-    const resolved = appId || options.app || getCurrentAppId();
-    if (!resolved) {
-        error("No app specified. Use <app-id>, --app, or 'primitive use <app-id>' to set context.");
+import { getCurrentAppId, resolveAppId } from "../lib/config.js";
+import { resolveCodegenSourceDir } from "../lib/codegen-shared/resolveCodegenSourceDir.js";
+import { resolveSyncDir } from "../lib/sync-paths.js";
+import { parseCsv, applyColumnMap, buildRows } from "../lib/csv.js";
+import { chunk, parseBatchSize } from "../lib/batch.js";
+import { generateDbTypes, } from "../lib/db-codegen/dbGenerator.js";
+import { generateDbSwiftTypes } from "../lib/swift-codegen/dbGenerator.js";
+import { success, error, info, warn, keyValue, result as printResult, formatTable, formatId, formatDate, json, } from "../lib/output.js";
+import { confirmPrompt } from "../lib/confirm-prompt.js";
+import { deprecateCommandGroup, warnDeprecated, } from "../lib/deprecation.js";
+/** Successor for the deprecated database CEL context commands and flags. */
+const CEL_CONTEXT_SUCCESSOR = "resource metadata categories (`primitive metadata get|set database <database-id> <category>`; define categories with `primitive config push`)";
+import { parseFilterOptions } from "../lib/record-filter.js";
+import { parseDataOption } from "../lib/data-input.js";
+import { ulid } from "ulid";
+import { normalizeCliListEnvelope, wholeListEnvelope, } from "../lib/paginate.js";
+import { pageCursorOption, pageLimitOption, parsePageLimit, printEmptyPage, printPageHint, } from "../lib/list-options.js";
+/**
+ * Render the flat `{ success, id, appliedFields }` response that
+ * `records/save` and `records/patch` return — these endpoints answer with a
+ * write receipt, not the stored record, so the human view shows the resolved id
+ * plus any server-applied fields (autoStamps / trigger-computed values).
+ */
+function renderRecordWriteResult(result, fallbackId, message) {
+    success(message);
+    keyValue("id", String(result?.id ?? fallbackId));
+    const applied = result?.appliedFields;
+    if (applied && typeof applied === "object" && Object.keys(applied).length > 0) {
+        for (const [key, value] of Object.entries(applied)) {
+            keyValue(`applied.${key}`, value === null || value === undefined ? "—" : String(value));
+        }
+    }
+}
+/**
+ * Refuse a write whose `--data` carries an `id` that is not the record being
+ * written. The server strips `id` from the record body on both the save and the
+ * patch path, so such an `id` would be dropped silently and the write would
+ * land on the id from the argument — somewhere the caller did not intend.
+ *
+ * `recordId` is the id the caller passed as an argument (absent on a `save`
+ * that mints one); `writtenId` is the id actually being written. Exits non-zero
+ * when they disagree with `--data` (#1965 review).
+ */
+function assertDataIdMatches(data, recordId, writtenId, commandPath) {
+    if (!data || typeof data !== "object")
+        return;
+    const dataId = data.id;
+    if (dataId === undefined || dataId === writtenId)
+        return;
+    error(recordId
+        ? `The "id" in --data ("${dataId}") does not match the record id "${recordId}". Remove it, or pass the id you mean as the argument.`
+        : `Pass the record id as the argument, not inside --data: ${commandPath} ${dataId} --data ...`);
+    process.exit(1);
+}
+/**
+ * Validate that the named operation is an import-compatible, save-like
+ * mutation before importing (issue #145, Codex finding (a)).
+ *
+ * The importer always builds `params: { modelName, id, data }`, and the batch
+ * endpoint rejects undeclared params per item. So we require the op to be a
+ * `mutation` whose declared `params` cover `modelName`, `id`, and `data`. This
+ * surfaces a clear up-front error instead of letting every row fail
+ * server-side. Exits non-zero on any mismatch.
+ */
+async function validateImportOperation(client, appId, databaseId, operationName) {
+    let ops;
+    try {
+        ops = await client.listDatabaseOperations(appId, databaseId);
+    }
+    catch (err) {
+        error(`Could not list operations for this database: ${err?.message || err}`);
+        process.exit(1);
+        return;
+    }
+    const op = (ops || []).find((o) => o?.name === operationName);
+    if (!op) {
+        error(`Operation "${operationName}" not found — create a mutation op (e.g. ` +
+            `\`seed_save\`) on this database type first.`);
         process.exit(1);
+        return;
+    }
+    if (op.type !== "mutation") {
+        error(`Operation "${operationName}" is a "${op.type}" op, not an import-compatible ` +
+            `mutation. CSV import needs a save-like mutation taking {modelName, id, data}.`);
+        process.exit(1);
+        return;
+    }
+    const params = op.params || {};
+    const missing = ["modelName", "id", "data"].filter((p) => !(p in params));
+    if (missing.length > 0) {
+        error(`Operation "${operationName}" is not import-compatible: its params are missing ` +
+            `${missing.join(", ")}. CSV import builds {modelName, id, data} per item, so the ` +
+            `op must declare those params (like \`seed_save\`).`);
+        process.exit(1);
+        return;
+    }
+}
+/**
+ * The full `databases records bulk` precondition value space, audited in one
+ * pass (issue #2437, Codex cycle 3). A precondition is field-equality only, so
+ * a value is one of: `null`, a boolean, a number, or a string. For each, what
+ * the DatabaseDO `condition` grammar can express, compared against the
+ * documents twin's strict JS equality (`evaluatePrecondition`):
+ *
+ * | Value             | Disposition | Why                                                                  |
+ * |-------------------|-------------|----------------------------------------------------------------------|
+ * | string            | round-trips | bound as TEXT; SQLite never equates TEXT with a number or a JSON bool |
+ * | number ≠ 0 and ≠1 | round-trips | bound as-is; no other JSON type extracts to that value                |
+ * | `null`            | rewritten   | paired with `$exists: true` so an absent key fails (cycle-2 fix)      |
+ * | `true` / `false`  | REJECTED    | bound as 1/0, and `json_extract` yields 1/0 for JSON booleans too     |
+ * | number 0 or 1     | REJECTED    | same collision seen from the other side: matches a stored `false`/`true` |
+ * | `{}` (no fields)  | see #2511   | sent as an empty `condition`, which the DO reads as "record must exist" |
+ * | object / array    | rejected    | not field-equality; rejected by the bulk validator before reaching here |
+ *
+ * The two REJECTED rows are the boolean/number collision: `JsonQueryTranslator`
+ * binds `true`/`false` as `1`/`0`, and SQLite's `json_extract` also returns a
+ * stored JSON boolean as `1`/`0`, so `{ enabled: true }` matches a record
+ * holding the number `1` and `{ retries: 1 }` matches a record holding `true`.
+ * The documents twin compares with `!==` and fails both. The `condition`
+ * grammar has no type predicate (`$exists` only distinguishes present from
+ * absent), so this cannot be translated exactly — the CLI rejects those values
+ * at the boundary instead, so the databases twin fails loudly rather than
+ * running with a weaker guard than the caller wrote. Issue #2507 tracks giving
+ * the grammar a type-aware equality, which would let these values be accepted.
+ *
+ * Returns an explanation when the value cannot be translated exactly, or
+ * `null` when it round-trips or is rewritten.
+ */
+export function untranslatablePreconditionValue(value) {
+    if (typeof value === "boolean") {
+        return (`a boolean precondition cannot be checked exactly on a database — the ` +
+            `record store compares JSON booleans as 1/0, so \`${value}\` would also ` +
+            `match a record holding the number ${value ? 1 : 0}`);
+    }
+    if (value === 0 || value === 1) {
+        return (`the number ${value} cannot be checked exactly on a database — the ` +
+            `record store compares JSON booleans as 1/0, so ${value} would also ` +
+            `match a record holding \`${value === 1}\``);
     }
-    return resolved;
+    return null;
+}
+/**
+ * Translate a `databases records bulk` op's documents-surface `precondition`
+ * into the DatabaseDO's per-op `condition` (issue #2437). See
+ * {@link untranslatablePreconditionValue} for the audit of the whole value
+ * space; this function handles the one value that is REWRITTEN rather than
+ * passed through or rejected.
+ *
+ * The two are NOT the same grammar, and a straight hand-off silently weakens
+ * the guard for one value: `null`. A `condition` is a query filter, so
+ * `{ approvedAt: null }` translates to
+ * `json_extract(_data, '$.approvedAt') IS NULL` — which is also true when the
+ * key is ABSENT. A guarded patch/delete would then execute against a record
+ * that never had the field. The documents surface evaluates the same
+ * precondition in JS (`evaluatePrecondition` in `src/document-models.ts`): an
+ * absent field reads `undefined`, and `undefined !== null`, so the guard fails
+ * closed there.
+ *
+ * Pin the database side to the documents meaning — "the key is present AND
+ * holds null" — by pairing each null check with an existence constraint.
+ * `$exists: true` translates to `json_type(_data, '$.<field>') IS NOT NULL`,
+ * true for a key holding JSON null and false for an absent key, so the pair
+ * emits `json_extract(...) IS NULL AND json_type(...) IS NOT NULL`.
+ *
+ * Non-null scalars need no rewrite: `= ?` against `json_extract` already fails
+ * for an absent field, because NULL never equals a bound value.
+ *
+ * Assumes the caller has already rejected `$`-prefixed keys, non-scalar values,
+ * and the values {@link untranslatablePreconditionValue} names — which is what
+ * leaves `$and` free to use here and what makes a pass-through exact.
+ */
+export function preconditionToCondition(precondition) {
+    const nullFields = Object.keys(precondition).filter((f) => precondition[f] === null);
+    if (nullFields.length === 0)
+        return { ...precondition };
+    const condition = {};
+    for (const [field, expected] of Object.entries(precondition)) {
+        if (expected !== null)
+            condition[field] = expected;
+    }
+    condition.$and = nullFields.flatMap((field) => [
+        { [field]: null },
+        { [field]: { $exists: true } },
+    ]);
+    return condition;
 }
 export function registerDatabasesCommands(program) {
     const databases = program
@@ -16,15 +194,32 @@ export function registerDatabasesCommands(program) {
         .addHelpText("after", `
 Examples:
   $ primitive databases list
+  $ primitive databases list --owner <user-id>
   $ primitive databases create "My Database"
   $ primitive databases get <database-id>
   $ primitive databases records models <database-id>
-  $ primitive databases records query <database-id> <model-name>
-  $ primitive databases records save <database-id> <model-name> --data '{"name":"Alice"}'
+  $ primitive databases records describe <database-id> <model-name>
+  $ primitive databases records query <database-id> <model-name> --filter '{"name":"Alice"}'
+  $ primitive databases records get <database-id> <model-name> <record-id>
+  $ primitive databases records count <database-id> <model-name> --filter '{"status":"open"}'
+  $ primitive databases records aggregate <database-id> <model-name> --op avg --field price
+  $ primitive databases records save <database-id> <model-name> [record-id] --data '{"name":"Alice"}'
+  $ primitive databases records patch <database-id> <model-name> <record-id> --data '{"name":"Alice"}'
+  $ primitive databases operations list <database-id>
+  $ primitive databases operations execute <database-id> <operation-name> --params '{"key":"value"}'
   $ primitive databases indexes list <database-id>
   $ primitive databases indexes create <database-id> --model contacts --field email
+  $ primitive databases records delete <database-id> <model-name> <record-id> --yes
+  $ primitive databases records delete-all <database-id> <model-name> --yes
+  $ primitive databases records delete-all <database-id> <model-name> --filter '{"status":"draft"}' --yes
+  $ primitive databases records bulk <database-id> --data-file ops.json --yes
   $ primitive databases permissions list <database-id>
-  $ primitive databases group-permissions list <database-id>
+
+Note: this group manages database *instances*. Database *type* configurations
+(schemas, rules, operations) are authored in TOML — see 'primitive config fields
+database-type-config' and the 'database-type-configs' group for inspection:
+  $ primitive database-type-configs list
+  $ rm database-type-configs/<database-type>.toml && primitive config push --prune
 `);
     // List databases
     databases
@@ -32,28 +227,49 @@ Examples:
         .description("List databases in an app")
         .argument("[app-id]", "App ID (uses current app if not specified)")
         .option("--app <app-id>", "App ID")
+        .option("--owner <user-id>", "Only list databases created by this user")
+        .addOption(pageLimitOption())
+        .addOption(pageCursorOption())
         .option("--json", "Output as JSON")
         .action(async (appId, options) => {
+        const limit = parsePageLimit(options.limit);
         const resolvedAppId = resolveAppId(appId, options);
         const client = new ApiClient();
         try {
-            const result = await client.listDatabases(resolvedAppId);
-            const list = Array.isArray(result) ? result : result?.databases ?? [];
+            const page = normalizeCliListEnvelope(await client.listDatabases(resolvedAppId, {
+                owner: options.owner,
+                limit,
+                cursor: options.cursor,
+            }));
+            const list = page.items;
             if (options.json) {
-                json(list);
+                json(page);
                 return;
             }
             if (list.length === 0) {
-                info("No databases found.");
+                printEmptyPage(page, "databases");
                 return;
             }
             console.log(formatTable(list, [
                 { header: "ID", key: "databaseId", format: formatId },
                 { header: "TITLE", key: "title" },
-                { header: "DEFAULT PERM", key: "defaultPermission", format: (v) => v || "—" },
+                { header: "TYPE", key: "databaseType", format: (v) => v || "—" },
                 { header: "PERMISSION", key: "permission" },
+                // `permission` reads "owner" on every row for an app admin, so it
+                // cannot confirm --owner narrowed anything. Show who created each
+                // database when the filter is in play.
+                ...(options.owner
+                    ? [
+                        {
+                            header: "CREATED BY",
+                            key: "createdBy",
+                            format: (v) => (v ? formatId(v) : "—"),
+                        },
+                    ]
+                    : []),
                 { header: "CREATED", key: "createdAt", format: formatDate },
             ]));
+            printPageHint(page);
         }
         catch (err) {
             error(err.message);
@@ -66,15 +282,42 @@ Examples:
         .description("Create a new database")
         .argument("<title>", "Database title")
         .option("--app <app-id>", "App ID")
-        .option("--default-permission <level>", "Default permission for all app users: reader or read-write")
+        .requiredOption("--type <database-type>", "Database type (required)")
+        .option("--cel-context <json>", "[deprecated] Initial CEL context as JSON (read from rules as database.celContext.*). Prefer --initial-metadata (resource metadata categories, separate readRule/writeRule).")
+        .option("--metadata <json>", "[deprecated] Initial CEL context as JSON (legacy alias for --cel-context); prefer --initial-metadata")
+        .option("--initial-metadata <json>", "Create-time resource metadata as JSON, keyed by category name (issue #1420). The recommended replacement for --cel-context: read from rules as md.self.<category>.<key>.")
         .option("--json", "Output as JSON")
         .action(async (title, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
         try {
-            const params = { title };
-            if (options.defaultPermission) {
-                params.defaultPermission = options.defaultPermission;
+            const params = { title, databaseType: options.type };
+            // `--cel-context` is the new user-facing name; `--metadata` remains
+            // supported for backwards compatibility. When both are provided,
+            // --cel-context wins.
+            if (options.celContext !== undefined || options.metadata !== undefined) {
+                warnDeprecated(`primitive databases create ${options.celContext !== undefined ? "--cel-context" : "--metadata"}`, "--initial-metadata (resource metadata categories)", 1815);
+            }
+            const contextSource = options.celContext ?? options.metadata;
+            if (contextSource) {
+                try {
+                    params.metadata = JSON.parse(contextSource);
+                }
+                catch {
+                    error(`Invalid ${options.celContext ? "--cel-context" : "--metadata"} JSON.`);
+                    process.exit(1);
+                }
+            }
+            // `--initial-metadata` is a separate concept: create-time per-category
+            // ResourceMetadata rows (issue #1420), not the database CEL context.
+            if (options.initialMetadata) {
+                try {
+                    params.initialMetadata = JSON.parse(options.initialMetadata);
+                }
+                catch {
+                    error("Invalid --initial-metadata JSON.");
+                    process.exit(1);
+                }
             }
             const result = await client.createDatabase(resolvedAppId, params);
             if (options.json) {
@@ -84,8 +327,8 @@ Examples:
             success("Database created.");
             keyValue("Database ID", result.databaseId);
             keyValue("Title", result.title);
-            if (result.defaultPermission) {
-                keyValue("Default Permission", result.defaultPermission);
+            if (result.databaseType) {
+                keyValue("Database Type", result.databaseType);
             }
         }
         catch (err) {
@@ -109,12 +352,11 @@ Examples:
                 json(result);
                 return;
             }
-            keyValue("Database ID", result.databaseId);
-            keyValue("Title", result.title);
-            keyValue("Default Permission", result.defaultPermission || "none");
-            keyValue("Rule Set", result.ruleSetId || "none");
-            keyValue("Permission", result.permission);
-            keyValue("Created", formatDate(result.createdAt));
+            printResult("Database ID", result.databaseId);
+            printResult("Title", result.title);
+            printResult("Database Type", result.databaseType || "none");
+            printResult("Permission", result.permission || "none");
+            printResult("Created", formatDate(result.createdAt));
         }
         catch (err) {
             error(err.message);
@@ -124,12 +366,11 @@ Examples:
     // Update database
     databases
         .command("update")
-        .description("Update a database (title, default permission, rule set)")
+        .description("Update a database (title, type)")
         .argument("<database-id>", "Database ID")
         .option("--app <app-id>", "App ID")
         .option("--title <title>", "New title")
-        .option("--default-permission <level>", "Default permission for all app users: reader, read-write, or none")
-        .option("--rule-set-id <id>", "Attach a rule set (use 'none' to detach)")
+        .option("--type <database-type>", "Database type (use 'none' to clear)")
         .option("--json", "Output as JSON")
         .action(async (databaseId, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
@@ -138,20 +379,14 @@ Examples:
         if (options.title) {
             params.title = options.title;
         }
-        if (options.defaultPermission !== undefined) {
-            params.defaultPermission =
-                options.defaultPermission === "none"
+        if (options.type !== undefined) {
+            params.databaseType =
+                options.type === "none"
                     ? null
-                    : options.defaultPermission;
-        }
-        if (options.ruleSetId !== undefined) {
-            params.ruleSetId =
-                options.ruleSetId === "none"
-                    ? null
-                    : options.ruleSetId;
+                    : options.type;
         }
         if (Object.keys(params).length === 0) {
-            error("Provide at least one of --title, --default-permission, or --rule-set-id.");
+            error("Provide at least one of --title or --type.");
             process.exit(1);
         }
         try {
@@ -163,8 +398,7 @@ Examples:
             success("Database updated.");
             keyValue("Database ID", result.databaseId);
             keyValue("Title", result.title);
-            keyValue("Default Permission", result.defaultPermission || "none");
-            keyValue("Rule Set", result.ruleSetId || "none");
+            keyValue("Database Type", result.databaseType || "none");
         }
         catch (err) {
             error(err.message);
@@ -181,15 +415,14 @@ Examples:
         .action(async (databaseId, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         if (!options.yes) {
-            const inquirer = await import("inquirer");
-            const { confirm } = await inquirer.default.prompt([
-                {
-                    type: "confirm",
-                    name: "confirm",
-                    message: `Delete database ${databaseId}? This cannot be undone.`,
-                    default: false,
-                },
-            ]);
+            let confirm;
+            try {
+                confirm = await confirmPrompt(`Delete database ${databaseId}? This cannot be undone.`);
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
             if (!confirm) {
                 info("Cancelled.");
                 return;
@@ -223,7 +456,7 @@ Examples:
             const result = await client.listDatabasePermissions(resolvedAppId, databaseId);
             const list = Array.isArray(result) ? result : result?.permissions ?? [];
             if (options.json) {
-                json(list);
+                json(wholeListEnvelope(list));
                 return;
             }
             if (list.length === 0) {
@@ -242,54 +475,35 @@ Examples:
             process.exit(1);
         }
     });
-    // Grant permission
-    permissions
-        .command("grant")
-        .description("Grant a user permission on a database")
-        .argument("<database-id>", "Database ID")
-        .requiredOption("--user-id <user-id>", "User ID to grant permission to")
-        .requiredOption("--permission <permission>", "Permission level: owner, read-write, or reader")
-        .option("--app <app-id>", "App ID")
-        .option("--json", "Output as JSON")
-        .action(async (databaseId, options) => {
+    // Add manager action handler
+    const addManagerAction = async (databaseId, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
         try {
-            const result = await client.grantDatabasePermission(resolvedAppId, databaseId, {
-                userId: options.userId,
-                permission: options.permission,
-            });
+            const result = await client.addDatabaseManager(resolvedAppId, databaseId, options.userId);
             if (options.json) {
                 json(result);
                 return;
             }
-            success(`Permission '${options.permission}' granted to user ${options.userId}.`);
+            success(`Manager added: user ${options.userId}.`);
         }
         catch (err) {
             error(err.message);
             process.exit(1);
         }
-    });
-    // Revoke permission
-    permissions
-        .command("revoke")
-        .description("Revoke a user's permission on a database")
-        .argument("<database-id>", "Database ID")
-        .argument("<user-id>", "User ID to revoke")
-        .option("--app <app-id>", "App ID")
-        .option("-y, --yes", "Skip confirmation prompt")
-        .action(async (databaseId, userId, options) => {
+    };
+    // Remove manager action handler
+    const removeManagerAction = async (databaseId, userId, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         if (!options.yes) {
-            const inquirer = await import("inquirer");
-            const { confirm } = await inquirer.default.prompt([
-                {
-                    type: "confirm",
-                    name: "confirm",
-                    message: `Revoke permission for user ${userId} on database ${databaseId}?`,
-                    default: false,
-                },
-            ]);
+            let confirm;
+            try {
+                confirm = await confirmPrompt(`Remove manager ${userId} from database ${databaseId}?`);
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
             if (!confirm) {
                 info("Cancelled.");
                 return;
@@ -297,18 +511,36 @@ Examples:
         }
         const client = new ApiClient();
         try {
-            await client.revokeDatabasePermission(resolvedAppId, databaseId, userId);
-            success(`Permission revoked for user ${userId}.`);
+            await client.removeDatabaseManager(resolvedAppId, databaseId, userId);
+            success(`Manager removed: user ${userId}.`);
         }
         catch (err) {
             error(err.message);
             process.exit(1);
         }
-    });
+    };
+    // Add manager (primary command)
+    permissions
+        .command("add-manager")
+        .description("Add a user as a manager of a database")
+        .argument("<database-id>", "Database ID")
+        .requiredOption("--user-id <user-id>", "User ID to add as manager")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(addManagerAction);
+    // Remove manager (primary command)
+    permissions
+        .command("remove-manager")
+        .description("Remove a manager from a database")
+        .argument("<database-id>", "Database ID")
+        .argument("<user-id>", "User ID to remove")
+        .option("--app <app-id>", "App ID")
+        .option("-y, --yes", "Skip confirmation prompt")
+        .action(removeManagerAction);
     // ---- Records subcommand group ----
     const records = databases
         .command("records")
-        .description("Query, create, and manage records in a database");
+        .description("Inspect and query records in a database");
     // List models
     records
         .command("models")
@@ -371,64 +603,108 @@ Examples:
             process.exit(1);
         }
     });
-    // Query records
+    // Query records (direct introspection via the records route)
     records
         .command("query")
-        .description("Query records in a database")
+        .description("Query records in a database model (admin only)")
         .argument("<database-id>", "Database ID")
-        .argument("<model-name>", "Model name")
-        .option("--filter <json>", "Filter as JSON", "{}")
-        .option("--limit <n>", "Max records to return", "25")
-        .option("--cursor <cursor>", "Pagination cursor")
+        .argument("<model-name>", "Model name to query")
         .option("--app <app-id>", "App ID")
+        .option("--filter <json>", "Filter as JSON (e.g. '{\"name\":\"Alice\"}')")
+        .option("--filter-file <path>", "Read filter from a JSON or TOML file")
+        .option("--limit <n>", "Maximum number of records to return", parseInt)
+        .option("--cursor <cursor>", "Pagination cursor from previous query")
         .option("--json", "Output as JSON")
         .action(async (databaseId, modelName, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
-        let filter = {};
-        try {
-            filter = JSON.parse(options.filter);
-        }
-        catch {
-            error("Invalid --filter JSON.");
-            process.exit(1);
-        }
+        const filter = parseFilterOptions(options);
         try {
-            const body = {
-                modelName,
-                filter,
-                options: { limit: parseInt(options.limit, 10) },
-            };
-            if (options.cursor)
-                body.options.cursor = options.cursor;
-            const result = await client.queryDatabaseRecords(resolvedAppId, databaseId, body);
-            const data = result.data || [];
+            const result = await client.queryDatabaseRecords(resolvedAppId, databaseId, modelName, { filter, limit: options.limit, cursor: options.cursor });
             if (options.json) {
                 json(result);
                 return;
             }
-            if (data.length === 0) {
+            const records = result.items;
+            if (records.length === 0) {
                 info("No records found.");
                 return;
             }
-            // Derive columns from first record
-            const cols = Object.keys(data[0]).filter((k) => k !== "type");
-            console.log(formatTable(data, cols.map((c) => ({
-                header: c.toUpperCase(),
-                key: c,
+            // Auto-detect columns from record keys
+            const allKeys = new Set();
+            for (const rec of records) {
+                for (const key of Object.keys(rec)) {
+                    allKeys.add(key);
+                }
+            }
+            // Put id first, then type, then the rest sorted
+            const orderedKeys = [];
+            if (allKeys.has("id")) {
+                orderedKeys.push("id");
+                allKeys.delete("id");
+            }
+            if (allKeys.has("type")) {
+                orderedKeys.push("type");
+                allKeys.delete("type");
+            }
+            orderedKeys.push(...[...allKeys].sort());
+            const columns = orderedKeys.map((key) => ({
+                header: key.toUpperCase(),
+                key,
                 format: (v) => {
                     if (v === null || v === undefined)
                         return "—";
-                    if (typeof v === "object") {
-                        const s = JSON.stringify(v);
-                        return s.length > 50 ? s.slice(0, 47) + "..." : s;
-                    }
-                    const s = String(v);
-                    return s.length > 50 ? s.slice(0, 47) + "..." : s;
+                    if (typeof v === "object")
+                        return JSON.stringify(v);
+                    return String(v);
                 },
-            }))));
-            if (result.hasMore) {
-                info(`More records available. Use --cursor ${result.cursor} to continue.`);
+            }));
+            console.log(formatTable(records, columns));
+            if (result.nextCursor) {
+                info(`More results available. Use --cursor ${result.nextCursor}`);
+            }
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // Get a single record by id
+    records
+        .command("get")
+        .description("Get a single record by id (admin only)")
+        .argument("<database-id>", "Database ID")
+        .argument("<model-name>", "Model name")
+        .argument("<record-id>", "Record ID")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (databaseId, modelName, recordId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            // A single-record fetch is a query filtered by primary-key id (there is
+            // no dedicated get endpoint — reuse queryDatabaseRecords).
+            const result = await client.queryDatabaseRecords(resolvedAppId, databaseId, modelName, { filter: { id: recordId }, limit: 1 });
+            const record = result.items[0];
+            if (options.json) {
+                json(record ?? null);
+                return;
+            }
+            if (!record) {
+                info(`No record found with id ${recordId} in ${modelName}.`);
+                return;
+            }
+            // `get` is a data command, so its fields go to stdout via `result()`
+            // — the #711 split (`result()` = the data the caller asked for,
+            // `keyValue()` = a post-action diagnostic summary). Issue #2437; the
+            // documents twin renders identically.
+            for (const [key, value] of Object.entries(record)) {
+                const rendered = value === null || value === undefined
+                    ? "—"
+                    : typeof value === "object"
+                        ? JSON.stringify(value)
+                        : String(value);
+                printResult(key, rendered);
             }
         }
         catch (err) {
@@ -439,101 +715,450 @@ Examples:
     // Count records
     records
         .command("count")
-        .description("Count records of a model")
+        .description("Count records in a database model (admin only)")
         .argument("<database-id>", "Database ID")
         .argument("<model-name>", "Model name")
-        .option("--filter <json>", "Filter as JSON", "{}")
         .option("--app <app-id>", "App ID")
+        .option("--filter <json>", "Filter as JSON (e.g. '{\"name\":\"Alice\"}')")
+        .option("--filter-file <path>", "Read filter from a JSON or TOML file")
         .option("--json", "Output as JSON")
         .action(async (databaseId, modelName, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
+        const filter = parseFilterOptions(options);
         const client = new ApiClient();
-        let filter = {};
         try {
-            filter = JSON.parse(options.filter);
+            const result = await client.countDatabaseRecords(resolvedAppId, databaseId, modelName, filter);
+            if (options.json) {
+                json(result);
+                return;
+            }
+            keyValue("count", String(result?.count ?? 0));
         }
-        catch {
-            error("Invalid --filter JSON.");
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // Aggregate records
+    const AGGREGATE_OPS = ["count", "sum", "avg", "min", "max"];
+    records
+        .command("aggregate")
+        .description("Aggregate records in a database model (count/sum/avg/min/max, optional group-by; admin only)")
+        .argument("<database-id>", "Database ID")
+        .argument("<model-name>", "Model name")
+        .option("--app <app-id>", "App ID")
+        .requiredOption("--op <operation>", `Aggregate operation: ${AGGREGATE_OPS.join("|")}`)
+        .option("--field <field>", "Field to aggregate (required for sum/avg/min/max)")
+        .option("--group-by <field>", "Group results by this field (repeatable)", (value, previous = []) => previous.concat(value), [])
+        .option("--filter <json>", "Filter as JSON")
+        .option("--filter-file <path>", "Read filter from a JSON or TOML file")
+        .option("--json", "Output as JSON")
+        .action(async (databaseId, modelName, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        if (!AGGREGATE_OPS.includes(options.op)) {
+            error(`Invalid --op "${options.op}". Expected one of: ${AGGREGATE_OPS.join(", ")}.`);
             process.exit(1);
         }
+        const operation = { type: options.op };
+        if (options.op === "count") {
+            if (options.field) {
+                error("--field is not valid for --op count.");
+                process.exit(1);
+            }
+        }
+        else {
+            if (!options.field) {
+                error(`--op ${options.op} requires --field.`);
+                process.exit(1);
+            }
+            operation.field = options.field;
+        }
+        const filter = parseFilterOptions(options);
+        const groupBy = options.groupBy || [];
+        const client = new ApiClient();
         try {
-            const result = await client.countDatabaseRecords(resolvedAppId, databaseId, {
-                modelName,
-                filter,
-            });
+            const result = await client.aggregateDatabaseRecords(resolvedAppId, databaseId, modelName, { operations: [operation], groupBy, filter });
             if (options.json) {
                 json(result);
                 return;
             }
-            console.log(`Count: ${result.count}`);
+            const aggregated = result?.result;
+            // Label the value column after the operation, including the field it
+            // ran over: `SUM` alone does not say what was summed. The field name is
+            // reproduced verbatim in both labels — it is a user-supplied
+            // identifier, and case-folding it produced `avg(lastvalue)` for
+            // `--field lastValue` (issue #2357).
+            const valueLabel = options.op === "count"
+                ? "COUNT"
+                : `${options.op.toUpperCase()}(${options.field})`;
+            const scalarLabel = options.op === "count"
+                ? "count"
+                : `${options.op.toLowerCase()}(${options.field})`;
+            if (groupBy.length === 0) {
+                // Ungrouped: one scalar per operation, keyed by the endpoint's
+                // operation name (`count`, `sum_<field>`, …). Render it as a
+                // key/value line — there is no group column to table.
+                const value = (aggregated ?? {})[options.op === "count" ? "count" : `${options.op}_${options.field}`];
+                keyValue(scalarLabel, value === null || value === undefined ? "—" : String(value));
+                return;
+            }
+            if (aggregated &&
+                typeof aggregated === "object" &&
+                !Array.isArray(aggregated) &&
+                Object.values(aggregated).every((v) => typeof v !== "object" || v === null)) {
+                // Flat { group -> value } shape (single operation, single group-by): render a table.
+                const rows = Object.entries(aggregated).map(([group, value]) => ({
+                    group,
+                    value: value === null || value === undefined ? "—" : String(value),
+                }));
+                console.log(formatTable(rows, [
+                    { header: "GROUP", key: "group" },
+                    { header: valueLabel, key: "value" },
+                ]));
+            }
+            else {
+                // Grouped/nested or multi-operation shape: print the structured result.
+                console.log(JSON.stringify(aggregated ?? {}, null, 2));
+            }
         }
         catch (err) {
             error(err.message);
             process.exit(1);
         }
     });
-    // Save record
+    // Upsert a record (create, or merge into an existing one)
     records
         .command("save")
-        .description("Create or update a record")
+        .description("Create a record, or merge fields into an existing one (admin only)")
         .argument("<database-id>", "Database ID")
         .argument("<model-name>", "Model name")
-        .option("--id <id>", "Record ID (auto-generated if omitted)")
-        .requiredOption("--data <json>", "Record data as JSON")
+        .argument("[record-id]", "Record ID (generated when omitted)")
         .option("--app <app-id>", "App ID")
+        .option("--data <json>", "Record fields as inline JSON")
+        .option("--data-file <path>", "Read the record fields from a JSON file")
         .option("--json", "Output as JSON")
-        .action(async (databaseId, modelName, options) => {
+        .action(async (databaseId, modelName, recordId, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
+        const data = parseDataOption(options, "record");
         const client = new ApiClient();
-        let data;
+        // The DatabaseDO requires an id on the plain save path (it only generates
+        // one for `upsertOn` writes). Mint the id client-side for a create so
+        // `save` works without an id, the same way CSV import does
+        // (`lib/csv.ts`).
+        const id = recordId || ulid();
+        assertDataIdMatches(data, recordId, id, "primitive databases records save <database-id> <model-name>");
         try {
-            data = JSON.parse(options.data);
+            const result = await client.saveDatabaseRecord(resolvedAppId, databaseId, modelName, id, data);
+            if (options.json) {
+                json(result);
+                return;
+            }
+            renderRecordWriteResult(result, id, `Record saved to ${modelName}.`);
         }
-        catch {
-            error("Invalid --data JSON.");
+        catch (err) {
+            error(err.message);
             process.exit(1);
-            return;
         }
-        const id = options.id || crypto.randomUUID().replace(/-/g, "").slice(0, 20);
+    });
+    // Patch a record (partial merge)
+    records
+        .command("patch")
+        .description("Merge fields into an existing record (admin only)")
+        .argument("<database-id>", "Database ID")
+        .argument("<model-name>", "Model name")
+        .argument("<record-id>", "Record ID")
+        .option("--app <app-id>", "App ID")
+        .option("--data <json>", "Fields to merge as inline JSON")
+        .option("--data-file <path>", "Read the fields to merge from a JSON file")
+        .option("--json", "Output as JSON")
+        .action(async (databaseId, modelName, recordId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const data = parseDataOption(options, "fields to merge");
+        const client = new ApiClient();
+        // Same guard as `save` — on this path `recordId` is required, so the
+        // "pass it as the argument" branch is unreachable here.
+        assertDataIdMatches(data, recordId, recordId, "primitive databases records patch <database-id> <model-name>");
         try {
-            const result = await client.saveDatabaseRecord(resolvedAppId, databaseId, {
-                modelName,
-                id,
-                data,
-            });
+            const result = await client.patchDatabaseRecord(resolvedAppId, databaseId, modelName, recordId, data);
             if (options.json) {
                 json(result);
                 return;
             }
-            success(`Record saved.`);
-            keyValue("ID", result.id || id);
+            renderRecordWriteResult(result, recordId, `Record ${recordId} patched in ${modelName}.`);
         }
         catch (err) {
             error(err.message);
             process.exit(1);
         }
     });
-    // Delete record
+    // Delete a single record
     records
         .command("delete")
-        .description("Delete a record")
+        .description("Delete a single record from a database model (admin only)")
         .argument("<database-id>", "Database ID")
         .argument("<model-name>", "Model name")
-        .argument("<record-id>", "Record ID")
+        .argument("<record-id>", "Record ID to delete")
         .option("--app <app-id>", "App ID")
         .option("-y, --yes", "Skip confirmation prompt")
+        .option("--json", "Output as JSON")
         .action(async (databaseId, modelName, recordId, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         if (!options.yes) {
-            const inquirer = await import("inquirer");
-            const { confirm } = await inquirer.default.prompt([
-                {
-                    type: "confirm",
-                    name: "confirm",
-                    message: `Delete record ${recordId} from ${modelName}?`,
-                    default: false,
-                },
-            ]);
+            let confirm;
+            try {
+                confirm = await confirmPrompt(`Delete record ${recordId} from ${modelName}? This cannot be undone.`);
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
+            if (!confirm) {
+                info("Cancelled.");
+                return;
+            }
+        }
+        const client = new ApiClient();
+        try {
+            const result = await client.deleteDatabaseRecord(resolvedAppId, databaseId, modelName, recordId);
+            if (options.json) {
+                json(result);
+                return;
+            }
+            success(`Record ${recordId} deleted from ${modelName}.`);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // Delete all records for a model
+    records
+        .command("delete-all")
+        .description("Delete all records for a model (queries then batch deletes, admin only)")
+        .argument("<database-id>", "Database ID")
+        .argument("<model-name>", "Model name")
+        .option("--app <app-id>", "App ID")
+        .option("--filter <json>", "Filter as JSON to select which records to delete")
+        .option("--filter-file <path>", "Read filter from a JSON or TOML file")
+        .option("-y, --yes", "Skip confirmation prompt")
+        .option("--json", "Output as JSON")
+        .action(async (databaseId, modelName, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        const filter = parseFilterOptions(options);
+        try {
+            // First, query to find all matching records
+            let allRecords = [];
+            let cursor;
+            let hasMore = true;
+            while (hasMore) {
+                const result = await client.queryDatabaseRecords(resolvedAppId, databaseId, modelName, { filter, limit: 100, cursor });
+                const records = result.items;
+                allRecords = allRecords.concat(records);
+                cursor = result.nextCursor;
+                hasMore = !!cursor && records.length > 0;
+            }
+            if (allRecords.length === 0) {
+                if (options.json) {
+                    json({ deleted: 0, modelName });
+                    return;
+                }
+                info("No matching records found.");
+                return;
+            }
+            if (!options.yes) {
+                let confirm;
+                try {
+                    confirm = await confirmPrompt(`Delete ${allRecords.length} record(s) from ${modelName}? This cannot be undone.`);
+                }
+                catch (err) {
+                    error(err.message);
+                    process.exit(1);
+                }
+                if (!confirm) {
+                    info("Cancelled.");
+                    return;
+                }
+            }
+            // Batch delete in chunks of 50
+            const BATCH_SIZE = 50;
+            let deleted = 0;
+            for (let i = 0; i < allRecords.length; i += BATCH_SIZE) {
+                const chunk = allRecords.slice(i, i + BATCH_SIZE);
+                const operations = chunk.map((r) => ({
+                    op: "delete",
+                    modelName,
+                    id: r.id,
+                }));
+                await client.batchDeleteDatabaseRecords(resolvedAppId, databaseId, operations);
+                deleted += chunk.length;
+            }
+            if (options.json) {
+                json({ deleted, modelName });
+                return;
+            }
+            success(`Deleted ${deleted} record(s) from ${modelName}.`);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // Apply an atomic multi-model operations blob (issue #2437).
+    //
+    // Takes the SAME `--data-file` blob as `documents records bulk` — one file
+    // works against either surface — and translates it to the DatabaseDO's
+    // `records/batch` wire shape (`{ op, modelName, id, data }`) with
+    // `atomic: true`, so the whole blob is all-or-nothing like the documents
+    // twin. Both guards the documents blob can carry survive the translation:
+    // `action: create` maps to `save` with `ifNotExists: true` (the DatabaseDO's
+    // strict-create flag, a 409 `ALREADY_EXISTS` inside the transaction), and an
+    // op's `precondition` maps to the DO's per-op `condition` (a 409
+    // `CONDITION_NOT_MET`). Both abort the whole batch, matching the documents
+    // twin.
+    const BULK_ACTIONS = ["create", "patch", "delete"];
+    const BULK_ACTION_TO_OP = {
+        create: "save",
+        patch: "patch",
+        delete: "delete",
+    };
+    // Mirrors the documents surface's `BULK_WRITE_OP_KEYS` / `BULK_DELETE_OP_KEYS`
+    // (`src/document-models.ts`). Unknown keys are an error rather than ignored:
+    // a guard the author asked for must never be dropped silently.
+    const BULK_OP_KEYS = ["model", "action", "id", "data", "precondition"];
+    const BULK_DELETE_OP_KEYS = ["model", "action", "id", "precondition"];
+    records
+        .command("bulk")
+        .description("Apply an atomic create/patch/delete operations blob to a database (admin only)")
+        .argument("<database-id>", "Database ID")
+        .requiredOption("--data-file <file>", "JSON file with { operations: [...] } or a bare operations array. " +
+        "Each op is { model, action: create|patch|delete, id, data, precondition? } " +
+        "— the same shape `documents records bulk` takes. `data` holds the " +
+        "record fields and is required on create/patch, not allowed on delete. " +
+        "A `create` against an id that already exists fails the whole batch, " +
+        "and a `precondition` that does not hold rolls the whole batch back")
+        .option("--app <app-id>", "App ID")
+        .option("-y, --yes", "Skip confirmation prompt")
+        .option("--json", "Output as JSON")
+        .action(async (databaseId, options) => {
+        const parsed = parseDataOption(options, "operations blob", {
+            allowArray: true,
+        });
+        const rawOperations = Array.isArray(parsed) ? parsed : parsed?.operations;
+        if (!Array.isArray(rawOperations) || rawOperations.length === 0) {
+            error("--data-file must contain { operations: [...] } or a non-empty operations array.");
+            process.exit(1);
+        }
+        // Translate to the batch wire shape, rejecting a malformed op before any
+        // request goes out so the caller sees which entry is wrong.
+        const operations = [];
+        for (let i = 0; i < rawOperations.length; i++) {
+            const op = rawOperations[i];
+            if (!op || typeof op !== "object" || Array.isArray(op)) {
+                error(`Operation ${i}: each operation must be a JSON object.`);
+                process.exit(1);
+            }
+            const action = op.action;
+            if (!BULK_ACTIONS.includes(action)) {
+                error(`Operation ${i}: invalid action "${action}". Expected one of: ${BULK_ACTIONS.join(", ")}.`);
+                process.exit(1);
+            }
+            if (!op.model || typeof op.model !== "string") {
+                error(`Operation ${i}: "model" is required and must be a model name.`);
+                process.exit(1);
+            }
+            if (!op.id || typeof op.id !== "string") {
+                error(`Operation ${i}: "id" is required.`);
+                process.exit(1);
+            }
+            // `data` on a delete gets its own message before the allowlist runs, so
+            // the caller is not told a first-class key is "unknown".
+            if (action === "delete" && op.data !== undefined) {
+                error(`Operation ${i}: "data" is not allowed on a delete.`);
+                process.exit(1);
+            }
+            const allowedKeys = action === "delete" ? BULK_DELETE_OP_KEYS : BULK_OP_KEYS;
+            const unknownKey = Object.keys(op).find((k) => !allowedKeys.includes(k));
+            if (unknownKey) {
+                error(`Operation ${i}: unknown key "${unknownKey}". Expected one of: ${allowedKeys.join(", ")}.`);
+                process.exit(1);
+            }
+            // A `precondition` is field-equality only, the same grammar the
+            // documents surface enforces (`validatePrecondition` in
+            // `src/document-models.ts`), so one blob means the same thing on both.
+            // `preconditionToCondition` translates it to the DO's per-op
+            // `condition`, checked inside the transaction: a mismatch is a 409 that
+            // rolls the whole batch back.
+            let condition;
+            if (op.precondition !== undefined && op.precondition !== null) {
+                if (typeof op.precondition !== "object" || Array.isArray(op.precondition)) {
+                    error(`Operation ${i}: "precondition" must be a field-equality object ({ field: scalar, … }).`);
+                    process.exit(1);
+                }
+                for (const [field, expected] of Object.entries(op.precondition)) {
+                    if (field.startsWith("$")) {
+                        error(`Operation ${i}: precondition operator "${field}" is not supported — preconditions are field-equality only ({ field: scalar, … }).`);
+                        process.exit(1);
+                    }
+                    if (expected !== null && typeof expected === "object") {
+                        error(`Operation ${i}: precondition on field "${field}" must be a scalar equality value — operators and nested objects/arrays are not supported.`);
+                        process.exit(1);
+                    }
+                    // Fail loudly on the values the `condition` grammar cannot check
+                    // exactly, rather than running with a weaker guard than the caller
+                    // wrote (issue #2437; the grammar fix is tracked in #2507).
+                    const untranslatable = untranslatablePreconditionValue(expected);
+                    if (untranslatable) {
+                        error(`Operation ${i}: precondition on field "${field}" is not supported — ${untranslatable}. ` +
+                            `Guard on a field whose value is a string or a number other than 0/1, or read the record ` +
+                            `first and gate the write on that.`);
+                        process.exit(1);
+                    }
+                }
+                condition = preconditionToCondition(op.precondition);
+            }
+            if (action === "delete") {
+                if (op.data !== undefined) {
+                    error(`Operation ${i}: "data" is not allowed on a delete.`);
+                    process.exit(1);
+                }
+                operations.push({
+                    op: "delete",
+                    modelName: op.model,
+                    id: op.id,
+                    ...(condition ? { condition } : {}),
+                });
+                continue;
+            }
+            if (!op.data ||
+                typeof op.data !== "object" ||
+                Array.isArray(op.data) ||
+                Object.keys(op.data).length === 0) {
+                error(`Operation ${i}: "data" is required and must be a non-empty object on a ${action}.`);
+                process.exit(1);
+            }
+            operations.push({
+                op: BULK_ACTION_TO_OP[action],
+                modelName: op.model,
+                id: op.id,
+                data: op.data,
+                // `create` is a STRICT create on both twins: `ifNotExists` is the
+                // DatabaseDO batch's strict-create flag (409 `ALREADY_EXISTS`), so a
+                // create against a live id fails the batch instead of merging.
+                ...(action === "create" ? { ifNotExists: true } : {}),
+                ...(condition ? { condition } : {}),
+            });
+        }
+        const resolvedAppId = resolveAppId(undefined, options);
+        if (!options.yes) {
+            let confirm;
+            try {
+                confirm = await confirmPrompt(`Apply ${operations.length} operation(s) atomically to database ${databaseId}?`);
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
             if (!confirm) {
                 info("Cancelled.");
                 return;
@@ -541,11 +1166,259 @@ Examples:
         }
         const client = new ApiClient();
         try {
-            await client.deleteDatabaseRecord(resolvedAppId, databaseId, {
-                modelName,
-                id: recordId,
+            await client.batchDatabaseRecords(resolvedAppId, databaseId, operations, {
+                atomic: true,
             });
-            success(`Record ${recordId} deleted.`);
+            // The batch endpoint answers with a per-operation `results` array; the
+            // documents twin answers with a rolled-up summary. Report the twin's
+            // summary so one blob produces one contract on both surfaces — the
+            // batch is atomic, so a 2xx means every op in the input applied.
+            //
+            // One reporting difference, documented alongside the verb: the
+            // documents twin's `deleted` counts records actually removed, because
+            // its DO reports that. The database batch issues a plain DELETE and
+            // reports no rows-affected, so `deleted` here counts delete operations
+            // applied — deleting an id that was not there still counts 1.
+            const added = rawOperations
+                .filter((op) => op.action === "create")
+                .map((op) => ({ model: op.model, id: op.id }));
+            const updated = rawOperations
+                .filter((op) => op.action === "patch")
+                .map((op) => ({ model: op.model, id: op.id }));
+            const deleted = rawOperations.filter((op) => op.action === "delete").length;
+            const summary = {
+                applied: added.length + updated.length + deleted,
+                added,
+                updated,
+                deleted,
+            };
+            if (options.json) {
+                json(summary);
+                return;
+            }
+            success(`Applied ${summary.applied} operation(s): ` +
+                `${added.length} added, ${updated.length} updated, ${deleted} deleted.`);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ---- CEL context subcommand group ----
+    // `cel-context` is the user-facing name for the dict that feeds CEL
+    // access rules and filter placeholders. `metadata` is kept as a hidden
+    // alias for backwards compatibility with existing scripts.
+    const registerCelContextGroup = (name, hidden) => {
+        const group = databases
+            .command(name, { hidden })
+            .description(hidden
+            ? "(deprecated: use resource metadata categories, `primitive metadata`) Manage database CEL context (alias of 'cel-context')"
+            : "(deprecated: use resource metadata categories, `primitive metadata`) Manage database CEL context (the dict referenced by access rules and filters)");
+        // CEL context is deprecated in favour of resource metadata categories
+        // (#1420, #1815), which carry separate read and write rules.
+        deprecateCommandGroup(group, CEL_CONTEXT_SUCCESSOR, { issue: 1815 });
+        group
+            .command("get")
+            .description("Read database CEL context")
+            .argument("<database-id>", "Database ID")
+            .option("--app <app-id>", "App ID")
+            .option("--json", "Output as JSON")
+            .action(async (databaseId, options) => {
+            const resolvedAppId = resolveAppId(undefined, options);
+            const client = new ApiClient();
+            try {
+                const result = await client.getDatabaseCelContext(resolvedAppId, databaseId);
+                if (options.json) {
+                    json(result);
+                    return;
+                }
+                printResult("Database ID", result.databaseId);
+                const ctx = result.celContext ?? result.metadata;
+                if (ctx && Object.keys(ctx).length > 0) {
+                    printResult("CEL Context", JSON.stringify(ctx, null, 2));
+                }
+                else {
+                    info("No CEL context set.");
+                }
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
+        });
+        group
+            .command("update")
+            .description("Update database CEL context (merge with existing)")
+            .argument("<database-id>", "Database ID")
+            .requiredOption("--data <json>", "CEL context fields as JSON (merged with existing)")
+            .option("--app <app-id>", "App ID")
+            .option("--json", "Output as JSON")
+            .action(async (databaseId, options) => {
+            const resolvedAppId = resolveAppId(undefined, options);
+            const client = new ApiClient();
+            let data;
+            try {
+                data = JSON.parse(options.data);
+            }
+            catch {
+                error("Invalid --data JSON.");
+                process.exit(1);
+                return;
+            }
+            try {
+                const result = await client.updateDatabaseCelContext(resolvedAppId, databaseId, data);
+                if (options.json) {
+                    json(result);
+                    return;
+                }
+                success("CEL context updated.");
+                const ctx = result.celContext ?? result.metadata;
+                if (ctx) {
+                    keyValue("CEL Context", JSON.stringify(ctx));
+                }
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
+        });
+    };
+    registerCelContextGroup("cel-context", false);
+    // Hidden legacy alias — `primitive databases metadata get/update` still works.
+    registerCelContextGroup("metadata", true);
+    // ---- Operations subcommand group ----
+    const operations = databases
+        .command("operations")
+        .description("List and execute registered operations on a database");
+    // List operations
+    operations
+        .command("list")
+        .description("List registered operations available on a database")
+        .argument("<database-id>", "Database ID")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (databaseId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const result = await client.listDatabaseOperations(resolvedAppId, databaseId);
+            const list = Array.isArray(result) ? result : [];
+            if (options.json) {
+                json(wholeListEnvelope(list));
+                return;
+            }
+            if (list.length === 0) {
+                info("No operations found.");
+                return;
+            }
+            console.log(formatTable(list, [
+                { header: "NAME", key: "name" },
+                { header: "TYPE", key: "type" },
+                { header: "MODEL", key: "modelName" },
+                { header: "ACCESS", key: "access" },
+            ]));
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // Execute operation
+    operations
+        .command("execute")
+        .description("Execute a registered operation on a database")
+        .argument("<database-id>", "Database ID")
+        .argument("<operation-name>", "Operation name")
+        .option("--params <json>", "Operation parameters as JSON")
+        .option("--limit <n>", "Max records to return (for queries)")
+        .option("--cursor <cursor>", "Pagination cursor")
+        .option("--token <jwt>", "Execute as a specific user (dev/test — JWT visible in process args)")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .option("--timing", "Show server-side timing breakdown")
+        .action(async (databaseId, operationName, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        let params;
+        if (options.params) {
+            try {
+                params = JSON.parse(options.params);
+            }
+            catch {
+                error("Invalid --params JSON.");
+                process.exit(1);
+                return;
+            }
+        }
+        const body = {};
+        if (params)
+            body.params = params;
+        if (options.limit)
+            body.limit = parseInt(options.limit, 10);
+        if (options.cursor)
+            body.cursor = options.cursor;
+        try {
+            const result = await client.executeDatabaseOperation(resolvedAppId, databaseId, operationName, body, options.token, { timing: !!options.timing });
+            if (options.json) {
+                json(result);
+                return;
+            }
+            // Smart display based on result shape. `executeDatabaseOperation()`
+            // has already normalized a query page to `{ items, hasMore,
+            // nextCursor? }` (#2440), so `items` is exactly "this result was a
+            // list" — the two branches cannot disagree about it.
+            if (Array.isArray(result.items)) {
+                if (result.items.length === 0) {
+                    info("No records found.");
+                }
+                else {
+                    const cols = Object.keys(result.items[0]).filter((k) => k !== "type");
+                    console.log(formatTable(result.items, cols.map((c) => ({
+                        header: c.toUpperCase(),
+                        key: c,
+                        format: (v) => {
+                            if (v === null || v === undefined)
+                                return "—";
+                            if (typeof v === "object") {
+                                const s = JSON.stringify(v);
+                                return s.length > 50 ? s.slice(0, 47) + "..." : s;
+                            }
+                            const s = String(v);
+                            return s.length > 50 ? s.slice(0, 47) + "..." : s;
+                        },
+                    }))));
+                }
+                // Gate on the cursor itself, the way `records query` does: `hasMore`
+                // without a cursor used to print the literal `undefined` (#2440).
+                if (result.nextCursor) {
+                    info(`More records available. Use --cursor ${result.nextCursor} to continue.`);
+                }
+            }
+            else if (result.count !== undefined) {
+                console.log(`Count: ${result.count}`);
+            }
+            else if (result.result !== undefined) {
+                // Aggregate result
+                json(result);
+            }
+            else if (result.results && Array.isArray(result.results)) {
+                // Batch/mutation results
+                success(`Operation executed (${result.results.length} result${result.results.length === 1 ? "" : "s"}).`);
+            }
+            else if (result.success !== undefined) {
+                success("Operation executed.");
+            }
+            else {
+                json(result);
+            }
+            // Display timing if present
+            if (result._timing) {
+                console.log("");
+                console.log("Timing:");
+                for (const [key, value] of Object.entries(result._timing)) {
+                    console.log(`  ${key}: ${value}ms`);
+                }
+            }
         }
         catch (err) {
             error(err.message);
@@ -571,7 +1444,7 @@ Examples:
             const result = await client.listDatabaseIndexes(resolvedAppId, databaseId, options.model);
             const list = result.indexes || [];
             if (options.json) {
-                json(list);
+                json(wholeListEnvelope(list));
                 return;
             }
             if (list.length === 0) {
@@ -634,15 +1507,14 @@ Examples:
         .action(async (databaseId, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         if (!options.yes) {
-            const inquirer = await import("inquirer");
-            const { confirm } = await inquirer.default.prompt([
-                {
-                    type: "confirm",
-                    name: "confirm",
-                    message: `Drop index on ${options.model}.${options.field}?`,
-                    default: false,
-                },
-            ]);
+            let confirm;
+            try {
+                confirm = await confirmPrompt(`Drop index on ${options.model}.${options.field}?`);
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
             if (!confirm) {
                 info("Cancelled.");
                 return;
@@ -661,103 +1533,586 @@ Examples:
             process.exit(1);
         }
     });
-    // ---- Group Permissions subcommand group ----
-    const groupPermissions = databases
-        .command("group-permissions")
-        .description("Manage group permissions on a database");
-    // List group permissions
-    groupPermissions
-        .command("list")
-        .description("List group permissions for a database")
+    // Reindex an existing instance from its type schema (issue #974). The
+    // on-demand remedy that brings a pre-existing database into compliance after
+    // a schema declares a field `unique = true` — registers any declared-but-
+    // missing unique index so `upsertOn` ops resolve. Idempotent.
+    databases
+        .command("reindex")
+        .description("Reprovision a database's unique indexes from its type schema")
         .argument("<database-id>", "Database ID")
+        .requiredOption("--from-schema", "Reprovision unique indexes declared in the type schema")
         .option("--app <app-id>", "App ID")
         .option("--json", "Output as JSON")
         .action(async (databaseId, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
         try {
-            const result = await client.listDatabaseGroupPermissions(resolvedAppId, databaseId);
-            const list = Array.isArray(result) ? result : result?.permissions ?? [];
+            const res = await client.reindexDatabaseFromSchema(resolvedAppId, databaseId);
             if (options.json) {
-                json(list);
+                json(res);
                 return;
             }
-            if (list.length === 0) {
-                info("No group permissions found.");
+            if (res.skipped) {
+                info(`Nothing to reindex (${res.reason}).`);
                 return;
             }
-            console.log(formatTable(list, [
-                { header: "GROUP_TYPE", key: "groupType" },
-                { header: "GROUP_ID", key: "groupId" },
-                { header: "PERMISSION", key: "permission" },
-                { header: "GRANTED", key: "grantedAt", format: formatDate },
-            ]));
+            success(`Reindexed from schema: ${res.registered} unique index${res.registered === 1 ? "" : "es"} provisioned.`);
         }
         catch (err) {
             error(err.message);
             process.exit(1);
         }
     });
-    // Grant group permission
-    groupPermissions
-        .command("grant")
-        .description("Grant a group permission on a database")
-        .argument("<database-id>", "Database ID")
-        .requiredOption("--group-type <type>", "Group type")
-        .requiredOption("--group-id <id>", "Group ID")
-        .requiredOption("--permission <permission>", "Permission level: read-write or reader")
+    // ---- Export / Import commands ----
+    databases
+        .command("export")
+        .description("Export a database (records, indexes, constraints)")
+        // Both positionals are declared optional and the action decides which is
+        // which (#3645). A required positional AFTER an optional one makes the
+        // optional one mandatory: commander binds the first value it sees to
+        // `[app-id]` and then reports the required argument missing, so
+        // `databases export <database-id>` never reached the action. The database
+        // id is still required — enforced below, where the shift is known.
+        .argument("[app-id]", "App ID (uses current app if not specified)")
+        .argument("[database-id]", "Database ID to export (required)")
         .option("--app <app-id>", "App ID")
+        .option("--output <dir>", "Output directory", "./primitive-export")
         .option("--json", "Output as JSON")
-        .action(async (databaseId, options) => {
-        const resolvedAppId = resolveAppId(undefined, options);
+        .action(async (first, second, options) => {
+        let resolvedAppId;
+        let databaseId;
+        if (second && !second.startsWith("-")) {
+            resolvedAppId = resolveAppId(first, options);
+            databaseId = second;
+        }
+        else {
+            resolvedAppId = resolveAppId(undefined, options);
+            databaseId = first;
+        }
+        if (!databaseId) {
+            error("Database ID is required.");
+            process.exit(1);
+        }
         const client = new ApiClient();
         try {
-            const result = await client.grantDatabaseGroupPermission(resolvedAppId, databaseId, {
-                groupType: options.groupType,
-                groupId: options.groupId,
-                permission: options.permission,
-            });
-            if (options.json) {
-                json(result);
+            await exportSingleDatabase(client, resolvedAppId, databaseId, options.output, options.json);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    databases
+        .command("import")
+        .description("Import a database from an export directory")
+        // Optional in commander, required in the action (#3645) — see `export`
+        // above for why a `<...>` here would make `[app-id]` mandatory.
+        .argument("[app-id]", "App ID (uses current app if not specified)")
+        .argument("[path]", "Path to database export directory (required)")
+        .option("--app <app-id>", "App ID")
+        .option("--overwrite", "Replace existing database if ID collides")
+        .option("--dry-run", "Show what would be imported without making changes")
+        .option("--batch-size <n>", "Records per batch write request (default: 5000)", "5000")
+        .option("--stop-on-error", "Abort the whole run on the first failing chunk (default: continue and report)")
+        .option("--json", "Output as JSON")
+        .action(async (first, second, options) => {
+        let resolvedAppId;
+        let importPath;
+        if (second && !second.startsWith("-")) {
+            resolvedAppId = resolveAppId(first, options);
+            importPath = second;
+        }
+        else {
+            resolvedAppId = resolveAppId(undefined, options);
+            importPath = first;
+        }
+        if (!importPath) {
+            error("Import path is required.");
+            process.exit(1);
+        }
+        // Validate --batch-size up front so a bad value fails before any write.
+        // Unlike `import-csv` (registered-batch path, hard 100k server cap),
+        // `records/batch` has no fixed server item cap — bound it with a
+        // conservative client-side ceiling to keep each request within
+        // Cloudflare body-size and Durable Object memory limits.
+        const parsedBatchSize = parseBatchSize(options.batchSize, {
+            max: IMPORT_BATCH_SIZE_CEILING,
+            overMaxMessage: `--batch-size cannot exceed ${IMPORT_BATCH_SIZE_CEILING} (a conservative client-side limit for batch write requests).`,
+        });
+        if ("error" in parsedBatchSize) {
+            error(parsedBatchSize.error);
+            process.exit(1);
+            return;
+        }
+        const batchSize = parsedBatchSize.value;
+        const client = new ApiClient();
+        try {
+            // Determine if this is a manifest-based export or a single database
+            let dbDirs = [];
+            const manifestPath = path.join(importPath, "manifest.json");
+            if (existsSync(path.join(importPath, "metadata.json"))) {
+                // Single database directory
+                dbDirs = [importPath];
+            }
+            else if (existsSync(manifestPath)) {
+                const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+                for (const dbId of manifest.databases || []) {
+                    const dbDir = path.join(importPath, "databases", dbId);
+                    if (existsSync(dbDir)) {
+                        dbDirs.push(dbDir);
+                    }
+                }
+            }
+            else if (existsSync(path.join(importPath, "databases"))) {
+                const entries = readdirSync(path.join(importPath, "databases"), { withFileTypes: true });
+                for (const entry of entries) {
+                    if (entry.isDirectory()) {
+                        dbDirs.push(path.join(importPath, "databases", entry.name));
+                    }
+                }
+            }
+            else {
+                error("No valid database export data found at the specified path.");
+                process.exit(1);
+            }
+            if (dbDirs.length === 0) {
+                info("No databases to import.");
                 return;
             }
-            success(`Permission '${options.permission}' granted to group ${options.groupType}/${options.groupId}.`);
+            const summary = {
+                created: 0,
+                updated: 0,
+                skipped: 0,
+                recordsImported: 0,
+                recordsFailed: 0,
+                batches: 0,
+                aborted: false,
+                indexesRegistered: 0,
+                batchErrors: [],
+            };
+            for (const dbDir of dbDirs) {
+                await importSingleDatabase(client, resolvedAppId, dbDir, {
+                    overwrite: options.overwrite || false,
+                    dryRun: options.dryRun || false,
+                    batchSize,
+                    stopOnError: options.stopOnError || false,
+                    json: options.json || false,
+                    summary,
+                });
+                // Fork 3: --stop-on-error stops the whole run across a multi-DB dir.
+                if (summary.aborted)
+                    break;
+            }
+            if (options.json) {
+                json({ ...summary, dryRun: options.dryRun || false });
+            }
+            else {
+                success("Database import complete:");
+                keyValue("  Databases created", String(summary.created));
+                if (summary.updated > 0)
+                    keyValue("  Databases updated", String(summary.updated));
+                if (summary.skipped > 0)
+                    keyValue("  Databases skipped", String(summary.skipped));
+                keyValue("  Records imported", String(summary.recordsImported));
+                if (summary.recordsFailed > 0)
+                    keyValue("  Records failed", String(summary.recordsFailed));
+                keyValue("  Batches", String(summary.batches));
+                if (summary.indexesRegistered > 0)
+                    keyValue("  Indexes registered", String(summary.indexesRegistered));
+                if (summary.aborted)
+                    warn("Aborted after a failing chunk (--stop-on-error).");
+                if (summary.batchErrors.length > 0) {
+                    error(`${summary.batchErrors.length} chunk(s) errored:`);
+                    for (const e of summary.batchErrors) {
+                        error(`  ${e.database} batch ${e.batch + 1}: ${e.error}`);
+                    }
+                }
+            }
+            // Non-zero exit if any chunk errored (default continue-and-report or
+            // --stop-on-error both surface failures this way).
+            if (summary.batchErrors.length > 0) {
+                process.exit(1);
+            }
         }
         catch (err) {
             error(err.message);
             process.exit(1);
         }
     });
-    // Revoke group permission
-    groupPermissions
-        .command("revoke")
-        .description("Revoke a group's permission on a database")
+    // ============================================
+    // CSV import (issue #145, Phase 1)
+    // ============================================
+    databases
+        .command("import-csv")
+        .description("Import rows from a CSV file into a database via a registered batch (bulk) save operation")
         .argument("<database-id>", "Database ID")
-        .argument("<group-type>", "Group type")
-        .argument("<group-id>", "Group ID")
+        .argument("<file>", "Path to the CSV file")
+        .requiredOption("--model <name>", "Model name passed in each item's params")
+        .option("--operation <op>", "Registered mutation operation to use (must be a {modelName,id,data} save-like op)", "seed_save")
+        .option("--column-map <json>", 'Map CSV headers to field names, e.g. \'{"CSV Header":"fieldName"}\'')
+        .option("--types <json>", 'Coerce fields by type, e.g. \'{"price":"number","active":"boolean"}\'')
+        .option("--id-column <col>", "Use this CSV column for record ids (else a ULID is generated)")
+        .option("--batch-size <n>", "Records per batch request (default: 5000)", "5000")
+        .option("--delimiter <char>", "CSV field delimiter (default: ',')", ",")
         .option("--app <app-id>", "App ID")
-        .option("-y, --yes", "Skip confirmation prompt")
-        .action(async (databaseId, groupType, groupId, options) => {
+        .option("--dry-run", "Parse + report row/batch counts without writing")
+        .option("--stop-on-error", "Abort the whole import on the first chunk error (default: best-effort continue)")
+        .option("--json", "Output a machine-readable result")
+        .action(async (databaseId, file, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
-        if (!options.yes) {
-            const inquirer = await import("inquirer");
-            const { confirm } = await inquirer.default.prompt([
-                {
-                    type: "confirm",
-                    name: "confirm",
-                    message: `Revoke permission for group ${groupType}/${groupId} on database ${databaseId}?`,
-                    default: false,
-                },
-            ]);
-            if (!confirm) {
-                info("Cancelled.");
+        const client = new ApiClient();
+        // Parse JSON flags up front for clear errors.
+        let columnMap;
+        if (options.columnMap) {
+            try {
+                columnMap = JSON.parse(options.columnMap);
+            }
+            catch {
+                error("Invalid --column-map JSON.");
+                process.exit(1);
+                return;
+            }
+        }
+        let types;
+        if (options.types) {
+            try {
+                types = JSON.parse(options.types);
+            }
+            catch {
+                error("Invalid --types JSON.");
+                process.exit(1);
                 return;
             }
         }
+        // The registered-batch (`executeBatch`) path rejects requests over
+        // 100000 items server-side; keep chunks under it.
+        const parsedBatchSize = parseBatchSize(options.batchSize, {
+            max: 100000,
+            overMaxMessage: "--batch-size cannot exceed 100000 (the server's per-request cap).",
+        });
+        if ("error" in parsedBatchSize) {
+            error(parsedBatchSize.error);
+            process.exit(1);
+            return;
+        }
+        const batchSize = parsedBatchSize.value;
+        if (!existsSync(file)) {
+            error(`CSV file not found: ${file}`);
+            process.exit(1);
+            return;
+        }
+        try {
+            // 1. Read + parse the CSV.
+            const raw = readFileSync(file, "utf-8");
+            let rows = parseCsv(raw, options.delimiter);
+            // 2. Apply column map.
+            rows = applyColumnMap(rows, columnMap);
+            // 3. Coerce types, assign ids, shape into batch items.
+            const { batch, rowCount } = buildRows(rows, {
+                modelName: options.model,
+                types,
+                idColumn: options.idColumn,
+            });
+            const chunks = chunk(batch, batchSize);
+            // 4. Validate the chosen op is an import-compatible save-like mutation
+            //    BEFORE writing (op-not-found / incompatible → clear up-front error
+            //    rather than per-row server-side failure). Skip the round-trip only
+            //    when there is genuinely nothing to import in a dry run.
+            if (!options.dryRun || rowCount > 0) {
+                await validateImportOperation(client, resolvedAppId, databaseId, options.operation);
+            }
+            // 5. Empty / headers-only CSV: no request, report 0/0.
+            if (rowCount === 0) {
+                if (options.json) {
+                    json({ imported: 0, failed: 0, rows: 0, batches: 0, errors: [], dryRun: !!options.dryRun });
+                }
+                else {
+                    info("No data rows found in CSV — nothing to import.");
+                    success("Imported: 0, Failed: 0");
+                }
+                return;
+            }
+            // 6. Dry run: report counts, no writes.
+            if (options.dryRun) {
+                if (options.json) {
+                    json({ dryRun: true, rows: rowCount, batches: chunks.length, batchSize });
+                }
+                else {
+                    info(`Dry run — no records written.`);
+                    keyValue("  Rows", String(rowCount));
+                    keyValue("  Batches", String(chunks.length));
+                    keyValue("  Batch size", String(batchSize));
+                }
+                return;
+            }
+            // 7. Import chunk by chunk; accumulate imported/failed + per-chunk errors.
+            let imported = 0;
+            let failed = 0;
+            const errors = [];
+            let aborted = false;
+            for (let i = 0; i < chunks.length; i++) {
+                const piece = chunks[i];
+                try {
+                    const res = await client.executeBatch(resolvedAppId, databaseId, options.operation, piece);
+                    imported += res.imported ?? 0;
+                    failed += res.failed ?? 0;
+                    if (!options.json) {
+                        info(`Batch ${i + 1}/${chunks.length}: imported ${res.imported ?? 0}, failed ${res.failed ?? 0}`);
+                    }
+                }
+                catch (err) {
+                    const msg = err?.message || String(err);
+                    errors.push({ batch: i, error: msg });
+                    failed += piece.length;
+                    if (!options.json) {
+                        warn(`Batch ${i + 1}/${chunks.length} failed: ${msg}`);
+                    }
+                    if (options.stopOnError) {
+                        aborted = true;
+                        break;
+                    }
+                }
+            }
+            if (options.json) {
+                json({ imported, failed, rows: rowCount, batches: chunks.length, errors, aborted });
+            }
+            else {
+                if (aborted) {
+                    warn(`Aborted after a chunk error (--stop-on-error).`);
+                }
+                success(`Imported: ${imported}, Failed: ${failed}`);
+                if (errors.length > 0) {
+                    error(`${errors.length} batch(es) errored:`);
+                    for (const e of errors) {
+                        error(`  Batch ${e.batch + 1}: ${e.error}`);
+                    }
+                }
+            }
+            // Non-zero exit if any chunk errored.
+            if (errors.length > 0) {
+                process.exit(1);
+            }
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ============================================
+    // Schema commands (issue #666)
+    // ============================================
+    const schema = databases
+        .command("schema")
+        .description("Manage the TOML schema attached to a database type");
+    schema
+        .command("generate")
+        .description("Scaffold a starting TOML schema for <database-type> from existing operations + DO introspection, and insert it into the local database-type-configs/<type>.toml file.")
+        .argument("<database-type>", "Database type name")
+        .option("-f, --force", "Overwrite an existing [models.*] block in the local file")
+        .option("--json", "Output the generated TOML as JSON")
+        .action(async (databaseType, options) => {
+        // Resolved before the API call, so a project the CLI cannot resolve is
+        // heard about without a round trip.
+        const targetDir = resolveSyncDir();
+        const resolvedAppId = getCurrentAppId();
         const client = new ApiClient();
         try {
-            await client.revokeDatabaseGroupPermission(resolvedAppId, databaseId, groupType, groupId);
-            success(`Permission revoked for group ${groupType}/${groupId}.`);
+            // 1. Call the server's :scaffold endpoint.
+            const result = await client.scaffoldDatabaseTypeSchema(resolvedAppId, databaseType);
+            const scaffoldedToml = result?.schema ?? "";
+            if (options.json) {
+                json({ schema: scaffoldedToml });
+                return;
+            }
+            // 2. Locate the local `database-type-configs/<type>.toml` file, at
+            // `<config-dir>/database-type-configs/<type>.toml`.
+            //
+            // ONE file, for ONE environment (#3153, F4). This used to scan every
+            // `primitive/<env>/` slot under the cwd and edit every
+            // match, which spliced a scaffold generated against the selected
+            // environment's server into other environments' committed files. The
+            // directory now comes from the same resolver every other tree command
+            // uses, so the file it edits is the selected environment's.
+            const candidateFiles = [];
+            const candidate = path.join(targetDir, "database-type-configs", `${databaseType}.toml`);
+            if (existsSync(candidate))
+                candidateFiles.push(candidate);
+            if (candidateFiles.length === 0) {
+                // No local file found — print the scaffold to stdout and tell
+                // the user where to put it.
+                info(`No local database-type-configs/${databaseType}.toml found at ${candidate}. Generated TOML:`);
+                console.log("");
+                console.log(scaffoldedToml);
+                return;
+            }
+            // 3. For each candidate, splice the scaffolded TOML at a stable
+            // anchor (before the first `[[operations]]` block, or at EOF). Per
+            // the plan-of-record, textual insertion is deliberate — smol-toml
+            // parse/stringify drops comments, so we splice as a raw string.
+            for (const targetPath of candidateFiles) {
+                const original = readFileSync(targetPath, "utf-8");
+                // Detect existing [models.*] block. If present, refuse unless --force.
+                const hasModelsBlock = /\n\[models\./.test("\n" + original);
+                if (hasModelsBlock && !options.force) {
+                    error(`${targetPath} already has [models.*] blocks. Re-run with --force to overwrite.`);
+                    process.exit(1);
+                }
+                // Strip existing [models.*] blocks if --force.
+                let cleaned = original;
+                if (hasModelsBlock && options.force) {
+                    cleaned = stripModelsBlocks(original);
+                }
+                // Splice: insert before the first [[operations]] block, otherwise
+                // at the end of file.
+                let merged;
+                const opsAnchor = cleaned.indexOf("\n[[operations]]");
+                if (opsAnchor >= 0) {
+                    merged =
+                        cleaned.slice(0, opsAnchor + 1) +
+                            scaffoldedToml +
+                            "\n" +
+                            cleaned.slice(opsAnchor + 1);
+                }
+                else {
+                    const sep = cleaned.endsWith("\n") ? "" : "\n";
+                    merged = cleaned + sep + scaffoldedToml + "\n";
+                }
+                writeFileSync(targetPath, merged);
+                success(`Inserted schema into ${targetPath}`);
+            }
+            info("Review the generated schema, fix types the generator guessed wrong, then run `primitive config push` (or `primitive config push --dry-run`).");
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ============================================
+    // Codegen command (issue #814)
+    // ============================================
+    databases
+        .command("codegen")
+        .description("Generate record + operation types from the local database-type-configs/*.toml schema. TypeScript (default): a <type>.generated.ts per database type (record interfaces, per-op input-params interfaces, per-op result aliases, and a typed <type>Ops factory). Swift (--lang swift): a <type>.generated.swift per database type (record structs, per-op params structs, per-op result typealiases, and a typed <Type>Ops factory).\n\nFormatting: the emitted TypeScript is already formatted the way Prettier's DEFAULT config formats it, so a `codegen` -> `prettier --write` -> `codegen --check` pipeline stays green. If your project uses a NON-default Prettier config (a different printWidth, trailingComma, or quote style), Prettier will reformat the generated files and `--check` will then fail: add the generated directory to `.prettierignore` and commit the raw emission instead.")
+        .argument("[database-type]", "Generate for a single database type (defaults to every database-type-configs/*.toml found)")
+        .option("-o, --output <dir>", "Output directory for the generated files (defaults to <config-dir>/database-type-configs/generated/)")
+        .option("--lang <lang>", "Target language for the generated types: 'ts' (default) or 'swift'.", "ts")
+        .option("--check", "Exit non-zero if generated output is out of date (CI guard); does not write. Compares byte-for-byte, so the file on disk must match the emission exactly.")
+        .option("--json", "Output the result summary as JSON")
+        .action(async (databaseType, options) => {
+        try {
+            // 0. Validate --lang up front so an unknown value fails clearly rather
+            //    than silently defaulting to the TS emitter.
+            const lang = String(options.lang ?? "ts").toLowerCase();
+            if (lang !== "ts" && lang !== "swift") {
+                error(`Unknown --lang "${options.lang}". Use "ts" or "swift".`);
+                process.exit(1);
+            }
+            // 1. The single source database-type-configs/ directory: the
+            //    environment's, and only ever the environment's (#1510, #3154).
+            const dbTypesSourceDir = resolveCodegenSourceDir({
+                subdir: "database-type-configs",
+            });
+            // 2. Collect the source .toml files (one per database type), filtered
+            //    to a single type when an argument is given.
+            const inputs = [];
+            for (const fileName of readdirSync(dbTypesSourceDir)) {
+                if (!fileName.endsWith(".toml"))
+                    continue;
+                const typeName = fileName.slice(0, -".toml".length);
+                if (databaseType && typeName !== databaseType)
+                    continue;
+                const tomlPath = path.join(dbTypesSourceDir, fileName);
+                inputs.push({
+                    databaseType: typeName,
+                    tomlPath,
+                    tomlContent: readFileSync(tomlPath, "utf-8"),
+                });
+            }
+            if (inputs.length === 0) {
+                error(databaseType
+                    ? `No database-type-configs/${databaseType}.toml found under primitive/<env>/.`
+                    : "No database-type-configs/*.toml files found to generate from.");
+                process.exit(1);
+            }
+            // 3. Resolve the output directory. Default: a `generated/` subdir of
+            //    the first source dir (keeps generated output beside the schema).
+            const outputDir = options.output
+                ? path.resolve(options.output)
+                : path.join(path.dirname(inputs[0].tomlPath), "generated");
+            // 4. Run codegen (or --check) with the selected emitter. Both the TS
+            //    and Swift generators return the same WriteOrCheckResult shape, so
+            //    the reporting below is emitter-agnostic; only the emitter (and the
+            //    regenerate hint) differs. When a single database-type filter
+            //    argument is given, the input set is partial — flag it so stale
+            //    cleanup is scoped to that type and sibling types' generated files
+            //    are left intact.
+            const codegenResult = lang === "swift"
+                ? await generateDbSwiftTypes({
+                    inputs,
+                    outputDir,
+                    check: !!options.check,
+                    singleType: !!databaseType,
+                })
+                : await generateDbTypes({
+                    inputs,
+                    outputDir,
+                    check: !!options.check,
+                    singleType: !!databaseType,
+                });
+            if (options.check) {
+                if (codegenResult.mismatches.length > 0) {
+                    if (options.json) {
+                        json({ ok: false, mismatches: codegenResult.mismatches });
+                    }
+                    else {
+                        error(`Check failed: ${codegenResult.mismatches.length} file(s) out of date.`);
+                        for (const m of codegenResult.mismatches) {
+                            error(`  ${m.reason}: ${path.relative(process.cwd(), m.filePath)}`);
+                        }
+                        // Echo back the options that decide WHERE and WHAT was
+                        // checked, the way `workflows codegen` does (#2895). Suggesting
+                        // a bare `databases codegen` after a `--check -o <dir>` sent
+                        // people to regenerate into the default
+                        // <config-dir>/database-type-configs/generated/ instead of the
+                        // directory that is actually out of date, so the files stayed
+                        // stale and the next check failed the same way (#2911).
+                        const regenerate = ["primitive databases codegen"];
+                        if (databaseType)
+                            regenerate.push(databaseType);
+                        if (lang === "swift")
+                            regenerate.push("--lang swift");
+                        if (options.output)
+                            regenerate.push(`-o ${options.output}`);
+                        info(`Run \`${regenerate.join(" ")}\` to regenerate.`);
+                    }
+                    process.exit(1);
+                }
+                if (options.json) {
+                    json({ ok: true, checked: codegenResult.writtenFiles.length });
+                }
+                else {
+                    success(`Check passed: ${codegenResult.writtenFiles.length} file(s) up to date.`);
+                }
+                return;
+            }
+            if (options.json) {
+                json({
+                    written: codegenResult.writtenFiles,
+                    deleted: codegenResult.deletedFiles,
+                });
+                return;
+            }
+            success(`Generated ${codegenResult.writtenFiles.length} file(s)` +
+                (codegenResult.deletedFiles.length > 0
+                    ? `, deleted ${codegenResult.deletedFiles.length} stale file(s).`
+                    : "."));
+            for (const f of codegenResult.writtenFiles) {
+                keyValue("  wrote", path.relative(process.cwd(), f));
+            }
+            for (const f of codegenResult.deletedFiles) {
+                keyValue("  deleted", path.relative(process.cwd(), f));
+            }
         }
         catch (err) {
             error(err.message);
@@ -765,4 +2120,274 @@ Examples:
         }
     });
 }
+/** Remove every existing `[models.*]` block from a TOML file body. */
+function stripModelsBlocks(text) {
+    const lines = text.split("\n");
+    const result = [];
+    let skipping = false;
+    for (const line of lines) {
+        const isModelsHeader = /^\s*\[models\b/.test(line);
+        const isOtherHeader = /^\s*\[(?!models\b)/.test(line);
+        if (isModelsHeader) {
+            skipping = true;
+            continue;
+        }
+        if (skipping && isOtherHeader) {
+            skipping = false;
+        }
+        if (!skipping)
+            result.push(line);
+    }
+    return result.join("\n");
+}
+// ============================================
+// Database export/import helpers
+// ============================================
+async function exportSingleDatabase(client, appId, databaseId, outputDir, jsonOutput) {
+    const dbDir = path.join(outputDir, "databases", databaseId);
+    mkdirSync(dbDir, { recursive: true });
+    // 1. Fetch database metadata
+    const dbMeta = await client.getDatabase(appId, databaseId);
+    // Warn about databaseType sync
+    if (dbMeta.databaseType) {
+        warn(`This database uses type "${dbMeta.databaseType}". Make sure to \`primitive config push\` the type config before importing into a new app.`);
+    }
+    // 2. Write metadata
+    const metadata = {
+        databaseId: dbMeta.databaseId || databaseId,
+        title: dbMeta.title,
+        databaseType: dbMeta.databaseType || null,
+        metadata: dbMeta.metadata || null,
+    };
+    writeFileSync(path.join(dbDir, "metadata.json"), JSON.stringify(metadata, null, 2));
+    // 3. Export records: list models, then query each.
+    // listDatabaseModels() resolves to `{ models: string[] }`, not a bare array,
+    // so unwrap it before iterating (mirrors the `databases records models`
+    // consumer above). Without this, `for (const modelName of models)` throws
+    // "models is not iterable" and records.jsonl is left empty (#1396).
+    const models = (await client.listDatabaseModels(appId, databaseId)).models || [];
+    let totalRecords = 0;
+    const recordsFile = path.join(dbDir, "records.jsonl");
+    // Clear file
+    writeFileSync(recordsFile, "");
+    for (const modelName of models) {
+        let cursor;
+        let hasMore = true;
+        while (hasMore) {
+            const result = await client.queryDatabaseRecords(appId, databaseId, modelName, {
+                limit: 100,
+                cursor,
+            });
+            const records = result.items;
+            for (const record of records) {
+                const line = JSON.stringify({ _type: modelName, _id: record.id, _data: record });
+                appendFileSync(recordsFile, line + "\n");
+                totalRecords++;
+            }
+            cursor = result.nextCursor;
+            hasMore = !!cursor && records.length > 0;
+        }
+    }
+    // 4. Export indexes
+    const indexes = await client.listDatabaseIndexes(appId, databaseId);
+    writeFileSync(path.join(dbDir, "indexes.json"), JSON.stringify(indexes, null, 2));
+    // 5. Export unique constraints
+    const constraints = await client.listDatabaseUniqueConstraints(appId, databaseId);
+    writeFileSync(path.join(dbDir, "constraints.json"), JSON.stringify(constraints, null, 2));
+    if (jsonOutput) {
+        json({
+            databaseId,
+            title: metadata.title,
+            databaseType: metadata.databaseType,
+            models: models.length,
+            records: totalRecords,
+            indexes: indexes.length,
+            constraints: constraints.length,
+            exportPath: dbDir,
+        });
+    }
+    else {
+        success(`Exported database ${databaseId} (${metadata.title || "untitled"}) to ${dbDir}`);
+        keyValue("  Models", String(models.length));
+        keyValue("  Records", String(totalRecords));
+        keyValue("  Indexes", String(indexes.length));
+    }
+}
+/**
+ * Conservative client-side ceiling for `databases import --batch-size`.
+ * `records/batch` has no fixed server-side item cap (unlike the
+ * registered-batch path used by `import-csv`), so this bounds each request to
+ * keep it within Cloudflare body-size and Durable Object memory limits.
+ */
+const IMPORT_BATCH_SIZE_CEILING = 25000;
+async function importSingleDatabase(client, appId, dbDir, options) {
+    const { overwrite, dryRun, batchSize, stopOnError, json: jsonOutput, summary } = options;
+    const metadataPath = path.join(dbDir, "metadata.json");
+    if (!existsSync(metadataPath)) {
+        warn(`Skipping ${dbDir}: no metadata.json found`);
+        summary.skipped++;
+        return;
+    }
+    const metadata = JSON.parse(readFileSync(metadataPath, "utf-8"));
+    const databaseId = metadata.databaseId;
+    if (dryRun) {
+        // Report record/batch counts without writing anything (no DB creation,
+        // no index registration, no batch write).
+        const recordCount = countRecordLines(dbDir);
+        const batchCount = chunk(new Array(recordCount), batchSize).length;
+        summary.created++;
+        summary.recordsImported += recordCount;
+        summary.batches += batchCount;
+        info(`[dry-run] Would import database ${databaseId} (${metadata.title || "untitled"}) — ${recordCount} record(s), ${batchCount} batch(es)`);
+        return;
+    }
+    // Check if database type exists — warn if not
+    if (metadata.databaseType) {
+        warn(`Database uses type "${metadata.databaseType}". Ensure the type config exists in the target app (use \`primitive config push\`).`);
+    }
+    // Check if database exists — use the original ID for overwrite scenarios
+    let targetDatabaseId = databaseId;
+    let exists = false;
+    try {
+        await client.getDatabase(appId, databaseId);
+        exists = true;
+    }
+    catch {
+        exists = false;
+    }
+    if (exists && !overwrite) {
+        warn(`Skipping ${databaseId}: already exists (use --overwrite to replace)`);
+        summary.skipped++;
+        return;
+    }
+    // Create database if it doesn't exist
+    // Note: server auto-generates the ID, so we capture it for subsequent operations
+    if (!exists) {
+        const createData = {
+            title: metadata.title || "Imported Database",
+        };
+        if (metadata.databaseType) {
+            createData.databaseType = metadata.databaseType;
+        }
+        if (metadata.metadata) {
+            createData.metadata = metadata.metadata;
+        }
+        const created = await client.createDatabase(appId, createData);
+        targetDatabaseId = created.databaseId || created.id || databaseId;
+        summary.created++;
+    }
+    else {
+        summary.updated++;
+    }
+    // Register indexes
+    const indexesPath = path.join(dbDir, "indexes.json");
+    if (existsSync(indexesPath)) {
+        const indexes = JSON.parse(readFileSync(indexesPath, "utf-8"));
+        for (const idx of indexes) {
+            try {
+                await client.registerDatabaseIndex(appId, targetDatabaseId, {
+                    modelName: idx.modelName || idx.model_name,
+                    fieldName: idx.fieldName || idx.field_name,
+                    fieldType: idx.fieldType || idx.field_type || "string",
+                    unique: idx.isUnique || idx.is_unique || false,
+                });
+                summary.indexesRegistered++;
+            }
+            catch {
+                // Index may already exist
+            }
+        }
+    }
+    // Register unique constraints
+    const constraintsPath = path.join(dbDir, "constraints.json");
+    if (existsSync(constraintsPath)) {
+        const constraints = JSON.parse(readFileSync(constraintsPath, "utf-8"));
+        for (const c of constraints) {
+            try {
+                await client.registerDatabaseUniqueConstraint(appId, targetDatabaseId, {
+                    modelName: c.modelName || c.model_name,
+                    constraintName: c.constraintName || c.constraint_name,
+                    fields: c.fields ? (typeof c.fields === "string" ? JSON.parse(c.fields) : c.fields) : [],
+                });
+            }
+            catch {
+                // Constraint may already exist
+            }
+        }
+    }
+    // Import records via chunked batch writes (was one save per record).
+    const recordsPath = path.join(dbDir, "records.jsonl");
+    if (existsSync(recordsPath)) {
+        const lines = readFileSync(recordsPath, "utf-8").split("\n").filter(Boolean);
+        // Map each records.jsonl line to a batch save op. Preserve the explicit
+        // `_type`/`_id`; strip the redundant id/type keys out of `_data` (the
+        // per-record loop did the same) so they don't duplicate into stored data.
+        const ops = lines.map((line) => {
+            const record = JSON.parse(line);
+            const { _type, _id, _data } = record;
+            const { id: _ignoredId, type: _ignoredType, ...data } = _data;
+            return { op: "save", modelName: _type, id: _id, data };
+        });
+        const chunks = chunk(ops, batchSize);
+        summary.batches += chunks.length;
+        for (let i = 0; i < chunks.length; i++) {
+            const piece = chunks[i];
+            let chunkFailed = false;
+            try {
+                const res = await client.batchDatabaseRecords(appId, targetDatabaseId, piece);
+                const results = res?.results ?? [];
+                let imported = 0;
+                let failed = 0;
+                const firstErrors = [];
+                for (let j = 0; j < piece.length; j++) {
+                    const r = results[j];
+                    if (r && r.success) {
+                        imported++;
+                    }
+                    else {
+                        failed++;
+                        if (r?.error && firstErrors.length < 3)
+                            firstErrors.push(r.error);
+                    }
+                }
+                summary.recordsImported += imported;
+                summary.recordsFailed += failed;
+                if (failed > 0) {
+                    chunkFailed = true;
+                    summary.batchErrors.push({
+                        database: databaseId,
+                        batch: i,
+                        error: `${failed} record(s) failed${firstErrors.length ? `: ${firstErrors.join("; ")}` : ""}`,
+                    });
+                }
+                if (!jsonOutput) {
+                    info(`  ${databaseId} batch ${i + 1}/${chunks.length}: imported ${imported}, failed ${failed}`);
+                }
+            }
+            catch (err) {
+                // Chunk-level failure (e.g. a 400 for a malformed op): the whole chunk
+                // is rejected, so every item in it counts as failed.
+                const msg = err?.message || String(err);
+                chunkFailed = true;
+                summary.recordsFailed += piece.length;
+                summary.batchErrors.push({ database: databaseId, batch: i, error: msg });
+                if (!jsonOutput) {
+                    warn(`  ${databaseId} batch ${i + 1}/${chunks.length} failed: ${msg}`);
+                }
+            }
+            if (chunkFailed && stopOnError) {
+                summary.aborted = true;
+                return;
+            }
+        }
+    }
+    info(`Imported database ${databaseId} (${metadata.title || "untitled"})`);
+}
+/** Count non-empty lines in a database export's records.jsonl (0 if absent). */
+function countRecordLines(dbDir) {
+    const recordsPath = path.join(dbDir, "records.jsonl");
+    if (!existsSync(recordsPath))
+        return 0;
+    return readFileSync(recordsPath, "utf-8").split("\n").filter(Boolean).length;
+}
 //# sourceMappingURL=databases.js.map