@tenderprompt/cli 0.1.12 → 0.1.14

package/README.md

@@ -34,6 +34,8 @@ session:
 - build and preview a commit through the Tender API
 - publish only after a dry run or explicit `--confirm publish`
 - inspect artifact-scoped analytics without SQL or platform credentials
+- inspect artifact-scoped app database tables, schema, and bounded read-only
+  query output
 - run server-validated chart specs and export aggregate rows
 - generate starter analytics suggestions
 - create, list, update, and delete saved analytics dashboards and charts, with
@@ -87,6 +89,8 @@ TTL values are intentionally bounded:
 
 Use `--profile publish` only when the token should be allowed to publish.
 Publish still requires explicit confirmation with `--confirm publish`.
+Use `--profile db-read --artifact <app-id>` for read-only app database
+inspection.
 
 Credential precedence is explicit-first:
 
@@ -128,6 +132,11 @@ tender app validate artifact_123 --json
 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 --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
@@ -226,6 +235,61 @@ filter. `analytics query` is read-only, so use
 query fails for a missing dashboard-query property, the CLI prints the exact
 activation commands to run and does not perform that write automatically.
 
+Event payload properties can be tracked by the app, observed in bounded catalog
+samples, and still not be queryable in fast dashboard charts. Register intended
+dashboard dimensions and metrics before meaningful traffic starts. Use
+dimensions for grouping values such as variant, plan, step, source, or outcome,
+and metrics for numeric values such as score, amount, duration, or quantity.
+Making a property queryable does not require an app redeploy, but older
+dashboard-query rows may not fully populate grouped charts until new traffic
+arrives. Do not make every property queryable; avoid PII, secrets, free text,
+ids, URLs, or high-cardinality values unless the chart has a clear purpose.
+
+## App Database
+
+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. Commands that read data require an explicit `--env preview`
+or `--env published`; there is no default environment.
+
+Start with capabilities:
+
+```bash
+tender auth login --device --profile db-read --artifact artifact_123 --ttl 7d --save-profile db --json
+
+tender app db capabilities artifact_123 --profile db --json
+```
+
+Common read-only commands:
+
+```bash
+tender app db tables artifact_123 --env published --profile db --json
+
+tender app db schema artifact_123 --env published --table votes --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 --env published --file ./debug.sql --limit 50 --offset 100 --profile db --json
+
+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. 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.
+
 ## Safety Model
 
 - Local agents run in the user's environment, not in Tender.
@@ -242,6 +306,8 @@ activation commands to run and does not perform that write automatically.
   tenant/artifact-scoped.
 - Raw analytics event export is intentionally not available; exports are bounded
   catalog metadata or validated aggregate query rows.
+- App database commands require `db:read`, should use artifact-scoped tokens,
+  and never require provider account ids or runtime storage identifiers.
 
 ## Related Package
 

package/dist/index.js

@@ -41,16 +41,34 @@ class TenderCliUsageError extends Error {
 }
 class TenderCliAnalyticsApiError extends Error {
     reasonCode;
-    constructor(message, reasonCode) {
+    scope;
+    example;
+    constructor(message, reasonCode, scope = null, example = null) {
         super(message);
-        this.reasonCode = reasonCode;
         this.name = "TenderCliAnalyticsApiError";
+        this.reasonCode = reasonCode;
+        this.scope = scope;
+        this.example = example;
+    }
+}
+class TenderCliDbApiError extends Error {
+    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";
 const DEFAULT_BASE_URL = "https://app.tenderprompt.com";
 const ARTIFACT_SOURCE_EXPORT_MAX_FILES = 1000;
 const ARTIFACT_SOURCE_EXPORT_MAX_FILE_BYTES = 2 * 1024 * 1024;
+const DB_SQL_STATEMENT_MAX_BYTES = 100 * 1024;
+const DB_MAX_BOUND_PARAMETERS = 100;
 function rootHelp() {
     return `Usage: tender <command> [options]
 
@@ -89,6 +107,10 @@ Commands:
                              Run a server-validated chart spec
   tender app analytics suggestions <app-id>
                              Generate useful starter chart suggestions
+  tender app db capabilities <app-id>
+                             Describe app database query limits and policy
+  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
   tender app context status <app-id>
@@ -120,6 +142,10 @@ Examples:
   tender app analytics summary artifact_123 --range 30d --json
   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 --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
@@ -142,12 +168,12 @@ Examples:
   tender auth status --json`;
 }
 function authLoginHelp() {
-    return `Usage: tender auth login --device [--base-url <url>] [--profile <edit-preview|publish|create>] [--artifact <artifact-id>] [--ttl <7d|14d|30d>] [--save-profile <name>] [--no-poll] [--json]
+    return `Usage: tender auth login --device [--base-url <url>] [--profile <edit-preview|publish|create|db-read>] [--artifact <artifact-id>] [--ttl <7d|14d|30d>] [--save-profile <name>] [--no-poll] [--json]
 
 Options:
   --device                 Use the OAuth device-code flow.
   --base-url <url>         Tender base URL. Defaults to TENDER_BASE_URL or https://app.tenderprompt.com.
-  --profile <value>        Token permission profile: edit-preview, publish, or create. Defaults to edit-preview.
+  --profile <value>        Token permission profile: edit-preview, publish, create, or db-read. Defaults to edit-preview.
   --artifact <artifact-id> Scope the token to one artifact. Required for normal edit-preview agent work.
   --ttl <value>            Token lifetime: 7d, 14d, or 30d. Defaults to 7d.
   --save-profile <name>    Local config profile name. Defaults to default.
@@ -157,7 +183,8 @@ Options:
 Examples:
   tender auth login --device --profile edit-preview --artifact artifact_123 --ttl 7d
   tender auth login --device --profile publish --artifact artifact_123 --ttl 7d --save-profile publish --json
-  tender auth login --device --profile create --ttl 7d --save-profile account`;
+  tender auth login --device --profile create --ttl 7d --save-profile account
+  tender auth login --device --profile db-read --artifact artifact_123 --ttl 7d --save-profile db`;
 }
 function authStatusHelp() {
     return `Usage: tender auth status [--profile <name>] [--json]
@@ -217,6 +244,14 @@ Commands:
                              List properties available to dashboard queries
   tender app analytics properties activate <app-id>
                              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> --env <preview|published>
+                             List app database tables and views
+  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> --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
   tender app context status <app-id>
@@ -257,6 +292,10 @@ Examples:
   tender app analytics charts delete artifact_123 --chart analytics_chart_123 --dry-run --json
   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 --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
@@ -435,6 +474,62 @@ Examples:
   tender app analytics properties activate artifact_123 --event signup_started --property plan --type dimension --dry-run --json
   tender app analytics properties activate artifact_123 --event score_saved --property score --type metric --json`;
 }
+function dbHelp() {
+    return `Usage: tender app db <command> <app-id> [options]
+
+Commands:
+  tender app db capabilities <app-id>  Describe app database policy and limits
+  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 --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]
+
+Examples:
+  tender app db capabilities artifact_123 --json`;
+}
+function dbTablesHelp() {
+    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 --env published --json
+  tender app db tables artifact_123 --env preview --json`;
+}
+function dbSchemaHelp() {
+    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 --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> --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 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 --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]
 
@@ -767,6 +862,7 @@ function tenderCliCapabilities() {
                 "tender auth --help",
                 "tender app --help",
                 "tender app analytics --help",
+                "tender app db --help",
                 "tender app bindings outbound --help",
             ],
         },
@@ -832,6 +928,23 @@ function tenderCliCapabilities() {
                     "Use list before writes so agents can avoid duplicates and explain the exact chart they are changing.",
                 ],
             },
+            {
+                name: "app_database_inspection",
+                when: "When inspecting app-local database tables from a scoped token.",
+                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> --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.",
+                    "Read-only policy is enforced by the server before the runtime shim executes SQL.",
+                    "Use --file - to pipe SQL from stdin without prompts.",
+                ],
+            },
             {
                 name: "outbound_http_binding",
                 when: "When app code needs external APIs, OAuth/token exchange, webhooks, provider SDKs, or secrets.",
@@ -925,6 +1038,30 @@ function tenderCliCapabilities() {
                 writes: true,
                 dryRun: true,
             },
+            {
+                command: "tender app db capabilities <artifact-id> --json",
+                purpose: "Inspect app database policy, limits, and supported capabilities for one artifact.",
+                requiresAuth: true,
+                writes: false,
+            },
+            {
+                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> --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> --env published --sql \"select * from <table-name> limit 20\" --json",
+                purpose: "Run one bounded read-only app database query.",
+                requiresAuth: true,
+                writes: false,
+            },
         ],
         security: [
             "Prefer artifact-scoped device tokens.",
@@ -932,6 +1069,7 @@ function tenderCliCapabilities() {
             "Do not call Tender HTTP APIs directly from agent workflows.",
             "Do not put third-party fetch calls in src/server.ts; use outbound bindings.",
             "Do not request direct query credentials or raw SQL for analytics.",
+            "Do not use tenant ids, runner names, provider account ids, or runtime storage identifiers for app database inspection.",
         ],
     };
 }
@@ -2264,10 +2402,11 @@ function parseContextRefreshArgs(args) {
 function parseTokenProfile(value) {
     if (value === "edit-preview" ||
         value === "publish" ||
-        value === "create") {
+        value === "create" ||
+        value === "db-read") {
         return value;
     }
-    throw new TenderCliUsageError("--profile must be one of edit-preview, publish, or create.");
+    throw new TenderCliUsageError("--profile must be one of edit-preview, publish, create, or db-read.");
 }
 function parsePositiveIntegerFlag(value, flag) {
     const parsed = Number(value);
@@ -2276,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" };
@@ -2341,6 +2487,9 @@ function parseAuthLoginArgs(args) {
     if (tokenProfile === "create" && artifactId) {
         throw new TenderCliUsageError("--profile create must be account-scoped; remove --artifact.");
     }
+    if (tokenProfile === "db-read" && !artifactId) {
+        throw new TenderCliUsageError("--profile db-read requires --artifact <artifact-id>.");
+    }
     return {
         command: "auth login",
         baseUrl,
@@ -2941,10 +3090,12 @@ function analyticsChartTemplates() {
             purpose: "Compare a queryable dimension property observed in events.",
             usableAsIs: false,
             placeholders: {
+                eventName: "<event_name>",
                 property: "<queryable_dimension_property>",
             },
             adaptWith: [
                 "Use a queryable property key from capabilities chartSpec.groupBy, such as property:plan.",
+                "Choose the event that owns the property and keep the event_name filter.",
                 "Choose stable categorical properties with enough observations to compare.",
             ],
             spec: {
@@ -2953,7 +3104,7 @@ function analyticsChartTemplates() {
                 visualization: "bar",
                 metric: { name: "custom_event_count" },
                 groupBy: [{ field: "property:<queryable_dimension_property>" }],
-                filters: [],
+                filters: [{ field: "event_name", op: "=", value: "<event_name>" }],
                 range: { preset: "30d" },
                 sort: [{ field: "value", direction: "desc" }],
                 limit: 10,
@@ -2966,10 +3117,12 @@ function analyticsChartTemplates() {
             purpose: "Track an observed numeric event property over time.",
             usableAsIs: false,
             placeholders: {
+                eventName: "<event_name>",
                 metric: "avg:<queryable_metric_property>",
             },
             adaptWith: [
                 "Use a queryable numeric property key from capabilities chartSpec.metrics.",
+                "Choose the event that owns the property and keep the event_name filter.",
                 "Prefer averages for scores, durations, quantities, or ordinal values.",
             ],
             spec: {
@@ -2978,7 +3131,7 @@ function analyticsChartTemplates() {
                 visualization: "line",
                 metric: { name: "avg:<queryable_metric_property>" },
                 groupBy: [{ field: "day" }],
-                filters: [],
+                filters: [{ field: "event_name", op: "=", value: "<event_name>" }],
                 range: { preset: "30d" },
                 sort: [{ field: "label", direction: "asc" }],
                 limit: 30,
@@ -3292,6 +3445,303 @@ function parseAnalyticsPropertiesActivateArgs(args) {
         ...parsed,
     };
 }
+function parseDbCommonArgs(args, startIndex) {
+    let baseUrl = null;
+    let flagToken = null;
+    let profileName = null;
+    let json = false;
+    const remaining = [];
+    for (let index = startIndex; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--json") {
+            json = true;
+            continue;
+        }
+        if (arg === "--base-url") {
+            baseUrl = parseBaseUrlFlag(args, index);
+            index += 1;
+            continue;
+        }
+        if (arg === "--token") {
+            flagToken = parseTokenFlag(args, index);
+            index += 1;
+            continue;
+        }
+        if (arg === "--profile") {
+            profileName = parseProfileName(args[index + 1], "--profile");
+            index += 1;
+            continue;
+        }
+        remaining.push(arg);
+    }
+    return { baseUrl, flagToken, profileName, json, remaining };
+}
+function parseDbEnvironment(value) {
+    if (!value || value.startsWith("--")) {
+        throw new TenderCliUsageError("--env requires a value. Use preview or published.");
+    }
+    if (value === "preview") {
+        return "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("--")) {
+        throw new TenderCliUsageError(`${flag} requires a value.`);
+    }
+    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.");
+    }
+    return value;
+}
+function parseDbParameter(value) {
+    const raw = parseDbFlagValue(value, "--param");
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed === null ||
+            typeof parsed === "string" ||
+            typeof parsed === "number") {
+            return parsed;
+        }
+    }
+    catch {
+        // Fall back to a string binding.
+    }
+    return raw;
+}
+function parseDbCapabilitiesArgs(args) {
+    if (args.includes("--help") || args.includes("-h")) {
+        return { command: "help", topic: "app db capabilities" };
+    }
+    const artifactId = args[0];
+    if (!artifactId || artifactId.startsWith("-")) {
+        throw new TenderCliUsageError("app id is required. Example: tender app db capabilities <app-id> --json");
+    }
+    const parsed = parseDbCommonArgs(args, 1);
+    if (parsed.remaining.length > 0) {
+        throw new TenderCliUsageError(`Unknown app db capabilities option: ${parsed.remaining[0]}`);
+    }
+    return { command: "app db capabilities", artifactId, ...parsed };
+}
+function parseDbTablesArgs(args) {
+    if (args.includes("--help") || args.includes("-h")) {
+        return { command: "help", topic: "app db tables" };
+    }
+    const artifactId = args[0];
+    if (!artifactId || artifactId.startsWith("-")) {
+        throw new TenderCliUsageError("app id is required. Example: tender app db tables <app-id> --env published --json");
+    }
+    const parsed = parseDbCommonArgs(args, 1);
+    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;
+            continue;
+        }
+        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) {
+    if (args.includes("--help") || args.includes("-h")) {
+        return { command: "help", topic: "app db schema" };
+    }
+    const artifactId = args[0];
+    if (!artifactId || artifactId.startsWith("-")) {
+        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 = 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;
+            continue;
+        }
+        if (arg === "--table") {
+            tableName = parseRequiredFlagValue(parsed.remaining[index + 1], "--table");
+            index += 1;
+            continue;
+        }
+        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 --env published --table votes --json");
+    }
+    return {
+        command: "app db schema",
+        artifactId,
+        environment,
+        tableName,
+        ...parsed,
+    };
+}
+function parseDbQueryArgs(args) {
+    if (args.includes("--help") || args.includes("-h")) {
+        return { command: "help", topic: "app db query" };
+    }
+    const artifactId = args[0];
+    if (!artifactId || artifactId.startsWith("-")) {
+        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 = 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;
+            continue;
+        }
+        if (arg === "--sql") {
+            if (sqlSource) {
+                throw new TenderCliUsageError("--sql and --file cannot be repeated or combined.");
+            }
+            sqlSource = {
+                kind: "inline",
+                value: parseDbSqlFlagValue(parsed.remaining[index + 1]),
+            };
+            index += 1;
+            continue;
+        }
+        if (arg === "--file") {
+            if (sqlSource) {
+                throw new TenderCliUsageError("--sql and --file cannot be repeated or combined.");
+            }
+            sqlSource = {
+                kind: "file",
+                value: parseDbFilePath(parsed.remaining[index + 1]),
+            };
+            index += 1;
+            continue;
+        }
+        if (arg === "--param") {
+            params.push(parseDbParameter(parsed.remaining[index + 1]));
+            index += 1;
+            continue;
+        }
+        if (arg === "--limit") {
+            limit = parsePositiveIntegerFlag(parsed.remaining[index + 1], "--limit");
+            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 --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.`);
+    }
+    return {
+        command: "app db query",
+        artifactId,
+        environment,
+        sqlSource,
+        params,
+        limit,
+        offset,
+        ...parsed,
+    };
+}
 function parseTenderArgs(args) {
     if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
         return { command: "help", topic: "root" };
@@ -3441,6 +3891,27 @@ function parseTenderArgs(args) {
             resourceArgs[3] === "delete") {
             return parseAnalyticsChartsDeleteArgs(resourceArgs.slice(4));
         }
+        if (resourceArgs[1] === "db" &&
+            (resourceArgs[2] === undefined ||
+                resourceArgs[2] === "--help" ||
+                resourceArgs[2] === "-h")) {
+            return { command: "help", topic: "app db" };
+        }
+        if (resourceArgs[1] === "db" && resourceArgs[2] === "capabilities") {
+            return parseDbCapabilitiesArgs(resourceArgs.slice(3));
+        }
+        if (resourceArgs[1] === "db" && resourceArgs[2] === "tables") {
+            return parseDbTablesArgs(resourceArgs.slice(3));
+        }
+        if (resourceArgs[1] === "db" && resourceArgs[2] === "schema") {
+            return parseDbSchemaArgs(resourceArgs.slice(3));
+        }
+        if (resourceArgs[1] === "db" && resourceArgs[2] === "query") {
+            return parseDbQueryArgs(resourceArgs.slice(3));
+        }
+        if (resourceArgs[1] === "db") {
+            throw new TenderCliUsageError(`Unknown app db command: ${resourceArgs[2]}`);
+        }
         if (resourceArgs[1] === "context" &&
             (resourceArgs[2] === undefined ||
                 resourceArgs[2] === "--help" ||
@@ -3833,15 +4304,72 @@ 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;
 }
+function appendDbEnvironment(params, environment) {
+    params.set("env", environment);
+}
+async function requestDbApi(input) {
+    const params = new URLSearchParams();
+    if (input.environment) {
+        appendDbEnvironment(params, input.environment);
+    }
+    if (input.tableName) {
+        params.set("table", input.tableName);
+    }
+    const query = params.size > 0 ? `?${params.toString()}` : "";
+    const response = await input.fetcher(`${input.baseUrl}/api/v1/artifacts/${encodeURIComponent(input.artifactId)}/db/${input.dbPath}${query}`, {
+        method: input.method,
+        headers: {
+            authorization: `Bearer ${input.token}`,
+            accept: "application/json",
+            ...(input.body === undefined ? {} : { "content-type": "application/json" }),
+        },
+        body: input.body === undefined ? undefined : JSON.stringify(input.body),
+    });
+    const payload = await parseJsonResponse(response);
+    if (!response.ok || !payload?.ok) {
+        const reasonCode = (typeof payload?.reasonCode === "string" && payload.reasonCode) ||
+            `http_${response.status}`;
+        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: ${example}.`,
+        ].join("\n"), reasonCode, {
+            artifactId: input.artifactId,
+            surface: `db/${input.dbPath}`,
+        }, example);
+    }
+    return payload;
+}
+function dbCorrectedExample(artifactId, dbPath) {
+    if (dbPath === "capabilities") {
+        return `tender app db capabilities ${artifactId} --json`;
+    }
+    if (dbPath === "tables") {
+        return `tender app db tables ${artifactId} --env published --json`;
+    }
+    if (dbPath === "schema") {
+        return `tender app db schema ${artifactId} --env published --table <table-name> --json`;
+    }
+    return `tender app db query ${artifactId} --env published --sql "select * from <table-name> limit 20" --json`;
+}
 function analyticsCorrectedExample(artifactId, analyticsPath) {
     if (analyticsPath === "capabilities") {
         return `tender app analytics capabilities ${artifactId} --include-catalog --range 30d --json`;
@@ -4089,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;
@@ -6127,6 +6655,137 @@ async function resolveAnalyticsCredentials(command, runtime) {
         env: runtime.env ?? process.env,
     });
 }
+async function resolveDbCredentials(command, runtime) {
+    return await resolveApiCredentials({
+        baseUrl: command.baseUrl,
+        flagToken: command.flagToken,
+        profileName: command.profileName,
+        env: runtime.env ?? process.env,
+    });
+}
+function validateDbSql(sql) {
+    if (!sql.trim()) {
+        throw new TenderCliUsageError("SQL statement is required.");
+    }
+    const byteLength = new TextEncoder().encode(sql).byteLength;
+    if (byteLength > DB_SQL_STATEMENT_MAX_BYTES) {
+        throw new TenderCliUsageError(`SQL statement is limited to ${DB_SQL_STATEMENT_MAX_BYTES} bytes.`);
+    }
+}
+async function readDbSql(command, runtime) {
+    const sql = command.sqlSource.kind === "inline"
+        ? command.sqlSource.value
+        : command.sqlSource.value === "-"
+            ? runtime.stdin
+            : await readFile(path.resolve(command.sqlSource.value), "utf8");
+    if (!sql) {
+        throw new TenderCliUsageError("--file - requires SQL on stdin.");
+    }
+    validateDbSql(sql);
+    return sql;
+}
+function printDbPayload(command, io, payload, fallbackLines) {
+    if (command.json) {
+        io.stdout(JSON.stringify(payload, null, 2));
+    }
+    else {
+        io.stdout(fallbackLines.join("\n"));
+    }
+}
+async function runDbCapabilities(command, io, runtime) {
+    const credentials = await resolveDbCredentials(command, runtime);
+    const payload = await requestDbApi({
+        artifactId: command.artifactId,
+        dbPath: "capabilities",
+        method: "GET",
+        baseUrl: credentials.baseUrl,
+        token: credentials.token,
+        fetcher: runtime.fetcher ?? fetch,
+    });
+    const limits = isCliJsonRecord(payload.limits) ? payload.limits : {};
+    const runtimeInfo = isCliJsonRecord(payload.runtime) ? payload.runtime : {};
+    printDbPayload(command, io, payload, [
+        `app_id: ${command.artifactId}`,
+        `backend: ${String(runtimeInfo.backend ?? "app-database")}`,
+        `default_limit: ${String(limits.defaultLimit ?? "")}`,
+        `max_limit: ${String(limits.maxInteractiveLimit ?? "")}`,
+    ]);
+    return 0;
+}
+async function runDbTables(command, io, runtime) {
+    const credentials = await resolveDbCredentials(command, runtime);
+    const payload = await requestDbApi({
+        artifactId: command.artifactId,
+        dbPath: "tables",
+        method: "GET",
+        baseUrl: credentials.baseUrl,
+        token: credentials.token,
+        fetcher: runtime.fetcher ?? fetch,
+        environment: command.environment,
+    });
+    const rows = Array.isArray(payload.rows) ? payload.rows : [];
+    printDbPayload(command, io, payload, [
+        `app_id: ${command.artifactId}`,
+        `environment: ${command.environment}`,
+        `tables: ${rows.length}`,
+    ]);
+    return 0;
+}
+async function runDbSchema(command, io, runtime) {
+    const credentials = await resolveDbCredentials(command, runtime);
+    const payload = await requestDbApi({
+        artifactId: command.artifactId,
+        dbPath: "schema",
+        method: "GET",
+        baseUrl: credentials.baseUrl,
+        token: credentials.token,
+        fetcher: runtime.fetcher ?? fetch,
+        environment: command.environment,
+        tableName: command.tableName,
+    });
+    const rows = Array.isArray(payload.rows) ? payload.rows : [];
+    printDbPayload(command, io, payload, [
+        `app_id: ${command.artifactId}`,
+        `environment: ${command.environment}`,
+        `table: ${command.tableName}`,
+        `schema_rows: ${rows.length}`,
+    ]);
+    return 0;
+}
+async function runDbQuery(command, io, runtime) {
+    const credentials = await resolveDbCredentials(command, runtime);
+    const sql = await readDbSql(command, runtime);
+    const body = {
+        environment: command.environment,
+        mode: "read",
+        sql,
+        params: command.params,
+        ...(command.limit === null ? {} : { limit: command.limit }),
+        offset: command.offset,
+    };
+    const payload = await requestDbApi({
+        artifactId: command.artifactId,
+        dbPath: "query",
+        method: "POST",
+        baseUrl: credentials.baseUrl,
+        token: credentials.token,
+        fetcher: runtime.fetcher ?? fetch,
+        body,
+    });
+    const rows = Array.isArray(payload.rows) ? payload.rows : [];
+    printDbPayload(command, io, payload, [
+        `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;
+}
 async function runAnalyticsSummary(command, io, runtime) {
     const credentials = await resolveAnalyticsCredentials(command, runtime);
     const payload = await requestAnalyticsApi({
@@ -6530,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());
@@ -6660,6 +7413,21 @@ export async function runTenderCli(args, io = {
             else if (command.topic === "app analytics properties activate") {
                 io.stdout(analyticsPropertiesActivateHelp());
             }
+            else if (command.topic === "app db") {
+                io.stdout(dbHelp());
+            }
+            else if (command.topic === "app db capabilities") {
+                io.stdout(dbCapabilitiesHelp());
+            }
+            else if (command.topic === "app db tables") {
+                io.stdout(dbTablesHelp());
+            }
+            else if (command.topic === "app db schema") {
+                io.stdout(dbSchemaHelp());
+            }
+            else if (command.topic === "app db query") {
+                io.stdout(dbQueryHelp());
+            }
             else if (command.topic === "app") {
                 io.stdout(appHelp());
             }
@@ -6776,22 +7544,44 @@ export async function runTenderCli(args, io = {
         if (command.command === "app analytics properties activate") {
             return await runAnalyticsPropertiesActivate(command, io, runtime);
         }
+        if (command.command === "app db capabilities") {
+            return await runDbCapabilities(command, io, runtime);
+        }
+        if (command.command === "app db tables") {
+            return await runDbTables(command, io, runtime);
+        }
+        if (command.command === "app db schema") {
+            return await runDbSchema(command, io, runtime);
+        }
+        if (command.command === "app db query") {
+            return await runDbQuery(command, io, runtime);
+        }
         if (command.command === "app git remote") {
             return await runGitRemote(command, io, runtime);
         }
         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;
     }
 }
 const currentFile = fileURLToPath(import.meta.url);
+function hasFlagValue(args, flag, value) {
+    return args.some((arg, index) => (arg === flag && args[index + 1] === value) || arg === `${flag}=${value}`);
+}
 function shouldReadEntrypointStdin(args) {
     return (args[0] === "app" &&
         ((args[1] === "git" && args[2] === "credential") ||
-            (args[1] === "analytics" && args.includes("--spec") && args.includes("-"))));
+            (args[1] === "analytics" && hasFlagValue(args, "--spec", "-")) ||
+            (args[1] === "db" &&
+                args[2] === "query" &&
+                hasFlagValue(args, "--file", "-"))));
 }
 async function readEntrypointStdin() {
     if (process.stdin.isTTY) {

package/package.json

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