ente-cli 0.4.89 → 0.4.91

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.
 
@@ -103,6 +104,7 @@ project `.env` file.
 ```bash
 ente search "Alice"
 ente entity list --type person
+ente entity get "Alice" --projection full --limit 50 --json
 ente entity rename "Lorey Georg" "Georg Lorey"
 ente task list --due today
 ente activity create --type note --title "Meeting notes" --entity "Alice" --space "Personal"
@@ -124,6 +126,14 @@ ente tasks
 ente guide              # concepts; `ente guide <topic>`: entities, tasks, activities, search, patterns, limits
 ```
 
+Entity search, list and detail default to the compact projection. Search returns
+5 matches by default; list returns 50, and detail returns 20 activities. Search
+and list accept up to 1,000 results; detail accepts up to 200 activities.
+`--projection full` returns the public fields without compact text excerpts.
+`entity get` also accepts `--hours-back` and `--min-count`. A missing or
+archived detail returns `{"data":null}` in JSON. JSON preserves the canonical
+result under `data`; a root `spaces` map supplies the CLI's space labels.
+
 Every command supports `--json`. Run `ente --help` or `ente <group> --help`.
 
 ### Command groups
@@ -138,7 +148,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 +415,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 +454,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 +515,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

@@ -131,6 +131,8 @@ Check the exit before parsing. Do not append a successful help command and treat
 its exit as the preceding command's result. `entity show` reports the supported
 `entity get` command and fails without making a request.
 
+Entity reads default to compact public DTOs. Search defaults to 5 results; entity list without a query defaults to 50; entity get defaults to 20 activities. Search/list accept at most 1,000, and get accepts at most 200. Use `--projection full` for full public text and fields. JSON keeps the canonical result under `data` with space labels in the root `spaces` envelope. Missing or archived detail returns `data: null`.
+
 For inbox coverage, page the unfiltered `agent mail threads` list to completion,
 then inspect thread messages, including updates to older threads. `--unread`
 and `--needs-reply` answer different questions; unread alone misses read but
@@ -153,16 +155,16 @@ ente auth profiles
 # Ask keeps scoped evidence on synthesis failure; check synthesisStatus.
 # Optional sourceHash/sourceFingerprint/passage metadata binds citations to a source version.
 # query remains deterministic and never starts embedding/indexing. See guide ask-the-graph.
-ente search "Alice" [--type person] [--json]
+ente search "Alice" [--type person] [--space <name>] [--limit 5] [--projection compact|full] [--json]
 ente ask "What's open with Erik?" [--space <name>] [--entity <name>] [--evidence] [--json]   # AI answer + citations
 ente query "QM system export" [--space <name>] [--entity <name>] [--since <epoch-ms>] [--until <epoch-ms>] [--limit 12] [--verbose] [--json]         # evidence only, no AI
 
 # Entities
-ente entity list [--query <text>] [--type person|org|project|topic|place|object] [--space <name>] [--limit 50] [--archived] [--json]
+ente entity list [--query <text>] [--type person|org|project|topic|place|object] [--space <name>] [--limit <count>] [--projection compact|full] [--archived] [--json]
 ente entity create "Jane Doe" --type person [--pin "Acme Corp"] [--share-parents --parent-space-grant-fingerprint <token>] [--alias "JD"] [--attr email=jane@acme.com] [--tag vip] [--description "CTO at Acme"] [--json]
 ente entity create "Leistungsphase 1" --type topic --space "Studio" --parent "Building A" --exclusive-parent [--json]
 ente entity duplicate <name-or-id> --space <space> [--name "New project"] [--include-exclusive-children] [--json]
-ente entity get "Jane Doe" [--json]
+ente entity get "Jane Doe" [--limit 20] [--hours-back <hours>] [--min-count 5] [--projection compact|full] [--json]
 ente entity update "Jane Doe" [--name "Jane A. Doe"] [--alias-add "Jane"] [--alias-remove "JD"] [--attr role=CEO] [--tag vip] [--description "…"] [--json]
 ente entity rename "Lorey Georg" "Georg Lorey"        # change display name
 ente entity pin "Jane Doe" "Acme Corp" [--role "student"] [--share-parents --parent-space-grant-fingerprint <token>] [--json]
@@ -176,8 +178,8 @@ ente entity restore <entity-id> [--share-parents --parent-space-grant-fingerprin
 # Activities
 ente activity list [--entity "Jane"] [--compact] [--cursor <nextCursor>] [--min-count 0] [--type note|conversation|meeting|call|message|task] [--attr k=v] [--only-open] [--hours 168] [--limit 20] [--sort deadline|created] [--json]
 ente activity create --type meeting --title "Call with Jane" --entity "Jane Doe" --entity "Acme Corp" --space "Work" [--content "…"] [--content-file ./notes.md] [--auto-link --entity-space-grant-fingerprint <token>] [--json]
-ente activity search "quarterly review" [--entity "Acme"] [--type meeting] [--limit 10] [--json]
-ente activity get <activityId> [--json]                # complete detail: body, full nested agenda, messages/replies, entities, attachments
+ente activity search "quarterly review" [--entity "Acme"] [--type meeting] [--limit 20] [--projection compact|full] [--json]
+ente activity get <activityId> [--projection compact|full] [--json]                # public detail; use --projection full for full text and attachments
 ente activity transcript <activityId> [--grep "Preis"] [--context 2] [--recording <id>] [--json]   # transcript of the recording behind it
 ente activity update <activityId> [--title "…"] [--content "…"] [--deadline "2026-05-26" | --clear-deadline] [--entity-add "Bob"] [--entity-remove "Carol"] [--agent-assignee <agentId> ... | --clear-agent-assignees] [--json]
 ente activity content read <activityId> [--cursor <cursor> --expected-version <version>] [--max-blocks 20] [--max-characters 12000] [--json]
@@ -189,9 +191,9 @@ ente activity restore <activityId> [--json]
 
 # Database lists (entity + typed columns; each row is a note/task activity; no date column type)
 ente list create "<name>" --space "<space>" [--icon <topic-icon>] [--column "key[=Label]:text|number|boolean|single-select|multi-select[:opt,opt]"] [--pin "<parent>" [--share-parents --parent-space-grant-fingerprint <token>]] [--json]
-ente list add "<list>" --title "…" [--attr k=v ...] [--key <textColumn>] [--content-file ./row.md] [--json]   # --key = upsert by that cell
+ente list add "<list>" [--space "<space>"] --title "…" [--attr k=v ...] [--key <textColumn>] [--content-file ./row.md] [--json]   # --key = upsert by that cell
 ente list update "<list>" <rowId> [--attr k=v ...] [--title "…"] [--json]      # empty value clears a cell
-ente list import "<list>" --file rows.jsonl --key <textColumn> [--dry-run] [--concurrency 4] [--json]   # {"title","attrs","content"} per line → created/updated/unchanged
+ente list import "<list>" [--space "<space>"] --file rows.jsonl --key <textColumn> [--dry-run] [--concurrency 4] [--json]   # {"title","attrs","content"} per line → created/updated/unchanged
 ente list show "<list>" [--all | --cursor <nextCursor>] [--limit 100] [--where k=v ...] [--view] [--json]   # all rows by default; --view = table's saved filters
 # Rows are activities: trash with `ente activity delete <rowId>`, promote with `ente activity update <rowId> --entity-add "<entity>"`. Guide: playbooks/database-list-sync.md
 
@@ -250,6 +252,12 @@ ente agent mail reply <thread-id> --message <message-id> --reply-all (--text "Re
 ente agent mail mark <thread-id> --state-version <version> (--handled | --open | --needs-reply | --read | --unread) [--json]
 ```
 
+New list rows require explicit `--space`, including import dry runs and lists in a single space. Updates to existing rows keep their current space.
+
+
+Activity search and get return canonical public DTOs, defaulting to compact text. Use `--projection full` to include full public fields and attachment metadata. Missing or archived detail returns `data: null`. Search accepts at most 200 results and `--entity` includes the same bounded direct-child history as other canonical reads. The JSON result stays under `data`; `spaces` is a separate label envelope. Activity list keeps its installed filtering, sorting and pagination profile.
+
+
 Received attachments are available through the same bound agent credential;
 no browser login is needed. `ente agent mail show <thread-id> --json` lists
 `attachments` on each message with `attachmentId`, `filename`, `mimeType`, and
@@ -424,6 +432,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 +472,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 +638,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 +646,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.