@tenderprompt/cli 0.1.11 → 0.1.13

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,10 @@ 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 --json
+tender app db schema artifact_123 --table votes --json
+tender app db query artifact_123 --sql "select * from votes limit 20" --json
 ```
 
 ## Analytics
@@ -169,7 +177,7 @@ tender app analytics suggestions artifact_123 --range 30d --json
 
 tender app analytics charts templates --json
 
-tender app analytics property-slots list artifact_123 --json
+tender app analytics properties list artifact_123 --json
 ```
 
 Safe write previews:
@@ -177,7 +185,7 @@ Safe write previews:
 ```bash
 tender app analytics dashboards artifact_123 --create "Agent dashboard" --dry-run --json
 
-tender app analytics property-slots activate artifact_123 \
+tender app analytics properties activate artifact_123 \
   --event signup_started \
   --property plan \
   --type dimension \
@@ -217,14 +225,65 @@ inspection. For example, inspect where the app calls
 `__TP_ANALYTICS.invoke(...)`, propose a chart spec, validate it with
 `analytics query`, and only then create a saved chart.
 Use `charts templates --json` for reusable chart shapes; adapt any placeholders
-to observed events, paths, or promoted property keys before querying or saving.
-Property group-bys and property metrics need promoted slots; `charts create`
-and `charts update` activate missing slots automatically when the spec includes
-an `event_name = ...` filter. `analytics query` is read-only, so use
-`property-slots activate` first when trying an ad hoc property query. When a
+to observed events, paths, or queryable property keys before querying or saving.
+Property group-bys and property metrics need the custom event property to be
+available for dashboard queries; `charts create` and `charts update` activate
+missing properties automatically when the spec includes an `event_name = ...`
+filter. `analytics query` is read-only, so use
+`properties activate` first when trying an ad hoc property query. When a
 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.
+
+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 --profile db --json
+
+tender app db schema artifact_123 --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 \
+  --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 --file - --profile db --json < debug.sql
+```
+
+The query command sends one read-only statement with positional bindings.
+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.
@@ -237,10 +296,12 @@ activation commands to run and does not perform that write automatically.
   remote URLs.
 - Analytics commands use tenant/artifact-scoped API routes. They do not expose
   raw query credentials or raw SQL.
-- Property slot activation is an explicit analytics write and remains
+- Dashboard-query property activation is an explicit analytics write and remains
   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