ente-cli 0.4.88 → 0.4.90

package/README.md

@@ -86,8 +86,9 @@ ENTE_PROFILE=mail-operator ente agent mail threads --unread
 
 Agent keys use scoped REST calls and signed CLI JWTs carrying the agent and
 credential IDs. Content calls recheck the live key and agent policy, including
-cached JWT calls. Human-only settings and administration stay in the web app;
-there is no unrestricted account-key fallback. CLI pairing without `--agent`
+cached JWT calls. Human-only settings stay in the web app; administration uses
+a separate platform key (see Admin access). There is no unrestricted account-key
+fallback. CLI pairing without `--agent`
 creates a named connection agent. MCP authorization creates a connection agent
 named for the client.
 
@@ -138,7 +139,8 @@ Every command supports `--json`. Run `ente --help` or `ente <group> --help`.
 | `list` | `create` (`--column`, `--pin`), `add` (`--key` upsert), `update` (`--attr`, `--title`), `import` (JSONL upsert by `--key`, `--dry-run`), `show` (`--all`, `--cursor`, `--where`, `--view`), `column add`, `column remove` |
 | `pins` | `list` |
 | `space` | `members` |
-| `recording` | `list`, `show`, `inspect`, `rerun` (admin only) |
+| `recording` | `list`, `show`, `inspect`, `rerun`, `orphans`, `backups` (platform key) |
+| `admin` | `tables`, `get`, `page` — read-only inspector over any table (platform key) |
 | `canvas` | `boards`, `html list`, `html get`, `html create`, `html update`, `html delete` |
 | `notification` | `send` (emails only your own Ente account address; optional HTML, file attachments, and CID inline images) |
 | `agent` | `list`, `threads`, `show`, `new`, `send`, `config show`, `config set-prompt`, `schedules configure` |
@@ -404,9 +406,38 @@ Published conversations remain durable after provider cache expiry/disconnect.
 Their individual messages appear in entity activity feeds; activity content reads
 return bounded, read-only email blocks with continuation cursors.
 
+### Admin access (platform key)
+
+Admin commands (`recording …`, `users …`, `health page`, `admin …`) use the
+platform key of a global admin, never the agent key. Issue it in the web app
+under Admin → Platform keys, then store it once:
+
+```bash
+ente auth platform login --url <convex-site-url> --key-stdin   # verifies the exchange first
+ente auth platform status [--json]
+ente auth platform logout
+```
+
+It lives in `platform.toml` next to the profiles (or the env pair
+`ENTE_PLATFORM_API_URL`/`ENTE_PLATFORM_API_KEY`) and reaches every admin
+function, including `users reset-password` and `users set-admin`, but no user,
+space or agent command. Without it admin commands fail; they never fall back.
+
+`ENTE_PLATFORM_PROFILE` selects a named file in `platform-profiles/<name>.toml`.
+Agent profiles keep their existing `profiles/<name>.toml` paths.
+
+```bash
+ente admin tables                                   # every inspectable table
+ente admin get <table> <id> [--json]                # one document, secrets "[redacted]"
+ente admin page <table> [--limit 20] [--cursor <c>] [--order asc|desc] [--json]
+```
+
+The inspector is read-only, reads any user's data, and includes `_storage` and
+`_scheduled_functions`; Convex Auth's own tables are not inspectable.
+
 ### Guardian health (global admin)
 
-`ente health page --profile default --source toolMessages --since <epoch-ms> --until <epoch-ms> --json`
+`ente health page --source toolMessages --since <epoch-ms> --until <epoch-ms> --json`
 reads one content-free aggregate page. Use `--source threads --status idle|running|error`
 or `--source recordings --status pending|transcribing|structuring|reflecting|done|error`
 for current job counts. Use `--since 0` for active jobs; terminal recording statuses require a positive
@@ -414,10 +445,10 @@ for current job counts. Use `--since 0` for active jobs; terminal recording stat
 timestamps are outside that coverage.
 `--stale-after-ms` defaults to 1800000; `--limit` accepts 1–100. Follow
 `data.continueCursor` with `--cursor` and unchanged arguments until `data.isDone`.
-Counts are page-local. Tool windows are at most seven days. This is a human-only
-global administration endpoint. Agent-bound CLI credentials cannot call it,
-including credentials sponsored by an administrator. Use the web administration
-interface for these operations; creating a broader agent key does not grant access.
+Counts are page-local. Tool windows are at most seven days. This is a global
+administration endpoint: it uses the platform key (see Admin access), never an
+agent-bound credential, even one sponsored by an administrator. Creating a broader
+agent key does not grant access.
 No customer content or record IDs are returned. Unknown tool names become `other`.
 See `docs/admin-health-monitoring.md` for collector continuity and limits.
 
@@ -475,7 +506,7 @@ across pages. Results put aggregates and continuation under `data.page`, with
 window/observation/coverage alongside. Read every page before claiming complete
 counts; terminal recording history excludes missing progress timestamps. No
 message bodies or customer identifiers. The legacy `health page` remains a
-separate human-admin JWT surface and never serves as a fallback.
+separate platform-key admin surface and never serves as a fallback.
 
 Diagnostics is unavailable inside Ente-hosted chats, recordings and automations.
 Use the external operator command. Whole-history panel sharing does not grant

package/dist/SKILL.md

@@ -424,6 +424,35 @@ ente models web-search on|off                              # Linkup web search f
 ente users set-plan <email> own_models                     # admin: move a user onto the plan
 ```
 
+### Admin access (platform key)
+
+Admin commands (`recording …`, `users …`, `health page`, `admin …`) use the
+platform key of a global admin, never the agent key. Issue it in the web app
+under Admin → Platform keys, then store it once:
+
+```bash
+ente auth platform login --url <convex-site-url> --key-stdin   # verifies the exchange first
+ente auth platform status [--json]
+ente auth platform logout
+```
+
+It lives in `platform.toml` next to the profiles (or the env pair
+`ENTE_PLATFORM_API_URL`/`ENTE_PLATFORM_API_KEY`) and reaches every admin
+function, including `users reset-password` and `users set-admin`, but no user,
+space or agent command. Without it admin commands fail; they never fall back.
+
+`ENTE_PLATFORM_PROFILE` selects a named file in `platform-profiles/<name>.toml`.
+Agent profiles keep their existing `profiles/<name>.toml` paths.
+
+```bash
+ente admin tables                                   # every inspectable table
+ente admin get <table> <id> [--json]                # one document, secrets "[redacted]"
+ente admin page <table> [--limit 20] [--cursor <c>] [--order asc|desc] [--json]
+```
+
+The inspector is read-only, reads any user's data, and includes `_storage` and
+`_scheduled_functions`; Convex Auth's own tables are not inspectable.
+
 ### Recordings (admin — debug a failing recording)
 
 ```bash
@@ -435,7 +464,7 @@ ente recording backups [--state failed|joining|capturing] [--user <email|id>] [-
 ente recording backups join <backupId> [--now]     # retry a failed join; --now joins one still waiting for its device
 ```
 
-- Admin-only (`api.admin.recordings.*`); the ordinary `recordings.*` API is creator-scoped.
+- Admin-only (`api.admin.recordings.*`, platform key); the ordinary `recordings.*` API is creator-scoped.
 - `rerun` never modifies or deletes the stored audio; `--wait` polls to `done`/`error` and exits non-zero on failure.
 - `--status` scans newest-first and says so when the sweep is capped.
 - A backup in `failed` holds the only server copy of audio whose device never came back; read `error`, fix the cause, then `backups join`.
@@ -601,7 +630,7 @@ Prepare a new review for remaining contents. Cancel only before execution.
 
 ### Guardian health (global admin)
 
-`ente health page --profile default --source toolMessages --since <epoch-ms> --until <epoch-ms> --json`
+`ente health page --source toolMessages --since <epoch-ms> --until <epoch-ms> --json`
 reads one content-free aggregate page. Use `--source threads --status idle|running|error`
 or `--source recordings --status pending|transcribing|structuring|reflecting|done|error`
 for current job counts. Use `--since 0` for active jobs; terminal recording statuses require a positive
@@ -609,10 +638,10 @@ for current job counts. Use `--since 0` for active jobs; terminal recording stat
 timestamps are outside that coverage.
 `--stale-after-ms` defaults to 1800000; `--limit` accepts 1–100. Follow
 `data.continueCursor` with `--cursor` and unchanged arguments until `data.isDone`.
-Counts are page-local. Tool windows are at most seven days. This is a human-only
-global administration endpoint. Agent-bound CLI credentials cannot call it,
-including credentials sponsored by an administrator. Use the web administration
-interface for these operations; creating a broader agent key does not grant access.
+Counts are page-local. Tool windows are at most seven days. This is a global
+administration endpoint: it uses the platform key (see Admin access), never an
+agent-bound credential, even one sponsored by an administrator. Creating a broader
+agent key does not grant access.
 No customer content or record IDs are returned. Unknown tool names become `other`.
 See `docs/admin-health-monitoring.md` for collector continuity and limits.