@lotics/cli 0.321.100 → 0.321.102

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -116,7 +116,7 @@ run_app_query {"app_id":"app_…","alias":"order_list","params":{"status_is":"op
116
116
  | `sort` | An order in place of the query's own: `[{ "field_key": "<column>", "order": "asc" }]`, `asc` or `desc`, each `field_key` an output column's name |
117
117
  | `count` | `true`: `total`, the number of rows, in place of the rows; with `count_by`, `counts` per value of one column, keyed by an option's label, a member's name or a linked row's display; with `count_where` — a map of name → filter, never beside `count_by` — `counts` per name. Never with `fields`, `sort`, `limit` or `cursor` |
118
118
  | `aggregate` | Groups of the result in place of its rows, one row per group: `by` (up to 3 columns), `bands` (a number column of `by` grouped by its breakpoints), or `day` (a date column, answered as `__day`), `sum` (a number column, answered as `__sum`) and `avg` (a number column averaged over the group's rows that hold one, answered as `__avg`), each group with its `__count`. Sent with `params` and `filters` alone. Buckets are by day only: a period's total is one call per period, with `from` and `to` or a date filter |
119
- | `limit`, `cursor` | A page — 200 rows at most, 50 where no `limit` is stated — and the `next_cursor` of the page before it; `truncated` says more rows matched than `rows` holds |
119
+ | `limit`, `cursor` | A page — 1,000 rows at most, 50 where no `limit` is stated — and the `next_cursor` of the page before it; `truncated` says more rows matched than `rows` holds |
120
120
  | `runs` | Several reads in one call, 20 at most, each with its own `alias` and arguments, answered in order under `runs`. Never beside an `alias` of the call's own |
121
121
 
122
122
  A query that states its own `limit` lists at most that many rows: `truncated` is `true` where more match, and `total` is
@@ -29,9 +29,9 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
29
29
  | `lotics run <tool> --json '<json>'` | Execute a tool (full JSON output) |
30
30
  | `lotics run <tool>` — **file cells** | A file in a tool's result carries its `fil_…` id and metadata and **no `url`**, on every tool and in both output modes. That is not a broken file — this surface resolves no URL for a cell. Reach the bytes with `lotics file download <file_id>`, which takes the id straight from the cell; the text output says so whenever a result carries one. |
31
31
  | — | **Every tool is invoked here, including the ones that RUN something** (`run_app_workflow`, `run_app_query`) and every one that builds: `set_tables` (a list of table documents), `set_app` (one app), `set_workflow`. A command exists only for work that touches a local file: `app apply`, `app create --custom`, `app pull`, `app deploy`. |
32
- | — | **An app's queries and workflows take more than their params and inputs** (`lotics docs agent_surface`). `run_app_query '{"app_id","alias","params"}'` also takes `filters` and `sort` over the query's output columns, `fields` (the columns to return), `count` with `count_by` or `count_where`, `aggregate`, `limit` (200 rows at most; 50 where none is stated) and `cursor`, and `runs` — up to 20 reads in one call, each `{"alias", …}`, a refused one answered with its `error`; one call's rows total at most 262,144 bytes. `export: {"list", …narrowing}` instead of the read arguments makes the workbook of a List that states `export: true`, `list` its View id (`lotics docs agent_surface`). `run_app_workflow '{"app_id","alias","inputs"}'` also takes `dry_run: true` — a rehearsal on the real inputs, nothing written or sent; the answer is what the run would return, with the reads it made under `dry_run.reads`, the calls it would make under `dry_run.writes` and the papers it rendered under `dry_run.papers` and the parts of the answer it could not say under `dry_run.unpredicted`; a workflow no dry run is offered of answers `status: "not_previewed"` — and `runs` — up to 50 runs in order, the first refused, failed or not previewed ending the call, an input `{"from_run": <index>, "path": "data.<key>"}` reading an earlier run's answer. |
32
+ | — | **An app's queries and workflows take more than their params and inputs** (`lotics docs agent_surface`). `run_app_query '{"app_id","alias","params"}'` also takes `filters` and `sort` over the query's output columns, `fields` (the columns to return), `count` with `count_by` or `count_where`, `aggregate`, `limit` (1,000 rows at most; 50 where none is stated) and `cursor`, and `runs` — up to 20 reads in one call, each `{"alias", …}`, a refused one answered with its `error`; one call's rows total at most 262,144 bytes. `export: {"list", …narrowing}` instead of the read arguments makes the workbook of a List that states `export: true`, `list` its View id (`lotics docs agent_surface`). `run_app_workflow '{"app_id","alias","inputs"}'` also takes `dry_run: true` — a rehearsal on the real inputs, nothing written or sent; the answer is what the run would return, with the reads it made under `dry_run.reads`, the calls it would make under `dry_run.writes` and the papers it rendered under `dry_run.papers` and the parts of the answer it could not say under `dry_run.unpredicted`; a workflow no dry run is offered of answers `status: "not_previewed"` — and `runs` — up to 50 runs in order, the first refused, failed or not previewed ending the call, an input `{"from_run": <index>, "path": "data.<key>"}` reading an earlier run's answer. |
33
33
  | — | **The exit code reports the WORK, not just the call — for the tool that RUNS one.** `run_app_workflow` whose envelope carries a failed `status` (`error`/`failed`/`cancelled`, or `not_previewed` — a dry run asked for and not given) exit non-zero and print `<tool> → <status>: <message>` to stderr, so `lotics run … && next-step` cannot walk past a refused run. The rule is an allowlist of FAILURE — an unrecognized status exits 0, so a status added later never turns a working script red. A parked run (`awaiting_input`) is not a failure: it is waiting for an answer and the work is still live. Only a TOP-LEVEL `status` counts; one inside the data belongs to the data. Any OTHER tool's `status` is data, and exits 0. |
34
- | `lotics run <tool> '<json>'` with `as_file: true` | An answer that names its own file (`_file`) is saved as that file where the command runs, or in `-o <dir>`: a page's as the whole JSON answer, a whole set's (`query_records` with no page, or `all: true`) downloaded from `_file.url` as it arrives, JSON Lines. The path prints after the answer (on stderr under `--json`). The same call names the same file, so running it again replaces it. |
34
+ | `lotics run <tool> '<json>'` with `as_file: true` | An answer that names its own file (`_file`) is saved as that file where the command runs, or in `-o <dir>`: a page's as the whole JSON answer, a whole set's (`query_records` with no page, `all: true` or not) downloaded from `_file.url` as it arrives, JSON Lines. The path prints after the answer (on stderr under `--json`). The same call names the same file, so running it again replaces it. |
35
35
  | `lotics run <tool> '<json>' -o <dir>` | Also save every **signed link** the answer carries — an object with a `url`, a `filename` and the `expires_at` its signature ends at, at any depth, such as `screenshot_app`'s images. Each is fetched into `<dir>` (created if missing) under its `filename`, taking a free spelling beside a file of that name already there, and a link's `snapshot` text is written beside it as `<name>.txt`. The written paths follow the answer on **stdout**, one per line (on stderr under `--json`, whose stdout stays the one object). A link is signed for an hour; one the store no longer serves exits non-zero. A workspace file states no `expires_at` and is left to `lotics file download`. |
36
36
  | `lotics run set_members '{"members": {"<email or member id>": {"role": "member", "name": "…"}}}'` | Invite to this workspace (`name` is the name the invitation carries) or set a person's role in it (`role`: `member` or `admin`; `null` takes the person, or the invitation pending to that address, out of it); `groups` keeps the member groups in the same call. An admin of this workspace or an organization owner. Renaming or removing a person, restoring one, co-ownership and a member who signs in by a name are a person's in Settings → Members, and no tool takes them. The whole input is checked before an email is sent. A member's `lotics tools` lists neither `set_members` nor `set_workspace`. View-as is the web app's preview alone; the CLI acts as the signed-in member. |
37
37
  | `lotics run <tool> --print-created` | Report the records the call created, grouped by table, with a paste-ready `delete_records` per table and the mandatory caveat naming what cannot be auto-undone (external integrations, notifications, possible sub-workflows). Works for any tool that returns a `side_effects` block, not workflows alone. |
@@ -60,7 +60,7 @@ A stored text is changed by `edits`, never sent whole again: `set_workflow` (wit
60
60
 
61
61
  A long text not stored yet rides a file. `set_workflow` takes `source_file_id` in place of `source`, `set_knowledge` takes `content_file_id` in place of `content`, and `set_template` takes `template_file_id` in place of an html or email `template`: write the text where you work, upload it with `upload_file` (`files`), and pass the `file_id` the upload answers.
62
62
 
63
- Many rows come as a file. `query_records` with `as_file: true` lists no rows and sends them as a file: over MCP an embedded file (a whole set up to 12 MiB, a link past that), on the CLI a file `lotics run` saves where it runs (or in `-o <dir>`) and names. With `limit`, `offset`, `page_size`, `pagination` or `comments: true`, the file is that page as JSON, the answer whole: `records`, each with `record_id`, `data` and `display` keyed by field alias. Without them it is every row the call matches, in its order, as JSON Lines: one row a line, each as `records` lists it. That file is also at `_file.url` for an hour, `_file.rows` counts its rows, and `all: true` sends the same file. A call matching no row answers `total: 0` and no file. One organization writes one such file at a time. A set too large to write within about 80 seconds is refused with how many rows were written; narrow it with `filters`, or name fewer fields with `field_keys`.
63
+ Many rows come as a file. `query_records` with `as_file: true` lists no rows and sends them as a file: over MCP an embedded file (a whole set up to 12 MiB, a link past that), on the CLI a file `lotics run` saves where it runs (or in `-o <dir>`) and names. With `limit`, `offset`, `page_size`, `pagination` or `comments: true`, the file is that page as JSON, the answer whole: `records`, each with `record_id`, `data` and `display` keyed by field alias. Without them it is every row the call matches, in its order, as JSON Lines: one row a line, each as `records` lists it. That file is also at `_file.url` for an hour and `_file.rows` counts its rows. `all: true` with `as_file` sends the same file; `all` alone lists every row in the answer instead, up to 1,000 rows (more is refused, naming `as_file`). A call matching no row answers `total: 0` and no file. One organization writes one such file at a time. A set too large to write within about 80 seconds is refused with how many rows were written; narrow it with `filters`, or name fewer fields with `field_keys`.
64
64
 
65
65
  Many rows go back as a file too. `create_records` and `update_records` take `rows_file_id`: a JSON file holding the call's per-row keys, in place of stating them. Everything else stays in the call: `table_id`, `dry_run`, `row_op`, `return_fields`.
66
66
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lotics/cli",
3
- "version": "0.321.100",
3
+ "version": "0.321.102",
4
4
  "description": "Lotics SDK and CLI for AI agents",
5
5
  "type": "module",
6
6
  "bin": {