@softr/cli 0.1.5 → 0.1.6

package/README.md

@@ -241,10 +241,18 @@ crm/
 | `db fields update <table> <field> [--name] [--type] [--options <json>] [--[no-]multiple]`     | Change a field; what is not passed stays as it is, `--options` replaces the options as a whole.                                                                                                 |
 | `db fields delete <table> <field>`                                                            | Delete a field and its values in every record.                                                                                                                                                  |
 | `db views list <table>`                                                                       | The views of a table (the API reads views only).                                                                                                                                                |
+| `db records list <table> [--view <view>] [--limit <n>] [--offset <n>] [--all]`                | Records through a view, the table's default view unless `--view`; one page or `--all` in pages of 200.                                                                                          |
+| `db records search <table> [--filter <json>] [--sort <field[:desc]>]...`                      | Records by a filter ([operators](https://docs.softr.io/softr-api/softr-database-api/records/search-records)); without `--filter`, every record.                                                 |
+| `db records get <table> <recordId>`                                                           | One record.                                                                                                                                                                                     |
+| `db records create <table> --fields <json>` / `update <table> <recordId> --fields <json>`     | Create a record, or change some of its fields. `--fields` is inline JSON, `@<file>` or `-`.                                                                                                     |
+| `db records delete <table> <recordId>`                                                        | Delete a record.                                                                                                                                                                                |
+| `db records upload <table> <recordId> <field> <file> [--name <fileName>]`                     | Add a local file to an attachment field, stored under the local file name unless `--name`.                                                                                                      |
 
 Tables and fields take an id or an exact name; a name two items share is an error that lists their ids. The table,
 field and view commands take the database from `--database <id>`, else `SOFTR_DATABASE_ID`, else the database
 directory, and keep its cache current; a delete always resolves the name on the server, never from the cache.
+Records are keyed by field name in the output and take field names in `--fields`, filters and `--sort`; the CLI maps
+them to ids, which the API needs. `--field-ids` keys the output by id. Records are never written to disk.
 
 ## Agent skills
 

package/dist/cli.mjs

@@ -2661,8 +2661,8 @@ var Option = class {
    * @param {(string | string[])} names
    * @return {Option}
    */
-  conflicts(names) {
-    this.conflictsWith = this.conflictsWith.concat(names);
+  conflicts(names2) {
+    this.conflictsWith = this.conflictsWith.concat(names2);
     return this;
   }
   /**
@@ -3268,8 +3268,8 @@ var Command = class _Command extends EventEmitter {
    * @param {string} names
    * @return {Command} `this` command for chaining
    */
-  arguments(names) {
-    names.trim().split(/ +/).forEach((detail) => {
+  arguments(names2) {
+    names2.trim().split(/ +/).forEach((detail) => {
       this.argument(detail);
     });
     return this;
@@ -4951,9 +4951,9 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * @param {string} [path]
    * @return {(string|null|Command)}
    */
-  executableDir(path15) {
-    if (path15 === void 0) return this._executableDir;
-    this._executableDir = path15;
+  executableDir(path16) {
+    if (path16 === void 0) return this._executableDir;
+    this._executableDir = path16;
     return this;
   }
   /**
@@ -5310,12 +5310,12 @@ function executionOrder(config) {
   collect(config.actions, []);
   const outgoing = new Map(appearance.map((id) => [id, []]));
   const indegree = new Map(appearance.map((id) => [id, 0]));
-  for (const path15 of pathSets.flat()) {
-    const to = path15.toActionId;
-    if (!to || !nodes.has(path15.fromActionId) || !nodes.has(to) || outgoing.get(path15.fromActionId).includes(to)) {
+  for (const path16 of pathSets.flat()) {
+    const to = path16.toActionId;
+    if (!to || !nodes.has(path16.fromActionId) || !nodes.has(to) || outgoing.get(path16.fromActionId).includes(to)) {
       continue;
     }
-    outgoing.get(path15.fromActionId).push(to);
+    outgoing.get(path16.fromActionId).push(to);
     indegree.set(to, indegree.get(to) + 1);
   }
   const queue = [...nodes.values()].filter((node) => node.kind === "trigger").map((node) => node.id);
@@ -6130,43 +6130,45 @@ var BASE_URLS = {
   studio: (target) => target.studioApiUrl,
   tables: (target) => target.tablesApiUrl
 };
-async function send(client, service, method, path15, body) {
+async function send(client, service, method, path16, body) {
   const init = {
     method,
     headers: { ...authHeaders(client, service), Accept: "application/json" }
   };
-  if (body !== void 0) {
+  if (body instanceof FormData) {
+    init.body = body;
+  } else if (body !== void 0) {
     init.headers = { ...init.headers, "Content-Type": "application/json" };
     init.body = JSON.stringify(body);
   }
-  const response = await fetch(`${BASE_URLS[service](client.target)}${path15}`, init);
+  const response = await fetch(`${BASE_URLS[service](client.target)}${path16}`, init);
   if (response.ok) {
     return response;
   }
   const text = await response.text();
   throw new SoftrApiError(
-    `${method} ${path15} failed with status ${response.status}${text ? `: ${text}` : ""}`,
+    `${method} ${path16} failed with status ${response.status}${text ? `: ${text}` : ""}`,
     response.status,
     text,
     hintFor(response.status, client, service)
   );
 }
-async function apiRequest(client, method, path15, body) {
-  const response = await send(client, "workflows", method, path15, body);
+async function apiRequest(client, method, path16, body) {
+  const response = await send(client, "workflows", method, path16, body);
   return await response.json();
 }
-async function apiRequestVoid(client, method, path15, body) {
-  await send(client, "workflows", method, path15, body);
+async function apiRequestVoid(client, method, path16, body) {
+  await send(client, "workflows", method, path16, body);
 }
-async function tablesRequest(client, method, path15, body) {
-  const response = await send(client, "tables", method, path15, body);
+async function tablesRequest(client, method, path16, body) {
+  const response = await send(client, "tables", method, path16, body);
   return await response.json();
 }
-async function tablesRequestVoid(client, method, path15, body) {
-  await send(client, "tables", method, path15, body);
+async function tablesRequestVoid(client, method, path16, body) {
+  await send(client, "tables", method, path16, body);
 }
-async function studioRequest(client, method, path15, body) {
-  const response = await send(client, "studio", method, path15, body);
+async function studioRequest(client, method, path16, body) {
+  const response = await send(client, "studio", method, path16, body);
   return await response.json();
 }
 
@@ -6992,12 +6994,12 @@ function parseTree(text, errors = [], options = ParseOptions.DEFAULT) {
   }
   return result;
 }
-function findNodeAtLocation(root, path15) {
+function findNodeAtLocation(root, path16) {
   if (!root) {
     return void 0;
   }
   let node = root;
-  for (let segment of path15) {
+  for (let segment of path16) {
     if (typeof segment === "string") {
       if (node.type !== "object" || !Array.isArray(node.children)) {
         return void 0;
@@ -7351,14 +7353,14 @@ function getNodeType(value) {
 
 // node_modules/jsonc-parser/lib/esm/impl/edit.js
 function setProperty(text, originalPath, value, options) {
-  const path15 = originalPath.slice();
+  const path16 = originalPath.slice();
   const errors = [];
   const root = parseTree(text, errors);
   let parent = void 0;
   let lastSegment = void 0;
-  while (path15.length > 0) {
-    lastSegment = path15.pop();
-    parent = findNodeAtLocation(root, path15);
+  while (path16.length > 0) {
+    lastSegment = path16.pop();
+    parent = findNodeAtLocation(root, path16);
     if (parent === void 0 && value !== void 0) {
       if (typeof lastSegment === "string") {
         value = { [lastSegment]: value };
@@ -7581,8 +7583,8 @@ function printParseErrorCode(code) {
   }
   return "<unknown ParseErrorCode>";
 }
-function modify(text, path15, value, options) {
-  return setProperty(text, path15, value, options);
+function modify(text, path16, value, options) {
+  return setProperty(text, path16, value, options);
 }
 function applyEdits(text, edits) {
   let sortedEdits = edits.slice(0).sort((a, b) => {
@@ -13593,8 +13595,8 @@ function typeOfField(field) {
   return field.allowMultipleEntries ? arrayOf(base) : base;
 }
 var SEGMENT = /^(?:\.?\[\s*'((?:[^'\\]|\\.)*)'\s*\]|\.?\[\s*"((?:[^"\\]|\\.)*)"\s*\]|\.?\[\s*(\d+)\s*\]|\.?\[\s*\*\s*\]|\.([^.[\]]+))/;
-function parsePath(path15) {
-  let rest = path15.trim();
+function parsePath(path16) {
+  let rest = path16.trim();
   if (rest.startsWith("$")) {
     rest = rest.slice(1);
   }
@@ -14094,10 +14096,10 @@ function describePlaceholder(placeholder, raw, config, outputs, depth) {
 function untested(nodeId) {
   return `node "${nodeId}" has no test output yet (run: softr workflows test ${nodeId})`;
 }
-function describeOutputRef(nodeId, path15, source, outputs) {
-  const segments = parsePath(path15);
+function describeOutputRef(nodeId, path16, source, outputs) {
+  const segments = parsePath(path16);
   if (!segments) {
-    return { type: UNKNOWN, source, verified: false, note: `unsupported path "${path15}"` };
+    return { type: UNKNOWN, source, verified: false, note: `unsupported path "${path16}"` };
   }
   const row = outputs[nodeId];
   if (!row) {
@@ -14608,6 +14610,73 @@ async function deleteField(client, databaseId, tableId, fieldId) {
 async function listViews(client, databaseId, tableId) {
   return (await tablesRequest(client, "GET", `${tablePath(databaseId, tableId)}/views`)).data;
 }
+function recordsPath(databaseId, tableId, recordId) {
+  const records = `${tablePath(databaseId, tableId)}/records`;
+  return recordId ? `${records}/${encodeURIComponent(recordId)}` : records;
+}
+function names(fieldNames) {
+  return fieldNames ? "fieldNames=true" : "fieldNames=false";
+}
+async function listRecords(client, databaseId, tableId, query) {
+  const params = new URLSearchParams({ offset: String(query.offset), limit: String(query.limit) });
+  if (query.viewId) {
+    params.set("viewId", query.viewId);
+  }
+  const response = await tablesRequest(
+    client,
+    "GET",
+    `${recordsPath(databaseId, tableId)}?${params.toString()}&${names(query.fieldNames)}`
+  );
+  return { records: response.data, metadata: response.metadata };
+}
+async function searchRecords(client, databaseId, tableId, search, fieldNames) {
+  const response = await tablesRequest(
+    client,
+    "POST",
+    `${recordsPath(databaseId, tableId)}/search?${names(fieldNames)}`,
+    search
+  );
+  return { records: response.data, metadata: response.metadata };
+}
+async function getRecord(client, databaseId, tableId, recordId, fieldNames) {
+  return (await tablesRequest(
+    client,
+    "GET",
+    `${recordsPath(databaseId, tableId, recordId)}?${names(fieldNames)}`
+  )).data;
+}
+async function createRecord(client, databaseId, tableId, fields, fieldNames) {
+  return (await tablesRequest(
+    client,
+    "POST",
+    `${recordsPath(databaseId, tableId)}?${names(fieldNames)}`,
+    {
+      fields
+    }
+  )).data;
+}
+async function updateRecord(client, databaseId, tableId, recordId, fields, fieldNames) {
+  return (await tablesRequest(
+    client,
+    "PATCH",
+    `${recordsPath(databaseId, tableId, recordId)}?${names(fieldNames)}`,
+    { fields }
+  )).data;
+}
+async function deleteRecord(client, databaseId, tableId, recordId) {
+  await tablesRequestVoid(client, "DELETE", recordsPath(databaseId, tableId, recordId));
+}
+async function uploadAttachment(client, databaseId, tableId, recordId, fieldId, file) {
+  const form = new FormData();
+  form.set("file", new Blob([file.content]), file.name);
+  form.set("fileName", file.name);
+  return (await tablesRequest(
+    client,
+    "PUT",
+    `${recordsPath(databaseId, tableId, recordId)}/fields/${encodeURIComponent(fieldId)}/upload-attachment`,
+    form
+  )).data;
+}
 
 // src/config/credentials.ts
 import { chmod, mkdir as mkdir4, readFile as readFile5, writeFile as writeFile5 } from "node:fs/promises";
@@ -14645,8 +14714,8 @@ function refreshFailureHint(status) {
   return status === 401 ? "The OAuth grant is gone (revoked or older than 30 days). Run: softr login" : "The studio could not renew the login right now; try again in a moment.";
 }
 async function tokenRequest(target, form) {
-  const path15 = "/v1/oauth/token";
-  const response = await fetch(`${target.studioApiUrl}${path15}`, {
+  const path16 = "/v1/oauth/token";
+  const response = await fetch(`${target.studioApiUrl}${path16}`, {
     method: "POST",
     headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
     body: new URLSearchParams({ ...form, client_id: oauthClientId() }).toString()
@@ -14654,7 +14723,7 @@ async function tokenRequest(target, form) {
   if (!response.ok) {
     const text = await response.text();
     throw new SoftrApiError(
-      `POST ${path15} failed with status ${response.status}${text ? `: ${text}` : ""}`,
+      `POST ${path16} failed with status ${response.status}${text ? `: ${text}` : ""}`,
       response.status,
       text,
       form["grant_type"] === "refresh_token" ? refreshFailureHint(response.status) : void 0
@@ -14898,15 +14967,25 @@ async function writeSchemaCache(dir, database, tables) {
 function viewsDir(dir) {
   return path8.join(dir, DB_CACHE_DIR_NAME, "views");
 }
+async function readViewsCache(dir, tableId) {
+  try {
+    return JSON.parse(await readFile6(path8.join(viewsDir(dir), `${tableId}.json`), "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return void 0;
+    }
+    throw error;
+  }
+}
 async function writeViewsCache(dir, tableId, views) {
   const value = { tableId, views, refreshedAt: (/* @__PURE__ */ new Date()).toISOString() };
   await mkdir5(viewsDir(dir), { recursive: true });
   await writeFile6(path8.join(viewsDir(dir), `${tableId}.json`), JSON.stringify(value, null, 2) + "\n");
 }
 async function pruneViewsCache(dir, tableIds) {
-  let names;
+  let names2;
   try {
-    names = await readdir2(viewsDir(dir));
+    names2 = await readdir2(viewsDir(dir));
   } catch (error) {
     if (error.code === "ENOENT") {
       return;
@@ -14914,7 +14993,7 @@ async function pruneViewsCache(dir, tableIds) {
     throw error;
   }
   await Promise.all(
-    names.filter((name) => name.endsWith(".json") && !tableIds.has(name.slice(0, -".json".length))).map((name) => rm(path8.join(viewsDir(dir), name), { force: true }))
+    names2.filter((name) => name.endsWith(".json") && !tableIds.has(name.slice(0, -".json".length))).map((name) => rm(path8.join(viewsDir(dir), name), { force: true }))
   );
 }
 async function refreshSchemaCache(client, dir, databaseId) {
@@ -15603,8 +15682,9 @@ ${path11.join(relativeDir(process.cwd(), target.dir), DB_CONFIG_FILE_NAME)} stil
   });
 }
 
-// src/commands/db/schema.ts
-var import_cli_table32 = __toESM(require_cli_table3(), 1);
+// src/commands/db/records.ts
+import { readFile as readFile9 } from "node:fs/promises";
+import path12 from "node:path";
 
 // src/commands/db/json-input.ts
 import { readFile as readFile8 } from "node:fs/promises";
@@ -15617,7 +15697,11 @@ async function readJsonArgument(value, option, hint) {
     }
     text = Buffer.concat(chunks).toString("utf8");
   } else if (value.startsWith("@")) {
-    text = await readFile8(value.slice(1), "utf8");
+    try {
+      text = await readFile8(value.slice(1), "utf8");
+    } catch {
+      throw new CliError(`Cannot read ${value.slice(1)} for ${option}.`);
+    }
   }
   try {
     return JSON.parse(text);
@@ -15627,6 +15711,7 @@ async function readJsonArgument(value, option, hint) {
 }
 
 // src/commands/db/schema.ts
+var import_cli_table32 = __toESM(require_cli_table3(), 1);
 var FIELD_REFERENCE_URL = "https://docs.softr.io/softr-api/softr-database-api/table-fields/add-table-field";
 var TABLE_ARGUMENT = "the table id or exact name";
 var FIELD_ARGUMENT = "the field id or exact name";
@@ -15666,6 +15751,50 @@ async function findTableCached(context, reference) {
   const cached = context.dir && context.cache ? byIdOrName(context.cache.tables, reference, "table") : void 0;
   return cached ?? findTableOnServer(context, reference);
 }
+async function findFields(context, table, references) {
+  const resolve = (current3) => {
+    const fields2 = /* @__PURE__ */ new Map();
+    for (const reference of references) {
+      const field = byIdOrName(current3.fields, reference, "field");
+      if (field) {
+        fields2.set(reference, field);
+      }
+    }
+    return fields2;
+  };
+  let current2 = table;
+  let fields = resolve(current2);
+  if (fields.size < new Set(references).size && context.dir) {
+    current2 = await findTableOnServer(context, table.id);
+    fields = resolve(current2);
+  }
+  const missing = references.filter((reference) => !fields.has(reference));
+  if (missing.length) {
+    throw new CliError(
+      `Table ${current2.name} has no field with the id or name ${missing.map((name) => `"${name}"`).join(", ")}.`,
+      `"softr db tables get ${current2.id}" shows its fields.`
+    );
+  }
+  return { table: current2, fields };
+}
+async function readViews(context, table) {
+  const views = await listViews(context.client, context.databaseId, table.id);
+  if (context.dir) {
+    await writeViewsCache(context.dir, table.id, views);
+  }
+  return views;
+}
+async function findView(context, table, reference) {
+  const cached = context.dir ? (await readViewsCache(context.dir, table.id))?.views : void 0;
+  const view = (cached ? byIdOrName(cached, reference, "view") : void 0) ?? byIdOrName(await readViews(context, table), reference, "view");
+  if (!view) {
+    throw new CliError(
+      `Table ${table.name} has no view with the id or name "${reference}".`,
+      `"softr db views list ${table.id}" shows its views.`
+    );
+  }
+  return view;
+}
 async function findField(context, tableReference, reference) {
   const table = await findTableOnServer(context, tableReference);
   const field = byIdOrName(table.fields, reference, "field");
@@ -15682,15 +15811,8 @@ async function afterSchemaWrite(context) {
     context.cache = await refreshSchemaCache(context.client, context.dir, context.databaseId);
   }
 }
-function parseOptions(json) {
-  if (json === void 0) {
-    return void 0;
-  }
-  try {
-    return JSON.parse(json);
-  } catch {
-    throw new CliError("--options is not valid JSON.", `The options of each field type: ${FIELD_REFERENCE_URL}`);
-  }
+function parseOptions(value) {
+  return value === void 0 ? Promise.resolve(void 0) : readJsonArgument(value, "--options", `The options of each field type: ${FIELD_REFERENCE_URL}`);
 }
 function parseFieldSpec(spec) {
   const colon = spec.lastIndexOf(":");
@@ -15860,11 +15982,11 @@ function registerFields(db2) {
     emit(options, renderField(table, field), { tableId: table.id, field });
   });
   withDatabaseOptions(
-    fields.command("add").description("Add a field to a table").argument("<table>", TABLE_ARGUMENT).argument("<name>", "the field name").requiredOption("--type <TYPE>", "the field type, for example SINGLE_LINE_TEXT, NUMBER, SELECT, LINKED_RECORD").option("--options <json>", `the type's options as JSON (${FIELD_REFERENCE_URL})`).option("--description <text>", "what the field holds").option("--multiple", "allow several values (SELECT, LINKED_RECORD, USER, ATTACHMENT)")
+    fields.command("add").description("Add a field to a table").argument("<table>", TABLE_ARGUMENT).argument("<name>", "the field name").requiredOption("--type <TYPE>", "the field type, for example SINGLE_LINE_TEXT, NUMBER, SELECT, LINKED_RECORD").option("--options <json>", `the type's options as JSON, @<file> or - for stdin (${FIELD_REFERENCE_URL})`).option("--description <text>", "what the field holds").option("--multiple", "allow several values (SELECT, LINKED_RECORD, USER, ATTACHMENT)")
   ).action(
     async (tableReference, name, opts, command) => {
       const options = globalOptions(command);
-      const fieldOptions = parseOptions(opts.options);
+      const fieldOptions = await parseOptions(opts.options);
       const context = await schemaContext(opts);
       const table = await findTableCached(context, tableReference);
       const field = await addField(context.client, context.databaseId, table.id, {
@@ -15882,10 +16004,13 @@ function registerFields(db2) {
     }
   );
   withDatabaseOptions(
-    fields.command("update").description("Change a field: what is not passed stays as it is").argument("<table>", TABLE_ARGUMENT).argument("<field>", FIELD_ARGUMENT).option("--name <name>", "the new name").option("--type <TYPE>", "the new type").option("--options <json>", `the new options as JSON, replacing the current ones (${FIELD_REFERENCE_URL})`).option("--description <text>", "the new description").option("--multiple", "allow several values").option("--no-multiple", "allow one value only")
+    fields.command("update").description("Change a field: what is not passed stays as it is").argument("<table>", TABLE_ARGUMENT).argument("<field>", FIELD_ARGUMENT).option("--name <name>", "the new name").option("--type <TYPE>", "the new type").option(
+      "--options <json>",
+      `the new options as JSON, @<file> or - for stdin, replacing the current ones (${FIELD_REFERENCE_URL})`
+    ).option("--description <text>", "the new description").option("--multiple", "allow several values").option("--no-multiple", "allow one value only")
   ).action(
     async (tableReference, reference, opts, command) => {
-      const fieldOptions = parseOptions(opts.options);
+      const fieldOptions = await parseOptions(opts.options);
       if (!opts.name && !opts.type && fieldOptions === void 0 && opts.description === void 0 && opts.multiple === void 0) {
         throw new CliError("Nothing to change: pass --name, --type, --options, --description or --[no-]multiple.");
       }
@@ -15930,17 +16055,299 @@ function registerViews(db2) {
     const options = globalOptions(command);
     const context = await schemaContext(opts);
     const table = await findTableOnServer(context, reference);
-    const items = await listViews(context.client, context.databaseId, table.id);
-    if (context.dir) {
-      await writeViewsCache(context.dir, table.id, items);
-    }
+    const items = await readViews(context, table);
     emit(options, renderViews(items), { tableId: table.id, views: items });
   });
 }
 
+// src/commands/db/records.ts
+var SEARCH_DOCS_URL = "https://docs.softr.io/softr-api/softr-database-api/records/search-records";
+var MAX_PAGE = 200;
+function withOutputOptions(command) {
+  return command.option("--field-ids", "key record fields by field id instead of field name");
+}
+function withPagingOptions(command) {
+  return command.option("--limit <n>", `records per page, 1 to ${MAX_PAGE} (default 20)`).option("--offset <n>", "records to skip (default 0)").option("--all", `every record, read in pages of ${MAX_PAGE}`);
+}
+function parseCount(value, option, max) {
+  if (value === void 0) {
+    return void 0;
+  }
+  const count = Number(value);
+  if (!Number.isInteger(count) || count < 0 || max !== void 0 && (count < 1 || count > max)) {
+    throw new CliError(`${option} must be a whole number${max ? ` from 1 to ${max}` : " of 0 or more"}.`);
+  }
+  return count;
+}
+function paging(opts) {
+  if (opts.all && opts.limit !== void 0) {
+    throw new CliError("Pass --all or --limit, not both.");
+  }
+  return {
+    offset: parseCount(opts.offset, "--offset") ?? 0,
+    limit: opts.all ? MAX_PAGE : parseCount(opts.limit, "--limit", MAX_PAGE) ?? 20,
+    all: opts.all === true
+  };
+}
+async function readPages(first, read) {
+  const page = await read(first.offset, first.limit);
+  if (!first.all) {
+    return page;
+  }
+  const records = [...page.records];
+  let offset2 = first.offset + page.records.length;
+  while (page.records.length && offset2 < page.metadata.total) {
+    const next = await read(offset2, first.limit);
+    if (!next.records.length) {
+      break;
+    }
+    records.push(...next.records);
+    offset2 += next.records.length;
+  }
+  return { records, metadata: { offset: first.offset, limit: records.length, total: page.metadata.total } };
+}
+function asObject(value, option) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new CliError(`${option} must be a JSON object.`);
+  }
+  return value;
+}
+async function fieldIdsFor(context, table, references) {
+  const found = await findFields(context, table, references);
+  return { table: found.table, ids: new Map([...found.fields].map(([reference, field]) => [reference, field.id])) };
+}
+async function mapFieldKeys(context, table, fields) {
+  const { ids } = await fieldIdsFor(context, table, Object.keys(fields));
+  return Object.fromEntries(Object.entries(fields).map(([key, value]) => [ids.get(key), value]));
+}
+function fieldReferences(condition, found) {
+  if (Array.isArray(condition)) {
+    condition.forEach((item) => fieldReferences(item, found));
+  } else if (condition && typeof condition === "object") {
+    for (const [key, value] of Object.entries(condition)) {
+      if (key === "leftSide" && typeof value === "string") {
+        found.add(value);
+      } else {
+        fieldReferences(value, found);
+      }
+    }
+  }
+}
+function replaceFieldReferences(condition, ids) {
+  if (Array.isArray(condition)) {
+    return condition.map((item) => replaceFieldReferences(item, ids));
+  }
+  if (condition && typeof condition === "object") {
+    return Object.fromEntries(
+      Object.entries(condition).map(([key, value]) => [
+        key,
+        key === "leftSide" && typeof value === "string" ? ids.get(value) ?? value : replaceFieldReferences(value, ids)
+      ])
+    );
+  }
+  return condition;
+}
+function parseSort(spec) {
+  const colon = spec.lastIndexOf(":");
+  const direction = colon > 0 ? spec.slice(colon + 1).trim().toUpperCase() : "";
+  if (direction === "ASC" || direction === "DESC") {
+    return { field: spec.slice(0, colon).trim(), sortType: direction };
+  }
+  return { field: spec.trim(), sortType: "ASC" };
+}
+function withFieldNames(record, table) {
+  const names2 = new Map(table.fields.map((field) => [field.id, field.name]));
+  return {
+    ...record,
+    fields: Object.fromEntries(Object.entries(record.fields).map(([key, value]) => [names2.get(key) ?? key, value]))
+  };
+}
+function formatValue(value) {
+  return typeof value === "string" ? value : JSON.stringify(value);
+}
+function renderRecord(record) {
+  return [record.id, ...Object.entries(record.fields).map(([key, value]) => `  ${key}: ${formatValue(value)}`)].join(
+    "\n"
+  );
+}
+function renderPage(page) {
+  if (!page.records.length) {
+    return page.metadata.total ? `No records from offset ${page.metadata.offset}; ${page.metadata.total} in all.` : "No records.";
+  }
+  const shown = page.records.length;
+  const end = page.metadata.offset + shown;
+  const footer = end < page.metadata.total ? `${shown} of ${page.metadata.total} records; --offset ${end} for the next ones, or --all.` : `${shown} of ${page.metadata.total} records.`;
+  return [...page.records.map(renderRecord), footer].join("\n\n");
+}
+function registerRecords(db2) {
+  const records = db2.command("records").description("The records of a table; fields are keyed by name unless --field-ids");
+  withOutputOptions(
+    withPagingOptions(
+      withDatabaseOptions(
+        records.command("list").description(
+          `List a table's records in the order and with the filter of a view, the table's default view unless --view; "records search" without --filter reads every record`
+        ).argument("<table>", TABLE_ARGUMENT).option("--view <view>", "the view id or exact name (default: the table's default view)")
+      )
+    )
+  ).action(
+    async (reference, opts, command) => {
+      const options = globalOptions(command);
+      const pages = paging(opts);
+      const context = await schemaContext(opts);
+      const table = await findTableCached(context, reference);
+      const viewId = opts.view ? (await findView(context, table, opts.view)).id : void 0;
+      const page = await readPages(
+        pages,
+        (offset2, limit) => listRecords(context.client, context.databaseId, table.id, {
+          viewId,
+          offset: offset2,
+          limit,
+          fieldNames: !opts.fieldIds
+        })
+      );
+      emit(options, renderPage(page), { tableId: table.id, ...page });
+    }
+  );
+  withOutputOptions(
+    withPagingOptions(
+      withDatabaseOptions(
+        records.command("search").description("Find records by a filter, sorted by fields").argument("<table>", TABLE_ARGUMENT).option(
+          "--filter <json>",
+          `the condition as JSON, @<file> or - for stdin; leftSide takes a field name or id (operators: ${SEARCH_DOCS_URL})`
+        ).option(
+          "--sort <field[:asc|desc]>",
+          "sort by a field, repeatable",
+          (value, previous) => [...previous, value],
+          []
+        )
+      )
+    )
+  ).action(
+    async (reference, opts, command) => {
+      const options = globalOptions(command);
+      const pages = paging(opts);
+      const parsed = opts.filter === void 0 ? void 0 : asObject(await readJsonArgument(opts.filter, "--filter"), "--filter");
+      const condition = parsed && "condition" in parsed ? parsed["condition"] : parsed;
+      const sorts = opts.sort.map(parseSort);
+      const context = await schemaContext(opts);
+      const references = new Set(sorts.map((sort) => sort.field));
+      fieldReferences(condition, references);
+      const { table, ids } = await fieldIdsFor(context, await findTableCached(context, reference), [...references]);
+      const search = (offset2, limit) => ({
+        paging: { offset: offset2, limit },
+        ...sorts.length ? { sorting: sorts.map((sort) => ({ sortingField: ids.get(sort.field), sortType: sort.sortType })) } : {},
+        ...condition === void 0 ? {} : { filter: { condition: replaceFieldReferences(condition, ids) } }
+      });
+      const page = await readPages(
+        pages,
+        (offset2, limit) => searchRecords(context.client, context.databaseId, table.id, search(offset2, limit), !opts.fieldIds)
+      );
+      emit(options, renderPage(page), { tableId: table.id, ...page });
+    }
+  );
+  withOutputOptions(
+    withDatabaseOptions(
+      records.command("get").description("Show one record").argument("<table>", TABLE_ARGUMENT).argument("<recordId>", "the record id")
+    )
+  ).action(async (reference, recordId, opts, command) => {
+    const options = globalOptions(command);
+    const context = await schemaContext(opts);
+    const table = await findTableCached(context, reference);
+    const record = await getRecord(context.client, context.databaseId, table.id, recordId, !opts.fieldIds);
+    emit(options, renderRecord(record), { tableId: table.id, record });
+  });
+  withOutputOptions(
+    withDatabaseOptions(
+      records.command("create").description("Create a record").argument("<table>", TABLE_ARGUMENT).requiredOption(
+        "--fields <json>",
+        "the values as a JSON object keyed by field name or id, @<file> or - for stdin; {} creates an empty record"
+      )
+    )
+  ).action(async (reference, opts, command) => {
+    const options = globalOptions(command);
+    const fields = asObject(await readJsonArgument(opts.fields, "--fields"), "--fields");
+    const context = await schemaContext(opts);
+    const table = await findTableCached(context, reference);
+    const record = await createRecord(
+      context.client,
+      context.databaseId,
+      table.id,
+      await mapFieldKeys(context, table, fields),
+      !opts.fieldIds
+    );
+    emit(options, `Created record ${record.id} in ${table.name}.`, { tableId: table.id, record });
+  });
+  withOutputOptions(
+    withDatabaseOptions(
+      records.command("update").description("Change some fields of a record; the others keep their values").argument("<table>", TABLE_ARGUMENT).argument("<recordId>", "the record id").requiredOption(
+        "--fields <json>",
+        "the new values as a JSON object keyed by field name or id, @<file> or - for stdin; null clears a field"
+      )
+    )
+  ).action(
+    async (reference, recordId, opts, command) => {
+      const options = globalOptions(command);
+      const fields = asObject(await readJsonArgument(opts.fields, "--fields"), "--fields");
+      if (!Object.keys(fields).length) {
+        throw new CliError("Nothing to change: --fields is an empty object.");
+      }
+      const context = await schemaContext(opts);
+      const table = await findTableCached(context, reference);
+      const record = await updateRecord(
+        context.client,
+        context.databaseId,
+        table.id,
+        recordId,
+        await mapFieldKeys(context, table, fields),
+        !opts.fieldIds
+      );
+      emit(options, `Updated record ${record.id} in ${table.name}.`, { tableId: table.id, record });
+    }
+  );
+  withDatabaseOptions(
+    records.command("delete").description("Delete a record").argument("<table>", TABLE_ARGUMENT).argument("<recordId>", "the record id")
+  ).action(async (reference, recordId, opts, command) => {
+    const options = globalOptions(command);
+    const context = await schemaContext(opts);
+    const table = await findTableOnServer(context, reference);
+    await deleteRecord(context.client, context.databaseId, table.id, recordId);
+    emit(options, `Deleted record ${recordId} from ${table.name}.`, { tableId: table.id, deleted: recordId });
+  });
+  withOutputOptions(
+    withDatabaseOptions(
+      records.command("upload").description("Add a local file to a record's attachment field").argument("<table>", TABLE_ARGUMENT).argument("<recordId>", "the record id").argument("<field>", "the attachment field, by id or exact name").argument("<file>", "the file to upload").option("--name <fileName>", "the file name to store (default: the local file name)")
+    )
+  ).action(
+    async (reference, recordId, fieldReference, file, opts, command) => {
+      const options = globalOptions(command);
+      let content;
+      try {
+        content = await readFile9(file);
+      } catch {
+        throw new CliError(`Cannot read ${file}.`);
+      }
+      const context = await schemaContext(opts);
+      const found = await findFields(context, await findTableCached(context, reference), [fieldReference]);
+      const field = found.fields.get(fieldReference);
+      if (field.type !== "ATTACHMENT") {
+        throw new CliError(`Field "${fieldReference}" has the type ${field.type}; upload needs an ATTACHMENT field.`);
+      }
+      const uploaded = await uploadAttachment(context.client, context.databaseId, found.table.id, recordId, field.id, {
+        name: opts.name ?? path12.basename(file),
+        content
+      });
+      const record = opts.fieldIds ? uploaded : withFieldNames(uploaded, found.table);
+      emit(options, `Uploaded ${opts.name ?? path12.basename(file)} to record ${record.id} in ${found.table.name}.`, {
+        tableId: found.table.id,
+        record
+      });
+    }
+  );
+}
+
 // src/commands/integrations.ts
 var import_cli_table33 = __toESM(require_cli_table3(), 1);
-import path12 from "node:path";
+import path13 from "node:path";
 function toRow(integration) {
   return {
     id: integration.id,
@@ -15972,7 +16379,7 @@ Use the ID as the integrationId input of a node (see "spec <TYPE>").`;
 }
 async function workflowDirOf(cwd, dir) {
   if (dir) {
-    return path12.resolve(cwd, dir);
+    return path13.resolve(cwd, dir);
   }
   return await configExists(cwd) ? cwd : void 0;
 }
@@ -16386,28 +16793,28 @@ function renderIssues(issues) {
 
 // src/project/variables.ts
 var MAX_VARIABLES = 200;
-function appendKey(path15, key) {
-  return /^[A-Za-z_]\w*$/.test(key) ? `${path15}.${key}` : `${path15}['${key.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}']`;
+function appendKey(path16, key) {
+  return /^[A-Za-z_]\w*$/.test(key) ? `${path16}.${key}` : `${path16}['${key.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}']`;
 }
 function isPrimitive2(value) {
   return value !== void 0 && value !== null && typeof value !== "object";
 }
-function walk(type, raw, path15, token, out) {
+function walk(type, raw, path16, token, out) {
   if (out.length >= MAX_VARIABLES) {
     return;
   }
-  out.push({ variable: token(path15), path: path15, type, ...isPrimitive2(raw) ? { example: raw } : {} });
+  out.push({ variable: token(path16), path: path16, type, ...isPrimitive2(raw) ? { example: raw } : {} });
   if (type.kind === "object") {
     for (const [key, field] of Object.entries(type.fields)) {
       const rawField = raw !== null && typeof raw === "object" && !Array.isArray(raw) ? raw[key] : void 0;
-      walk(field.type, rawField, appendKey(path15, key), token, out);
+      walk(field.type, rawField, appendKey(path16, key), token, out);
     }
   } else if (type.kind === "array") {
-    walk(type.items, Array.isArray(raw) ? raw[0] : void 0, `${path15}[*]`, token, out);
+    walk(type.items, Array.isArray(raw) ? raw[0] : void 0, `${path16}[*]`, token, out);
   }
 }
 function collectVariables(nodeId, sample, metadata) {
-  const token = (path15) => `{outputs.${nodeId}:::${path15}}`;
+  const token = (path16) => `{outputs.${nodeId}:::${path16}}`;
   const variables = [];
   if (sample !== void 0 && sample !== null) {
     walk(typeOfJson(sample), sample, "$", token, variables);
@@ -16739,19 +17146,19 @@ function pathFromKeys(keys) {
     const only = keys[0].trim();
     return only.startsWith("$") ? only : `$${only.startsWith("[") ? "" : "."}${only}`;
   }
-  let path15 = "$";
+  let path16 = "$";
   for (const key of keys) {
     if (key === "*") {
-      path15 += "[*]";
+      path16 += "[*]";
     } else if (/^\d+$/.test(key)) {
-      path15 += `[${key}]`;
+      path16 += `[${key}]`;
     } else if (/^[A-Za-z_]\w*$/.test(key)) {
-      path15 += `.${key}`;
+      path16 += `.${key}`;
     } else {
-      path15 += `['${key.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}']`;
+      path16 += `['${key.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}']`;
     }
   }
-  return path15;
+  return path16;
 }
 function keysAt(type) {
   switch (type.kind) {
@@ -16776,12 +17183,12 @@ function registerPlaceholder(program3) {
     }
     const rows = await readStateFile(dir, OUTPUTS_FILE) ?? [];
     const outputs = indexOutputs(rows);
-    const path15 = pathFromKeys(keys);
-    if (!parsePath(path15)) {
-      throw new CliError(`Cannot read the path "${path15}".`);
+    const path16 = pathFromKeys(keys);
+    if (!parsePath(path16)) {
+      throw new CliError(`Cannot read the path "${path16}".`);
     }
     const isLoop = location.node.type === LOOP_TYPE;
-    const token = isLoop ? `{loopActionGroup.${nodeId}:::loopVariables.items${path15 === "$" ? "" : path15.slice(1)}}` : `{outputs.${nodeId}:::${path15}}`;
+    const token = isLoop ? `{loopActionGroup.${nodeId}:::loopVariables.items${path16 === "$" ? "" : path16.slice(1)}}` : `{outputs.${nodeId}:::${path16}}`;
     const [description] = describeInputData(
       { id: "probe", type: "CUSTOM_CODE", inputs: { inputData: { probe: token } } },
       config,
@@ -16791,7 +17198,7 @@ function registerPlaceholder(program3) {
       throw new CliError("Could not evaluate the token.");
     }
     if (description.type.kind === "unknown") {
-      const segments = parsePath(path15) ?? [];
+      const segments = parsePath(path16) ?? [];
       let hint = description.note ?? "not found";
       const row = outputs[nodeId];
       if (row?.hasSample && segments.length) {
@@ -16817,7 +17224,7 @@ function registerPlaceholder(program3) {
     emit(options, `${token}
 type: ${type}${example3}  (${status})`, {
       token,
-      path: path15,
+      path: path16,
       type,
       example: description.example ?? null,
       verified: description.verified,
@@ -16827,10 +17234,10 @@ type: ${type}${example3}  (${status})`, {
 }
 
 // src/commands/pull.ts
-import path13 from "node:path";
+import path14 from "node:path";
 async function targetDir(cwd, explicitDir, workflowId, title) {
   if (explicitDir) {
-    return path13.resolve(cwd, explicitDir);
+    return path14.resolve(cwd, explicitDir);
   }
   if (await configExists(cwd)) {
     const existing = await readConfig(cwd);
@@ -16842,13 +17249,13 @@ async function targetDir(cwd, explicitDir, workflowId, title) {
     }
     return cwd;
   }
-  return path13.join(cwd, slug(title));
+  return path14.join(cwd, slug(title));
 }
 function registerPull(program3) {
   program3.command("pull").description("Download a workflow into softr-workflows.jsonc and one code file per custom code node").argument("[workflowId]", "the workflow id (last segment of its studio URL); omit to list what you can pull").option("--dir <path>", "target directory (default: this directory if it holds the workflow, else ./<title-slug>)").option("--force", "overwrite an existing softr-workflows.jsonc and its code files").action(async (workflowId, opts, command) => {
     const options = globalOptions(command);
     const cwd = process.cwd();
-    const remembered = await readState(opts.dir ? path13.resolve(cwd, opts.dir) : cwd);
+    const remembered = await readState(opts.dir ? path14.resolve(cwd, opts.dir) : cwd);
     const target = resolveTarget(remembered);
     const client = await authenticatedClient(target);
     if (!workflowId) {
@@ -16861,7 +17268,7 @@ function registerPull(program3) {
     const dir = await targetDir(cwd, opts.dir, workflowId, workflow.title);
     if (await configExists(dir) && !opts.force) {
       throw new CliError(
-        `${path13.join(dir, CONFIG_FILE_NAME)} already exists.`,
+        `${path14.join(dir, CONFIG_FILE_NAME)} already exists.`,
         "Pass --force to overwrite it and its code files."
       );
     }
@@ -16883,7 +17290,7 @@ Sample outputs not available, inputData types are unknown: ${error.message}`;
     if (!outputsNote) {
       outputsFile = await writeStateFile(dir, "outputs.json", rows);
     }
-    const files = [configFile2, ...codeFiles].map((file) => path13.relative(cwd, file));
+    const files = [configFile2, ...codeFiles].map((file) => path14.relative(cwd, file));
     emitWithVersionNote(
       options,
       config,
@@ -17141,23 +17548,23 @@ function registerPin(program3) {
 }
 
 // src/commands/push.ts
-import path14 from "node:path";
+import path15 from "node:path";
 
 // src/project/placeholder-check.ts
 var TOKEN = /\{(?:outputs|loopActionGroup)\.[^:{}]+:::[^{}]*\}/g;
-function* stringsIn(value, path15) {
+function* stringsIn(value, path16) {
   if (typeof value === "string") {
-    yield [path15, value];
+    yield [path16, value];
   } else if (Array.isArray(value)) {
     for (const [index, item] of value.entries()) {
-      yield* stringsIn(item, `${path15}[${index}]`);
+      yield* stringsIn(item, `${path16}[${index}]`);
     }
   } else if (value !== null && typeof value === "object") {
     for (const [key, item] of Object.entries(value)) {
       if (key === "actions" || key === "paths") {
         continue;
       }
-      yield* stringsIn(item, path15 ? `${path15}.${key}` : key);
+      yield* stringsIn(item, path16 ? `${path16}.${key}` : key);
     }
   }
 }
@@ -17268,7 +17675,7 @@ ${unbacked.map(
         draft: result.draft,
         inlined,
         studioUrl,
-        dir: path14.resolve(dir),
+        dir: path15.resolve(dir),
         unbackedPlaceholders: unbacked
       }
     );
@@ -17591,7 +17998,7 @@ Pass --workspace <id> to a command, or set SOFTR_WORKSPACE_ID, to work in one of
 // package.json
 var package_default = {
   name: "@softr/cli",
-  version: "0.1.5",
+  version: "0.1.6",
   description: "The Softr command line: build, test and publish Softr workflows from local files, manage Softr Databases; more Softr APIs to come",
   keywords: [
     "softr",
@@ -17667,4 +18074,5 @@ registerDatabases(db);
 registerTables(db);
 registerFields(db);
 registerViews(db);
+registerRecords(db);
 program2.parseAsync(process.argv).catch(reportError);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softr/cli",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "The Softr command line: build, test and publish Softr workflows from local files, manage Softr Databases; more Softr APIs to come",
   "keywords": [
     "softr",