@tenderprompt/cli 0.1.13 → 0.1.14

package/README.md

@@ -133,9 +133,10 @@ tender app build artifact_123 --commit "$(git rev-parse HEAD)" --json
 tender app preview artifact_123 --commit "$(git rev-parse HEAD)" --stream --json
 tender app publish artifact_123 --dry-run --json
 tender app db capabilities artifact_123 --json
-tender app db tables artifact_123 --json
-tender app db schema artifact_123 --table votes --json
-tender app db query artifact_123 --sql "select * from votes limit 20" --json
+tender app db tables artifact_123 --env published --json
+tender app db schema artifact_123 --env published --table votes --json
+tender app db query artifact_123 --env published --sql "select * from votes limit 20" --json
+tender app db query artifact_123 --env published --sql "select * from votes order by created_at" --limit 50 --offset 50 --json
 ```
 
 ## Analytics
@@ -249,7 +250,8 @@ ids, URLs, or high-cardinality values unless the chart has a clear purpose.
 App database commands are artifact-scoped and go through Tender's server-side
 authorization and read-only query checks. The CLI only accepts an app id; it
 does not accept tenant ids, runner names, provider account ids, or runtime
-storage identifiers.
+storage identifiers. Commands that read data require an explicit `--env preview`
+or `--env published`; there is no default environment.
 
 Start with capabilities:
 
@@ -262,24 +264,28 @@ tender app db capabilities artifact_123 --profile db --json
 Common read-only commands:
 
 ```bash
-tender app db tables artifact_123 --profile db --json
+tender app db tables artifact_123 --env published --profile db --json
 
-tender app db schema artifact_123 --table votes --profile db --json
+tender app db schema artifact_123 --env published --table votes --profile db --json
 
-tender app db query artifact_123 --sql "select * from votes limit 20" --profile db --json
+tender app db query artifact_123 --env published --sql "select * from votes limit 20" --profile db --json
 
 tender app db query artifact_123 \
+  --env published \
   --sql "select * from votes where choice = ?" \
   --param coffee \
   --profile db \
   --json
 
-tender app db query artifact_123 --file ./debug.sql --limit 50 --profile db --json
+tender app db query artifact_123 --env published --file ./debug.sql --limit 50 --offset 100 --profile db --json
 
-tender app db query artifact_123 --file - --profile db --json < debug.sql
+tender app db query artifact_123 --env published --file - --offset 100 --profile db --json < debug.sql
 ```
 
-The query command sends one read-only statement with positional bindings.
+The query command sends one read-only statement with positional bindings. Query
+responses include `requestedLimit`, `appliedLimit`, `maxInteractiveLimit`,
+`offset`, and `nextOffset`; agents must request each page explicitly and should
+not auto-drain large tables. The interactive row cap is 50 rows per request.
 Client and server limits include a 100 KB statement cap and at most 100 bound
 parameters. The server enforces the final policy, row limits, response limits,
 artifact scope, and audit logging.

package/dist/index.js

@@ -41,18 +41,26 @@ class TenderCliUsageError extends Error {
 }
 class TenderCliAnalyticsApiError extends Error {
     reasonCode;
-    constructor(message, reasonCode) {
+    scope;
+    example;
+    constructor(message, reasonCode, scope = null, example = null) {
         super(message);
         this.name = "TenderCliAnalyticsApiError";
         this.reasonCode = reasonCode;
+        this.scope = scope;
+        this.example = example;
     }
 }
 class TenderCliDbApiError extends Error {
     reasonCode;
-    constructor(message, reasonCode) {
+    scope;
+    example;
+    constructor(message, reasonCode, scope, example) {
         super(message);
         this.name = "TenderCliDbApiError";
         this.reasonCode = reasonCode;
+        this.scope = scope;
+        this.example = example;
     }
 }
 const DEFAULT_PROFILE_NAME = "default";
@@ -101,7 +109,7 @@ Commands:
                              Generate useful starter chart suggestions
   tender app db capabilities <app-id>
                              Describe app database query limits and policy
-  tender app db query <app-id> --sql <sql>
+  tender app db query <app-id> --env <preview|published> --sql <sql>
                              Run one read-only app database query
   tender app context fetch <app-id>
                              Fetch managed agent context into a checkout
@@ -135,9 +143,9 @@ Examples:
   tender app analytics query artifact_123 --spec chart.json --json
   tender app analytics suggestions artifact_123 --range 30d --json
   tender app db capabilities artifact_123 --json
-  tender app db tables artifact_123 --json
-  tender app db schema artifact_123 --table votes --json
-  tender app db query artifact_123 --sql "select * from votes limit 20" --json
+  tender app db tables artifact_123 --env published --json
+  tender app db schema artifact_123 --env published --table votes --json
+  tender app db query artifact_123 --env published --sql "select * from votes limit 20" --json
   tender app context fetch artifact_123 --dir ./widget --dry-run --json
   tender app context status artifact_123 --dir ./widget --json
   tender app context refresh artifact_123 --dir ./widget --dry-run --json
@@ -238,11 +246,11 @@ Commands:
                              Make a custom event property queryable
   tender app db capabilities <app-id>
                              Describe app database query limits and policy
-  tender app db tables <app-id>
+  tender app db tables <app-id> --env <preview|published>
                              List app database tables and views
-  tender app db schema <app-id> --table <name>
+  tender app db schema <app-id> --env <preview|published> --table <name>
                              Show table and index schema for one table
-  tender app db query <app-id> --sql <sql>
+  tender app db query <app-id> --env <preview|published> --sql <sql>
                              Run one read-only app database query
   tender app context fetch <app-id>
                              Fetch AGENTS.md, skills, and Tender App scaffold files
@@ -285,9 +293,9 @@ Examples:
   tender app analytics properties list artifact_123 --json
   tender app analytics properties activate artifact_123 --event signup_started --property plan --type dimension --dry-run --json
   tender app db capabilities artifact_123 --json
-  tender app db tables artifact_123 --json
-  tender app db schema artifact_123 --table votes --json
-  tender app db query artifact_123 --sql "select * from votes limit 20" --json
+  tender app db tables artifact_123 --env published --json
+  tender app db schema artifact_123 --env published --table votes --json
+  tender app db query artifact_123 --env published --sql "select * from votes limit 20" --json
   tender app context fetch artifact_123 --dir ./widget --dry-run --json
   tender app context status artifact_123 --dir ./widget --json
   tender app context refresh artifact_123 --dir ./widget --dry-run --json
@@ -471,16 +479,19 @@ function dbHelp() {
 
 Commands:
   tender app db capabilities <app-id>  Describe app database policy and limits
-  tender app db tables <app-id>        List app database tables and views
-  tender app db schema <app-id>        Show schema for one table
-  tender app db query <app-id>         Run one read-only SQL query
+  tender app db tables <app-id> --env <preview|published>
+                                      List app database tables and views
+  tender app db schema <app-id> --env <preview|published>
+                                      Show schema for one table
+  tender app db query <app-id> --env <preview|published>
+                                      Run one read-only SQL query
 
 Examples:
   tender app db capabilities artifact_123 --json
-  tender app db tables artifact_123 --json
-  tender app db schema artifact_123 --table votes --json
-  tender app db query artifact_123 --sql "select * from votes limit 20" --json
-  tender app db query artifact_123 --file ./debug.sql --param active --limit 50 --json`;
+  tender app db tables artifact_123 --env published --json
+  tender app db schema artifact_123 --env published --table votes --json
+  tender app db query artifact_123 --env published --sql "select * from votes limit 20" --json
+  tender app db query artifact_123 --env published --file ./debug.sql --param active --limit 50 --json`;
 }
 function dbCapabilitiesHelp() {
     return `Usage: tender app db capabilities <app-id> [--base-url <url>] [--token <token>] [--profile <name>] [--json]
@@ -489,33 +500,35 @@ Examples:
   tender app db capabilities artifact_123 --json`;
 }
 function dbTablesHelp() {
-    return `Usage: tender app db tables <app-id> [--env preview] [--base-url <url>] [--token <token>] [--profile <name>] [--json]
+    return `Usage: tender app db tables <app-id> --env <preview|published> [--base-url <url>] [--token <token>] [--profile <name>] [--json]
 
 Examples:
-  tender app db tables artifact_123 --json
+  tender app db tables artifact_123 --env published --json
   tender app db tables artifact_123 --env preview --json`;
 }
 function dbSchemaHelp() {
-    return `Usage: tender app db schema <app-id> --table <name> [--env preview] [--base-url <url>] [--token <token>] [--profile <name>] [--json]
+    return `Usage: tender app db schema <app-id> --env <preview|published> --table <name> [--base-url <url>] [--token <token>] [--profile <name>] [--json]
 
 Examples:
-  tender app db schema artifact_123 --table votes --json
+  tender app db schema artifact_123 --env published --table votes --json
   tender app db schema artifact_123 --table preference_votes --env preview --json`;
 }
 function dbQueryHelp() {
-    return `Usage: tender app db query <app-id> (--sql <sql> | --file <path|->) [--param <value>] [--limit <n>] [--env preview] [--base-url <url>] [--token <token>] [--profile <name>] [--json]
+    return `Usage: tender app db query <app-id> --env <preview|published> (--sql <sql> | --file <path|->) [--param <value>] [--limit <n>] [--offset <n>] [--base-url <url>] [--token <token>] [--profile <name>] [--json]
 
 Options:
+  --env <value>     Target app environment: preview or published. Required.
   --sql <sql>       SQL statement. Must be one read-only statement.
   --file <path|->   Read SQL from a file or stdin with -.
-  --param <value>   Bind one positional parameter. Repeat for multiple params. Values parse as JSON scalars, falling back to string.
-  --limit <n>       Interactive row limit. Server caps the maximum.
+  --param <value>   Bind one positional parameter. Repeat for multiple params. Values parse as numbers or null; other values are passed as strings.
+  --limit <n>       Interactive row limit. Server caps the maximum at 50.
+  --offset <n>      Skip rows before returning results. Server caps the maximum offset.
 
 Examples:
-  tender app db query artifact_123 --sql "select * from votes limit 20" --json
-  tender app db query artifact_123 --sql "select * from votes where choice = ?" --param coffee --json
-  tender app db query artifact_123 --file ./debug.sql --limit 50 --json
-  tender app db query artifact_123 --file - --json < debug.sql`;
+  tender app db query artifact_123 --env published --sql "select * from votes limit 20" --json
+  tender app db query artifact_123 --env published --sql "select * from votes where choice = ?" --param coffee --json
+  tender app db query artifact_123 --env published --file ./debug.sql --limit 50 --offset 100 --json
+  tender app db query artifact_123 --env published --file - --json < debug.sql`;
 }
 function artifactsListHelp() {
     return `Usage: tender app list [--base-url <url>] [--token <token>] [--profile <name>] [--json]
@@ -921,10 +934,10 @@ function tenderCliCapabilities() {
                 commands: [
                     "tender auth login --device --profile db-read --artifact <artifact-id> --ttl 7d --save-profile db --json",
                     "tender app db capabilities <artifact-id> --profile db --json",
-                    "tender app db tables <artifact-id> --profile db --json",
-                    "tender app db schema <artifact-id> --table <table-name> --profile db --json",
-                    "tender app db query <artifact-id> --sql \"select * from <table-name> limit 20\" --profile db --json",
-                    "tender app db query <artifact-id> --file ./debug.sql --profile db --json",
+                    "tender app db tables <artifact-id> --env published --profile db --json",
+                    "tender app db schema <artifact-id> --env published --table <table-name> --profile db --json",
+                    "tender app db query <artifact-id> --env published --sql \"select * from <table-name> limit 20\" --profile db --json",
+                    "tender app db query <artifact-id> --env published --file ./debug.sql --profile db --json",
                 ],
                 notes: [
                     "The CLI only accepts artifact ids. It never accepts tenant ids, runner names, provider account ids, or runtime storage identifiers.",
@@ -1032,19 +1045,19 @@ function tenderCliCapabilities() {
                 writes: false,
             },
             {
-                command: "tender app db tables <artifact-id> --json",
+                command: "tender app db tables <artifact-id> --env published --json",
                 purpose: "List app database tables and views for one artifact.",
                 requiresAuth: true,
                 writes: false,
             },
             {
-                command: "tender app db schema <artifact-id> --table <table-name> --json",
+                command: "tender app db schema <artifact-id> --env published --table <table-name> --json",
                 purpose: "Inspect table, index, and trigger schema for one app database table.",
                 requiresAuth: true,
                 writes: false,
             },
             {
-                command: "tender app db query <artifact-id> --sql \"select * from <table-name> limit 20\" --json",
+                command: "tender app db query <artifact-id> --env published --sql \"select * from <table-name> limit 20\" --json",
                 purpose: "Run one bounded read-only app database query.",
                 requiresAuth: true,
                 writes: false,
@@ -2402,6 +2415,13 @@ function parsePositiveIntegerFlag(value, flag) {
     }
     return parsed;
 }
+function parseNonNegativeIntegerFlag(value, flag) {
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 0) {
+        throw new TenderCliUsageError(`${flag} requires a non-negative integer.`);
+    }
+    return parsed;
+}
 function parseAuthLoginArgs(args) {
     if (args.includes("--help") || args.includes("-h")) {
         return { command: "help", topic: "auth login" };
@@ -3457,10 +3477,23 @@ function parseDbCommonArgs(args, startIndex) {
     return { baseUrl, flagToken, profileName, json, remaining };
 }
 function parseDbEnvironment(value) {
-    if (value === undefined || value === "preview") {
+    if (!value || value.startsWith("--")) {
+        throw new TenderCliUsageError("--env requires a value. Use preview or published.");
+    }
+    if (value === "preview") {
         return "preview";
     }
-    throw new TenderCliUsageError("--env must be preview.");
+    if (value === "published" ||
+        value === "live" ||
+        value === "production" ||
+        value === "prod") {
+        return "published";
+    }
+    throw new TenderCliUsageError("--env must be preview or published.");
+}
+function parseFlagAssignment(arg, flag) {
+    const prefix = `${flag}=`;
+    return arg.startsWith(prefix) ? arg.slice(prefix.length) : null;
 }
 function parseDbFlagValue(value, flag) {
     if (!value || value.startsWith("--")) {
@@ -3468,6 +3501,12 @@ function parseDbFlagValue(value, flag) {
     }
     return value;
 }
+function parseDbSqlFlagValue(value) {
+    if (value === undefined || value.length === 0) {
+        throw new TenderCliUsageError("--sql requires a value.");
+    }
+    return value;
+}
 function parseDbFilePath(value) {
     if (!value || (value !== "-" && value.startsWith("-"))) {
         throw new TenderCliUsageError("--file requires a SQL file path or - for stdin.");
@@ -3509,12 +3548,17 @@ function parseDbTablesArgs(args) {
     }
     const artifactId = args[0];
     if (!artifactId || artifactId.startsWith("-")) {
-        throw new TenderCliUsageError("app id is required. Example: tender app db tables <app-id> --json");
+        throw new TenderCliUsageError("app id is required. Example: tender app db tables <app-id> --env published --json");
     }
     const parsed = parseDbCommonArgs(args, 1);
-    let environment = "preview";
+    let environment = null;
     for (let index = 0; index < parsed.remaining.length; index += 1) {
         const arg = parsed.remaining[index];
+        const envAssignment = parseFlagAssignment(arg, "--env");
+        if (envAssignment !== null) {
+            environment = parseDbEnvironment(envAssignment);
+            continue;
+        }
         if (arg === "--env") {
             environment = parseDbEnvironment(parsed.remaining[index + 1]);
             index += 1;
@@ -3522,6 +3566,9 @@ function parseDbTablesArgs(args) {
         }
         throw new TenderCliUsageError(`Unknown app db tables option: ${arg}`);
     }
+    if (!environment) {
+        throw new TenderCliUsageError("--env is required. Example: tender app db tables artifact_123 --env published --json");
+    }
     return { command: "app db tables", artifactId, environment, ...parsed };
 }
 function parseDbSchemaArgs(args) {
@@ -3530,13 +3577,23 @@ function parseDbSchemaArgs(args) {
     }
     const artifactId = args[0];
     if (!artifactId || artifactId.startsWith("-")) {
-        throw new TenderCliUsageError("app id is required. Example: tender app db schema <app-id> --table votes --json");
+        throw new TenderCliUsageError("app id is required. Example: tender app db schema <app-id> --env published --table votes --json");
     }
     const parsed = parseDbCommonArgs(args, 1);
-    let environment = "preview";
+    let environment = null;
     let tableName = null;
     for (let index = 0; index < parsed.remaining.length; index += 1) {
         const arg = parsed.remaining[index];
+        const envAssignment = parseFlagAssignment(arg, "--env");
+        if (envAssignment !== null) {
+            environment = parseDbEnvironment(envAssignment);
+            continue;
+        }
+        const tableAssignment = parseFlagAssignment(arg, "--table");
+        if (tableAssignment !== null) {
+            tableName = parseRequiredFlagValue(tableAssignment, "--table");
+            continue;
+        }
         if (arg === "--env") {
             environment = parseDbEnvironment(parsed.remaining[index + 1]);
             index += 1;
@@ -3549,8 +3606,11 @@ function parseDbSchemaArgs(args) {
         }
         throw new TenderCliUsageError(`Unknown app db schema option: ${arg}`);
     }
+    if (!environment) {
+        throw new TenderCliUsageError("--env is required. Example: tender app db schema artifact_123 --env published --table votes --json");
+    }
     if (!tableName) {
-        throw new TenderCliUsageError("--table is required. Example: tender app db schema artifact_123 --table votes --json");
+        throw new TenderCliUsageError("--table is required. Example: tender app db schema artifact_123 --env published --table votes --json");
     }
     return {
         command: "app db schema",
@@ -3566,15 +3626,58 @@ function parseDbQueryArgs(args) {
     }
     const artifactId = args[0];
     if (!artifactId || artifactId.startsWith("-")) {
-        throw new TenderCliUsageError("app id is required. Example: tender app db query <app-id> --sql \"select * from votes limit 20\" --json");
+        throw new TenderCliUsageError("app id is required. Example: tender app db query <app-id> --env published --sql \"select * from votes limit 20\" --json");
     }
     const parsed = parseDbCommonArgs(args, 1);
-    let environment = "preview";
+    let environment = null;
     let sqlSource = null;
     const params = [];
     let limit = null;
+    let offset = 0;
     for (let index = 0; index < parsed.remaining.length; index += 1) {
         const arg = parsed.remaining[index];
+        const envAssignment = parseFlagAssignment(arg, "--env");
+        if (envAssignment !== null) {
+            environment = parseDbEnvironment(envAssignment);
+            continue;
+        }
+        const sqlAssignment = parseFlagAssignment(arg, "--sql");
+        if (sqlAssignment !== null) {
+            if (sqlSource) {
+                throw new TenderCliUsageError("--sql and --file cannot be repeated or combined.");
+            }
+            sqlSource = {
+                kind: "inline",
+                value: parseDbSqlFlagValue(sqlAssignment),
+            };
+            continue;
+        }
+        const fileAssignment = parseFlagAssignment(arg, "--file");
+        if (fileAssignment !== null) {
+            if (sqlSource) {
+                throw new TenderCliUsageError("--sql and --file cannot be repeated or combined.");
+            }
+            sqlSource = {
+                kind: "file",
+                value: parseDbFilePath(fileAssignment),
+            };
+            continue;
+        }
+        const paramAssignment = parseFlagAssignment(arg, "--param");
+        if (paramAssignment !== null) {
+            params.push(parseDbParameter(paramAssignment));
+            continue;
+        }
+        const limitAssignment = parseFlagAssignment(arg, "--limit");
+        if (limitAssignment !== null) {
+            limit = parsePositiveIntegerFlag(limitAssignment, "--limit");
+            continue;
+        }
+        const offsetAssignment = parseFlagAssignment(arg, "--offset");
+        if (offsetAssignment !== null) {
+            offset = parseNonNegativeIntegerFlag(offsetAssignment, "--offset");
+            continue;
+        }
         if (arg === "--env") {
             environment = parseDbEnvironment(parsed.remaining[index + 1]);
             index += 1;
@@ -3586,7 +3689,7 @@ function parseDbQueryArgs(args) {
             }
             sqlSource = {
                 kind: "inline",
-                value: parseDbFlagValue(parsed.remaining[index + 1], "--sql"),
+                value: parseDbSqlFlagValue(parsed.remaining[index + 1]),
             };
             index += 1;
             continue;
@@ -3612,10 +3715,18 @@ function parseDbQueryArgs(args) {
             index += 1;
             continue;
         }
+        if (arg === "--offset") {
+            offset = parseNonNegativeIntegerFlag(parsed.remaining[index + 1], "--offset");
+            index += 1;
+            continue;
+        }
         throw new TenderCliUsageError(`Unknown app db query option: ${arg}`);
     }
+    if (!environment) {
+        throw new TenderCliUsageError("--env is required. Example: tender app db query artifact_123 --env published --sql \"select * from votes limit 20\" --json");
+    }
     if (!sqlSource) {
-        throw new TenderCliUsageError("--sql or --file is required. Example: tender app db query artifact_123 --sql \"select * from votes limit 20\" --json");
+        throw new TenderCliUsageError("--sql or --file is required. Example: tender app db query artifact_123 --env published --sql \"select * from votes limit 20\" --json");
     }
     if (params.length > DB_MAX_BOUND_PARAMETERS) {
         throw new TenderCliUsageError(`App database queries are limited to ${DB_MAX_BOUND_PARAMETERS} bound parameters.`);
@@ -3627,6 +3738,7 @@ function parseDbQueryArgs(args) {
         sqlSource,
         params,
         limit,
+        offset,
         ...parsed,
     };
 }
@@ -4192,12 +4304,16 @@ async function requestAnalyticsApi(input) {
         const message = (typeof payload?.message === "string" && payload.message) ||
             (typeof payload?.reasonCode === "string" && payload.reasonCode) ||
             `Analytics request failed with HTTP ${response.status}.`;
+        const example = analyticsCorrectedExample(input.artifactId, input.analyticsPath);
         throw new TenderCliAnalyticsApiError([
             message,
             `Scope: artifact ${input.artifactId}, analytics/${input.analyticsPath || "summary"}.`,
             `Reason: ${reasonCode}.`,
-            `Example: ${analyticsCorrectedExample(input.artifactId, input.analyticsPath)}.`,
-        ].join("\n"), reasonCode);
+            `Example: ${example}.`,
+        ].join("\n"), reasonCode, {
+            artifactId: input.artifactId,
+            surface: `analytics/${input.analyticsPath || "summary"}`,
+        }, example);
     }
     return payload;
 }
@@ -4229,12 +4345,16 @@ async function requestDbApi(input) {
         const message = (typeof payload?.message === "string" && payload.message) ||
             (typeof payload?.reasonCode === "string" && payload.reasonCode) ||
             `App database request failed with HTTP ${response.status}.`;
+        const example = dbCorrectedExample(input.artifactId, input.dbPath);
         throw new TenderCliDbApiError([
             message,
             `Scope: artifact ${input.artifactId}, db/${input.dbPath}.`,
             `Reason: ${reasonCode}.`,
-            `Example: ${dbCorrectedExample(input.artifactId, input.dbPath)}.`,
-        ].join("\n"), reasonCode);
+            `Example: ${example}.`,
+        ].join("\n"), reasonCode, {
+            artifactId: input.artifactId,
+            surface: `db/${input.dbPath}`,
+        }, example);
     }
     return payload;
 }
@@ -4243,12 +4363,12 @@ function dbCorrectedExample(artifactId, dbPath) {
         return `tender app db capabilities ${artifactId} --json`;
     }
     if (dbPath === "tables") {
-        return `tender app db tables ${artifactId} --json`;
+        return `tender app db tables ${artifactId} --env published --json`;
     }
     if (dbPath === "schema") {
-        return `tender app db schema ${artifactId} --table <table-name> --json`;
+        return `tender app db schema ${artifactId} --env published --table <table-name> --json`;
     }
-    return `tender app db query ${artifactId} --sql "select * from <table-name> limit 20" --json`;
+    return `tender app db query ${artifactId} --env published --sql "select * from <table-name> limit 20" --json`;
 }
 function analyticsCorrectedExample(artifactId, analyticsPath) {
     if (analyticsPath === "capabilities") {
@@ -4497,7 +4617,7 @@ async function requestAnalyticsQueryWithPropertyGuidance(input) {
                 spec: input.spec,
             });
             if (guidance) {
-                throw new TenderCliAnalyticsApiError(`${error.message}\n\n${guidance}`, error.reasonCode);
+                throw new TenderCliAnalyticsApiError(`${error.message}\n\n${guidance}`, error.reasonCode, error.scope, error.example);
             }
         }
         throw error;
@@ -6641,6 +6761,7 @@ async function runDbQuery(command, io, runtime) {
         sql,
         params: command.params,
         ...(command.limit === null ? {} : { limit: command.limit }),
+        offset: command.offset,
     };
     const payload = await requestDbApi({
         artifactId: command.artifactId,
@@ -6656,7 +6777,12 @@ async function runDbQuery(command, io, runtime) {
         `app_id: ${command.artifactId}`,
         `environment: ${command.environment}`,
         `rows: ${rows.length}`,
+        `offset: ${String(payload.offset ?? command.offset)}`,
+        `applied_limit: ${String(payload.appliedLimit ?? command.limit ?? "")}`,
         `truncated: ${String(payload.truncated ?? false)}`,
+        ...(typeof payload.nextOffset === "number"
+            ? [`next_offset: ${payload.nextOffset}`]
+            : []),
     ]);
     return 0;
 }
@@ -7063,12 +7189,106 @@ async function runAnalyticsChartsDelete(command, io, runtime) {
     ]);
     return 0;
 }
+function cliErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message.split("\n")[0] ?? error.message;
+    }
+    return String(error);
+}
+function cliErrorCode(error) {
+    if (error instanceof TenderCliDbApiError || error instanceof TenderCliAnalyticsApiError) {
+        return error.reasonCode;
+    }
+    if (error && typeof error === "object" && "code" in error) {
+        const code = error.code;
+        if (code === "ENOENT") {
+            return "file_not_found";
+        }
+        if (typeof code === "string" && code.length > 0) {
+            return code.toLowerCase();
+        }
+    }
+    return error instanceof TenderCliUsageError ? "cli_usage_error" : "cli_error";
+}
+function commandNameForError(args, command) {
+    if (command) {
+        return command.command === "help" ? `help ${command.topic}` : command.command;
+    }
+    if (args[0] === "app" && args[1] === "db" && args[2]) {
+        return `app db ${args[2]}`;
+    }
+    if (args[0] === "app" && args[1]) {
+        return `app ${args[1]}`;
+    }
+    return args[0] ?? "unknown";
+}
+function dbPathFromCommandName(commandName) {
+    if (commandName === "app db capabilities") {
+        return "capabilities";
+    }
+    if (commandName === "app db tables") {
+        return "tables";
+    }
+    if (commandName === "app db schema") {
+        return "schema";
+    }
+    if (commandName === "app db query") {
+        return "query";
+    }
+    return null;
+}
+function artifactIdForError(args, command) {
+    if (command && "artifactId" in command) {
+        return command.artifactId;
+    }
+    if (args[0] === "app" && args[1] === "db" && args[3] && !args[3].startsWith("-")) {
+        return args[3];
+    }
+    return null;
+}
+function scopeForError(error, args, command) {
+    if (error instanceof TenderCliDbApiError || error instanceof TenderCliAnalyticsApiError) {
+        return error.scope;
+    }
+    const commandName = commandNameForError(args, command);
+    const dbPath = dbPathFromCommandName(commandName);
+    const artifactId = artifactIdForError(args, command);
+    if (dbPath && artifactId) {
+        return {
+            artifactId,
+            surface: `db/${dbPath}`,
+        };
+    }
+    return null;
+}
+function exampleForError(error, args, command) {
+    if (error instanceof TenderCliDbApiError || error instanceof TenderCliAnalyticsApiError) {
+        return error.example;
+    }
+    const commandName = commandNameForError(args, command);
+    const dbPath = dbPathFromCommandName(commandName);
+    const artifactId = artifactIdForError(args, command) ?? "artifact_123";
+    return dbPath ? dbCorrectedExample(artifactId, dbPath) : null;
+}
+function cliErrorPayload(error, args, command) {
+    const scope = scopeForError(error, args, command);
+    const example = exampleForError(error, args, command);
+    return {
+        ok: false,
+        command: commandNameForError(args, command),
+        reasonCode: cliErrorCode(error),
+        message: cliErrorMessage(error),
+        ...(scope ? { scope } : {}),
+        ...(example ? { example } : {}),
+    };
+}
 export async function runTenderCli(args, io = {
     stdout: (message) => console.log(message),
     stderr: (message) => console.error(message),
 }, runtime = {}) {
+    let command = null;
     try {
-        const command = parseTenderArgs(args);
+        command = parseTenderArgs(args);
         if (command.command === "help") {
             if (command.topic === "capabilities") {
                 io.stdout(capabilitiesHelp());
@@ -7342,6 +7562,10 @@ export async function runTenderCli(args, io = {
         return await runDoctor(command, io);
     }
     catch (error) {
+        if (args.includes("--json") && args[0] === "app" && args[1] === "db") {
+            io.stdout(JSON.stringify(cliErrorPayload(error, args, command), null, 2));
+            return error instanceof TenderCliUsageError ? 2 : 1;
+        }
         io.stderr(error instanceof Error ? error.message : String(error));
         io.stderr("Run `tender --help` for examples.");
         return error instanceof TenderCliUsageError ? 2 : 1;
@@ -7349,7 +7573,7 @@ export async function runTenderCli(args, io = {
 }
 const currentFile = fileURLToPath(import.meta.url);
 function hasFlagValue(args, flag, value) {
-    return args.some((arg, index) => arg === flag && args[index + 1] === value);
+    return args.some((arg, index) => (arg === flag && args[index + 1] === value) || arg === `${flag}=${value}`);
 }
 function shouldReadEntrypointStdin(args) {
     return (args[0] === "app" &&

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tenderprompt/cli",
-	"version": "0.1.13",
+	"version": "0.1.14",
 	"type": "module",
 	"bin": {
 		"tender": "bin/tender.js"