@lotics/cli 0.321.38 → 0.321.39
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/AGENTS.md +3 -3
- package/README.md +5 -5
- package/dist/src/cli.js +38 -41
- package/dist/src/client.d.ts +4 -6
- package/dist/src/client.js +4 -4
- package/docs/cli_reference.md +2 -2
- package/package.json +1 -1
package/AGENTS.md
CHANGED
|
@@ -52,7 +52,7 @@ something exists, read `lotics --help` § COMMANDS — the whole section, not a
|
|
|
52
52
|
(`lotics → <org> / <workspace>`); read it back before trusting a write. Resolution precedence is
|
|
53
53
|
in README § Organizations.
|
|
54
54
|
- **A machine with no key can still sign in, and the sign-in never blocks you.** `lotics auth
|
|
55
|
-
login
|
|
55
|
+
login` takes no argument and sends no mail: it prints the page a person opens and the code that page must show,
|
|
56
56
|
records the request, and EXITS. They press Confirm whenever they get to it; the next command that
|
|
57
57
|
NEEDS a credential collects the key before doing its own work, so "sign in" costs you one command
|
|
58
58
|
and then re-running what you wanted. Never wrap it in a timeout waiting for a human — `--wait`
|
|
@@ -76,12 +76,12 @@ something exists, read `lotics --help` § COMMANDS — the whole section, not a
|
|
|
76
76
|
reads inside a workspace the key reaches, runs as before, while managing people, sharing or
|
|
77
77
|
ownership, creating or deleting a workspace, changing workspace settings, setting credit limits,
|
|
78
78
|
reading the access log and publishing an app's API answer `403` and name the remedy: an admin signed in, so
|
|
79
|
-
`lotics auth login
|
|
79
|
+
`lotics auth login` and run it again. A sign-in acts as that person and is refused none of
|
|
80
80
|
them. Do not retry a `403` with the same credential and do not ask for a wider key — no answer on
|
|
81
81
|
the key's own screen grants this.
|
|
82
82
|
- **A 401 names its remedy — act on the hint, do not retry.** "This credential expired / was
|
|
83
83
|
revoked / belongs to a member who is no longer active" carries the one remedy that ends this
|
|
84
|
-
credential: run `lotics auth login
|
|
84
|
+
credential: run `lotics auth login` for a sign-in, or ask the admin who issued it for a
|
|
85
85
|
new key. A credential minted before that was recorded carries BOTH, because nothing on the row
|
|
86
86
|
tells them apart — so on a box with no browser, take the second. Only an UNRECOGNIZED key gets
|
|
87
87
|
the generic "Invalid or disabled API key", and that one is generic on purpose, so re-sending it
|
package/README.md
CHANGED
|
@@ -104,7 +104,7 @@ The CLI checks for updates once per day and prints a note on stderr, naming the
|
|
|
104
104
|
|
|
105
105
|
**Two kinds of credential, and which you hold decides what `logout` does.** `auth signup` / `auth login` give this machine a **sign-in** — it acts as you, carries whatever role you have, and is yours to see and revoke at Settings → Security → *Keys and terminals*; it lapses after 90 days of disuse, and each use pushes that out. `auth api-key` saves an **API key** an admin issued. A key an admin creates in Settings has its own name and its own access, reaching either every app and table or only the ones chosen on the key; an older key created FOR a person carries that person's access and stops working when that person is removed. Either kind often lives on a server and on other people's machines too, and only an admin revokes it. `lotics auth whoami` prints which kind this machine holds — from the saved profile, or from the server when the profile does not say.
|
|
106
106
|
|
|
107
|
-
When a credential stops working the refusal says which of the three ways it is dead — "… was revoked." / "… expired." / "… belongs to a member who is no longer active in this organization." — and its `hint` names the remedy: `lotics auth login
|
|
107
|
+
When a credential stops working the refusal says which of the three ways it is dead — "… was revoked." / "… expired." / "… belongs to a member who is no longer active in this organization." — and its `hint` names the remedy: `lotics auth login` for a terminal sign-in, ask an admin for a new key for an API key. A credential whose record does not say which of the two it is gets both. A key the server does not recognize at all gets one generic answer, deliberately: an unrecognized key learns nothing from being refused.
|
|
108
108
|
|
|
109
109
|
**`lotics auth signup`** — Creates a new Lotics account, organization, workspace, and API key in one step. Sends a magic link email so you can access the web app.
|
|
110
110
|
|
|
@@ -113,15 +113,15 @@ lotics auth signup # interactive prompts
|
|
|
113
113
|
lotics auth signup a@b.com --name "Agent" # non-interactive
|
|
114
114
|
```
|
|
115
115
|
|
|
116
|
-
**`lotics auth login`** — Signs in an account that already exists, on a new machine or to add another organization to one that holds a key (the one you pick becomes active). **It does not wait for you.** It prints the page to open
|
|
116
|
+
**`lotics auth login`** — Signs in an account that already exists, on a new machine or to add another organization to one that holds a key (the one you pick becomes active). **It does not wait for you.** It takes no argument and sends no mail: it prints the page to open and the code that page must show, then exits. Sign in there if asked, check the code, pick the organization, press Confirm — and run whatever you wanted to run: the next command that needs a credential collects the key before doing its own work.
|
|
117
117
|
|
|
118
118
|
```bash
|
|
119
|
-
lotics auth login
|
|
119
|
+
lotics auth login # prints the page + code, exits — nothing to keep open
|
|
120
120
|
# …press Confirm in the browser…
|
|
121
121
|
lotics auth whoami # picks up the key, then answers
|
|
122
122
|
|
|
123
|
-
lotics auth login
|
|
124
|
-
lotics auth login
|
|
123
|
+
lotics auth login --wait # one command instead: holds the terminal until Confirm
|
|
124
|
+
lotics auth login --local # pins this directory to that org (implies --wait)
|
|
125
125
|
```
|
|
126
126
|
|
|
127
127
|
A command run before you press Confirm names the page and the code again and exits 1; the request is good for 15 minutes, after which the next command says to ask again. Re-running `auth login` is always safe — it replaces the request, so only the newest code is the live one.
|
package/dist/src/cli.js
CHANGED
|
@@ -283,22 +283,22 @@ function errorCode(cause) {
|
|
|
283
283
|
}
|
|
284
284
|
var WEB_APP_URL = process.env.LOTICS_WEB_URL ?? "https://lotics.ai";
|
|
285
285
|
var PUBLIC_FETCH_TIMEOUT_MS = 1e4;
|
|
286
|
-
async function startCliLogin(apiUrl
|
|
286
|
+
async function startCliLogin(apiUrl) {
|
|
287
287
|
let response;
|
|
288
288
|
try {
|
|
289
289
|
response = await fetch(`${apiUrl}/v1/cli/login_requests`, {
|
|
290
290
|
method: "POST",
|
|
291
291
|
headers: { "Content-Type": "application/json" },
|
|
292
|
-
body: JSON.stringify({
|
|
292
|
+
body: JSON.stringify({}),
|
|
293
293
|
signal: AbortSignal.timeout(PUBLIC_FETCH_TIMEOUT_MS)
|
|
294
294
|
});
|
|
295
295
|
} catch (error62) {
|
|
296
296
|
throw new Error(
|
|
297
|
-
`Could not reach Lotics to
|
|
297
|
+
`Could not reach Lotics to ask for a sign-in (${error62 instanceof Error ? error62.message : String(error62)}). Check your connection, or sign in at ${WEB_APP_URL}.`
|
|
298
298
|
);
|
|
299
299
|
}
|
|
300
300
|
if (!response.ok) {
|
|
301
|
-
throw new Error(`Lotics answered ${response.status} asking for a sign-in
|
|
301
|
+
throw new Error(`Lotics answered ${response.status} asking for a sign-in.`);
|
|
302
302
|
}
|
|
303
303
|
return await response.json();
|
|
304
304
|
}
|
|
@@ -1845,7 +1845,7 @@ async function saveSignedLinks(links, dir, timeoutMs) {
|
|
|
1845
1845
|
}
|
|
1846
1846
|
|
|
1847
1847
|
// src/version.ts
|
|
1848
|
-
var VERSION = "0.321.
|
|
1848
|
+
var VERSION = "0.321.39";
|
|
1849
1849
|
|
|
1850
1850
|
// src/timezone.ts
|
|
1851
1851
|
function machineTimezone() {
|
|
@@ -1888,10 +1888,10 @@ var examples_default = '# Worked examples\n\nEach section is one treatment, cut
|
|
|
1888
1888
|
var agent_surface_default = '# An app\'s agent surface\n\nEverything a person reads or does in an app, an agent reads or does through that app\'s **queries** and\n**workflows** \u2014 the same ones its screen runs, under the same permissions and the same rules. Three tools\nreach them, over MCP and as `lotics run <tool>`:\n\n| Tool | Answers |\n|---|---|\n| `get_app` | The app\'s `catalog`: its queries and workflows by alias, each one\'s description, its params or inputs with their types and legal values, and under a query\'s line its output columns (`returns`) \u2014 beside what each table they name holds, in its owner\'s words \u2014 and, for the app\'s author, `notes`: what its stored tree compiles with, each at its address under its rule id (`list.layout-call`, a root List drawing a table over rows a board layout would draw, with the layouts to state; `list.filter-unshown`, a filter no row draws, which the app leaves out) |\n| `run_app_query` | The rows, a count or the groups of one query \u2014 or of several in one call |\n| `run_app_workflow` | One write \u2014 or several in order \u2014 or a dry run of it that writes nothing |\n\nAn app generates this surface from its tree; Query and Workflow nodes declare what the screen never\nasks (`agent_surface/declaring-more`). Every root List of an app (a change may add one at any time) is part of it: each List\'s list, its rows by id, its page\'s\nLists and its Acts are queries and workflows of the same app, named by that List\'s table \u2014 `get_app` lists them in the\none roster, and nothing of a root List is another app\'s. Every caller the app is shared with is answered them, its rows narrowed by the app\'s row rules. A custom-code app\'s surface is the queries and workflows bound on it\n(`app_bindings`).\n\n## Finding what an app offers\n\n`get_workspace` maps the workspace. Its `search` matches the keys and descriptions of the Query and Workflow nodes an app declares, and the app\'s line names the matching keys; it never matches the generated `act_`, `create_` or `update_` aliases. `get_app` then gives the contracts. An agent runs a declared node before it falls back to `query_records`.\n\n## What every app generates\n\nA name in angle brackets is the app\'s alias for that thing; an `<entity>` is the alias of a table the app reads. `get_app` lists the ones a given\napp has.\n\n### Queries\n\n<!-- generated:start queries -->\n\n| Called | What it says of itself | Takes | Generated for |\n|---|---|---|---|\n| `<entity>_list` | Every row of <entity> the reader may see. | `search`?; `<scope entity>_id` where the app states `scope`; `<filter>_is`? per List `filters` field holding one value \u2014 a select, a one-row link, a member, a yes/no; `<filter>_from`? / `<filter>_to`? per date filter \u2014 none for a date holding a span; `<filter>_min`? / `<filter>_max`? per number filter \u2014 none over sources, none for a looked-up link or member, none for a number read in each row\'s own unit or currency | every entity the app draws; the filter params on the app\'s own entity alone; a root List after the first over an entity, whose chips differ from the first\'s, adds one of its own, called by its key |\n| `<entity>_list_<tab>` | The <entity> rows of the tab "<tab>". | the list\'s; `from`? / `to`? on a tab dated `in` a period; `to` on a tab of rows `open` on a day | each Tab of the register, and of each later root List over an entity, called by its key; none over sources, none for a Tab whose period reads a date holding a span |\n| `<entity>_totals_<tab>` | The <child> rows added per <entity> row, by "<link>", over the period from `from` to `to`, dated by "<date>": . | `from`; `to` | each Tab of the register stating `totals`, and of each later root List over an entity, called by its key |\n| `<entity>_record` | One row of <entity> by its id. | `<entity>_id` | every entity the app draws |\n| `<child>_by_<link>` | The <child> rows under one <entity>, through "<link>". | `<entity>_id` | each List of child rows on the record; one narrowed by `where` or ordered by `sort` adds `_<field>_<option>` and `_sorted_<field>` to its name |\n| `outside_<key>_one` | One row of <entity> by its id. | `record` | each Outside: the record a link opens, projected to the fields the Outside states |\n| `outside_<key>_<child>` | The <child> rows under one <entity>, through "<link>". | `record` | each List of an Outside: the rows under the record a link opens, projected to the List\'s columns |\n| `<child>_by_<link>_days` | The <child> rows of the <entity> rows handed in whose "<day>" falls from one day to another. | `<entity>_ids`; `from`; `to` | a roster List: the List of its cells |\n| `<entity>_<link>_pick` | The <target> rows "<link>" may point at, narrowed by what the reader typed. | `search`?; `same_<link>` per `same` link | a written link a write rule narrows (`options_where`, `same`) |\n| `<child>_by_<link>_picks` | The <child> rows no <entity> holds through "<link>" yet, that one <entity> may pick, narrowed by what the reader typed. | `search`?; `same_<link>` per `same` link | a List with `pick`: it picks existing rows into the record |\n| `<key>` | <label>: how many <entity> rows there are. Each row carries `__count`. | the list\'s; `from`? / `to`? where the reading states `over`, or its `tab` is dated `in` a period; `to` where its `tab` is of rows `open` on a day | each Reading of a List\'s band, called by its `key` \u2014 but the work against its plan (a Reading stating `planned` and `done`), which reads the List\'s own rows; none over sources |\n| `<key>` | <label>: how many <entity> rows there are. Each row carries `__count`. | `from`? / `to`? where the reading states `over` | each Reading and List of a Sheet, called by its `key` |\n| `<key>` | <label>: how many <child> rows there are. Each row carries `__count`. | `<entity>_id`; `same_<field>` where it is a List stating `same`; `record_<field>` per `where` bound to a field of the record | each Reading of a Record page, each List that only reads on it (its `key`, else its entity\'s alias) and each funnel, called by its `key` |\n| `<reading>_bound` | <label> / <bound>: the sum of "<bound>" over the <entity> rows. Each row carries `__count`, `__sum`. | its reading\'s | a Reading whose value `records.limits` bounds: the bound\'s sum, beside the Reading\'s own |\n| `<reading>_on_hand` | <label> / <on-hand entity>: how many <on-hand entity> rows there are, per "<field>". Each row carries `<field>`, `__count`. | none: every row of its entity its `where` keeps, whatever the place | a Reading with `on_hand` (a shortfall): the on-hand rows\' groups, beside the Reading\'s own |\n| `<entity>_export_rows` | Every row of <entity> the reader may see, with every field "<template>" may print. | the list\'s | an Export of the register that fills a template |\n| `<entity>_export_rows_of_<source>` | Every row of <entity> the reader may see, with every field "<template>" may print. | the list\'s | an Export over some of a List\'s sources: their rows alone, each source named in turn |\n| `<entity>_moves` | Each move in <history> of the <entity> rows handed in: the status it went to, when and by whom, earliest first. | `<entity>_ids` | an entity whose status keeps a history (`records.status.history`) |\n| `<entity>_plan_load` | How many <entity> rows each <place> holds, over every table the register reads \u2014 the rows with no <place> counted apart. | | a register laid out as a `plan`: its places\' counts of present rows |\n\n<!-- generated:end queries -->\n\nA reading\'s query returns groups, never the rows it read: one row for all of them, or one per value it\nsplits by, or per day. Each row carries the alias of each field it splits by, `__day` where it splits by\nday, `__count`, and `__sum` where it sums a number; its description states which. An average is `__sum`\nover `__count`, both over the rows holding a value.\n\nA Reading is called by its `key` (`reference/reading-node`), and a List that only reads by its `key`, else its entity\'s alias \u2014 wherever its List stands in the app, so a move in the tree changes no name. Each is its own among the app\'s Readings, Lists that only read and Queries.\n\nA register reading\'s query reads the rows it names, whatever a screen has open: the rows of its `tab` where\nit states one, every tab\'s where it states none \u2014 its description says which. One placed in time (`over`)\nreads every day unless the call states `from` or `to`.\n\n### Queries the screen runs for itself\n\nThey run like any other, and `get_app` leaves them out: each feeds one control, and takes ids\nthe screen already holds.\n\n<!-- generated:start screen-queries -->\n\n| Called | What it says of itself | Takes | Generated for |\n|---|---|---|---|\n| `<child>_<link>_target` | One <entity> row by its id, where a <child> row\'s "<link>" may point at it. | `<entity>_id` | a List with `pick` whose link a write rule narrows |\n| `<entity>_<field>_values` | Each "<field>" the <entity> rows hold, once, most held first, narrowed by what the reader typed. | `search`? | a text field a write rule offers values to (`suggest`) |\n| `<entity>_pictures` | The picture and name of each <entity> row among the ids handed in. | `<entity>_ids` | a link to several pictured rows |\n| `<entity>_count_by_<scope>` | How many <entity> rows each <scope entity> holds. | | an app stating `scope` |\n| `<task>_progress_by_<link>` | How many <task> rows each <entity> row handed in holds, at each status. | `<entity>_ids` | rows whose task rows are counted done |\n| `<entity>_sub_counts_by_<link>` | How many <entity> rows stand under each <entity> row handed in, through <link>, at each status. | `<entity>_ids` | a record\'s rows block over a hierarchy (`nests`), for the rows it draws |\n| `<entity>_plan_places` | Every <place> the <entity> rows stand at, with what the plan draws of each. | | a register laid out as a `plan`: the places its rows stand at |\n| `<lane>_lanes` | The <lane> rows of one <scope entity>, each a lane of the board. | `<scope entity>_id` | a lanes board inside an app stating `scope` |\n| `<entity>_same_<link>` | The <entity> rows naming one "<link>". | `same`; `before` where its line reads rows before a moment | a statement line that carries rows (`parts`) |\n\n<!-- generated:end screen-queries -->\n\n### Workflows\n\n<!-- generated:start workflows -->\n\n| Called | What it says of itself | Takes | Generated for |\n|---|---|---|---|\n| `create_<entity>` | Opens one row of <entity>. | every field the add asks, and the link it files the row under | an entity the app adds rows of |\n| `update_<entity>` | Changes one row of <entity>; every input but the row is optional, and one left out is left as it is. | `record_id`, and each field a person edits \u2014 a files field or a link to several rows as `<field>_added` / `<field>_removed` | an entity the app edits |\n| `move_<list>` | Gives rows of <entity> to a <lane> together: every row is judged before any is written, so a refusal leaves them all as they were. `lane` left out leaves the <lane> as it is, `lane` empty clears it; `day` dates only the rows holding none; `order` places each by its number. | `record_ids`, `lane` (left out, the lane stays; empty, none), `day` for the rows holding none, and `order`: each row\'s id and number | a lanes board of days with no hour whose app writes its lane |\n| `remove_<entity>` | Removes one row of <entity>. | `record_id` | an entity the app removes rows of |\n| `restore_<entity>` | Brings back one deleted row of <entity>. | `record_id` | an entity the app removes rows of |\n| `act_<act>` | <label> \u2014 on one row of <entity>, refused where its conditions do not hold. | `record_id` \u2014 `record_ids` on an act over several rows \u2014 and what the act asks | each Act that names no workflow of its own |\n| `archive_<act>` | Hands back every file of <label> on one row of <entity> as one archive. | `record_id` | an Act making a set of papers (`templates`) |\n\n<!-- generated:end workflows -->\n\nA Workflow node is called by its `key`, and every Act by `act_<key>`; an Act that names its own `workflow` is also called by that workflow\'s alias.\n\n## Calling a query\n\n```\nget_app {"app_id":"app_\u2026"}\nrun_app_query {"app_id":"app_\u2026","alias":"order_list","params":{"status_is":"open","due_on_to":"2031-03-14"}}\n```\n\n| Argument | Does |\n|---|---|\n| `params` | The query\'s declared params. A required one is always sent; an optional one left out narrows nothing. A select takes the option\'s alias as `get_app` lists it in `select(label=alias|\u2026)` \u2014 a link a record id, a member a member id, a date `yyyy-mm-dd` |\n| `filters` | Narrows the result further, by the query\'s output columns (`filters`) |\n| `fields` | The output columns to return, in place of all of them; each row then holds them and the id of the record it is |\n| `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 |\n| `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` \u2014 a map of name \u2192 filter, never beside `count_by` \u2014 `counts` per name. Never with `fields`, `sort`, `limit` or `cursor` |\n| `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 |\n| `limit`, `cursor` | A page \u2014 200 rows at most, 50 where no `limit` is stated \u2014 and the `next_cursor` of the page before it; `truncated` says more rows matched than `rows` holds |\n| `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 |\n\nA query that states its own `limit` lists at most that many rows: `truncated` is `true` where more match, and `total` is\nthe rows the filtered query matches without it. A `count`, `count_by`, `count_where` and an `aggregate` are over every row\nthe query matches, never over the rows its `limit` lists.\n\nThe rows of one call, across its reads, total at most 262,144 bytes: a read past that is refused, naming\n`fields` and `limit` as what narrows it. The names `filters`, `fields`, `sort`, `count_by` and `aggregate`\ntake are the ones on the query\'s `returns` line.\n\nA list\'s params are how a person narrows that register: `search`, the row\'s id on an app that works inside\none row (`scope`), and a param for each filter the register states that one value or a range narrows. A\nfilter with no param \u2014 on a looked-up link or member, on a number read in each row\'s own unit or currency,\non a date holding a span, or on a List of several tables (`sources`) \u2014 is narrowed by `filters`, where a\nnumber condition names the unit its value is in as `unit_option`, an option of the figure\'s select by label\nor key. Each tab of a register is a query of its own, taking the list\'s params and the period its rows are\nread over; a tab\'s totals take the folder\'s id too, in an app that works inside one row.\n\n## Exporting a file\n\n```\nrun_app_query {"app_id":"app_\u2026","export":{"key":"by_carrier","per":"\u2026","tab":"in_yard","status":["\u2026"]}}\n```\n\n`export` makes the file the register\'s Export button makes, from what the caller reads, and answers it under `files` as a workspace\nfile like any other a tool makes: `file_id`, `url`, `filename`, `mime_type`. `key` is the\nkey of an Export of a List in `get_app`\'s tree, at the root or below a row\'s page; it is sent without `alias` or any other argument of a\nread. An option is named by its name or its id, as a read\'s filters name it; a member by its id or its name, for a member\nof the app\'s organization; a row, by its id. The other keys\nnarrow the file as the register\'s own controls do, each absent one leaving the register\'s opening view:\n\n| Key | Takes |\n|---|---|\n| `per` | The option, row id or member id the report is made for \u2014 required by an Export that states `per`, refused by one that does not; a member, here and in a member chip, is an id or a name, found as a filter on a member column finds one |\n| `tab`, `period`, `window` | A Tab\'s key (the first when absent); `{ "from", "to" }` days `yyyy-MM-dd` (`yyyy-MM-ddTHH:mm` on a date-and-time field) the tabs read over; a calendar\'s or board\'s days |\n| `status` | Options of the register\'s status that are kept |\n| `filters` | `{ "<field>": <value> }` by the field\'s alias, a value `null` clearing the register\'s opening chip; a value is one of the shapes below |\n| `search`, `overdue`, `waiting` | Words searched, one line each of a pasted list; `true`: only the rows past a deadline; `true`: only the rows waiting on the caller |\n| `sort`, `group`, `folder` | `{ "field", "dir" }`; a field alias; a folder id |\n| `row` | The id of the row whose rows a List below a row\'s page exports: required there and refused on a root View, and the reader must be able to open that row |\n\n| A `filters` value | For a field that is |\n|---|---|\n| `{ "kind": "ids", "ids": [...], "unset"?: true }` | a select (options) or a link to rows (row ids); `unset` also keeps rows holding none |\n| `{ "kind": "members", "mine": false, "ids": [...], "unset"?: true }` | a member; `mine` is the caller |\n| `{ "kind": "dates", "from": "yyyy-MM-dd" \\| null, "to": \u2026 \\| null, "unset"?: true }` | a date; `null` leaves an end open; `unset` also keeps rows holding none |\n| `{ "kind": "yes_no", "value": true }` | a yes/no |\n| `{ "kind": "number", "min": 1 \\| null, "max": \u2026 \\| null, "unit"?: "\u2026" }` | a number; `unit` the option of a unit or currency field |\n| `{ "kind": "bands", "bands": [{ "min", "max" }] }` | a number the register cuts into tiers |\n\nA key the register lacks, a tab it does not hold or a value its field cannot take is refused, naming it.\n\n## Calling a workflow\n\n```\nrun_app_workflow {"app_id":"app_\u2026","alias":"act_hand_over","inputs":{"record_id":"rec_\u2026"},"dry_run":true}\nrun_app_workflow {"app_id":"app_\u2026","alias":"act_hand_over","inputs":{"record_id":"rec_\u2026"}}\n```\n\n| Argument | Does |\n|---|---|\n| `inputs` | The workflow\'s declared inputs. An update takes the record and only the fields that change |\n| `dry_run` | `true`: the run is made and taken back, so nothing is kept, and the answer is what the run would return, with the calls it would make \u2014 or `status: "not_previewed"` where the workflow cannot be dry-run (`agent_surface/a-dry-run`) |\n| `as_member` | For an organization owner: the run is a dry run, judged as that member would press it \u2014 their stage owners, row rules and app access \u2014 and writes nothing. Anyone else is refused; a record tool takes it the same way, and so do `query_records` and `run_app_query`, which answer what that member would read, and `screenshot_app`, which draws the app as that member sees it |\n| `runs` | Several runs in one call, 50 at most, in order, each its own write, answered under `runs`. The first one refused, failed or not dry-run ends the call. An input `{"from_run": 0, "path": "data.record_id"}` is an earlier run\'s answer at that path. A run states its own `dry_run`, or takes the call\'s. Dry runs one after another share their rows, taken back together, so a run reads what the one before it made; a run reads a dry run\'s answer only from a run dry-run in that stretch |\n\n```\nrun_app_workflow {"app_id":"app_\u2026","runs":[\n {"alias":"create_order","inputs":{"customer":"rec_\u2026","item":"rec_\u2026","due_on":"2031-03-14"}},\n {"alias":"act_hand_over","inputs":{"record_id":{"from_run":0,"path":"data.record_id"}}}\n]}\n```\n\nAn act that reads papers (`intake`) is read by the caller: no platform agent reads for it. Its save `act_<alias>` takes `fields` (what the papers state), `rows` (the child rows listed) and `papers` (`[{"file":"fil_\u2026","kind":"<option>"}]`), and `dry_run` shows the record and rows it would make.\n\n## A dry run\n\nA dry run is the run itself on the real inputs, taken back: it is made in a transaction that is rolled back, so a read after a write reads that write, a branch or a loop walks the values the run would hold, and a call fed by an earlier call\'s answer gets it. No row, number, event, audit entry or table workflow outlives it. A write of the workspace\'s rows is made by its table \u2014 checks, write rules, stage owners \u2014 and the first refusal is the dry run\'s answer. A connected service\'s read-only call is made; a service write, a send, a notification or a button that runs another workflow is not, and is answered as a "would" with its payload. A guard (`when`, `requires`, a check, a lock) refuses it with the press\'s own sentence. A paper it makes is rendered for the answer and its file is removed with the dry run; an act that makes a paper is dry-run like any other, never refused for it. A body that sets the record\'s status also answers `moves`. Its answer carries `status`,\n`message`, `field_errors` and `data` as the run would return them, and under `dry_run`:\n\n| Key | Holds |\n|---|---|\n| `available` | `true` |\n| `writes` | The calls the run would make that are not reads, in order. The app\'s owner and an admin, who may read the workflow\'s body, read each call\'s `step_id`, `tool_name` and `input`. Another member reads each step that would write once: its `step_id` and `tool_name`, and where the step states them outright, the `table_id` it names and how many `records` it lists |\n| `reads` | The reads made for real, in order, each with its `input` and what it `returned` (cut at 2,000 characters, `truncated`), for the app\'s owner and an admin |\n| `papers` | Each paper rendered: its `step_id` and `filename`. The file is not kept |\n| `unpredicted` | The parts of the answer left out \u2014 `message`, `field_errors`, `data` \u2014 because each reads what a call the dry run did not make would answer |\n\nWhat a write sets off once it commits \u2014 a table\'s own workflows, its events \u2014 does not happen in a dry run.\n\nA workflow is not dry-run where its body reads the answer of a call that leaves the workspace, to branch,\nloop, check or feed another call, where it reads or writes rows after such a call (the run would find them as\nthat call left them), where it runs an agent, where it waits, where a step cannot be evaluated, fails\nfor a reason that is no table\'s refusal, or sends its call an input the call refuses, and where the run is past\nwhat one dry run walks \u2014 its steps, the passes of a loop, 50 reads, 50 writes or 20 seconds, which the runs of\none call share and the database holds it to: a lock wait that outlasts them ends the dry run. The\nanswer is then `status: "not_previewed"` with\n`dry_run: { "available": false, "reason" }`, and nothing ran \u2014 within `runs`, it ends the call. The same\nanswers a caller outside the app\'s organization.\n\n## A reviewed act\n\nAn act that states `review` runs a workflow that only proposes: call it with the inputs the act asks and it answers,\nwriting nothing, the changeset its body proposes in `data.review` \u2014 `table_id`, `creates` (each with its `key`) and\n`updates` (each with its `record_id`), each row\'s `data` holding only the fields that change, by field alias, with an\noptional `note` and `ticked` (`false` where the body leaves it for a person to choose), and `unplaced`, what was read\nand matched nothing; the platform adds a `sha` to every row. Call it again with the same inputs and `approved`,\n`{ "updates": [{ "record_id", "sha" }], "creates": [{ "key", "sha" }] }`, listing the rows to write with the `sha` each\ncarries in the proposal, copied as it came \u2014 never computed \u2014 and the platform writes those rows as that second call\nproposes them, each only where it proposes the values read:\n\n```\nrun_app_workflow {"app_id":"app_\u2026","alias":"match_statement","inputs":{"record_ids":["rec_\u2026"],"statement":"fil_\u2026"}}\nrun_app_workflow {"app_id":"app_\u2026","alias":"match_statement","inputs":{"record_ids":["rec_\u2026"],"statement":"fil_\u2026","approved":{"updates":[{"record_id":"rec_\u2026","sha":"9f2c\u2026"}],"creates":[{"key":"line-4","sha":"41d0\u2026"}]}}}\n```\n\nThe answer\'s `data.applied` names the run (`execution_id`), the records `updated`, what each held before (`previous`), each `created` record by its key,\nand each approved row `left` with its `reason`: `not_proposed` (the second call no longer proposes it), `not_acted`\n(an update of a record the act was not run on), `changed` (the second call proposes other values than were read \u2014 read\nthe proposal again), `empty` (an update changing no field), `missing`, `locked` or `conflict`. Every approved row is\nchecked before any is written, and all are written in one transaction or none; the status history of each row written\nthat moved is recorded by the same run. `applied.previous` holds, for each record in `updated`, what the fields the call wrote held before (null for an empty one): `update_records` with it as `set` puts them back, and `delete_records` of a `created` record takes that row away. An act over every\nrow in view takes no `record_ids`. A `file` input takes the id of a file uploaded to the workspace.\n\nAn Act that `makes` a cadence\'s rows proposes the same way with no body: `creates` are the child rows still owed, each\n`key` `<parent id>|<day>`, a row its write would refuse unticked with the refusal as its `note`, and `unplaced` says what\nstays off the pattern and how many closed days were skipped.\n\n## A refusal\n\nA workflow re-checks on the server what the screen shows of its own act or save: what an act requires, a\nduplicate, whose step it is, a row the caller may not see. Each write it makes also meets the table\'s own\nrules (a bound, a span, a stage\'s owner, its lock), which hold on every path a record is written by. A row its table\nlocked is refused in every app\'s act and save, naming who can change it; an app\'s own Check only makes a row read-only\nin that app. An unlock in an app\'s run is judged as the member it runs for, never the app\'s owner. A run refused\nbefore it writes writes nothing; one whose later write a table\'s rule refuses keeps the writes before it.\nEither answers `status: "error"` with the sentence a person would read as `message`, and under `field_errors`\nthe sentence for each input it was refused over. A value of the wrong type, a missing required input and an unknown\nalias are refused before the body runs: the call itself fails with the sentence, and `field_errors` where\nan input is at fault \u2014 within `runs`, a run refused for its inputs answers `status: "error"` in its place,\nand the runs before it stand. A refused read fails the same way, naming the param or the column; within\n`runs`, it answers its `error` and the other reads are still answered.\n\n## Declaring more\n\nWhat the business asks an agent in the app again and again, and no screen draws, is stated in the app\'s tree as Query and Workflow nodes, beside its\nActs: every figure or list whose definition is the business\'s own (open orders, what a customer owes, low stock) and every recurring operation (close the month, send to the accounting service, chase overdue invoices), each with a `description` written for an agent. A question asked once stays on `query_records` with `aggregate`. A Workflow gets an Act only where a person presses it; work only an agent does has no button. Both are checked and compiled when the tree is written (`set_app`; `reference/query-node`, `reference/workflow-node`).\n\n**What the data decides, the system decides.** Whatever follows from the rows and the rules is stated where it holds for every writer, never left to a caller: a fact of one row in its table (`required`, `unique`, `min` and `max`, `options_where`, a check); a value that follows from others as a formula, a lookup or `default_from`; a step of the work in the status\'s `stages` and its Acts (`when`, `requires`); who reads which rows in the table\'s `read_scope` and the app\'s `rows`; what a write sets off in a table\'s workflow; and a decision over many rows or papers (which papers a household\'s facts call for) in a Workflow that computes it and refuses what breaks it, every call the same. A caller\'s inputs are what only it knows: the facts it read, a judgement it made. An override of what the system computes is an optional input, never the way the work is done. A Workflow refuses only what would leave a row invalid or put a false statement on a paper, naming the fact that fixes it; what leaves room for error but is not wrong (a blank printed for handwriting, an unusual choice) it does and reports as a warning in what it returns.\n\n**A query** \u2014 the rows of one table, or one figure of them, in the app\'s own aliases:\n\n```jsonc\n{\n "type": "Query",\n "key": "orders_overdue",\n "description": "A customer\'s orders still open past the day they were due, longest overdue first.",\n "params": {\n "customer": { "type": "record_link", "entity": "customer", "required": false, "description": "Only this customer\'s orders." },\n "as_of": { "type": "date", "description": "The day an order is overdue on: due before it." }\n },\n "rows": "order",\n "fields": ["customer", "item", "due_on", "price"],\n "where": { "status": ["baking"], "customer": { "param": "customer" }, "due_on": { "to": { "param": "as_of" } } },\n "sort": { "field": "due_on" }\n}\n```\n\nIt reads under the app\'s `rows` (every row, where the app states none of the table) and, on the app\'s own table, exactly the rows its list reads \u2014\nso never the table of an app whose List reads `sources`, several tables. A condition reading an\noptional param narrows nothing when the call leaves it out; no param compares a number read in each row\'s\nown unit or currency, or a date holding a span. A Query returns its `fields`; a caller counts, sums or\naverages them with `run_app_query`\'s `aggregate`. A Query, a Workflow and\na Reading\'s `key` take no name the app generates (`reference/app.generated-name`).\n\n**A workflow** \u2014 a write no Act of the record makes, typed in the app\'s tree and its code set on the app:\n\n```jsonc\n{\n "type": "Workflow",\n "key": "import_bookings",\n "description": "Books every order a sheet lists, reusing an order the sheet already booked.",\n "inputs": {\n "sheet": { "type": "file", "description": "The order sheet, one order per row." },\n "booked_by": { "type": "member", "required": false, "description": "Who the orders are taken by; absent, the caller." }\n },\n "outputs": { "added": { "type": "number" }, "reused": { "type": "number" } }\n}\n```\n\n`set_workflow` sets its code (`workflows`). A query the app holds that\nthe tree does not declare is listed by `get_app` as `unstated_queries` and removed by the next write,\nwhose answer notes it; declared as a Query node, it is the tree\'s. A caller sees the description and\neach input\'s `description` and nothing else, so each says what the value is and what leaving it out means;\nthe check notes one that says nothing.\n\n**Shape each for a caller that is not looking at a screen.** One job a person hands an agent \u2014 a paper read,\na message answered, a sheet brought in \u2014 is one declared workflow named for the job, never a chain of the\ngenerated per-row workflows. Take a list where the job covers many rows, a record\'s lines among them. A workflow\'s code\nthat writes more than one row makes them in one `save_record` workflow step, all or nothing, and recognises\nwhat exists by the identity the input itself carries, declared unique on its table, so the same input sent\ntwice updates instead of adding. Return the ids under `outputs`, so the next run can read them. Gate what\ncannot be undone behind an approval step.\n\n## Prove an app as an agent\n\nRun on one of the owner\'s own rows, moved only as far as its stage; a record made for the run takes a number and a stage move nobody asked for.\n\n1. `get_app` \u2014 every job the app\'s `description` names has an alias that does it or reads it.\n2. `run_app_query` the list with no param, then with each param a person would narrow by; `count: true`\n answers how many without the rows.\n3. `run_app_query` `<entity>_record` with one row\'s id, and each `<child>_by_<link>` under it.\n4. `run_app_workflow` an act with `dry_run: true`, then without.\n5. `run_app_workflow` an act its record is not ready for: the answer is `status: "error"` with the sentence\n the screen would show.\n6. `run_app_workflow` the app\'s job workflow with the input a person would hand it \u2014 the paper read, the row:\n it completes in one call. Call it again with the same input: nothing is added.\n';
|
|
1889
1889
|
|
|
1890
1890
|
// AGENTS.md
|
|
1891
|
-
var AGENTS_default = "# @lotics/cli \u2014 agent index\n\nThe model an agent needs before driving this CLI: which surface answers which question, what the\nconventions are, and where the traps are.\n\n| Read | For |\n|---|---|\n| `lotics --help` | The verb inventory (\xA7 COMMANDS) and global flags. The verb LIST is generated and never stale; the prose beside each verb is hand-written, so where it disagrees with `docs/cli_reference.md`, the reference wins. |\n| `lotics tools` \xB7 `lotics tools <name>` | The agent tool registry and one tool's full JSON Schema. |\n| `lotics docs` \xB7 `lotics docs <area>[/<section>]` \xB7 `lotics docs [<area>] --grep <text>` | This CLI's references, carried inside it so each describes the binary answering. Capped at a page: a doc that does not fit hands back its opening and the addresses into it, so the next call is smaller than the last. A page the copy lacks \u2014 one the server added since this binary was built, which a refusal can cite \u2014 is read from the server's `docs` tool with this machine's credential, and so is every `--grep`, over the references the server serves. A custom-code app's SDK reference is `node_modules/@lotics/app-sdk/AGENTS.md` inside the app. |\n| `lotics docs reference` \xB7 `lotics docs reference/<section>` | The keys of a table document and the components of an app tree: a table's fields keyed by alias, how a row of each table is recognised (`records`), and the apps stated over them. Every key, every field type with the config it needs, the rules, and a worked example. |\n| `lotics docs design` \xB7 `lotics docs design/<section>` | Designing an app \u2014 the treatment each kind of row takes with the `reference` page stating its keys, the visual bar, looking at what a write built, and the rubric a build answers. Opens on the visual bar; a finding names its section. |\n| `lotics docs examples` \xB7 `lotics docs examples/<treatment>` | Each treatment worked through in an app of a complete workspace: the job, the props to read, where it is the wrong one, and the excerpt. |\n| [docs/getting_started.md](./docs/getting_started.md) | What a workspace holds, and the one page to open for each job: building a workspace, changing an app, a rule on a table, a document, data and questions, a connected service, sharing. The first page an agent outside the product reads. |\n| [docs/build.md](./docs/build.md) | A workspace or an app built call by call \u2014 tables with a check, the paper, the app, what the owner will ask an agent, the owner's rows, pressing it \u2014 in one worked example, at any time: an app added or changed weeks later starts there too. |\n| [docs/app_architecture.md](./docs/app_architecture.md) | Which apps a business needs, one per main entity, with a worked split; who gets each, and which rows each person reads. |\n| [docs/working_in_a_workspace.md](./docs/working_in_a_workspace.md) | The right means for each job once the apps exist: an app's act for a business operation, a record write for data entry, a query for a figure the business defines, a count for the rest. |\n| [docs/cli_reference.md](./docs/cli_reference.md) | Per-command contracts, flags, exit codes, and gotchas \u2014 the detail `--help` compresses. |\n| [docs/data_model.md](./docs/data_model.md) | Tables, their fields, and how they relate \u2014 one fact per column, one table per kind of thing and the NAME-OVERLAP probe that says when a split has broken, one vocabulary wherever values are copied, a copy boundary that accounts for every source field, provenance as a link, a declared natural key, history as rows, and why derived DEPTH costs more than row count; then the choices around a field's type, and how a field is changed (a list replaces whole, what refuses a deletion, what `force` consents to). Separate from build because every workspace starts with tables and many never get an app. |\n| [docs/filters.md](./docs/filters.md) | The one filter grammar every filter-taking tool, view and rollup reads \u2014 conditions, groups, and the operators per field type. |\n| [docs/field_values.md](./docs/field_values.md) | The value each field type takes in a write. |\n| [docs/workflows.md](./docs/workflows.md) | Writing a workflow body \u2014 triggers, steps, what an expression reads, the helpers, approvals and agent steps, and table checks. |\n| [docs/app_bindings.md](./docs/app_bindings.md) | The queries, workflows and agents an app binds \u2014 the query tree, typed inputs and outputs, and an agent's declaration. |\n| [docs/document_templates.md](./docs/document_templates.md) | Generating PDF/Excel/Word/email from reusable templates, and what a template an app's Act makes is handed. |\n| [docs/knowledge_docs.md](./docs/knowledge_docs.md) | Authoring the procedures, policies and glossary an agent can't guess with `set_knowledge`; who can read a doc; searching and reading it line by line. |\n| [docs/migration.md](./docs/migration.md) | What to DO when something an earlier CLI wrote to disk no longer matches what it does \u2014 local app projects are gone, and each verb that read one has a replacement. |\n| [README.md](./README.md) | Install, auth, and worked examples. |\n\n## Two surfaces, and the trap between them\n\n**`lotics tools` is not the CLI's capability list.** There are two disjoint surfaces:\n\n- **Tools** (`lotics tools`, `lotics run <tool>`) \u2014 the *agent tool registry*: what an agent, workflow,\n or automation may call. Workspace data, templates, knowledge, admin.\n- **Commands** (`lotics --help` \xA7 COMMANDS) \u2014 the CLI's *own verbs*: auth and org/workspace scoping,\n file upload and download, and those that touch a local file for an app \u2014 `app apply`,\n `app create --custom`, `app pull` and `app deploy`.\n\nSeveral capabilities exist **only** as commands and appear nowhere in `lotics tools` \u2014 downloading a\nfile is the one most often mistaken for missing. Concluding \"the platform can't do X\" from the tool\nlist alone is a mistake; check both.\n\n**`lotics <verb> --help` prints that verb's entries from \xA7 COMMANDS** (`lotics app --help`,\n`lotics file download --help`); `lotics report --help` prints the report frame. To find out whether\nsomething exists, read `lotics --help` \xA7 COMMANDS \u2014 the whole section, not a narrow grep.\n\n## Conventions that hold across every command\n\n- **Scope is resolved per invocation.** `LOTICS_ORG` / `LOTICS_WORKSPACE` (or `LOTICS_API_KEY`) scope a\n single call without changing the active org or a directory pin \u2014 the safe way to touch one tenant\n from a shell serving many. Every command that resolves a workspace echoes its target to **stderr**\n (`lotics \u2192 <org> / <workspace>`); read it back before trusting a write. Resolution precedence is\n in README \xA7 Organizations.\n- **A machine with no key can still sign in, and the sign-in never blocks you.** `lotics auth\n login <email>` prints the page a person opens (also mailed) and the code that page must show,\n records the request, and EXITS. They press Confirm whenever they get to it; the next command that\n NEEDS a credential collects the key before doing its own work, so \"sign in\" costs you one command\n and then re-running what you wanted. Never wrap it in a timeout waiting for a human \u2014 `--wait`\n exists if you really want one blocking command, and killing that one is safe too (the request\n survives and the next command claims it). A command run before Confirm exits 1 naming the page and\n code again; once the 15 minutes are up it says to ask again. `lotics auth signup <email>` for an email that\n already has an account creates nothing and names `auth login`.\n- **A credential is either a SIGN-IN or an API KEY, and `logout` treats them differently.** A profile\n from `auth login` / `auth signup` acts as the person who confirmed it and is theirs \u2014 `lotics auth\n logout` revokes it server-side, and it lapses on its own after 90 idle days (each use pushes that\n out). A profile from `auth api-key` holds a key an ADMIN issued. A key created in Settings carries\n its OWN access \u2014 every app and table, or only the ones chosen on the key, so a listing that comes\n back short is the key's reach, not a bug \u2014 while an older key created FOR a person carries that\n person's access and dies with their membership. Either is routinely also on a server and on\n other machines, so logout only forgets it locally and says so; only an admin revokes it. A profile that states no kind (saved before the field existed) is resolved against the SERVER\n and revoked only if the answer is a sign-in; a bare `--api-key` / `LOTICS_API_KEY` names no\n profile to remove at all. Nothing is ever revoked on a guess \u2014 between two, the destructive one is\n wrong. `lotics auth whoami` prints the kind, asking the server when the store cannot say.\n- **A key created in Settings never administers the organization, whatever its access.** The verbs\n `docs/cli_reference.md` reserves to an organization owner or a workspace admin split in two under a key: `workspace doctor`, which only\n reads inside a workspace the key reaches, runs as before, while managing people, sharing or\n ownership, creating or deleting a workspace, changing workspace settings, setting credit limits,\n reading the access log and publishing an app's API answer `403` and name the remedy: an admin signed in, so\n `lotics auth login <email>` and run it again. A sign-in acts as that person and is refused none of\n them. Do not retry a `403` with the same credential and do not ask for a wider key \u2014 no answer on\n the key's own screen grants this.\n- **A 401 names its remedy \u2014 act on the hint, do not retry.** \"This credential expired / was\n revoked / belongs to a member who is no longer active\" carries the one remedy that ends this\n credential: run `lotics auth login <email>` for a sign-in, or ask the admin who issued it for a\n new key. A credential minted before that was recorded carries BOTH, because nothing on the row\n tells them apart \u2014 so on a box with no browser, take the second. Only an UNRECOGNIZED key gets\n the generic \"Invalid or disabled API key\", and that one is generic on purpose, so re-sending it\n teaches nothing. A `reason` rides on the body for a script to branch on, since the code stays\n `unauthorized` for every 401.\n- **Large payloads bypass `ARG_MAX`** \u2014 `lotics run <tool> @args.json`, or piped stdin behind `-`. A leading `@` is\n unambiguously a file path (JSON args start with `{`).\n- **stdout is the payload, stderr is the narration.** Progress, status lines, and the target echo go to\n stderr; the result goes to stdout, so piping stays clean. `--json` switches stdout from the\n agent-readable summary to the full structured object.\n- **Every tool is invoked one way \u2014 `lotics run <tool>`.** Including the ones that RUN something\n (`run_app_workflow`, `run_app_query`) and every one that builds\n (`set_tables`, `set_app`, `set_workflow`). A command\n exists only for work that touches a local file.\n- **Building is two tools, each a writer that creates without an id and edits with one.** `set_tables`\n takes `{ \"tables\": [...] }` \u2014 always a list, one or many, all or nothing \u2014 each table a document keyed\n by alias (fields keyed by alias; a link names its table by id, or by the `ref` of another table of the\n same call, and states `multi`; a two-way link states `pair` on both tables), edited by an RFC 7396\n merge patch of that document, where `null` deletes. A call carries at most 50 tables, 200 first rows a table,\n and 2000 rows and 2000 documents in all. `set_app` takes ONE app: `{ \"body\": <the App tree> }` to create, the app's\n `name`, `description`, `icon` and `color` being props of the App node; `{ \"app_id\": \u2026, \"nodes\": { \"<address>\": <patch> } }`\n to change a node, refused with `base_version_id` when the app has moved past the version you read. `dry_run` checks\n without writing, a refusal lists everything wrong in the call, and every answer states the permissions the write\n granted and removed. The answer shows what the platform drew where the tree is silent (nothing is stored for it) and says what it placed or folded in what the tree states; a placement is stored. A new workspace: one `set_tables` call with\n the tables, then every `set_app` call, then fixes.\n- **Every change to an app mints a version of it, and applying the earlier tree again is the undo.** An apply, a\n deploy, a single `set_app_*`: each is a new version. Applying the earlier tree again restores the app \u2014 never a table change or a row a workflow wrote,\n so try a write on a throwaway record.\n- **Exit codes are assertable, and they report the WORK rather than the call.** `lotics run` exits\n non-zero when a `run_app_workflow` result's own envelope carries a failed\n `status` (`error`/`failed`/`cancelled`, or `not_previewed`: a dry run asked for and not given) \u2014 any other tool's top-level status is data and exits 0 \u2014\n so `lotics run \u2026 && next-step` cannot walk past a refused run; `workspace doctor` exits non-zero on\n findings. An unrecognized status exits 0 \u2014 the list is an allowlist of failure, so a status added\n later never turns a working script red \u2014 and a parked run (`awaiting_input`) is not a failure.\n- **An app that PUBLISHES an API turns every later binding write into a release.** Publishing\n snapshots what the app's queries, workflows and agents promise to callers outside it \u2014 a\n customer's own site or server, which nobody here can redeploy. From then on an additive change\n re-snapshots silently and a breaking one is REFUSED, naming each change; the tool's\n `acknowledge_breaking_api_change` carries it out and snapshots the break as a new contract version.\n- **Exposure is per app, all or nothing** \u2014 a public share or a key reaches every alias an app\n declares, so what outsiders may call is a second app over the same tables\n ([docs/app_architecture.md](./docs/app_architecture.md)).\n- **`--print-created` / `--cleanup` on any call that reports `side_effects`.** The first prints the\n records created plus a paste-ready cleanup plan and what cannot be auto-undone; the second runs\n those deletes (records only \u2014 never files, integrations or notifications). Neither is a rollback.\n- **Text output is the default and is built for reading**; reach for `--json` only when a field is\n needed programmatically.\n- **`lotics report '<json>'` is the channel for what nothing else records.** Reach for it\n when the platform is genuinely missing something (a capability that does not exist \u2014 no\n command ran), when a success was wrong (exited 0, wrong effect), or when an error did\n not name the remedy \u2014 not for your own mistakes, which the logs already show.\n **It is a frame, not a paragraph** \u2014 `{goal, actual, expected?, tried?, wanted?}`, because a log\n reconstructs what you RAN and never what you WANTED, and that gap is the report. `goal` and\n `actual` are required; there is no severity or category to pick. The\n session's commands attach themselves \u2014 do not retype them. Run it bare for the full prompt; a\n long one rides `@file.json` or an explicit `-` for stdin (bare NEVER reads stdin).\n- **`LOTICS_TELEMETRY=1` correlates a whole session** so the authoring loop's rough edges can be\n found and fixed. Off by default; set it in the shell profile, not per command (each invocation is\n its own process). It sends no arguments, no file contents, and no record data \u2014 see README\n \xA7 Diagnostics.\n\n## Where this CLI is not the answer\n\n- **Editing an app in a local directory.** An app stated as a tree is changed by applying the\n tree again; its bindings through their `set_app_*` tools; a custom-code app's code by deploying\n its directory again. Nothing reads a local copy of a live app back.\n- **OAuth connections.** Attaching a connected account is web-only; the CLI can list them.\n";
|
|
1891
|
+
var AGENTS_default = "# @lotics/cli \u2014 agent index\n\nThe model an agent needs before driving this CLI: which surface answers which question, what the\nconventions are, and where the traps are.\n\n| Read | For |\n|---|---|\n| `lotics --help` | The verb inventory (\xA7 COMMANDS) and global flags. The verb LIST is generated and never stale; the prose beside each verb is hand-written, so where it disagrees with `docs/cli_reference.md`, the reference wins. |\n| `lotics tools` \xB7 `lotics tools <name>` | The agent tool registry and one tool's full JSON Schema. |\n| `lotics docs` \xB7 `lotics docs <area>[/<section>]` \xB7 `lotics docs [<area>] --grep <text>` | This CLI's references, carried inside it so each describes the binary answering. Capped at a page: a doc that does not fit hands back its opening and the addresses into it, so the next call is smaller than the last. A page the copy lacks \u2014 one the server added since this binary was built, which a refusal can cite \u2014 is read from the server's `docs` tool with this machine's credential, and so is every `--grep`, over the references the server serves. A custom-code app's SDK reference is `node_modules/@lotics/app-sdk/AGENTS.md` inside the app. |\n| `lotics docs reference` \xB7 `lotics docs reference/<section>` | The keys of a table document and the components of an app tree: a table's fields keyed by alias, how a row of each table is recognised (`records`), and the apps stated over them. Every key, every field type with the config it needs, the rules, and a worked example. |\n| `lotics docs design` \xB7 `lotics docs design/<section>` | Designing an app \u2014 the treatment each kind of row takes with the `reference` page stating its keys, the visual bar, looking at what a write built, and the rubric a build answers. Opens on the visual bar; a finding names its section. |\n| `lotics docs examples` \xB7 `lotics docs examples/<treatment>` | Each treatment worked through in an app of a complete workspace: the job, the props to read, where it is the wrong one, and the excerpt. |\n| [docs/getting_started.md](./docs/getting_started.md) | What a workspace holds, and the one page to open for each job: building a workspace, changing an app, a rule on a table, a document, data and questions, a connected service, sharing. The first page an agent outside the product reads. |\n| [docs/build.md](./docs/build.md) | A workspace or an app built call by call \u2014 tables with a check, the paper, the app, what the owner will ask an agent, the owner's rows, pressing it \u2014 in one worked example, at any time: an app added or changed weeks later starts there too. |\n| [docs/app_architecture.md](./docs/app_architecture.md) | Which apps a business needs, one per main entity, with a worked split; who gets each, and which rows each person reads. |\n| [docs/working_in_a_workspace.md](./docs/working_in_a_workspace.md) | The right means for each job once the apps exist: an app's act for a business operation, a record write for data entry, a query for a figure the business defines, a count for the rest. |\n| [docs/cli_reference.md](./docs/cli_reference.md) | Per-command contracts, flags, exit codes, and gotchas \u2014 the detail `--help` compresses. |\n| [docs/data_model.md](./docs/data_model.md) | Tables, their fields, and how they relate \u2014 one fact per column, one table per kind of thing and the NAME-OVERLAP probe that says when a split has broken, one vocabulary wherever values are copied, a copy boundary that accounts for every source field, provenance as a link, a declared natural key, history as rows, and why derived DEPTH costs more than row count; then the choices around a field's type, and how a field is changed (a list replaces whole, what refuses a deletion, what `force` consents to). Separate from build because every workspace starts with tables and many never get an app. |\n| [docs/filters.md](./docs/filters.md) | The one filter grammar every filter-taking tool, view and rollup reads \u2014 conditions, groups, and the operators per field type. |\n| [docs/field_values.md](./docs/field_values.md) | The value each field type takes in a write. |\n| [docs/workflows.md](./docs/workflows.md) | Writing a workflow body \u2014 triggers, steps, what an expression reads, the helpers, approvals and agent steps, and table checks. |\n| [docs/app_bindings.md](./docs/app_bindings.md) | The queries, workflows and agents an app binds \u2014 the query tree, typed inputs and outputs, and an agent's declaration. |\n| [docs/document_templates.md](./docs/document_templates.md) | Generating PDF/Excel/Word/email from reusable templates, and what a template an app's Act makes is handed. |\n| [docs/knowledge_docs.md](./docs/knowledge_docs.md) | Authoring the procedures, policies and glossary an agent can't guess with `set_knowledge`; who can read a doc; searching and reading it line by line. |\n| [docs/migration.md](./docs/migration.md) | What to DO when something an earlier CLI wrote to disk no longer matches what it does \u2014 local app projects are gone, and each verb that read one has a replacement. |\n| [README.md](./README.md) | Install, auth, and worked examples. |\n\n## Two surfaces, and the trap between them\n\n**`lotics tools` is not the CLI's capability list.** There are two disjoint surfaces:\n\n- **Tools** (`lotics tools`, `lotics run <tool>`) \u2014 the *agent tool registry*: what an agent, workflow,\n or automation may call. Workspace data, templates, knowledge, admin.\n- **Commands** (`lotics --help` \xA7 COMMANDS) \u2014 the CLI's *own verbs*: auth and org/workspace scoping,\n file upload and download, and those that touch a local file for an app \u2014 `app apply`,\n `app create --custom`, `app pull` and `app deploy`.\n\nSeveral capabilities exist **only** as commands and appear nowhere in `lotics tools` \u2014 downloading a\nfile is the one most often mistaken for missing. Concluding \"the platform can't do X\" from the tool\nlist alone is a mistake; check both.\n\n**`lotics <verb> --help` prints that verb's entries from \xA7 COMMANDS** (`lotics app --help`,\n`lotics file download --help`); `lotics report --help` prints the report frame. To find out whether\nsomething exists, read `lotics --help` \xA7 COMMANDS \u2014 the whole section, not a narrow grep.\n\n## Conventions that hold across every command\n\n- **Scope is resolved per invocation.** `LOTICS_ORG` / `LOTICS_WORKSPACE` (or `LOTICS_API_KEY`) scope a\n single call without changing the active org or a directory pin \u2014 the safe way to touch one tenant\n from a shell serving many. Every command that resolves a workspace echoes its target to **stderr**\n (`lotics \u2192 <org> / <workspace>`); read it back before trusting a write. Resolution precedence is\n in README \xA7 Organizations.\n- **A machine with no key can still sign in, and the sign-in never blocks you.** `lotics auth\n login` takes no argument and sends no mail: it prints the page a person opens and the code that page must show,\n records the request, and EXITS. They press Confirm whenever they get to it; the next command that\n NEEDS a credential collects the key before doing its own work, so \"sign in\" costs you one command\n and then re-running what you wanted. Never wrap it in a timeout waiting for a human \u2014 `--wait`\n exists if you really want one blocking command, and killing that one is safe too (the request\n survives and the next command claims it). A command run before Confirm exits 1 naming the page and\n code again; once the 15 minutes are up it says to ask again. `lotics auth signup <email>` for an email that\n already has an account creates nothing and names `auth login`.\n- **A credential is either a SIGN-IN or an API KEY, and `logout` treats them differently.** A profile\n from `auth login` / `auth signup` acts as the person who confirmed it and is theirs \u2014 `lotics auth\n logout` revokes it server-side, and it lapses on its own after 90 idle days (each use pushes that\n out). A profile from `auth api-key` holds a key an ADMIN issued. A key created in Settings carries\n its OWN access \u2014 every app and table, or only the ones chosen on the key, so a listing that comes\n back short is the key's reach, not a bug \u2014 while an older key created FOR a person carries that\n person's access and dies with their membership. Either is routinely also on a server and on\n other machines, so logout only forgets it locally and says so; only an admin revokes it. A profile that states no kind (saved before the field existed) is resolved against the SERVER\n and revoked only if the answer is a sign-in; a bare `--api-key` / `LOTICS_API_KEY` names no\n profile to remove at all. Nothing is ever revoked on a guess \u2014 between two, the destructive one is\n wrong. `lotics auth whoami` prints the kind, asking the server when the store cannot say.\n- **A key created in Settings never administers the organization, whatever its access.** The verbs\n `docs/cli_reference.md` reserves to an organization owner or a workspace admin split in two under a key: `workspace doctor`, which only\n reads inside a workspace the key reaches, runs as before, while managing people, sharing or\n ownership, creating or deleting a workspace, changing workspace settings, setting credit limits,\n reading the access log and publishing an app's API answer `403` and name the remedy: an admin signed in, so\n `lotics auth login` and run it again. A sign-in acts as that person and is refused none of\n them. Do not retry a `403` with the same credential and do not ask for a wider key \u2014 no answer on\n the key's own screen grants this.\n- **A 401 names its remedy \u2014 act on the hint, do not retry.** \"This credential expired / was\n revoked / belongs to a member who is no longer active\" carries the one remedy that ends this\n credential: run `lotics auth login` for a sign-in, or ask the admin who issued it for a\n new key. A credential minted before that was recorded carries BOTH, because nothing on the row\n tells them apart \u2014 so on a box with no browser, take the second. Only an UNRECOGNIZED key gets\n the generic \"Invalid or disabled API key\", and that one is generic on purpose, so re-sending it\n teaches nothing. A `reason` rides on the body for a script to branch on, since the code stays\n `unauthorized` for every 401.\n- **Large payloads bypass `ARG_MAX`** \u2014 `lotics run <tool> @args.json`, or piped stdin behind `-`. A leading `@` is\n unambiguously a file path (JSON args start with `{`).\n- **stdout is the payload, stderr is the narration.** Progress, status lines, and the target echo go to\n stderr; the result goes to stdout, so piping stays clean. `--json` switches stdout from the\n agent-readable summary to the full structured object.\n- **Every tool is invoked one way \u2014 `lotics run <tool>`.** Including the ones that RUN something\n (`run_app_workflow`, `run_app_query`) and every one that builds\n (`set_tables`, `set_app`, `set_workflow`). A command\n exists only for work that touches a local file.\n- **Building is two tools, each a writer that creates without an id and edits with one.** `set_tables`\n takes `{ \"tables\": [...] }` \u2014 always a list, one or many, all or nothing \u2014 each table a document keyed\n by alias (fields keyed by alias; a link names its table by id, or by the `ref` of another table of the\n same call, and states `multi`; a two-way link states `pair` on both tables), edited by an RFC 7396\n merge patch of that document, where `null` deletes. A call carries at most 50 tables, 200 first rows a table,\n and 2000 rows and 2000 documents in all. `set_app` takes ONE app: `{ \"body\": <the App tree> }` to create, the app's\n `name`, `description`, `icon` and `color` being props of the App node; `{ \"app_id\": \u2026, \"nodes\": { \"<address>\": <patch> } }`\n to change a node, refused with `base_version_id` when the app has moved past the version you read. `dry_run` checks\n without writing, a refusal lists everything wrong in the call, and every answer states the permissions the write\n granted and removed. The answer shows what the platform drew where the tree is silent (nothing is stored for it) and says what it placed or folded in what the tree states; a placement is stored. A new workspace: one `set_tables` call with\n the tables, then every `set_app` call, then fixes.\n- **Every change to an app mints a version of it, and applying the earlier tree again is the undo.** An apply, a\n deploy, a single `set_app_*`: each is a new version. Applying the earlier tree again restores the app \u2014 never a table change or a row a workflow wrote,\n so try a write on a throwaway record.\n- **Exit codes are assertable, and they report the WORK rather than the call.** `lotics run` exits\n non-zero when a `run_app_workflow` result's own envelope carries a failed\n `status` (`error`/`failed`/`cancelled`, or `not_previewed`: a dry run asked for and not given) \u2014 any other tool's top-level status is data and exits 0 \u2014\n so `lotics run \u2026 && next-step` cannot walk past a refused run; `workspace doctor` exits non-zero on\n findings. An unrecognized status exits 0 \u2014 the list is an allowlist of failure, so a status added\n later never turns a working script red \u2014 and a parked run (`awaiting_input`) is not a failure.\n- **An app that PUBLISHES an API turns every later binding write into a release.** Publishing\n snapshots what the app's queries, workflows and agents promise to callers outside it \u2014 a\n customer's own site or server, which nobody here can redeploy. From then on an additive change\n re-snapshots silently and a breaking one is REFUSED, naming each change; the tool's\n `acknowledge_breaking_api_change` carries it out and snapshots the break as a new contract version.\n- **Exposure is per app, all or nothing** \u2014 a public share or a key reaches every alias an app\n declares, so what outsiders may call is a second app over the same tables\n ([docs/app_architecture.md](./docs/app_architecture.md)).\n- **`--print-created` / `--cleanup` on any call that reports `side_effects`.** The first prints the\n records created plus a paste-ready cleanup plan and what cannot be auto-undone; the second runs\n those deletes (records only \u2014 never files, integrations or notifications). Neither is a rollback.\n- **Text output is the default and is built for reading**; reach for `--json` only when a field is\n needed programmatically.\n- **`lotics report '<json>'` is the channel for what nothing else records.** Reach for it\n when the platform is genuinely missing something (a capability that does not exist \u2014 no\n command ran), when a success was wrong (exited 0, wrong effect), or when an error did\n not name the remedy \u2014 not for your own mistakes, which the logs already show.\n **It is a frame, not a paragraph** \u2014 `{goal, actual, expected?, tried?, wanted?}`, because a log\n reconstructs what you RAN and never what you WANTED, and that gap is the report. `goal` and\n `actual` are required; there is no severity or category to pick. The\n session's commands attach themselves \u2014 do not retype them. Run it bare for the full prompt; a\n long one rides `@file.json` or an explicit `-` for stdin (bare NEVER reads stdin).\n- **`LOTICS_TELEMETRY=1` correlates a whole session** so the authoring loop's rough edges can be\n found and fixed. Off by default; set it in the shell profile, not per command (each invocation is\n its own process). It sends no arguments, no file contents, and no record data \u2014 see README\n \xA7 Diagnostics.\n\n## Where this CLI is not the answer\n\n- **Editing an app in a local directory.** An app stated as a tree is changed by applying the\n tree again; its bindings through their `set_app_*` tools; a custom-code app's code by deploying\n its directory again. Nothing reads a local copy of a live app back.\n- **OAuth connections.** Attaching a connected account is web-only; the CLI can list them.\n";
|
|
1892
1892
|
|
|
1893
1893
|
// docs/cli_reference.md
|
|
1894
|
-
var cli_reference_default = "# @lotics/cli \u2014 CLI Command Reference\n\nPer-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. Start at [AGENTS.md](../AGENTS.md) for the model this reference assumes; `lotics --help` is the authoritative, always-current verb list.\n\n| Command | What it does |\n|---|---|\n| `lotics` / `lotics --help` | Show full help: capabilities, the verb list (\xA7 COMMANDS), flags, config. `lotics <verb> --help` prints that verb's entries alone (`lotics app --help`, `lotics file download --help`); `lotics report --help` prints the report frame. |\n| `lotics auth signup <email>` | Create account + org + API key, sends magic link email. Refused on a private instance, whose people arrive by invitation; prints that creating the account accepts the Terms and Privacy Policy. Registers the new org as a profile; `--local` pins this directory to it (pointer) instead of setting the global default. |\n| `lotics auth login <email>` | Sign in an account that already exists, on a machine holding no key. **Two steps, and it does not wait for the person.** The first prints the page to open \u2014 `https://lotics.ai/cli_login/<request_id>`, also mailed \u2014 and the code that page must show, records the request, and exits 0. They sign in there if asked, check the code and press Confirm. **Then the next command that needs a credential collects the key** before it does its own work, so the second step is just re-running whatever was wanted; a command run before Confirm exits 1 naming the page and the code again, and once the 15 minutes are up it says to ask again. The handful that run WITHOUT a credential \u2014 `docs` among them \u2014 claim nothing, so one of those run after Confirm still answers as though signed out. `--wait` keeps one command instead, holding the terminal until Confirm; `--local` pins this directory to that org rather than setting the global default, and implies `--wait` (a pin names THIS directory, so only the terminal that stays in it can write one). `--json` prints `organization_id`, `workspace_id` and `organization_name` when it finishes signed in, and `request_id`, `confirm_url`, `code`, `email`, `expires_at` when it is the first step. The request's secret is never printed and the org's key never leaves the store. |\n| \u2014 | **A flag is refused on a verb that does not read it**, naming the verbs that do, before any request or credential: `--check` on `lotics run` would otherwise be parsed and ignored, and the write it was meant to stop would run. `--json`, `--workspace`, `--api-key` and `--timeout` are read by every verb. |\n| \u2014 | **Every call a verb makes waits for the server's answer**; `--timeout <ms>` (a whole number of milliseconds from 1 to 2147483647) stops each wait early. The wait ends without an answer when `--timeout` passes or no answer arrives from the server. A read with no answer changed nothing: the command exits non-zero naming the request id. A write with no answer exits non-zero with `error_code: \"outcome_unknown\"` and the request id under `--json`, because it cannot say whether the call took effect: read before running it again. The one fetch outside this is the download from an object-storage signed URL, which carries no request id and is stopped by `--timeout` alone. Under `--json` every error is one object on stdout: `error`, with `error_code` and `request_id` where the error has them. |\n| `lotics auth api-key [key]` | `whoami` \u2192 **upsert** the key's org as a profile in the global store (never overwrites). The profile records the instance the key was verified against (`LOTICS_API_URL`, default `https://api.lotics.ai`), and every later command for that org goes there. `--local` additionally pins this directory to it (pointer) instead of setting the global default. |\n| `lotics auth web` | Send a magic link email to access the web app (requires auth) |\n| `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 \u2014 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`. |\n| `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 \u2014 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 \u2192 Security \u2192 *Keys and terminals*. An **API key** (`auth api-key`) is only forgotten here \u2014 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 \u2192 API keys is admin-only and the credential may well be the holder's own sign-in, which they revoke themselves at Settings \u2192 Security \u2192 *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. |\n| \u2014 | **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.` carries `Run \\`lotics auth login <email>\\` to sign in again.` for a sign-in and `Ask an admin for a new API key (Settings \u2192 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 \u2014 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.` \u2014 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. |\n| `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). |\n| `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 \u2014 a read, a write, and a local check that needs no credential alike \u2014 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 \u2014 a server-side rename never moves it, and the new name resolves too, so both keep working and `lotics org` prints the pair. |\n| `lotics org use <name\\|id> [--local]` | Switch the active org by org name (case-insensitive, ambiguous \u2192 error) or id. No flag \u2192 global `active_org`; `--local` \u2192 a `.lotics/config.json` pointer in the current dir. |\n| `lotics workspace` | List workspaces in the active org, marks current with `(current)` |\n| `lotics workspace select <id>` | Set the workspace in the **active scope** \u2014 a local pin if the dir has one, else the active org's global profile. Records the workspace's NAME beside its id, which is what the `lotics \u2192 <org> / <workspace>` echo prints; `workspace list`, `workspace create`, `workspace rename` and `org use` record it too, so a target is named rather than identified. Until one command has listed it, the echo prints the id and says the name is not known yet. |\n| `lotics workspace create <name> [--timezone <Area/City>] [--currency <ISO>]` | Create a new workspace (organization owner only), auto-switches to it. Neither flag is defaulted from THIS machine, unlike signup: an extra workspace is routinely created by an operator for somebody else. Without `--timezone` the new workspace inherits the zone of the org's OLDEST workspace; without `--currency` it takes the org's default. Both ride the create, so the workspace is never briefly denominated in a currency nobody asked for. `--currency` takes an ISO-4217 code (case-insensitive; anything else is refused). |\n| `lotics workspace rename <name>` | Rename the **current** workspace (an admin of that workspace only) \u2014 the endpoint takes its target from the request's workspace, never a path id, so switch with `workspace select <id>` first and read the `lotics \u2192 <org> / <workspace>` echo before trusting it \u2014 both halves are names, and the rename moves the cached one in the same act. Carries the workspace's existing `default_currency` and `timezone` through unchanged: the endpoint takes the whole settings triple, so sending only a name would blank the other two. |\n| `lotics workspace settings [--name <n>] [--currency <ISO>] [--timezone <Area/City>]` | Change the CURRENT workspace's name, default currency or timezone \u2014 `PATCH /v1/workspace`, an admin of that workspace only. Only what you name changes; the endpoint takes the whole triple, so the CLI carries the two you did not. `rename` is this verb with the name alone, which is why it can never forget the other two. Both values are invisible once they are wrong: the currency decides how every money field RENDERS and the zone decides how every date BUCKETS, on a workspace whose whole purpose may be to look like the customer's own. `--json` prints the updated workspace. |\n| `lotics workspace delete <id> --yes` | Delete a workspace by id (organization owner only). **Soft delete** \u2014 `archived_at` is set, so it drops out of listings, can no longer be selected, and its tables/records go dark, while the data is retained and recoverable. Its **apps are cascade-archived** too \u2014 every app entry point (embedded, public link, standalone subdomain, incl. anonymous public links) stops serving. Refuses the org's **only** active workspace (400) and any workspace outside the caller's org (404). Requires `--yes` to confirm (destructive; the CLI is used non-interactively). |\n| `lotics workspace doctor` | An admin of that workspace only. Report workspace-wide dangling schema references via `GET /v1/workspaces/dangling-references` \u2014 every active app/workflow artifact whose prefixed schema id no longer resolves, printed as `<referent.kind> \"<name>\" (<id>) \u2192 <namespace> <id> (missing)`; healthy prints a one-line all-clear. **Exits non-zero (exit 1) on findings** so scripts can gate on it. Resolves the first workspace like every data command (runs before the global workspace resolution). Admin-only. |\n| `lotics tools` | List tools by category with descriptions |\n| `lotics tools <name>` | Full description, input JSON Schema, and the output schema where the tool answers a shape, for one tool; a workflow step says to call it from a workflow body, not `lotics run` |\n| `lotics run <tool> '<json>'` | Execute a tool (text output via toModelOutput). Args may also come from a file (`lotics run <tool> @args.json`) or stdin behind the `-` sentinel (`cat args.json \\| lotics run <tool> -`) \u2014 both bypass the OS `ARG_MAX` limit for large payloads (a knowledge-doc `content`, a bulk update). A leading `@` on the args is unambiguously a file path (JSON args start with `{`). **Stdin is asked for, never guessed.** `lotics run <tool>` with no payload runs the tool with no arguments and returns at once. `lotics report` takes the same sentinel. In PowerShell use `@file`: quotes inside an inline argument are consumed by the shell, and the CLI reports the JSON it received with its quotes gone \u2014 the error names both escapes. |\n| `lotics run <tool> --json '<json>'` | Execute a tool (full JSON output) |\n| `lotics run <tool>` \u2014 **file cells** | A file in a tool's result carries its `fil_\u2026` id and metadata and **no `url`**, on every tool and in both output modes. That is not a broken file \u2014 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. |\n| \u2014 | **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`. |\n| \u2014 | **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` \u2014 up to 20 reads in one call, each `{\"alias\", \u2026}`, a refused one answered with its `error`; one call's rows total at most 262,144 bytes. `export: {\"key\", \u2026narrowing}` 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` \u2014 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\"` \u2014 and `runs` \u2014 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. |\n| \u2014 | **The exit code reports the WORK, not just the call \u2014 for the tool that RUNS one.** `run_app_workflow` whose envelope carries a failed `status` (`error`/`failed`/`cancelled`, or `not_previewed` \u2014 a dry run asked for and not given) exit non-zero and print `<tool> \u2192 <status>: <message>` to stderr, so `lotics run \u2026 && next-step` cannot walk past a refused run. The rule is an allowlist of FAILURE \u2014 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. |\n| `lotics run <tool> '<json>' -o <dir>` | Also save every **signed link** the answer carries \u2014 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`. |\n| `lotics run set_members '{\"members\": {\"<email or member id>\": {\"role\": \"member\", \"name\": \"\u2026\"}}}'` | 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 \u2192 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. |\n| `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. |\n| `lotics run <tool> --cleanup` | Implies `--print-created`, then runs those deletes \u2014 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. |\n| `lotics file upload <file\\|dir...>` (alias `lotics upload`) \xB7 `--stdin` \xB7 `--base64` \xB7 `--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 \u2014 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** \u2014 an attachment decoded in memory, a generated document, a signed download link \u2014 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 \u2014 `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. |\n| `lotics file download <file_id> [<path>]` \xB7 `-o <dir>` | (alias `lotics download`) Download a stored file: `GET /v1/files/{id}/signed_url` \u2192 fetch the presigned URL and write it where you asked. **The two spellings mean two different things, and neither is read by shape: the positional `<path>` is the FILE to write, `-o <dir>` is the DIRECTORY to save into.** That is `cp` and `curl -o`, so nothing here consults an extension. A named file is written as named, its parent created, overwriting what is there \u2014 the point of naming it is that the next command opens that exact path. A directory is created if missing and written into under the stored filename (the response's `Content-Disposition`), taking a free spelling beside a file of that name already there so a repeat download never clobbers the first; with no destination at all, that filename lands in cwd. Give the destination once \u2014 a positional and `-o` together is refused, as is a positional that names an existing directory or ends in a separator (`a directory goes in -o`). The first argument is a **file id**, so a path in that slot is refused rather than sent as an id. The written path goes to **stdout** (under `--json`, `{file_id, path, filename, stored_filename}`) and the narration to stderr, so a download pipes into whatever opens it. `lotics file download record <record_id> <field_alias> [-o <dir>]` (the field named by the alias `query_records` shows it under) spreads every file on a record's file field over a DIRECTORY \u2014 there is no single file for N files to be. |\n| `lotics file list [--limit <n>] [--cursor <token>]` | The workspace's files, newest first \u2014 id, upload time, bytes, MIME type, filename on stdout, one per line (`--json` for the object). `GET /v1/files` with no `file_ids`. A file holding the content of a knowledge doc or template you cannot use is left out. **A page, not a dump**: the store only ever grows, so the last line prints the command for the next page and `next_cursor` is null on the last one. The cursor is opaque and keyset \u2014 pass it back as given \u2014 so an upload landing mid-sweep cannot make a walk skip or repeat a row. Every other file verb takes an id, so this is the only answer to \"what is in here\" short of reading Postgres. |\n| `lotics knowledge list [--include-hidden \\| --deleted]` | `GET /v1/knowledge_docs` \u2014 a table of id, name, tags, description (`--json` for the docs). **REST, not `get_workspace` kind `knowledge`**: the tool answers what the ASSISTANT may browse, and a hidden doc is out of that corpus by definition, so a tool-backed listing could never show one and the person who hid it would have no way back to it. Hidden docs are left out unless `--include-hidden` asks; those rows are marked `(hidden)`. **`--deleted` is the one tool-backed form**: it calls `get_workspace` with `kind: \"knowledge\"` and `include_archived: true`, page by page, and prints the deleted docs you can manage (id, name, deleted time, description); it cannot be combined with `--include-hidden`. |\n| `lotics knowledge create --name <n> [--description <d>] [--tags <a,b>] (--from <file.md> \\| --content <str>)` | Read the body client-side (a file XOR an inline string \u2014 exactly one required), then call `set_knowledge` with `{ name, description, content, tags? }` and no `knowledge_doc_id`, which makes a doc (description defaults to `\"\"`). `--tags` files the doc as it is made, which is the only moment a corpus reliably gets labelled. Prints the new id to stdout. Large files ride the POST body fine. |\n| `lotics knowledge get <id> [-o <file.md>]` | `GET /v1/knowledge_docs/{id}` (`getKnowledgeDoc`) \u2192 the doc with its **hydrated `content`** (the one whole-content read for a non-sandbox client; the tool `read_knowledge` reads a line range). `-o` writes the body via `writeFileAtomic`; else the body goes to stdout. `--json` prints the full doc instead. |\n| `lotics knowledge update <id> [--from <file.md> \\| --content <str>] [--name <n>] [--description <d>] [--tags <a,b>]` | Call `set_knowledge` with a `knowledge_doc_id` and **only** the provided fields (a body from --from/--content becomes `content`; the tool diffs + CASes the content change internally, so the CLI passes no `expected_content_file_id`). `--tags` REPLACES the doc's label set \u2014 the single-doc form, where the caller is looking at one doc and can state what it should carry. At least one field required; --from and --content are mutually exclusive. |\n| `lotics knowledge tag <id...> [--add <a,b>] [--remove <c,d>]` | `PATCH /v1/knowledge_docs` with `{ knowledge_doc_ids, add_tags?, remove_tags? }` \u2014 one transaction over the whole set. A **DIFF applied to each doc's own labels**, never a replacement: the docs named on one command line carry different labels, so one array across them would strip whatever the others were filed under. Removal matches case-insensitively; adding a label a doc already carries writes nothing. Ids may be separate arguments or comma-separated. At least one of --add/--remove required. |\n| `lotics knowledge hide <id...>` / `lotics knowledge unhide <id...>` | `PATCH /v1/knowledge_docs` with `{ knowledge_doc_ids, hidden }`. Hiding takes docs out of every **listing** \u2014 the Library's list, and the corpus `get_workspace` lists and its `search` searches \u2014 while leaving IAM untouched and keeping them readable **by id** (`read_knowledge` with an id, a code run staging one, an app agent's declared set). So it can never silently break an app that depends on a doc, and unhiding costs nothing. Refuses the no-argument form rather than reading it as \"everything\". |\n| `lotics knowledge rm <id...>` | Delete docs via `set_knowledge` (`{ knowledge_doc_id, delete: true }`), one call per id: each must be a live doc you manage that no app or workflow names, and the command reports which succeeded and which failed. Sharing and history are kept. The REST execute path does not gate `needsApproval`, so this runs unattended. |\n| `lotics knowledge restore <id...>` | Bring deleted docs back via `set_knowledge` (`{ knowledge_doc_id, restore: true }`), one call per id: each must be a deleted doc you manage, and the command reports which succeeded and which failed. Refuses the no-argument form. |\n| `lotics app create <name> --custom [path]` | **A custom-code app**: creates the app (`POST /v1/apps`) and links `[path]` (default `./<name>`, made when absent) to it by writing `package.json#lotics` (the app and its workspace, which is how `app deploy` in that directory finds both) \u2014 into the project's own `package.json` when it has one, every other key kept, otherwise a `package.json` holding the link alone. Nothing else is written and nothing is installed: the project is yours. `app deploy` needs `@lotics/app-sdk` (React 19) and an `npm run build` that writes a static `dist/` with an `index.html`. A directory already linked to an app is refused before the app row exists. The app has no version until the first `lotics app deploy`. `--custom` is required: a JSON app is made by `lotics app apply` (the tool `set_app`). The SDK's reference is `node_modules/@lotics/app-sdk/AGENTS.md` once the project installs it. |\n| `lotics app pull [app_id] [path]` | **An app's live definition, pulled.** The app is read with `get_app`: its author is shown a body, a JSON **tree** (with the addresses of its nodes) pulled as that tree and a custom-code app (its identity and Query nodes) as its source; an app whose stored tree does not read in this release is pulled as it is stored, with a warning giving the reason `get_app` gives (where the stored value is not a JSON object, nothing is pulled and the reason is the error); an app that shows the caller no body (the caller does not author it, or it has no version) is refused. **A JSON app**: the tree is written as JSON to `[path]` (a directory receives `./<name>.app.json`; default `./<name>.app.json`), and the app's id and current version beside it in `<file>.lotics.json` (`{ \"app_id\": \"\u2026\", \"version_id\": \"\u2026\", \"digest\": \"\u2026\" }`, the digest being the file as the CLI last left it; a record without all three is refused by `app apply`, naming `lotics app pull`) \u2014 a custom-code project records both in `package.json#lotics`, a single file has no such place \u2014 so the next `lotics app apply <file>` edits that app, and is refused if the app has since moved past that version. An existing file is overwritten only when its `.lotics.json` names this same app and the file is unchanged since it was last pulled or applied; a file with edits, or whose record names the app but no digest, is refused, naming `--force`, which overwrites it. `--force` is a flag of `app pull` alone. `--json` prints `{workspace_id, app_id, path, outcome}`. **A custom-code app**: its live source, as a project ready to deploy on it. The target is `[path]`, else this directory when it is the app's project (or no app is named), else `./<name>`. **The app's own project is brought up to date in place** \u2014 but only when it holds no edit since the version `package.json#lotics.current_version_id` names: its source (packed as a deploy packs it) is compared with that version's archive, ignoring `.lotics/` and `package.json#lotics`, and any difference refuses the pull, naming the changed files; a pull never merges, so local work is never lost. Already at the live version is a no-op that says so. **An empty or new directory receives the source whole**; any other directory is refused. Downloads come from `GET /v1/apps/{id}/versions/{version_id}/source`. `package.json#lotics` is then set to exactly the app, its workspace and the pulled version, dropping every other key an older CLI wrote there, so the next `lotics app deploy` builds on the live version; then `.lotics/` is written (`GET /v1/apps/{id}/types`) and dependencies installed (`npm ci` with a lockfile, else `npm install`, both `--ignore-scripts`). |\n| `lotics app apply <file> [--app <app_id>] [--check] [--json]` | **A JSON app, one at a time, through the tool `set_app`.** The file is an app's tree (`lotics docs reference`: the App node with the nodes under it, its tables and templates named by alias). **No app known** (no `--app`, no `<file>.lotics.json` beside it): the file is sent as `{ \"body\": \u2026 }` to make a new app, named by the body's `name`, and the id made is printed, then recorded with its version in `<file>.lotics.json`. **An app known**: its current tree is read (`get_app`) and the **RFC 7396 merge patch** that turns it into the file is sent as `body` with the `app_id` and the version the patch was computed against as `base_version_id` \u2014 a key the file drops is `null` in the patch, a list is replaced whole, what the file leaves alone is left alone, and a tree the app already has sends nothing and says so. **A file pulled at a version the app has since left is refused** where the stored tree changed since the pull (a version that moved only for a workflow's body applies) before anything is sent, naming both versions and `lotics app pull <app_id> <path>`: pull the current tree into another path, carry the edits over, apply that file. `--app` naming an app other than the sibling file's is refused too. A write that races the apply is refused by the server, which names the app's current version. A file that sets an object key to `null` is refused naming the key, since a merge patch reads `null` as a removal. `--app` names the app, else the sibling file does; an app whose `get_app` shows no body (it is not yours) is refused, **over a stored tree that does not read in this release the file is sent whole** (`set_app` with `app_id`, the file as `body` and the version read as `base_version_id`; no merge patch is computed against a tree that does not read) where it states `\"type\": \"App\"`, and any other file is refused, naming that only a whole tree replaces it; a custom-code app takes its identity (name, description, icon, colour) and, where the file states `children`, its Query nodes, which replace every query it holds; a file stating none leaves its queries alone and no `<file>.lotics.json` records it, since an identity write makes no version \u2014 its source deploys with `app deploy`. **The file is never rewritten**: a node the tree leaves out draws as the rows call for it and is stored nowhere (`lotics docs design`). It prints what `set_app` answered and reports its `outcome`: its notes and findings, every finding at once, and the saves, adds and Deletes the write grants and removes. **`--check` sends `dry_run`** (a flag of `app apply` alone, as is `--app`) \u2014 what would refuse the tree, and what it would grant and remove \u2014 and writes nothing, the file and its sibling included; an `outcome` of `refused` exits 1. A tree the app already has, or one `set_app` answers `unchanged`, records the version the app stays at in the sibling. **To go back to an earlier version, apply the earlier tree again.** Resolves and ANNOUNCES its workspace first. `--json` prints `{workspace_id, app_id, outcome, write}`, `outcome` being `set_app`'s: `created`, `updated`, `unchanged` or `refused` (with `--check`, what it would be). |\n| `lotics app deploy [-m <message>]` | **Build this directory and upload it as a new version of the live app.** Rewrites `.lotics/` with the declarations of the app's live bindings (`GET /v1/apps/{id}/types`, replacing each file there), then runs the project's `npm run typecheck` (warned about when absent; a type error in the app's own files stops the deploy, one inside an installed package is reported and does not) and `npm run build`, tars the source (without `node_modules`, `dist`, `.git`, `*.tsbuildinfo`) and `dist/`, and posts both to `POST /v1/apps/{id}/versions` on the version `package.json#lotics.current_version_id` names, then stamps the new one there. The version carries the app's queries, workflows, agents and capabilities forward unchanged \u2014 those are written through their tools. A project with no `build` script, or whose `package.json#lotics` still declares `queries`, `workflows`, `agents` or `capabilities`, is refused before anything is built; the refusal names the tool that sets each. **A 409 because another version went live since this directory's last deploy** (a deploy from elsewhere, a rollback) prints the server's sentence and the version that is live, and names `lotics app pull`: run in this directory, it brings an unedited project up to date, and lists the files a project with edits changed, to carry over into a fresh pull. `-m` (or a bare positional) is the version's message, optional. The workspace comes from `package.json#lotics.workspace_id` unless `--workspace` / `LOTICS_WORKSPACE` names another. |\n| `lotics docs` \\| `lotics docs <area>[/<section>]` \\| `lotics docs [<area>[/<section>]] --grep <text>` | **This CLI's own references, carried inside the binary** \u2014 the model reference, this index, and every doc under `docs/` \u2014 so the doc a reader opens describes the binary answering, listed by the job a reader comes to do. Capped at ONE PAGE: a doc that does not fit prints its opening and the addresses of what it holds (`lotics docs <area>/<section>`, each section's size beside it, or a table's row names), and every address prints within a page. **A reference the binary's copy lacks, or a part of one the server serves, is read from the server's `docs` tool** with this machine's credential, after the copy's refusal \u2014 a page the server added since this binary was built, which a server refusal can cite. A name matching more than one reference, or a part missing from a guide to this CLI, is answered by the copy alone. **`--grep` searches the references the server serves** (not this CLI's own guides, which it refuses), with this machine's credential, narrowed to the area or section named: literal text unless `--regex`; a literal search that finds nothing while the pattern read as an expression matches (`a|b`) returns those lines under a note saying so, and `--literal` keeps the literal zero; with `--case-sensitive`, `--diacritic-insensitive`, `--context-lines <n>` and `--limit <n>` \u2014 the dialect the knowledge lines of `get_workspace` with `search` are read in \u2014 each hit under the address that opens its page; any of those options without `--grep` is refused. A custom-code app's SDK reference ships inside `@lotics/app-sdk` in the app's `node_modules`. |\n| `lotics upgrade` | Update this CLI in place. Runs the same installer a person would, chosen by how THIS copy arrived: an npm install upgrades through npm, a script install re-runs the script \u2014 the runtime knows which (the executable is compiled, the npm bin runs under node), so nobody has to. It downloads nothing itself; resolving a version, verifying the checksum and replacing a running executable already exist in the installers, and a second copy of that inside the binary would be a second thing to get right. Replacing the binary while it runs is safe \u2014 a rename leaves the running image mapped on unix, and on Windows the installer moves the old aside precisely because the file is in use. Already current is a no-op that says so. Needs no auth. |\n| `lotics docs reference` \\| `lotics docs reference/<section>[/\u2026]` | **The reference for tables and apps, from inside the binary** \u2014 at this CLI's version; `lotics docs` lists it under \"Build an app\", after `design`. Its first page is what the documents compose with, the working order (jobs \u2192 tables and fields \u2192 `records` \u2192 one app per job \u2192 one `set_tables` call with every table, then every `set_app` call) and the section addresses; every page of it is whole. Every key of a table document and an app body, every field `type` with the config each one needs, the option / view / inline-template shapes, `records` (how a row of a table is recognised), `write_rules`, the apps (each register, record, act and check), the row format (relative dates `@today` / `@month-start` with whole-day offsets; links as `\"<table-ref>:<row-ref>\"` or a stored record's id), the rules, the caps of one `set_tables` call, and a worked example; **Offline, no account.** |\n| `lotics report '<json>'` \\| `lotics report @report.json` | File a report with the Lotics team about what got in your way. **Covers the classes telemetry structurally cannot see**: a capability that does not exist (no command ran, so nothing was recorded), a command that exited 0 having done the wrong thing, an error whose message did not name the remedy, and anything that made authoring slower than it should be. **A frame, not a paragraph** \u2014 `{goal, actual, expected?, tried?, wanted?}`, `goal` and `actual` required, unknown keys dropped rather than refused. **No severity or category.** Ingest is inline JSON, `@file`, or `-` for stdin. A bare sentence is refused with the frame printed beside it, so the fix is one step; a bare invocation prints the frame BEFORE asking for a credential, since someone whose key will not resolve is exactly who has something to report. **Not spooled**: unlike telemetry it posts inline, prints whether it landed, and exits non-zero if it did not, echoing the report back so a failed send never loses it. Runs regardless of `LOTICS_TELEMETRY` \u2014 invoking it IS the consent that passive collection needs an opt-in for \u2014 but with telemetry off there are no recorded commands to attach, and it says so rather than implying context it does not have. Requires auth. Never paste records, file contents, or credentials. **Prints the id of each frame filed** \u2014 a filing nobody can cite cannot be answered about. The ids come from the server, so an instance that only logs the frames prints the count alone; the CLI never mints one of its own, which would hand back a token that resolves to nothing. |\n\n";
|
|
1894
|
+
var cli_reference_default = "# @lotics/cli \u2014 CLI Command Reference\n\nPer-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. Start at [AGENTS.md](../AGENTS.md) for the model this reference assumes; `lotics --help` is the authoritative, always-current verb list.\n\n| Command | What it does |\n|---|---|\n| `lotics` / `lotics --help` | Show full help: capabilities, the verb list (\xA7 COMMANDS), flags, config. `lotics <verb> --help` prints that verb's entries alone (`lotics app --help`, `lotics file download --help`); `lotics report --help` prints the report frame. |\n| `lotics auth signup <email>` | Create account + org + API key, sends magic link email. Refused on a private instance, whose people arrive by invitation; prints that creating the account accepts the Terms and Privacy Policy. Registers the new org as a profile; `--local` pins this directory to it (pointer) instead of setting the global default. |\n| `lotics auth login` | Sign in an account that already exists, on a machine holding no key. It takes no argument and sends no mail. **Two steps, and it does not wait for the person.** The first prints the page to open \u2014 `https://lotics.ai/cli_login/<request_id>` \u2014 and the code that page must show, records the request, and exits 0. They sign in there if asked, check the code, pick the organization and press Confirm. **Then the next command that needs a credential collects the key** before it does its own work, so the second step is just re-running whatever was wanted; a command run before Confirm exits 1 naming the page and the code again, and once the 15 minutes are up it says to ask again. The handful that run WITHOUT a credential \u2014 `docs` among them \u2014 claim nothing, so one of those run after Confirm still answers as though signed out. `--wait` keeps one command instead, holding the terminal until Confirm; `--local` pins this directory to that org rather than setting the global default, and implies `--wait` (a pin names THIS directory, so only the terminal that stays in it can write one). `--json` prints `organization_id`, `workspace_id` and `organization_name` when it finishes signed in, and `request_id`, `confirm_url`, `code`, `expires_at` when it is the first step. The request's secret is never printed and the org's key never leaves the store. |\n| \u2014 | **A flag is refused on a verb that does not read it**, naming the verbs that do, before any request or credential: `--check` on `lotics run` would otherwise be parsed and ignored, and the write it was meant to stop would run. `--json`, `--workspace`, `--api-key` and `--timeout` are read by every verb. |\n| \u2014 | **Every call a verb makes waits for the server's answer**; `--timeout <ms>` (a whole number of milliseconds from 1 to 2147483647) stops each wait early. The wait ends without an answer when `--timeout` passes or no answer arrives from the server. A read with no answer changed nothing: the command exits non-zero naming the request id. A write with no answer exits non-zero with `error_code: \"outcome_unknown\"` and the request id under `--json`, because it cannot say whether the call took effect: read before running it again. The one fetch outside this is the download from an object-storage signed URL, which carries no request id and is stopped by `--timeout` alone. Under `--json` every error is one object on stdout: `error`, with `error_code` and `request_id` where the error has them. |\n| `lotics auth api-key [key]` | `whoami` \u2192 **upsert** the key's org as a profile in the global store (never overwrites). The profile records the instance the key was verified against (`LOTICS_API_URL`, default `https://api.lotics.ai`), and every later command for that org goes there. `--local` additionally pins this directory to it (pointer) instead of setting the global default. |\n| `lotics auth web` | Send a magic link email to access the web app (requires auth) |\n| `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 \u2014 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`. |\n| `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 \u2014 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 \u2192 Security \u2192 *Keys and terminals*. An **API key** (`auth api-key`) is only forgotten here \u2014 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 \u2192 API keys is admin-only and the credential may well be the holder's own sign-in, which they revoke themselves at Settings \u2192 Security \u2192 *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. |\n| \u2014 | **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.` carries `Run \\`lotics auth login\\` to sign in again.` for a sign-in and `Ask an admin for a new API key (Settings \u2192 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 \u2014 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.` \u2014 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. |\n| `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). |\n| `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 \u2014 a read, a write, and a local check that needs no credential alike \u2014 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 \u2014 a server-side rename never moves it, and the new name resolves too, so both keep working and `lotics org` prints the pair. |\n| `lotics org use <name\\|id> [--local]` | Switch the active org by org name (case-insensitive, ambiguous \u2192 error) or id. No flag \u2192 global `active_org`; `--local` \u2192 a `.lotics/config.json` pointer in the current dir. |\n| `lotics workspace` | List workspaces in the active org, marks current with `(current)` |\n| `lotics workspace select <id>` | Set the workspace in the **active scope** \u2014 a local pin if the dir has one, else the active org's global profile. Records the workspace's NAME beside its id, which is what the `lotics \u2192 <org> / <workspace>` echo prints; `workspace list`, `workspace create`, `workspace rename` and `org use` record it too, so a target is named rather than identified. Until one command has listed it, the echo prints the id and says the name is not known yet. |\n| `lotics workspace create <name> [--timezone <Area/City>] [--currency <ISO>]` | Create a new workspace (organization owner only), auto-switches to it. Neither flag is defaulted from THIS machine, unlike signup: an extra workspace is routinely created by an operator for somebody else. Without `--timezone` the new workspace inherits the zone of the org's OLDEST workspace; without `--currency` it takes the org's default. Both ride the create, so the workspace is never briefly denominated in a currency nobody asked for. `--currency` takes an ISO-4217 code (case-insensitive; anything else is refused). |\n| `lotics workspace rename <name>` | Rename the **current** workspace (an admin of that workspace only) \u2014 the endpoint takes its target from the request's workspace, never a path id, so switch with `workspace select <id>` first and read the `lotics \u2192 <org> / <workspace>` echo before trusting it \u2014 both halves are names, and the rename moves the cached one in the same act. Carries the workspace's existing `default_currency` and `timezone` through unchanged: the endpoint takes the whole settings triple, so sending only a name would blank the other two. |\n| `lotics workspace settings [--name <n>] [--currency <ISO>] [--timezone <Area/City>]` | Change the CURRENT workspace's name, default currency or timezone \u2014 `PATCH /v1/workspace`, an admin of that workspace only. Only what you name changes; the endpoint takes the whole triple, so the CLI carries the two you did not. `rename` is this verb with the name alone, which is why it can never forget the other two. Both values are invisible once they are wrong: the currency decides how every money field RENDERS and the zone decides how every date BUCKETS, on a workspace whose whole purpose may be to look like the customer's own. `--json` prints the updated workspace. |\n| `lotics workspace delete <id> --yes` | Delete a workspace by id (organization owner only). **Soft delete** \u2014 `archived_at` is set, so it drops out of listings, can no longer be selected, and its tables/records go dark, while the data is retained and recoverable. Its **apps are cascade-archived** too \u2014 every app entry point (embedded, public link, standalone subdomain, incl. anonymous public links) stops serving. Refuses the org's **only** active workspace (400) and any workspace outside the caller's org (404). Requires `--yes` to confirm (destructive; the CLI is used non-interactively). |\n| `lotics workspace doctor` | An admin of that workspace only. Report workspace-wide dangling schema references via `GET /v1/workspaces/dangling-references` \u2014 every active app/workflow artifact whose prefixed schema id no longer resolves, printed as `<referent.kind> \"<name>\" (<id>) \u2192 <namespace> <id> (missing)`; healthy prints a one-line all-clear. **Exits non-zero (exit 1) on findings** so scripts can gate on it. Resolves the first workspace like every data command (runs before the global workspace resolution). Admin-only. |\n| `lotics tools` | List tools by category with descriptions |\n| `lotics tools <name>` | Full description, input JSON Schema, and the output schema where the tool answers a shape, for one tool; a workflow step says to call it from a workflow body, not `lotics run` |\n| `lotics run <tool> '<json>'` | Execute a tool (text output via toModelOutput). Args may also come from a file (`lotics run <tool> @args.json`) or stdin behind the `-` sentinel (`cat args.json \\| lotics run <tool> -`) \u2014 both bypass the OS `ARG_MAX` limit for large payloads (a knowledge-doc `content`, a bulk update). A leading `@` on the args is unambiguously a file path (JSON args start with `{`). **Stdin is asked for, never guessed.** `lotics run <tool>` with no payload runs the tool with no arguments and returns at once. `lotics report` takes the same sentinel. In PowerShell use `@file`: quotes inside an inline argument are consumed by the shell, and the CLI reports the JSON it received with its quotes gone \u2014 the error names both escapes. |\n| `lotics run <tool> --json '<json>'` | Execute a tool (full JSON output) |\n| `lotics run <tool>` \u2014 **file cells** | A file in a tool's result carries its `fil_\u2026` id and metadata and **no `url`**, on every tool and in both output modes. That is not a broken file \u2014 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. |\n| \u2014 | **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`. |\n| \u2014 | **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` \u2014 up to 20 reads in one call, each `{\"alias\", \u2026}`, a refused one answered with its `error`; one call's rows total at most 262,144 bytes. `export: {\"key\", \u2026narrowing}` 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` \u2014 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\"` \u2014 and `runs` \u2014 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. |\n| \u2014 | **The exit code reports the WORK, not just the call \u2014 for the tool that RUNS one.** `run_app_workflow` whose envelope carries a failed `status` (`error`/`failed`/`cancelled`, or `not_previewed` \u2014 a dry run asked for and not given) exit non-zero and print `<tool> \u2192 <status>: <message>` to stderr, so `lotics run \u2026 && next-step` cannot walk past a refused run. The rule is an allowlist of FAILURE \u2014 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. |\n| `lotics run <tool> '<json>' -o <dir>` | Also save every **signed link** the answer carries \u2014 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`. |\n| `lotics run set_members '{\"members\": {\"<email or member id>\": {\"role\": \"member\", \"name\": \"\u2026\"}}}'` | 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 \u2192 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. |\n| `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. |\n| `lotics run <tool> --cleanup` | Implies `--print-created`, then runs those deletes \u2014 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. |\n| `lotics file upload <file\\|dir...>` (alias `lotics upload`) \xB7 `--stdin` \xB7 `--base64` \xB7 `--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 \u2014 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** \u2014 an attachment decoded in memory, a generated document, a signed download link \u2014 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 \u2014 `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. |\n| `lotics file download <file_id> [<path>]` \xB7 `-o <dir>` | (alias `lotics download`) Download a stored file: `GET /v1/files/{id}/signed_url` \u2192 fetch the presigned URL and write it where you asked. **The two spellings mean two different things, and neither is read by shape: the positional `<path>` is the FILE to write, `-o <dir>` is the DIRECTORY to save into.** That is `cp` and `curl -o`, so nothing here consults an extension. A named file is written as named, its parent created, overwriting what is there \u2014 the point of naming it is that the next command opens that exact path. A directory is created if missing and written into under the stored filename (the response's `Content-Disposition`), taking a free spelling beside a file of that name already there so a repeat download never clobbers the first; with no destination at all, that filename lands in cwd. Give the destination once \u2014 a positional and `-o` together is refused, as is a positional that names an existing directory or ends in a separator (`a directory goes in -o`). The first argument is a **file id**, so a path in that slot is refused rather than sent as an id. The written path goes to **stdout** (under `--json`, `{file_id, path, filename, stored_filename}`) and the narration to stderr, so a download pipes into whatever opens it. `lotics file download record <record_id> <field_alias> [-o <dir>]` (the field named by the alias `query_records` shows it under) spreads every file on a record's file field over a DIRECTORY \u2014 there is no single file for N files to be. |\n| `lotics file list [--limit <n>] [--cursor <token>]` | The workspace's files, newest first \u2014 id, upload time, bytes, MIME type, filename on stdout, one per line (`--json` for the object). `GET /v1/files` with no `file_ids`. A file holding the content of a knowledge doc or template you cannot use is left out. **A page, not a dump**: the store only ever grows, so the last line prints the command for the next page and `next_cursor` is null on the last one. The cursor is opaque and keyset \u2014 pass it back as given \u2014 so an upload landing mid-sweep cannot make a walk skip or repeat a row. Every other file verb takes an id, so this is the only answer to \"what is in here\" short of reading Postgres. |\n| `lotics knowledge list [--include-hidden \\| --deleted]` | `GET /v1/knowledge_docs` \u2014 a table of id, name, tags, description (`--json` for the docs). **REST, not `get_workspace` kind `knowledge`**: the tool answers what the ASSISTANT may browse, and a hidden doc is out of that corpus by definition, so a tool-backed listing could never show one and the person who hid it would have no way back to it. Hidden docs are left out unless `--include-hidden` asks; those rows are marked `(hidden)`. **`--deleted` is the one tool-backed form**: it calls `get_workspace` with `kind: \"knowledge\"` and `include_archived: true`, page by page, and prints the deleted docs you can manage (id, name, deleted time, description); it cannot be combined with `--include-hidden`. |\n| `lotics knowledge create --name <n> [--description <d>] [--tags <a,b>] (--from <file.md> \\| --content <str>)` | Read the body client-side (a file XOR an inline string \u2014 exactly one required), then call `set_knowledge` with `{ name, description, content, tags? }` and no `knowledge_doc_id`, which makes a doc (description defaults to `\"\"`). `--tags` files the doc as it is made, which is the only moment a corpus reliably gets labelled. Prints the new id to stdout. Large files ride the POST body fine. |\n| `lotics knowledge get <id> [-o <file.md>]` | `GET /v1/knowledge_docs/{id}` (`getKnowledgeDoc`) \u2192 the doc with its **hydrated `content`** (the one whole-content read for a non-sandbox client; the tool `read_knowledge` reads a line range). `-o` writes the body via `writeFileAtomic`; else the body goes to stdout. `--json` prints the full doc instead. |\n| `lotics knowledge update <id> [--from <file.md> \\| --content <str>] [--name <n>] [--description <d>] [--tags <a,b>]` | Call `set_knowledge` with a `knowledge_doc_id` and **only** the provided fields (a body from --from/--content becomes `content`; the tool diffs + CASes the content change internally, so the CLI passes no `expected_content_file_id`). `--tags` REPLACES the doc's label set \u2014 the single-doc form, where the caller is looking at one doc and can state what it should carry. At least one field required; --from and --content are mutually exclusive. |\n| `lotics knowledge tag <id...> [--add <a,b>] [--remove <c,d>]` | `PATCH /v1/knowledge_docs` with `{ knowledge_doc_ids, add_tags?, remove_tags? }` \u2014 one transaction over the whole set. A **DIFF applied to each doc's own labels**, never a replacement: the docs named on one command line carry different labels, so one array across them would strip whatever the others were filed under. Removal matches case-insensitively; adding a label a doc already carries writes nothing. Ids may be separate arguments or comma-separated. At least one of --add/--remove required. |\n| `lotics knowledge hide <id...>` / `lotics knowledge unhide <id...>` | `PATCH /v1/knowledge_docs` with `{ knowledge_doc_ids, hidden }`. Hiding takes docs out of every **listing** \u2014 the Library's list, and the corpus `get_workspace` lists and its `search` searches \u2014 while leaving IAM untouched and keeping them readable **by id** (`read_knowledge` with an id, a code run staging one, an app agent's declared set). So it can never silently break an app that depends on a doc, and unhiding costs nothing. Refuses the no-argument form rather than reading it as \"everything\". |\n| `lotics knowledge rm <id...>` | Delete docs via `set_knowledge` (`{ knowledge_doc_id, delete: true }`), one call per id: each must be a live doc you manage that no app or workflow names, and the command reports which succeeded and which failed. Sharing and history are kept. The REST execute path does not gate `needsApproval`, so this runs unattended. |\n| `lotics knowledge restore <id...>` | Bring deleted docs back via `set_knowledge` (`{ knowledge_doc_id, restore: true }`), one call per id: each must be a deleted doc you manage, and the command reports which succeeded and which failed. Refuses the no-argument form. |\n| `lotics app create <name> --custom [path]` | **A custom-code app**: creates the app (`POST /v1/apps`) and links `[path]` (default `./<name>`, made when absent) to it by writing `package.json#lotics` (the app and its workspace, which is how `app deploy` in that directory finds both) \u2014 into the project's own `package.json` when it has one, every other key kept, otherwise a `package.json` holding the link alone. Nothing else is written and nothing is installed: the project is yours. `app deploy` needs `@lotics/app-sdk` (React 19) and an `npm run build` that writes a static `dist/` with an `index.html`. A directory already linked to an app is refused before the app row exists. The app has no version until the first `lotics app deploy`. `--custom` is required: a JSON app is made by `lotics app apply` (the tool `set_app`). The SDK's reference is `node_modules/@lotics/app-sdk/AGENTS.md` once the project installs it. |\n| `lotics app pull [app_id] [path]` | **An app's live definition, pulled.** The app is read with `get_app`: its author is shown a body, a JSON **tree** (with the addresses of its nodes) pulled as that tree and a custom-code app (its identity and Query nodes) as its source; an app whose stored tree does not read in this release is pulled as it is stored, with a warning giving the reason `get_app` gives (where the stored value is not a JSON object, nothing is pulled and the reason is the error); an app that shows the caller no body (the caller does not author it, or it has no version) is refused. **A JSON app**: the tree is written as JSON to `[path]` (a directory receives `./<name>.app.json`; default `./<name>.app.json`), and the app's id and current version beside it in `<file>.lotics.json` (`{ \"app_id\": \"\u2026\", \"version_id\": \"\u2026\", \"digest\": \"\u2026\" }`, the digest being the file as the CLI last left it; a record without all three is refused by `app apply`, naming `lotics app pull`) \u2014 a custom-code project records both in `package.json#lotics`, a single file has no such place \u2014 so the next `lotics app apply <file>` edits that app, and is refused if the app has since moved past that version. An existing file is overwritten only when its `.lotics.json` names this same app and the file is unchanged since it was last pulled or applied; a file with edits, or whose record names the app but no digest, is refused, naming `--force`, which overwrites it. `--force` is a flag of `app pull` alone. `--json` prints `{workspace_id, app_id, path, outcome}`. **A custom-code app**: its live source, as a project ready to deploy on it. The target is `[path]`, else this directory when it is the app's project (or no app is named), else `./<name>`. **The app's own project is brought up to date in place** \u2014 but only when it holds no edit since the version `package.json#lotics.current_version_id` names: its source (packed as a deploy packs it) is compared with that version's archive, ignoring `.lotics/` and `package.json#lotics`, and any difference refuses the pull, naming the changed files; a pull never merges, so local work is never lost. Already at the live version is a no-op that says so. **An empty or new directory receives the source whole**; any other directory is refused. Downloads come from `GET /v1/apps/{id}/versions/{version_id}/source`. `package.json#lotics` is then set to exactly the app, its workspace and the pulled version, dropping every other key an older CLI wrote there, so the next `lotics app deploy` builds on the live version; then `.lotics/` is written (`GET /v1/apps/{id}/types`) and dependencies installed (`npm ci` with a lockfile, else `npm install`, both `--ignore-scripts`). |\n| `lotics app apply <file> [--app <app_id>] [--check] [--json]` | **A JSON app, one at a time, through the tool `set_app`.** The file is an app's tree (`lotics docs reference`: the App node with the nodes under it, its tables and templates named by alias). **No app known** (no `--app`, no `<file>.lotics.json` beside it): the file is sent as `{ \"body\": \u2026 }` to make a new app, named by the body's `name`, and the id made is printed, then recorded with its version in `<file>.lotics.json`. **An app known**: its current tree is read (`get_app`) and the **RFC 7396 merge patch** that turns it into the file is sent as `body` with the `app_id` and the version the patch was computed against as `base_version_id` \u2014 a key the file drops is `null` in the patch, a list is replaced whole, what the file leaves alone is left alone, and a tree the app already has sends nothing and says so. **A file pulled at a version the app has since left is refused** where the stored tree changed since the pull (a version that moved only for a workflow's body applies) before anything is sent, naming both versions and `lotics app pull <app_id> <path>`: pull the current tree into another path, carry the edits over, apply that file. `--app` naming an app other than the sibling file's is refused too. A write that races the apply is refused by the server, which names the app's current version. A file that sets an object key to `null` is refused naming the key, since a merge patch reads `null` as a removal. `--app` names the app, else the sibling file does; an app whose `get_app` shows no body (it is not yours) is refused, **over a stored tree that does not read in this release the file is sent whole** (`set_app` with `app_id`, the file as `body` and the version read as `base_version_id`; no merge patch is computed against a tree that does not read) where it states `\"type\": \"App\"`, and any other file is refused, naming that only a whole tree replaces it; a custom-code app takes its identity (name, description, icon, colour) and, where the file states `children`, its Query nodes, which replace every query it holds; a file stating none leaves its queries alone and no `<file>.lotics.json` records it, since an identity write makes no version \u2014 its source deploys with `app deploy`. **The file is never rewritten**: a node the tree leaves out draws as the rows call for it and is stored nowhere (`lotics docs design`). It prints what `set_app` answered and reports its `outcome`: its notes and findings, every finding at once, and the saves, adds and Deletes the write grants and removes. **`--check` sends `dry_run`** (a flag of `app apply` alone, as is `--app`) \u2014 what would refuse the tree, and what it would grant and remove \u2014 and writes nothing, the file and its sibling included; an `outcome` of `refused` exits 1. A tree the app already has, or one `set_app` answers `unchanged`, records the version the app stays at in the sibling. **To go back to an earlier version, apply the earlier tree again.** Resolves and ANNOUNCES its workspace first. `--json` prints `{workspace_id, app_id, outcome, write}`, `outcome` being `set_app`'s: `created`, `updated`, `unchanged` or `refused` (with `--check`, what it would be). |\n| `lotics app deploy [-m <message>]` | **Build this directory and upload it as a new version of the live app.** Rewrites `.lotics/` with the declarations of the app's live bindings (`GET /v1/apps/{id}/types`, replacing each file there), then runs the project's `npm run typecheck` (warned about when absent; a type error in the app's own files stops the deploy, one inside an installed package is reported and does not) and `npm run build`, tars the source (without `node_modules`, `dist`, `.git`, `*.tsbuildinfo`) and `dist/`, and posts both to `POST /v1/apps/{id}/versions` on the version `package.json#lotics.current_version_id` names, then stamps the new one there. The version carries the app's queries, workflows, agents and capabilities forward unchanged \u2014 those are written through their tools. A project with no `build` script, or whose `package.json#lotics` still declares `queries`, `workflows`, `agents` or `capabilities`, is refused before anything is built; the refusal names the tool that sets each. **A 409 because another version went live since this directory's last deploy** (a deploy from elsewhere, a rollback) prints the server's sentence and the version that is live, and names `lotics app pull`: run in this directory, it brings an unedited project up to date, and lists the files a project with edits changed, to carry over into a fresh pull. `-m` (or a bare positional) is the version's message, optional. The workspace comes from `package.json#lotics.workspace_id` unless `--workspace` / `LOTICS_WORKSPACE` names another. |\n| `lotics docs` \\| `lotics docs <area>[/<section>]` \\| `lotics docs [<area>[/<section>]] --grep <text>` | **This CLI's own references, carried inside the binary** \u2014 the model reference, this index, and every doc under `docs/` \u2014 so the doc a reader opens describes the binary answering, listed by the job a reader comes to do. Capped at ONE PAGE: a doc that does not fit prints its opening and the addresses of what it holds (`lotics docs <area>/<section>`, each section's size beside it, or a table's row names), and every address prints within a page. **A reference the binary's copy lacks, or a part of one the server serves, is read from the server's `docs` tool** with this machine's credential, after the copy's refusal \u2014 a page the server added since this binary was built, which a server refusal can cite. A name matching more than one reference, or a part missing from a guide to this CLI, is answered by the copy alone. **`--grep` searches the references the server serves** (not this CLI's own guides, which it refuses), with this machine's credential, narrowed to the area or section named: literal text unless `--regex`; a literal search that finds nothing while the pattern read as an expression matches (`a|b`) returns those lines under a note saying so, and `--literal` keeps the literal zero; with `--case-sensitive`, `--diacritic-insensitive`, `--context-lines <n>` and `--limit <n>` \u2014 the dialect the knowledge lines of `get_workspace` with `search` are read in \u2014 each hit under the address that opens its page; any of those options without `--grep` is refused. A custom-code app's SDK reference ships inside `@lotics/app-sdk` in the app's `node_modules`. |\n| `lotics upgrade` | Update this CLI in place. Runs the same installer a person would, chosen by how THIS copy arrived: an npm install upgrades through npm, a script install re-runs the script \u2014 the runtime knows which (the executable is compiled, the npm bin runs under node), so nobody has to. It downloads nothing itself; resolving a version, verifying the checksum and replacing a running executable already exist in the installers, and a second copy of that inside the binary would be a second thing to get right. Replacing the binary while it runs is safe \u2014 a rename leaves the running image mapped on unix, and on Windows the installer moves the old aside precisely because the file is in use. Already current is a no-op that says so. Needs no auth. |\n| `lotics docs reference` \\| `lotics docs reference/<section>[/\u2026]` | **The reference for tables and apps, from inside the binary** \u2014 at this CLI's version; `lotics docs` lists it under \"Build an app\", after `design`. Its first page is what the documents compose with, the working order (jobs \u2192 tables and fields \u2192 `records` \u2192 one app per job \u2192 one `set_tables` call with every table, then every `set_app` call) and the section addresses; every page of it is whole. Every key of a table document and an app body, every field `type` with the config each one needs, the option / view / inline-template shapes, `records` (how a row of a table is recognised), `write_rules`, the apps (each register, record, act and check), the row format (relative dates `@today` / `@month-start` with whole-day offsets; links as `\"<table-ref>:<row-ref>\"` or a stored record's id), the rules, the caps of one `set_tables` call, and a worked example; **Offline, no account.** |\n| `lotics report '<json>'` \\| `lotics report @report.json` | File a report with the Lotics team about what got in your way. **Covers the classes telemetry structurally cannot see**: a capability that does not exist (no command ran, so nothing was recorded), a command that exited 0 having done the wrong thing, an error whose message did not name the remedy, and anything that made authoring slower than it should be. **A frame, not a paragraph** \u2014 `{goal, actual, expected?, tried?, wanted?}`, `goal` and `actual` required, unknown keys dropped rather than refused. **No severity or category.** Ingest is inline JSON, `@file`, or `-` for stdin. A bare sentence is refused with the frame printed beside it, so the fix is one step; a bare invocation prints the frame BEFORE asking for a credential, since someone whose key will not resolve is exactly who has something to report. **Not spooled**: unlike telemetry it posts inline, prints whether it landed, and exits non-zero if it did not, echoing the report back so a failed send never loses it. Runs regardless of `LOTICS_TELEMETRY` \u2014 invoking it IS the consent that passive collection needs an opt-in for \u2014 but with telemetry off there are no recorded commands to attach, and it says so rather than implying context it does not have. Requires auth. Never paste records, file contents, or credentials. **Prints the id of each frame filed** \u2014 a filing nobody can cite cannot be answered about. The ids come from the server, so an instance that only logs the frames prints the count alone; the CLI never mints one of its own, which would hand back a token that resolves to nothing. |\n\n";
|
|
1895
1895
|
|
|
1896
1896
|
// docs/data_model.md
|
|
1897
1897
|
var data_model_default = '# The data model \u2014 tables, their fields, and how they relate\n\nThe decisions here outlive any one app, and most become expensive the moment a second screen depends\non them. They stand apart from building an app on purpose: **every workspace starts with tables\nand many never get an app**, so schema design is not a chapter of app building.\n\nThe rules below share one signature. **Both sides read correctly on their own**, so nothing reports\nthe problem \u2014 no error, no empty column, no failing query. Each is found by looking for it. Then,\nunder **Fields**, what each field type takes.\n\n## One fact, one column\n\n**Read the table\'s existing fields first (`get_table`), and add nothing that stores a fact the table already\nstores.** A value written as text and the same value held as a `link` are one fact in\ntwo columns \u2014 a customer\'s city typed into a text box beside a link to the city record, a status\nword beside the select that decides it, a total beside the formula that computes it.\n\nTwo columns for one fact do not stay equal. Some writer sets only one of them, and nothing reports\nthe divergence: both rows still look correct on their own. A reader that then matches on the text\nhalf treats "Acme" and "Acme Ltd" as different records, so an import creates a duplicate every time\nit runs.\n\n- **Prefer the link, the select, or the formula.** Text is a RENDERING of a record; compose it when\n you read, rather than storing it a second time.\n- **Renaming, retyping or re-pointing the existing field beats adding another.** A field\'s key is\n stable, so a rename breaks nothing that addresses it by key.\n- **Superseding a field means DELETING it**, not leaving it beside its replacement with a\n description that says which one is real.\n- **Empty is not the same as redundant.** A field nothing fills may still be the only home for a\n real distinction \u2014 read what it MEANS before removing it.\n- **A stored field becomes required only once every row holds a value**, so it always holds one: state its `default`,\n which the same write fills into every row holding it empty (a draft takes it when submitted), or fill the empty cells\n first; without either, the write is refused while a row holds it empty. A computed field\'s flag is checked as each row is written.\n Making a field required rebuilds the JSON apps that create its rows, so their creates set it; a workflow its author\n wrote, or a custom-code app\'s, that creates rows of the table without it refuses the change, naming each \u2014 a `default`\n lifts that, as does setting the field in each create; an autonumber, a derived date and a computed field fill\n themselves, and a copied field (`default_from`) fills only when the row sets its link.\n Changing a stage\'s date, the status\'s `default` or the status is refused while a stored create relies on the stamp, naming each workflow.\n\n## One entity, one table \u2014 and the test is measurable\n\nVariation belongs in a column \u2014 a multi-select role, a kind, a stage \u2014 not in a second table. Two\ntables for one kind of thing give the same real-world entity two rows, two ids and two halves of its\nhistory, and each screen shows whichever half it happens to link to.\n\nSplit tables are often right. A supplier book beside a customer book is a normal shape, and merging\non suspicion is a large repoint bought for nothing. So do not argue it in the abstract:\n\n> **List both tables\' names and look for one that appears in both.**\n\nNone means the split is holding. One means it has broken \u2014 the usual cause is a party you begin to\ninvoice as well as buy from \u2014 and the fix is to merge before a second screen depends on the copy.\n\n## One vocabulary wherever values are COPIED between tables\n\nTwo `select` fields for one concept carry different option keys even when their labels match. Copy an option by its\nalias or label: the record tools match an option by alias or label, so a value copied by alias lands\non the option of that alias on the other field. Prefer a link to a shared reference table where the set is open or\ngrowing. Where one side holds more values than the other, the wider side must **refuse** what the narrower one cannot\nexpress rather than quietly picking the nearest value.\n\nA value read through a link or a lookup reads exactly as the same field would on its own row: an option written by its alias in\na body and read as that alias, a member or a link by its id. A value a check matches\nacross tables is a link to one table, or a select whose options state the same aliases: two selects that state no alias in common never compare, and a save that compares them is refused, in a check\'s lookup too. A filter or a write on another table\'s select takes a value read from this one by its alias, else its label.\n\nA lookup reads as one flat list of the values it looks up, in a check and in every body: `first(record.x)` is the one value through a one-row link and `includes(record.x, v)` asks whether any row holds `v`; two selects that state no alias in common never compare. A single member, a single select, a number or a text reads as the value itself, and `first(...)` of one is refused when the body is saved. A rollup that adds up (a sum, a count) over no rows is 0, never empty, as `sum` over an empty list is; a min, a max or an average over no rows is empty.\n\n## A copy boundary accounts for EVERY source field\n\nEach field on the source gets a column on the destination, a deliberate drop with the reason written\ndown, or a refusal.\n\nA field with nowhere to land is data destroyed at the boundary, and it is invisible afterwards: the\ndestination is not empty and not obviously wrong \u2014 just a number that no longer agrees with where it\ncame from.\n\n## Provenance is a LINK, not a flag and not a copy\n\nA row created BY another row carries a link to it.\n\nThat link is what makes "is this the estimate or the actual", "where did this come from" and "have we\nalready imported this" answerable at all. A boolean records that something was true once; a link\nstays true, survives a rename, and lets the next write UPDATE the original instead of adding a second\nrow beside it.\n\n## Say what makes two rows the SAME row\n\nState it as the table\'s `natural_key` (`reference/write-rules`); a text key is also `unique`.\n\nAnything that imports, reconciles or de-duplicates has to decide identity, and with no declared key it falls back to\ncomparing displayed text \u2014 which is how one company arrives three times under three spellings. Name the key: a reference\nnumber, a tax id, a link plus a period. Then match on record ids and option aliases, never on rendered labels.\n\n## A stage\'s moment is a date on the row\n\nWho changed what, and when, is the platform\'s audit trail, which an agent already reads (`query_audit_logs`) under\nits own access to the table \u2014 so it is never a table of yours, and an app shows none of it: a history an app shows is\ntable-backed (`records.status.dates`, `records.status.history`, an event table an act makes).\n\nWhen the business reports, filters or prints the moment a row reached a stage (completed on, cancelled on), that\nmoment is a `date` field of the row, as `completed_at` and `canceled_at` are in SQL. State it as `records.status.dates`\n(`reference/status`): option \u2192 date. The record write path stamps it as a row is made at the option or moved into it,\nwhoever writes, so no one has to remember; a value the same write states wins, which loads past data as it happened. The\nplatform never clears a stamp: each date is when the row last entered the option, and leaving keeps it, and putting a\nchange back restamps nothing. A date range is a span, never a moment, so it is refused. It is the one way a status is\ntimed: a stage\'s `within` runs from its date, a straight-line process is one select whose options are its steps, each\ndated, and the stage is never read off a run of dates.\n\n`records.status.history` is for a business that reports on every move \u2014 moves per person, or time in a stage a row\nre-enters \u2014 and the platform appends one row per move. An event that carries facts of its own (a reason, an amount, a\nsignature, an inspection\'s findings) is its own table with those fields, made by the act that records it.\n\n## Keep derived chains shallow\n\nFormulas and rollups are computed and STORED when a row is written, and one that reads another recomputes with it. A\nrollup over a formula over a formula is paid three times on every touch, and again for every row upstream of it.\n**Depth costs more than row count**: chain depth is yours to keep down, row scanning is the platform\'s. A figure that\nreads itself back through its rows\' links (a task\'s total counting a subtask that lists the task) never settles: the\nwrite that closes the loop is refused, naming the row and the link, and so is a later write reaching it until a link is\nremoved. A figure read through a chain of rows settles up to 256 rows deep in one write.\n\n## Fields\n\nA field is stated inside its table\'s document in a `set_tables` call, keyed by alias. A name people read (a\ntable\'s, a field\'s, an option\'s) is in the owner\'s language; an alias stays English. Every field `type`, the\nkeys each one takes (notation, defaults, options, links, formulas, rollups, lookups, copies) and a worked\nexample are in `docs path="reference/field"`; this page holds the choices around them.\n\n### Types and formats\n\n`type` is one of `text`, `number`, `date`, `boolean`, `select`, `member`,\n`link`, `files`, `formula`, `rollup`, `lookup`, `autonumber`.\n\nA URL, an email, markdown, a checkbox, a datetime, money, a quantity or a percentage is a `format`\nor a `notation` on another type, never a `type`:\n\n| Wanted | Field |\n|---|---|\n| URL or external link | `{ type: "text", format: "link" }` |\n| Email or phone | `{ type: "text" }` |\n| Markdown | `{ type: "text", format: "markdown" }` |\n| Checkbox | `{ type: "boolean" }` |\n| Money | `{ type: "number", notation: { style: "currency", currency: "USD" } }` |\n| Quantity | `{ type: "number", notation: { style: "unit", unit: "kg" } }` |\n| Percentage | `{ type: "number", notation: { style: "unit", unit: "percent" } }` |\n| Datetime | `{ type: "date", format: "datetime" }` |\n| Month (a payroll or billing period) | `{ type: "date", format: "month" }` |\n| Date range | `{ type: "date", format: "date_range" }` |\n| Time of day (a class at 16:00, any day) | `{ type: "text", format: "time" }` |\n\nA unit is written in any of its words, the workspace\'s language included, and stored as its code: `ng\xE0y` and `days` are\n`day`, `gi\u1EDD` is `h`. A time of day is stored `HH:mm`; `min` and `max` bound one by another time field (an end after its\nstart), and a table\'s `no_overlap` spans two of them (`reference/write-rules`).\n### Changing a field\n\nRead the table with `get_table`, which answers its document exactly as `set_tables` takes it, then send `set_tables` with\nthe `table_id` and only what changes. The table is edited by an RFC 7396 merge patch of its document, so what the patch\nleaves alone is left alone and `null` deletes the field it names. Every key a table and a field take is in\n`docs path="reference/tables"` and `reference/field`.\n\nA table is named by its alias wherever a call names one (`table_id`, a link\'s `table`, a lookup, `records.history`), and a new table in the call is named by its `ref`, which becomes its alias. The alias is kept while the table exists, archived or not: asking for one an archived table holds is refused, offering to restore that table or to choose another alias. A filter in a table document (a rollup\'s `filter`, `options_where`, a colour\'s condition, a check\'s lookup) takes the record tools\' operators and values (`is`, `is_any_of`, `gte`, a plain date as a day). An `autonumber` field takes `next` (`"next": 232`): the number its next row gets, refused below the highest already issued.\n\n- **A list is replaced whole**, so an option cannot be nulled. To rename, recolour, add or remove an option, restate the\n field\'s whole `options` list, each option with its alias (`reference/field/select`). A rename changes the label and every\n record keeps its value; an alias left out is removed, which needs `force` while rows hold it.\n- **A number field becomes an `autonumber`** when every row holds its own whole number of 1 or more: the numbers are kept\n and the next row takes the one after the highest (a `next` must be above it). Otherwise the call is refused, saying how\n many rows are blank, repeated or not whole, with up to 5 row ids. No other type converts to or from an autonumber; add\n one as a new field, which numbers the rows already there from 1 (or from `next`) in creation order.\n- **Splitting an option is a rename plus an add.** The old option keeps its alias and takes the first part\'s label, so its\n rows and every app reference to it keep working; the second part is a new option. Rows that belong to the second part\n are then moved by a filtered `update_records`.\n- **A status history holds every option its status ever had** and follows them in the same write: an option added or renamed\n on the status is added or renamed on the history, which a call never restates. Removing an option on the status leaves it\n on the history, because the moves already written hold it. A call that changes nothing of the status\'s options leaves the\n history alone, and options only the history holds stay. Deleting a row deletes its history rows with it, and restoring\n the row restores them; they never hold a delete back.\n- A link names its table by id, or by the `ref` of another table of the same call, and states its `multi`. A two-way link\n states `pair` on one table, as `true` or as a free alias, and the platform makes the partner on the other table with the\n inverse cardinality; a many-to-many link states both sides, since the inverse of many is not decided.\n A link to its own table pairs with itself when `pair` is `true`, and with a second field of that table when `pair` names it\n (a parent and its children).\n A link already holding rows is paired the same way, with its partner stated beside it in the call: the partner is filled from\n the links the rows hold and no cell of the link is rewritten. `pair: null` lets a pair go, both fields staying one-way links\n with their values; a field that holds one row, the partner or the link itself, refuses a pair two rows would crowd, naming the rows.\n The partner may stand on a table the call does not name: `pair: "<alias>"` makes it there, or pairs the one-way link that table\n already holds under that alias, and the answer lists that table among the call\'s. Only someone who manages that table may.\n- A formula\'s `output_type` is inferred from its expression; state it only to override.\n- **A call\'s removals are judged together, on what the call leaves.** A table and the links and lookups naming it, removed in one call, pass; every reader left outside the call is named in one answer, not one per retry. An app reading a field or an option that leaves is rebuilt in the same call, and the answer (a dry run too) lists each node of its tree that changed: a column, a filter, a sort key or a field of a part that only drew the field is dropped, and a filter whose field the rows no longer draw is left out, and an option leaves every list of options it stood in. What has no meaning without it refuses the call, naming the node: an act that sets a removed option, a part left with nothing to draw, a list that held only the removed option. An app drawing a field that is retyped, or a link pointed at another table, is rebuilt too, its tree unchanged: where the field no longer lets the tree draw what it drew, the call refuses, naming the node, and a field that became a formula, rollup, lookup or autonumber leaves the app\'s allowlist of saves. A workflow body its author wrote is never rewritten: it is checked again against the tables as the call leaves them, and the call refuses, naming the workflow, only if it no longer checks. A table\'s check or workflow that reads a retyped field or a link pointed elsewhere is judged the same way and refuses, naming it, only if it no longer holds. Deleting one field through the table\'s field route drops no node: an app whose tree draws the field refuses it, naming the node.\n- **A field something reads cannot go.** A query, a workflow, a check, an app only its owner can rebuild, or another\n table\'s formula, rollup, lookup or copy that reads the field refuses its deletion, naming the reader. Change or remove\n the reader first, or in the same call.\n- **`force` consents to losing values:** deleting a field rows hold, removing an option rows hold, and a change of type\n or format that does not convert every value (a date made a month cuts a day other than the 1st, a text made a time\n clears a cell holding none). Unforced, the call is refused naming the cells; the API\'s table and field routes take\n `force` in the body and refuse with `error_code` `ConversionNeedsForce`, its `findings` counting the `cells` per field. A formula, lookup or rollup holds what it computes, so it is deleted without it.\n- A field the call makes required with a `default` answers how many rows took it: `defaulted` per field alias on\n `set_tables`, `rows_defaulted` on the API\'s table and field routes.\n- A money formula is proven by its numbers. `query_records` with `aggregate` the affected totals before the change and after, and\n compare. A new field in a formula is tested for the value you want, never for differing from an empty cell, which reads\n `""` and differs from every option.\n- A check\'s expressions are written in the language of `workflows/table-checks`.\n- Views are written with `set_table_views`, not `set_tables`: `views` is keyed by a view\'s id (patch; `null` deletes) or a new key (create), and `order` lists view ids or new keys. `get_table` lists each view\'s id and name and returns the definitions with `views: true`.\n- A refused edit writes nothing and lists everything wrong; `dry_run` is for reading the grants it would make or deciding `force`.\n\nA worked call: add the option `cancelled` to `stage` (the whole list restated), add a check, and consent to losing\nwhat rows hold.\n\n```json5\n{\n "tables": [\n {\n "table_id": "<id of the table>",\n "fields": {\n "stage": {\n "options": [\n { "alias": "draft", "label": "Draft" },\n { "alias": "confirmed", "label": "Confirmed" },\n { "alias": "cancelled", "label": "Cancelled", "color": "red" }\n ]\n }\n },\n "checks": {\n "returns_after_leaves": {\n "on": ["create", "update"],\n "when": "!isNull(record.returns)",\n "fail_when": "record.returns < record.leaves",\n "message": "\\"Return before departure\\"",\n "field": "returns"\n }\n }\n }\n ],\n "force": true,\n "dry_run": true\n}\n```\n\nSplitting `queued` into waiting and underway is one call of the same shape:\n\n```json5\n{ "tables": [{ "table_id": "<id of the table>", "fields": { "stage": { "options": [\n { "alias": "draft", "label": "Draft" },\n { "alias": "queued", "label": "Waiting" },\n { "alias": "underway", "label": "Underway", "color": "green" }\n] } } }] }\n```\n\n`table_id` picks the table patched; `fields` merges by alias, so only `stage` changes; `checks` adds one under its alias\n(`null` removes it); `force` consents to losing values (leave it out unless rows hold a removed option); `dry_run`\nchecks and writes nothing, for reading the grants or deciding `force` before the call that writes.\n';
|
|
@@ -2504,7 +2504,7 @@ var COMMANDS = [
|
|
|
2504
2504
|
flags: { auth: [], "auth signup": ["--name", "--timezone", "--local"], "auth login": ["--wait", "--local"], "auth api-key": ["--local"], "auth logout": ["--all"] },
|
|
2505
2505
|
help: [
|
|
2506
2506
|
" lotics auth signup <email> Create an account, org, workspace and API key",
|
|
2507
|
-
" lotics auth login
|
|
2507
|
+
" lotics auth login Sign in to an existing account from the browser",
|
|
2508
2508
|
" lotics auth api-key | whoami | logout | web",
|
|
2509
2509
|
" Save a key, name the active account, sign out,",
|
|
2510
2510
|
" mail a web link (lotics auth prints the flags)"
|
|
@@ -28183,20 +28183,19 @@ function expirySentence(pending) {
|
|
|
28183
28183
|
return ` The request expires in ${Math.max(1, Math.round(remaining / 6e4))} minutes.`;
|
|
28184
28184
|
}
|
|
28185
28185
|
function signInInstructions(pending, options) {
|
|
28186
|
-
const ask = `Sign in from your browser: open ${signInPageUrl(pending)}
|
|
28186
|
+
const ask = `Sign in from your browser: open ${signInPageUrl(pending)}, sign in if asked, check that the page shows code ${pending.code}, pick the organization, and press Confirm.`;
|
|
28187
28187
|
const then = options.waiting ? `Waiting here until you press Confirm.${expirySentence(pending)}` : `Then run your command again \u2014 this terminal picks up the key on its next command.${expirySentence(pending)}`;
|
|
28188
28188
|
return `${ask}
|
|
28189
28189
|
${then}`;
|
|
28190
28190
|
}
|
|
28191
|
-
async function startPendingLogin(
|
|
28191
|
+
async function startPendingLogin() {
|
|
28192
28192
|
const apiUrl = envApiUrl();
|
|
28193
|
-
const request = await startCliLogin(apiUrl
|
|
28193
|
+
const request = await startCliLogin(apiUrl);
|
|
28194
28194
|
const pending = {
|
|
28195
28195
|
request_id: request.request_id,
|
|
28196
28196
|
secret: request.secret,
|
|
28197
28197
|
code: request.code,
|
|
28198
28198
|
expires_at: request.expires_at,
|
|
28199
|
-
email: email3,
|
|
28200
28199
|
api_url: apiUrl
|
|
28201
28200
|
};
|
|
28202
28201
|
savePendingLogin(pending);
|
|
@@ -28217,12 +28216,11 @@ function saveApproval(state, pending, options) {
|
|
|
28217
28216
|
workspace_id: state.workspace_id
|
|
28218
28217
|
});
|
|
28219
28218
|
noteServerOrgName(state.organization_id, state.organization_name);
|
|
28220
|
-
const
|
|
28221
|
-
saveGlobalConfig(
|
|
28219
|
+
const { email: _previousAccount, ...rest } = loadGlobalConfig() ?? {};
|
|
28220
|
+
saveGlobalConfig(rest);
|
|
28222
28221
|
setActiveOrg(state.organization_id, options?.local === true ? "local" : "global");
|
|
28223
28222
|
clearPendingLogin();
|
|
28224
28223
|
return {
|
|
28225
|
-
email: pending.email,
|
|
28226
28224
|
orgId: state.organization_id,
|
|
28227
28225
|
orgName: state.organization_name,
|
|
28228
28226
|
workspaceId: state.workspace_id
|
|
@@ -28231,7 +28229,7 @@ function saveApproval(state, pending, options) {
|
|
|
28231
28229
|
async function claimPendingLogin() {
|
|
28232
28230
|
const pending = loadPendingLogin();
|
|
28233
28231
|
if (!pending) return { status: "none" };
|
|
28234
|
-
const expired = `The sign-in request expired. Run again: lotics auth login
|
|
28232
|
+
const expired = `The sign-in request expired. Run again: lotics auth login`;
|
|
28235
28233
|
const target = envApiUrl();
|
|
28236
28234
|
if (Date.parse(pending.expires_at) <= Date.now()) {
|
|
28237
28235
|
clearPendingLogin();
|
|
@@ -28245,17 +28243,17 @@ async function claimPendingLogin() {
|
|
|
28245
28243
|
if (state.status === "pending") {
|
|
28246
28244
|
return {
|
|
28247
28245
|
status: "waiting",
|
|
28248
|
-
message: `Still waiting for Confirm on ${signInPageUrl(pending)} (code ${pending.code}). Press it, then run this again \u2014 or ask again for a new one: lotics auth login
|
|
28246
|
+
message: `Still waiting for Confirm on ${signInPageUrl(pending)} (code ${pending.code}). Press it, then run this again \u2014 or ask again for a new one: lotics auth login`
|
|
28249
28247
|
};
|
|
28250
28248
|
}
|
|
28251
28249
|
clearPendingLogin();
|
|
28252
28250
|
return {
|
|
28253
28251
|
status: "gone",
|
|
28254
|
-
message: state.status === "claimed" ? `The sign-in request was already used. Run again: lotics auth login
|
|
28252
|
+
message: state.status === "claimed" ? `The sign-in request was already used. Run again: lotics auth login` : expired
|
|
28255
28253
|
};
|
|
28256
28254
|
}
|
|
28257
|
-
async function awaitCliLogin(
|
|
28258
|
-
const pending = await startPendingLogin(
|
|
28255
|
+
async function awaitCliLogin(options) {
|
|
28256
|
+
const pending = await startPendingLogin();
|
|
28259
28257
|
console.error(signInInstructions(pending, { waiting: true }));
|
|
28260
28258
|
const expiresAt = Date.parse(pending.expires_at);
|
|
28261
28259
|
for (; ; ) {
|
|
@@ -28271,12 +28269,10 @@ async function awaitCliLogin(email3, options) {
|
|
|
28271
28269
|
return saveApproval(state, pending, options);
|
|
28272
28270
|
}
|
|
28273
28271
|
if (state.status === "expired") {
|
|
28274
|
-
throw new Error(`
|
|
28272
|
+
throw new Error(`The sign-in request expired. Run "lotics auth login" again.`);
|
|
28275
28273
|
}
|
|
28276
28274
|
if (state.status === "claimed") {
|
|
28277
|
-
throw new Error(
|
|
28278
|
-
`That sign-in link was already used. Run "lotics auth login ${email3}" for a new one.`
|
|
28279
|
-
);
|
|
28275
|
+
throw new Error(`The sign-in request was already used. Run "lotics auth login" for a new one.`);
|
|
28280
28276
|
}
|
|
28281
28277
|
await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
|
|
28282
28278
|
}
|
|
@@ -28649,7 +28645,7 @@ Lotics is an AI-powered operations platform. Through this CLI you can:
|
|
|
28649
28645
|
AUTHENTICATION
|
|
28650
28646
|
lotics auth Show auth help
|
|
28651
28647
|
lotics auth signup <email> Create account (run "lotics auth" for details)
|
|
28652
|
-
lotics auth login
|
|
28648
|
+
lotics auth login Sign in on this machine \u2014 open the page it names,
|
|
28653
28649
|
press Confirm, then run your command again
|
|
28654
28650
|
lotics auth api-key <key> Save a key \u2014 registers its org as a profile
|
|
28655
28651
|
|
|
@@ -28743,8 +28739,8 @@ function printAuthHelp() {
|
|
|
28743
28739
|
console.log(`Authentication commands:
|
|
28744
28740
|
|
|
28745
28741
|
lotics auth signup <email> Create account, org, workspace, and API key
|
|
28746
|
-
lotics auth login
|
|
28747
|
-
wait: it prints the page to open
|
|
28742
|
+
lotics auth login Sign in an account that already exists. It does NOT
|
|
28743
|
+
wait: it prints the page to open and the
|
|
28748
28744
|
code that page must show, and exits. Press Confirm,
|
|
28749
28745
|
then run your command again \u2014 this terminal picks the
|
|
28750
28746
|
key up on its next command. --wait holds the terminal
|
|
@@ -28889,7 +28885,7 @@ async function handleSignup(positionalEmail, flags) {
|
|
|
28889
28885
|
if (outcome.kind === "email_taken") {
|
|
28890
28886
|
console.error(
|
|
28891
28887
|
`An account with ${email3} already exists.
|
|
28892
|
-
Sign in on this machine: lotics auth login
|
|
28888
|
+
Sign in on this machine: lotics auth login
|
|
28893
28889
|
Which account is saved: lotics auth whoami`
|
|
28894
28890
|
);
|
|
28895
28891
|
exitCli(1);
|
|
@@ -28906,14 +28902,16 @@ Check your email for a magic link to access the Lotics web app.`);
|
|
|
28906
28902
|
function waitsForConfirm(flags) {
|
|
28907
28903
|
return flags.wait || flags.local;
|
|
28908
28904
|
}
|
|
28909
|
-
async function handleLogin(
|
|
28910
|
-
|
|
28911
|
-
|
|
28912
|
-
|
|
28905
|
+
async function handleLogin(unexpected, flags) {
|
|
28906
|
+
if (unexpected.length > 0) {
|
|
28907
|
+
console.error(
|
|
28908
|
+
`lotics auth login takes no argument (got ${unexpected.join(", ")}).
|
|
28909
|
+
Usage: lotics auth login [--wait] [--local]`
|
|
28910
|
+
);
|
|
28913
28911
|
exitCli(1);
|
|
28914
28912
|
}
|
|
28915
28913
|
if (!waitsForConfirm(flags)) {
|
|
28916
|
-
const pending = await startPendingLogin(
|
|
28914
|
+
const pending = await startPendingLogin();
|
|
28917
28915
|
console.error(signInInstructions(pending, { waiting: false }));
|
|
28918
28916
|
if (flags.json) {
|
|
28919
28917
|
console.log(
|
|
@@ -28922,7 +28920,6 @@ async function handleLogin(positionalEmail, flags) {
|
|
|
28922
28920
|
request_id: pending.request_id,
|
|
28923
28921
|
confirm_url: signInPageUrl(pending),
|
|
28924
28922
|
code: pending.code,
|
|
28925
|
-
email: pending.email,
|
|
28926
28923
|
expires_at: pending.expires_at
|
|
28927
28924
|
},
|
|
28928
28925
|
null,
|
|
@@ -28934,7 +28931,7 @@ async function handleLogin(positionalEmail, flags) {
|
|
|
28934
28931
|
}
|
|
28935
28932
|
let account;
|
|
28936
28933
|
try {
|
|
28937
|
-
account = await awaitCliLogin(
|
|
28934
|
+
account = await awaitCliLogin(flags.local ? { local: true } : {});
|
|
28938
28935
|
} catch (error62) {
|
|
28939
28936
|
console.error(error62 instanceof Error ? error62.message : String(error62));
|
|
28940
28937
|
exitCli(1);
|
|
@@ -29034,16 +29031,16 @@ async function resolveContextOrClaim(flags, options) {
|
|
|
29034
29031
|
const claim2 = await claimPendingLogin();
|
|
29035
29032
|
if (claim2.status === "signed_in") {
|
|
29036
29033
|
const { account } = claim2;
|
|
29037
|
-
note(`Signed in
|
|
29038
|
-
return { ctx: resolveContext(flags, appWorkspaceId)
|
|
29034
|
+
note(`Signed in \u2014 org ${account.orgName} (${account.orgId}).`);
|
|
29035
|
+
return { ctx: resolveContext(flags, appWorkspaceId) };
|
|
29039
29036
|
}
|
|
29040
29037
|
const resolved = resolveContext(flags, appWorkspaceId);
|
|
29041
|
-
if (claim2.status === "none") return { ctx: resolved
|
|
29038
|
+
if (claim2.status === "none") return { ctx: resolved };
|
|
29042
29039
|
if (resolved) {
|
|
29043
29040
|
note(claim2.message);
|
|
29044
|
-
return { ctx: resolved
|
|
29041
|
+
return { ctx: resolved };
|
|
29045
29042
|
}
|
|
29046
|
-
return { ctx: null,
|
|
29043
|
+
return { ctx: null, refusal: claim2.message };
|
|
29047
29044
|
}
|
|
29048
29045
|
async function requireClient(flags, appWorkspaceId) {
|
|
29049
29046
|
const { ctx, refusal } = await resolveContextOrClaim(flags, { appWorkspaceId });
|
|
@@ -29322,7 +29319,7 @@ async function dispatch(argv2) {
|
|
|
29322
29319
|
return;
|
|
29323
29320
|
}
|
|
29324
29321
|
if (subcommand === "login") {
|
|
29325
|
-
await handleLogin(toolArgs, flags);
|
|
29322
|
+
await handleLogin(toolArgs === void 0 ? restArgs : [toolArgs, ...restArgs], flags);
|
|
29326
29323
|
return;
|
|
29327
29324
|
}
|
|
29328
29325
|
if (subcommand === "api-key") {
|
package/dist/src/client.d.ts
CHANGED
|
@@ -245,17 +245,15 @@ export type CliLoginState = {
|
|
|
245
245
|
workspace_id: string;
|
|
246
246
|
};
|
|
247
247
|
/**
|
|
248
|
-
* Ask Lotics
|
|
248
|
+
* Ask Lotics for a sign-in request, and read back whether it was confirmed.
|
|
249
249
|
*
|
|
250
250
|
* Plain functions rather than `LoticsClient` methods: there is no key to build
|
|
251
251
|
* a client around, and that is the whole point — this is the pair a terminal holding NO credential
|
|
252
252
|
* uses to obtain one. Sending an `Authorization` header would make the endpoint
|
|
253
|
-
* answerable only to callers who no longer need it.
|
|
254
|
-
*
|
|
255
|
-
* The same answer whether or not the address has an account: it would
|
|
256
|
-
* otherwise tell any stranger which emails are registered here.
|
|
253
|
+
* answerable only to callers who no longer need it. The request names nobody:
|
|
254
|
+
* whoever signs in on its page and confirms is the account it is for.
|
|
257
255
|
*/
|
|
258
|
-
export declare function startCliLogin(apiUrl: string
|
|
256
|
+
export declare function startCliLogin(apiUrl: string): Promise<CliLoginRequest>;
|
|
259
257
|
export declare function pollCliLogin(apiUrl: string, request_id: string, secret: string): Promise<CliLoginState>;
|
|
260
258
|
export declare class LoticsClient {
|
|
261
259
|
private apiKey;
|
package/dist/src/client.js
CHANGED
|
@@ -210,22 +210,22 @@ function errorCode(cause) {
|
|
|
210
210
|
}
|
|
211
211
|
var WEB_APP_URL = process.env.LOTICS_WEB_URL ?? "https://lotics.ai";
|
|
212
212
|
var PUBLIC_FETCH_TIMEOUT_MS = 1e4;
|
|
213
|
-
async function startCliLogin(apiUrl
|
|
213
|
+
async function startCliLogin(apiUrl) {
|
|
214
214
|
let response;
|
|
215
215
|
try {
|
|
216
216
|
response = await fetch(`${apiUrl}/v1/cli/login_requests`, {
|
|
217
217
|
method: "POST",
|
|
218
218
|
headers: { "Content-Type": "application/json" },
|
|
219
|
-
body: JSON.stringify({
|
|
219
|
+
body: JSON.stringify({}),
|
|
220
220
|
signal: AbortSignal.timeout(PUBLIC_FETCH_TIMEOUT_MS)
|
|
221
221
|
});
|
|
222
222
|
} catch (error) {
|
|
223
223
|
throw new Error(
|
|
224
|
-
`Could not reach Lotics to
|
|
224
|
+
`Could not reach Lotics to ask for a sign-in (${error instanceof Error ? error.message : String(error)}). Check your connection, or sign in at ${WEB_APP_URL}.`
|
|
225
225
|
);
|
|
226
226
|
}
|
|
227
227
|
if (!response.ok) {
|
|
228
|
-
throw new Error(`Lotics answered ${response.status} asking for a sign-in
|
|
228
|
+
throw new Error(`Lotics answered ${response.status} asking for a sign-in.`);
|
|
229
229
|
}
|
|
230
230
|
return await response.json();
|
|
231
231
|
}
|
package/docs/cli_reference.md
CHANGED
|
@@ -6,14 +6,14 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
|
|
|
6
6
|
|---|---|
|
|
7
7
|
| `lotics` / `lotics --help` | Show full help: capabilities, the verb list (§ COMMANDS), flags, config. `lotics <verb> --help` prints that verb's entries alone (`lotics app --help`, `lotics file download --help`); `lotics report --help` prints the report frame. |
|
|
8
8
|
| `lotics auth signup <email>` | Create account + org + API key, sends magic link email. Refused on a private instance, whose people arrive by invitation; prints that creating the account accepts the Terms and Privacy Policy. Registers the new org as a profile; `--local` pins this directory to it (pointer) instead of setting the global default. |
|
|
9
|
-
| `lotics auth login
|
|
9
|
+
| `lotics auth login` | Sign in an account that already exists, on a machine holding no key. It takes no argument and sends no mail. **Two steps, and it does not wait for the person.** The first prints the page to open — `https://lotics.ai/cli_login/<request_id>` — and the code that page must show, records the request, and exits 0. They sign in there if asked, check the code, pick the organization and press Confirm. **Then the next command that needs a credential collects the key** before it does its own work, so the second step is just re-running whatever was wanted; a command run before Confirm exits 1 naming the page and the code again, and once the 15 minutes are up it says to ask again. The handful that run WITHOUT a credential — `docs` among them — claim nothing, so one of those run after Confirm still answers as though signed out. `--wait` keeps one command instead, holding the terminal until Confirm; `--local` pins this directory to that org rather than setting the global default, and implies `--wait` (a pin names THIS directory, so only the terminal that stays in it can write one). `--json` prints `organization_id`, `workspace_id` and `organization_name` when it finishes signed in, and `request_id`, `confirm_url`, `code`, `expires_at` when it is the first step. The request's secret is never printed and the org's key never leaves the store. |
|
|
10
10
|
| — | **A flag is refused on a verb that does not read it**, naming the verbs that do, before any request or credential: `--check` on `lotics run` would otherwise be parsed and ignored, and the write it was meant to stop would run. `--json`, `--workspace`, `--api-key` and `--timeout` are read by every verb. |
|
|
11
11
|
| — | **Every call a verb makes waits for the server's answer**; `--timeout <ms>` (a whole number of milliseconds from 1 to 2147483647) stops each wait early. The wait ends without an answer when `--timeout` passes or no answer arrives from the server. A read with no answer changed nothing: the command exits non-zero naming the request id. A write with no answer exits non-zero with `error_code: "outcome_unknown"` and the request id under `--json`, because it cannot say whether the call took effect: read before running it again. The one fetch outside this is the download from an object-storage signed URL, which carries no request id and is stopped by `--timeout` alone. Under `--json` every error is one object on stdout: `error`, with `error_code` and `request_id` where the error has them. |
|
|
12
12
|
| `lotics auth api-key [key]` | `whoami` → **upsert** the key's org as a profile in the global store (never overwrites). The profile records the instance the key was verified against (`LOTICS_API_URL`, default `https://api.lotics.ai`), and every later command for that org goes there. `--local` additionally pins this directory to it (pointer) instead of setting the global default. |
|
|
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 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.` carries `Run \`lotics auth login
|
|
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.` carries `Run \`lotics auth login\` 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. |
|