@tenderprompt/cli 0.1.13 → 0.1.15

package/README.md

@@ -16,6 +16,7 @@ npm install -g @tenderprompt/cli
 Then run:
 
 ```bash
+tender --version
 tender capabilities --json
 ```
 
@@ -25,6 +26,8 @@ Use the CLI to work with Tender Apps from a local checkout or coding-agent
 session:
 
 - sign in with a bounded device token and optional artifact scope
+- print the installed CLI package version with `tender --version`, `tender -v`,
+  or `tender version --json`
 - list, create, and rename apps
 - bootstrap a local app checkout with Tender project context
 - configure the Tender artifact Git remote and credential helper
@@ -48,6 +51,7 @@ interactive prompts unless the command is explicitly an auth flow.
 ## Typical Flow
 
 ```bash
+tender --version
 tender capabilities --json
 
 tender auth login --device --profile edit-preview --artifact artifact_123 --ttl 7d
@@ -120,6 +124,7 @@ indexing the accepted commit after upstream Git accepts the push.
 ## Useful Commands
 
 ```bash
+tender --version
 tender capabilities --json
 tender app list --json
 tender app create --name "Exit Intent Widget" --json
@@ -133,9 +138,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 +255,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 +269,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/bin/tender.js

@@ -1,14 +1,6 @@
 #!/usr/bin/env node
 
-import { runTenderCli } from "../dist/index.js";
-
-function shouldReadEntrypointStdin(args) {
-	return (
-		args[0] === "artifacts" &&
-		args[1] === "git" &&
-		args[2] === "credential"
-	);
-}
+import { runTenderCli, shouldReadEntrypointStdin } from "../dist/index.js";
 
 async function readEntrypointStdin() {
 	if (process.stdin.isTTY) {

package/dist/index.d.ts

@@ -19,4 +19,5 @@ type TenderCommandResult = {
     stderr: string;
 };
 export declare function runTenderCli(args: string[], io?: TenderCliIo, runtime?: TenderCliRuntime): Promise<number>;
+export declare function shouldReadEntrypointStdin(args: string[]): boolean;
 export {};

package/dist/index.js

@@ -41,18 +41,28 @@ 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;
+    nextAction;
+    constructor(message, reasonCode, scope, example, nextAction = null) {
         super(message);
         this.name = "TenderCliDbApiError";
         this.reasonCode = reasonCode;
+        this.scope = scope;
+        this.example = example;
+        this.nextAction = nextAction;
     }
 }
 const DEFAULT_PROFILE_NAME = "default";
@@ -65,6 +75,8 @@ function rootHelp() {
     return `Usage: tender <command> [options]
 
 Commands:
+  tender --version
+                             Show the installed Tender CLI version
   tender capabilities --json
                              Describe the CLI command surface for coding agents
   tender auth login --device
@@ -101,7 +113,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
@@ -118,6 +130,7 @@ Commands:
                              Regenerate src/env.d.ts from app.json and bindings
 
 Examples:
+  tender --version
   tender capabilities --json
   tender auth login --device --profile edit-preview --artifact artifact_123 --ttl 7d
   tender auth status --json
@@ -135,9 +148,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 +251,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 +298,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
@@ -307,6 +320,17 @@ copying long command lists into skill prompts.
 Examples:
   tender capabilities --json`;
 }
+function versionHelp() {
+    return `Usage: tender --version
+       tender -v
+       tender version [--json]
+
+Prints the installed Tender CLI package version.
+
+Examples:
+  tender --version
+  tender version --json`;
+}
 function analyticsHelp() {
     return `Usage: tender app analytics <command> <app-id> [options]
 
@@ -471,16 +495,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 +516,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]
@@ -845,6 +874,7 @@ function tenderCliCapabilities() {
         discovery: {
             primary: "npm exec --yes @tenderprompt/cli@latest -- capabilities --json",
             layeredHelp: [
+                "tender --version",
                 "tender --help",
                 "tender auth --help",
                 "tender app --help",
@@ -921,10 +951,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.",
@@ -947,6 +977,18 @@ function tenderCliCapabilities() {
             },
         ],
         commands: [
+            {
+                command: "tender --version",
+                purpose: "Print the installed Tender CLI package version.",
+                requiresAuth: false,
+                writes: false,
+            },
+            {
+                command: "tender version --json",
+                purpose: "Print the installed Tender CLI package version in a stable JSON shape.",
+                requiresAuth: false,
+                writes: false,
+            },
             {
                 command: "tender capabilities --json",
                 purpose: "Discover this CLI surface in a machine-readable shape.",
@@ -1032,19 +1074,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,
@@ -1078,6 +1120,19 @@ function runCapabilities(command, io) {
     }
     return 0;
 }
+function runVersion(command, io) {
+    if (command.json) {
+        io.stdout(JSON.stringify({
+            ok: true,
+            name: CLI_PACKAGE_NAME,
+            version: CLI_PACKAGE_VERSION,
+        }, null, 2));
+    }
+    else {
+        io.stdout(CLI_PACKAGE_VERSION);
+    }
+    return 0;
+}
 function normalizeBaseUrl(value) {
     return (value ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
 }
@@ -2402,6 +2457,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" };
@@ -2575,6 +2637,20 @@ function parseCapabilitiesArgs(args) {
     }
     return { command: "capabilities", json };
 }
+function parseVersionArgs(args) {
+    if (args.includes("--help") || args.includes("-h")) {
+        return { command: "help", topic: "version" };
+    }
+    let json = false;
+    for (const arg of args) {
+        if (arg === "--json") {
+            json = true;
+            continue;
+        }
+        throw new TenderCliUsageError(`Unknown version option: ${arg}`);
+    }
+    return { command: "version", json };
+}
 function parseBindingId(value) {
     if (!value || value.startsWith("-")) {
         throw new TenderCliUsageError("--id requires a binding id.");
@@ -3457,10 +3533,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 +3557,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 +3604,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 +3622,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 +3633,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 +3662,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 +3682,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 +3745,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 +3771,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 +3794,7 @@ function parseDbQueryArgs(args) {
         sqlSource,
         params,
         limit,
+        offset,
         ...parsed,
     };
 }
@@ -3634,6 +3802,12 @@ function parseTenderArgs(args) {
     if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
         return { command: "help", topic: "root" };
     }
+    if (args[0] === "--version" || args[0] === "-v") {
+        return parseVersionArgs(args.slice(1));
+    }
+    if (args[0] === "version") {
+        return parseVersionArgs(args.slice(1));
+    }
     if (args[0] === "capabilities") {
         return parseCapabilitiesArgs(args.slice(1));
     }
@@ -4192,12 +4366,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 +4407,22 @@ 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 nextAction = typeof payload?.nextAction === "string" && payload.nextAction
+            ? payload.nextAction
+            : null;
+        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}`,
+            ...(input.scopeEnvironment ?? input.environment
+                ? { environment: input.scopeEnvironment ?? input.environment }
+                : {}),
+        }, example, nextAction);
     }
     return payload;
 }
@@ -4243,12 +4431,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 +4685,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 +6829,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,
@@ -6649,6 +6838,7 @@ async function runDbQuery(command, io, runtime) {
         baseUrl: credentials.baseUrl,
         token: credentials.token,
         fetcher: runtime.fetcher ?? fetch,
+        scopeEnvironment: command.environment,
         body,
     });
     const rows = Array.isArray(payload.rows) ? payload.rows : [];
@@ -6656,7 +6846,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,16 +7258,118 @@ 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 nextActionForError(error) {
+    return error instanceof TenderCliDbApiError ? error.nextAction : null;
+}
+function cliErrorPayload(error, args, command) {
+    const scope = scopeForError(error, args, command);
+    const example = exampleForError(error, args, command);
+    const nextAction = nextActionForError(error);
+    return {
+        ok: false,
+        command: commandNameForError(args, command),
+        reasonCode: cliErrorCode(error),
+        message: cliErrorMessage(error),
+        ...(scope ? { scope } : {}),
+        ...(nextAction ? { nextAction } : {}),
+        ...(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());
             }
+            else if (command.topic === "version") {
+                io.stdout(versionHelp());
+            }
             else if (command.topic === "auth login") {
                 io.stdout(authLoginHelp());
             }
@@ -7219,6 +7516,9 @@ export async function runTenderCli(args, io = {
         if (command.command === "capabilities") {
             return runCapabilities(command, io);
         }
+        if (command.command === "version") {
+            return runVersion(command, io);
+        }
         if (command.command === "auth login") {
             return await runAuthLogin(command, io, runtime);
         }
@@ -7342,6 +7642,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,9 +7653,9 @@ 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) {
+export function shouldReadEntrypointStdin(args) {
     return (args[0] === "app" &&
         ((args[1] === "git" && args[2] === "credential") ||
             (args[1] === "analytics" && hasFlagValue(args, "--spec", "-")) ||

package/package.json

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