@lotics/cli 0.321.24 → 0.321.26
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.
- package/README.md +1 -1
- package/dist/src/cli.js +6 -6
- package/docs/app_architecture.md +1 -1
- package/docs/cli_reference.md +2 -2
- package/docs/permissions.md +9 -6
- package/docs/working_in_a_workspace.md +3 -3
- package/package.json +1 -1
package/docs/app_architecture.md
CHANGED
|
@@ -32,7 +32,7 @@ How each tree is composed is `design`.
|
|
|
32
32
|
|
|
33
33
|
## Who gets each
|
|
34
34
|
|
|
35
|
-
Who does which job is asked in `build`'s one message before the first write. An app stays with admins until the answer comes, and sharing waits on it. `set_access` then gives each app to everyone who works its rows (ids from `get_workspace` kind `member`, which lists the people in this workspace); none loses access. Someone who works its rows and is not in the workspace is added first by an
|
|
35
|
+
Who does which job is asked in `build`'s one message before the first write. An app stays with admins until the answer comes, and sharing waits on it. `set_access` then gives each app to everyone who works its rows (ids from `get_workspace` kind `member`, which lists the people in this workspace); none loses access. Someone who works its rows and is not in the workspace is added first by an admin of the workspace (`set_members`, `role: "member"`), since a share reaches only people in the workspace. They need no
|
|
36
36
|
table access: an app runs as its owner. With no `rows` on the App they read every row; where people differ, `rows`
|
|
37
37
|
states one rule per table (`reference/read-scope`):
|
|
38
38
|
|
package/docs/cli_reference.md
CHANGED
|
@@ -13,7 +13,7 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
|
|
|
13
13
|
| `lotics auth web` | Send a magic link email to access the web app (requires auth) |
|
|
14
14
|
| `lotics auth whoami` | Print active account name, email, org, resolved workspace, the instance the credential belongs to, which **kind** of credential this machine holds (a sign-in from `auth login`, or an API key — read from the saved profile, and from the server when the profile does not say, which covers `--api-key`/`LOTICS_API_KEY` and a profile saved before the field existed; unknown only when neither can say), and the resolution **source** (flag/env/local/app-manifest/global). `--json` adds `workspace_id`, `api_url`, `credential_kind` + `source`. |
|
|
15
15
|
| `lotics auth logout [<name\|id>]` | In a pinned dir: delete the local pin. Else: remove the profile (default the active org), `--all` for every one. What happens server-side depends on which KIND of credential it is. A **sign-in** (`auth login` / `auth signup`) is revoked — logging that terminal out ends its credential rather than leaving a live one behind; a server that cannot be reached, or a credential already dead, never blocks the local forget, and one line names the org and Settings → Security → *Keys and terminals*. An **API key** (`auth api-key`) is only forgotten here — an admin issued it and it is routinely on a server and on other machines, so one terminal signing out must not kill it for everyone; the line says it is still active and names both pages, because Settings → API keys is admin-only and the credential may well be the holder's own sign-in, which they revoke themselves at Settings → Security → *Keys and terminals*. A profile saved before the kind was recorded states nothing, so the SERVER is asked (`auth whoami`) and it is revoked only if the answer is a sign-in: an older server, a credential minted before the column, and a request that fails all leave it alone. |
|
|
16
|
-
| — | **A refused credential says which
|
|
16
|
+
| — | **A refused credential says which way it is dead, and names the remedy that ends its kind.** `This credential expired.` / `was revoked.` / `belongs to a member who is no longer active in this organization.` / `must be saved again by an organization owner before it works.` (an all-access key an earlier release made, until its access is saved again) carries `Run \`lotics auth login <email>\` to sign in again.` for a sign-in and `Ask an admin for a new API key (Settings → API keys).` for an issued key. A credential minted before that was recorded still gets BOTH in one sentence, because nothing on the row tells them apart — so a headless box is never sent looking for a browser alone. A key the server does not recognize at all gets one flat `Invalid or disabled API key.` — deliberately, so a guessed key learns nothing, not even that it named a row. The body carries `reason` for a script to branch on, since the code stays `unauthorized` for every 401. Changing or resetting the account's password revokes its sign-ins, never an issued key. |
|
|
17
17
|
| `lotics org` | List saved orgs (profiles) from the global store with the instance each belongs to, marks active for this directory (a local pin wins over the global default). |
|
|
18
18
|
| `LOTICS_ORG=<name\|id>` | Scope every command in this shell to one saved org. **Resolved once, before any command dispatches**, so a value matching no saved credential refuses every verb with one sentence — a read, a write, and a local check that needs no credential alike — and refuses it before the first byte is written. It refuses even when a credential arrives another way, because `--api-key` / `LOTICS_API_KEY` outrank it in the precedence chain and a write must never fall through to whatever THOSE name while the variable says otherwise; when the variable resolves and a key is also given, the key decides and the command says so. The refusal lists the orgs this machine holds, so it is answerable without another command (`lotics org` is refused by the same rule). A name is whatever the credential was SAVED under — a server-side rename never moves it, and the new name resolves too, so both keep working and `lotics org` prints the pair. |
|
|
19
19
|
| `lotics org use <name\|id> [--local]` | Switch the active org by org name (case-insensitive, ambiguous → error) or id. No flag → global `active_org`; `--local` → a `.lotics/config.json` pointer in the current dir. |
|
|
@@ -33,7 +33,7 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
|
|
|
33
33
|
| — | **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: {"key", …narrowing}` instead of the read arguments makes the file an app's Export makes (`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. |
|
|
34
34
|
| — | **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. |
|
|
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
|
-
| `lotics run set_members '{"members": {"<email or member id>": {"role": "member", "name": "…"}}}'` | Invite to this workspace, rename, set the role in this workspace (`role`: `member` or `admin`; `null` takes the person out of it), set the organization role (`organization_role`: `co_owner` or `member`, the primary owner's), remove from the organization (`remove: true`) or restore members; `groups` keeps the member groups in the same call.
|
|
36
|
+
| `lotics run set_members '{"members": {"<email or member id>": {"role": "member", "name": "…"}}}'` | Invite to this workspace, rename, set the role in this workspace (`role`: `member` or `admin`; `null` takes the person out of it), set the organization role (`organization_role`: `co_owner` or `member`, the primary owner's), remove from the organization (`remove: true`) or restore members; `groups` keeps the member groups in the same call. An admin of this workspace or an organization owner; a workspace admin acts only on this workspace's people and renames or removes only a person wholly in workspaces they administer. 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. |
|
|
38
38
|
| `lotics run <tool> --cleanup` | Implies `--print-created`, then runs those deletes — harvested records **only**, never files / external calls / notifications. **Not a rollback**; a rollback is structurally impossible here. A partial cleanup exits non-zero so a script cannot read it as success. |
|
|
39
39
|
| `lotics file upload <file\|dir...>` (alias `lotics upload`) · `--stdin` · `--base64` · `--url <url>` | Upload files/directories. **The transport is chosen by size and is not a flag**: under 8 MiB the file is POSTed to `/v1/files`, several such files to a request up to half that route's 100 MiB cap; at or above it the CLI takes presigned part URLs and PUTs the bytes straight to object storage, so they never pass through the API. That threshold matches the AWS CLI's own `multipart_threshold`, and the number matters less than there being nothing to choose — one verb, any size, up to the 2 GiB a workspace may store. A large upload reads one part at a time, so memory stays flat regardless of file size, and a failure part-way abandons the parts already sent rather than leaving them billable and invisible. A directory expands to its immediate files; `--as <name>` renames a single upload. **Three alternative byte sources, for a caller that never had the bytes on disk** — an attachment decoded in memory, a generated document, a signed download link — each mutually exclusive with the others and with a path argument: `--stdin` takes raw bytes on stdin, `--base64` takes base64 on stdin (the shape attachments arrive in), `--url <url>` fetches the URL first. `--stdin`/`--base64` REQUIRE `--as`, because stdin carries no filename and the mime type is derived from it; `--url` falls back to `Content-Disposition` then the URL's last path segment. `--base64` decodes STRICTLY — `Buffer.from(s, "base64")` silently skips invalid characters and truncates on bad padding, so a corrupted pipe would otherwise store a short file that only fails when a human opens it. The `--url` fetch happens in the CLI, not the server: the URL comes from the operator running the command, so routing it through the backend would add an SSRF surface to buy what `curl` already does. |
|
package/docs/permissions.md
CHANGED
|
@@ -7,24 +7,27 @@ Who can reach what, what runs under whose access, and what a refusal means.
|
|
|
7
7
|
An agent over MCP, or a terminal signed in with `lotics auth login`, acts as the member who approved it: it reaches
|
|
8
8
|
what that member reaches, and no more. An `ltk_` key set to **Only selected ones** is its own narrow member: it reaches
|
|
9
9
|
the apps and tables named on it, and a share to everyone in a workspace does not reach it. A key set to **All apps and
|
|
10
|
-
tables** reaches
|
|
10
|
+
tables** reaches everything in the workspaces named on it, and not a workspace created after it. `get_workspace` lists what the caller can use.
|
|
11
11
|
|
|
12
12
|
## Who is in a workspace
|
|
13
13
|
|
|
14
14
|
A person is in a workspace only when added to it, as its **admin** or a **member**. Ownership and shares grant only
|
|
15
15
|
inside a workspace the person is in. **Organization owners** — the primary owner and co-owners — are admin of every
|
|
16
|
-
workspace and alone manage
|
|
17
|
-
organization's settings; only the primary owner makes or unmakes a co-owner. A workspace admin holds everything
|
|
16
|
+
workspace and alone manage organization roles, restores, people in no workspace, billing, usage, workspaces and the
|
|
17
|
+
organization's settings; only the primary owner makes or unmakes a co-owner. A workspace admin holds everything in
|
|
18
18
|
their workspace: its settings and instructions, sharing, apps and publishing them, tables, templates, docs, workflows,
|
|
19
|
-
connections and restores
|
|
20
|
-
|
|
19
|
+
connections and restores, and its people, invitations, groups, API keys and access log. They rename, reset the password
|
|
20
|
+
of or remove from the organization only a person who is in no workspace they do not administer and is no organization
|
|
21
|
+
owner; anyone else is an organization owner's. `get_workspace` kind `member` lists the people in this workspace; an organization owner passes
|
|
22
|
+
`all: true` for the whole organization. `set_members` adds a person to the workspace (`working_in_a_workspace`); a workspace admin adds only
|
|
23
|
+
someone already in a workspace, and an organization owner places someone in none.
|
|
21
24
|
|
|
22
25
|
## Ownership and sharing
|
|
23
26
|
|
|
24
27
|
Every table, app, knowledge doc, document template, skill, automation, notification workflow and connection has one
|
|
25
28
|
owner. Everything starts private, and sharing is the only way to widen it. `set_access` gives a member or a group in the
|
|
26
29
|
workspace, or everyone in it, a role on a resource (`working_in_a_workspace`). A share with someone outside the workspace,
|
|
27
|
-
or with a group
|
|
30
|
+
or with a group of another workspace, is refused: the person is added to the workspace first, by an admin of it with `set_members`. Several shares add up, the highest role wins, and
|
|
28
31
|
there is no deny.
|
|
29
32
|
|
|
30
33
|
**Lists are shorter than reach.** A listing shows your own work and what is shared with you. An admin's listing says what it left out (`not_listed`), and `all: true` on `get_workspace` lists it: apps, knowledge docs and templates. An admin's agent lists every table, automation and connection without it. A doc search covers what is listed, so a member's private doc enters an admin's answers only with `all: true`. By id, an admin reaches anything. Sharing an item with yourself through `set_access` lists it from then on.
|
|
@@ -21,11 +21,11 @@ Find the means in this order: `get_workspace` maps the workspace; `search` it by
|
|
|
21
21
|
|
|
22
22
|
## People
|
|
23
23
|
|
|
24
|
-
`get_workspace` with kind `member` lists the name and id of each person in this workspace; an organization owner passes `all: true` for everyone in the organization. An admin of the workspace also sees each one's email, organization `role`, `workspace_role` (`admin`, `member`, or null for a person outside it), `managed` and `sign_in_name`, and, on kind `app`, `knowledge` or `template`, `not_listed`: how many more they can reach, which `all: true` lists. Listed docs and templates carry `access`. An admin also reads the credit limits there. With kind `group`,
|
|
24
|
+
`get_workspace` with kind `member` lists the name and id of each person in this workspace; an organization owner passes `all: true` for everyone in the organization. An admin of the workspace also sees each one's email, organization `role`, `workspace_role` (`admin`, `member`, or null for a person outside it), `managed` and `sign_in_name`, and, on kind `app`, `knowledge` or `template`, `not_listed`: how many more they can reach, which `all: true` lists. Listed docs and templates carry `access`. An admin also reads the credit limits there. With kind `group`, everyone lists the groups of this workspace; an organization owner also lists the groups no workspace holds yet.
|
|
25
25
|
|
|
26
|
-
`set_members` is an organization owner's: `members` is a map keyed by an email address, a member id or a managed member's sign-in name, and `groups` a map keyed by a group id, or by a group's name, which sets the group of that name or creates it (refused where several groups share it: key that entry by id). In `members`, `role` is the person's role in THIS workspace, `member` or `admin`; `role: null` takes them out of it, ending their shares here and passing what they own here to the caller. An email no member holds invites that person to the organization as a member, with `role` as their place here (`member` when omitted; the invitation email goes out). A current member's entry sets `name`, `role`, and `organization_role`: `co_owner` or `member`, which only the primary owner sets; a co-owner made a member passes what they own in workspaces they are not in to the primary owner. A removed member's entry restores them as an organization member in no workspace, and takes only `name
|
|
26
|
+
`set_members` is an admin's of this workspace or an organization owner's: `members` is a map keyed by an email address, a member id or a managed member's sign-in name, and `groups` a map keyed by a group id, or by a group's name, which sets the group of that name or creates it (refused where several groups share it: key that entry by id). In `members`, `role` is the person's role in THIS workspace, `member` or `admin`; `role: null` takes them out of it, ending their shares here and passing what they own here to the caller. An email no member holds invites that person to the organization as a member, with `role` as their place here (`member` when omitted; the invitation email goes out). A current member's entry sets `name`, `role`, and `organization_role`: `co_owner` or `member`, which only the primary owner sets; a co-owner made a member passes what they own in workspaces they are not in to the primary owner. A removed member's entry restores them as an organization member in no workspace, and takes only `name`; only an organization owner restores. `remove: true` removes a member from the organization, or cancels the invitation pending to that address; removing a co-owner is the primary owner's. A workspace admin who is not an organization owner acts on this workspace's people only: never on an organization owner; renames or removes from the organization only a person in no workspace they do not administer; adds to this workspace only someone already in a workspace; an address invited elsewhere gets a place here on that invitation; `remove` on an invitation takes it out of this workspace, canceling it when no other workspace holds it. Each result says which changed: `added_to_workspace`, `workspace_role_changed`, `removed_from_workspace`, `organization_role_changed`, `removed`, `restored`. Sign-in names are compared in lowercase. A person adds a managed member and sets its password in Settings → Members. The primary owner is never removed, demoted or given a workspace role. A group belongs to this workspace and holds only its people. In `groups`, an entry sets `name`, `description` and the roster with `member_ids`, or with `add_member_ids` and `remove_member_ids` that leave the rest in place; a roster entry may be a key of `members`, so a person invited in the same call can join; `null` deletes the group. The whole input is checked before anything is written or sent; members are applied before groups, in the order given. A workspace admin's tool list carries `set_workspace` and `set_members`; a member's carries neither.
|
|
27
27
|
|
|
28
|
-
`set_access` gives members or groups in the workspace, or everyone in it (`organization`), a role on resources. A share with someone outside the workspace, or with a group
|
|
28
|
+
`set_access` gives members or groups in the workspace, or everyone in it (`organization`), a role on resources. A share with someone outside the workspace, or with a group of another workspace, is refused as outside the workspace; an admin of the workspace adds them first with `set_members` (`role: "member"`), then the share is made again. Role `owner`, on one member, hands every resource listed to that member, who is in the resource's workspace and whom only the resource's owner or an admin may name; a call cannot share an app and hand it over together, an app handed to or from a member loses its sharing, and an automation is turned off until its new owner turns it on. Handovers are applied one resource at a time, and a failure part-way names what was already applied. `set_workspace` takes `credit_limits` (`workspace`, `apps` by app id, `members` by member id; a number is the daily ceiling in credits, `null` removes it and asks for approval).
|
|
29
29
|
|
|
30
30
|
## Comments
|
|
31
31
|
|