@softr/cli 0.1.6-se21219.17 → 0.1.7-se22117.20

package/README.md

@@ -188,9 +188,13 @@ synced. That is how `push` knows there is nothing to send, how it notices that t
 
 #### The node types on offer
 
-`spec` lists them. The set is small on purpose: the generic triggers (webhook, schedules, Softr Tables and Softr Apps
+`spec` lists the curated set, small on purpose: the generic triggers (webhook, schedules, Softr Tables and Softr Apps
 events, incoming email), the control nodes (branch, filter, loop, wait), `RESPONDED_TO_WEBHOOK`, `CALL_API`, and
-`CUSTOM_CODE` for everything else. Other integrations stay in the studio. Each entry points to its public docs page.
+`CUSTOM_CODE` for code. Each entry points to its public docs page and comes with a template and an example.
+
+Any other node type the workflows service knows works in the file as well; the CLI just has no specification for it.
+`spec <TYPE>` says where to get one (the Softr MCP server or the studio), `add <TYPE> --node-version <v>` writes the node
+with empty inputs, and the service validates it on publish, as for every node.
 
 #### A typical session
 
@@ -226,27 +230,27 @@ crm/
   .softr-db/views/<tableId>.json  # the views of a table, once views list read them
 ```
 
-| Command                                                                                   | What it does                                                                                                                                                                                    |
-| ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `db list`                                                                                 | The databases the token reaches, across all workspaces, with their workspace and number of tables.                                                                                              |
-| `db get [<database>] [--dir <path>]`                                                      | One database with its tables, by id or exact name. Outside a database directory it creates `./<name-slug>/`; inside one it refreshes the cache, and a different database is an error.           |
-| `db create <name> [--description <text>] [--workspace <id>] [--dir <path>]`               | Create an empty database and its directory. The workspace defaults to `SOFTR_WORKSPACE_ID`, else to your only or default workspace among those where the token grants `databases.schema:write`. |
-| `db update [<databaseId>] [--name <name>] [--description <text>] [--dir <path>]`          | Change the name, the description or both.                                                                                                                                                       |
-| `db delete [<databaseId>] [--force] [--dir <path>]`                                       | Delete a database. One that still has tables needs `--force`, which also deletes the tables and all their records. The directory keeps its `softr-db.jsonc`; the cache goes.                    |
-| `db tables list` / `get <table>`                                                          | The tables of the database; one table with its fields (ids, types, primary/required/read-only).                                                                                                 |
-| `db tables create <name> [--field <name:TYPE>]... [--primary-field <name>]`               | Create a table with at least one `--field`; the first one names a record.                                                                                                                       |
-| `db tables update <table> [--name] [--description]` / `delete <table> [--force]`          | Rename or describe a table; delete it (`--force` when it still has records).                                                                                                                    |
-| `db fields get <table> <field>`                                                           | One field with its options.                                                                                                                                                                     |
-| `db fields add <table> <name> --type <TYPE> [--options <json>] [--multiple]`              | Add a field. The types and their options: [field reference](https://docs.softr.io/softr-api/softr-database-api/table-fields/add-table-field).                                                   |
-| `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`.                                                                                                      |
+| Command                                                                                       | What it does                                                                                                                                                                                    |
+| --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `db list`                                                                                     | The databases the token reaches, across all workspaces, with their workspace and number of tables.                                                                                              |
+| `db get [<database>] [--dir <path>]`                                                          | One database with its tables, by id or exact name. Outside a database directory it creates `./<name-slug>/`; inside one it refreshes the cache, and a different database is an error.           |
+| `db create <name> [--description <text>] [--workspace <id>] [--dir <path>]`                   | Create an empty database and its directory. The workspace defaults to `SOFTR_WORKSPACE_ID`, else to your only or default workspace among those where the token grants `databases.schema:write`. |
+| `db update [<databaseId>] [--name <name>] [--description <text>] [--dir <path>]`              | Change the name, the description or both.                                                                                                                                                       |
+| `db delete [<databaseId>] [--force] [--dir <path>]`                                           | Delete a database. One that still has tables needs `--force`, which also deletes the tables and all their records. The directory keeps its `softr-db.jsonc`; the cache goes.                    |
+| `db tables list` / `get <table>`                                                              | The tables of the database; one table with its fields (ids, types, primary/required/read-only).                                                                                                 |
+| `db tables create <name> [--field <name:TYPE>]... [--fields <json>] [--primary-field <name>]` | Create a table with at least one field: `--field` for types without options, `--fields` (a JSON array, `@<file>` or `-`) for any; the first one names a record.                                 |
+| `db tables update <table> [--name] [--description]` / `delete <table> [--force]`              | Rename or describe a table; delete it (`--force` when it still has records).                                                                                                                    |
+| `db fields get <table> <field>`                                                               | One field with its options.                                                                                                                                                                     |
+| `db fields add <table> <name> --type <TYPE> [--options <json>] [--multiple]`                  | Add a field. The types and their options: [field reference](https://docs.softr.io/softr-api/softr-database-api/table-fields/add-table-field).                                                   |
+| `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

package/dist/cli.mjs

@@ -6070,18 +6070,74 @@ var CATALOG = catalog_default;
 function catalogEntries(kind) {
   return CATALOG.filter((entry) => !kind || entry.kind === kind);
 }
-function findCatalogEntry(type, kind) {
+function catalogEntryOrNull(type, kind) {
   const wanted = type.trim().toUpperCase();
-  const entry = CATALOG.find((candidate) => candidate.type === wanted && (!kind || candidate.kind === kind));
+  return CATALOG.find((candidate) => candidate.type === wanted && (!kind || candidate.kind === kind));
+}
+function findCatalogEntry(type, kind) {
+  const entry = catalogEntryOrNull(type, kind);
   if (!entry) {
     const known = catalogEntries(kind).map((candidate) => candidate.type).join(", ");
     throw new CliError(
-      `"${type}" is not a node type this CLI offers${kind ? ` as a ${kind}` : ""}.`,
-      `Available: ${known}. The CLI is limited to code-first workflows on purpose; other integrations are configured in the studio.`
+      `"${type.trim().toUpperCase()}" is not in the CLI's curated set${kind ? ` of ${kind}s` : ""}.`,
+      `Curated: ${known}.
+${uncuratedGuidance(type)}`
     );
   }
   return entry;
 }
+function uncuratedGuidance(type) {
+  const wanted = type.trim().toUpperCase();
+  return [
+    `${wanted} is not in the curated set, so the CLI has no template or specification for it; the workflows service`,
+    "still runs it. Take its specification (inputs, the required ones, fixed options, version) from the Softr MCP server",
+    "(get_node_specifications; workflow_get_node_specifications in an agent runtime) or from the studio. Then write the",
+    "node with its type, version and inputs, or scaffold it: softr workflows add <TYPE> --node-version <v> [--kind trigger].",
+    "Push and test it as any node: the service validates it on publish and names what is wrong."
+  ].join("\n");
+}
+function resolveNodeType(type, choice) {
+  const entry = catalogEntryOrNull(type, choice.kind);
+  if (entry) {
+    if (choice.version) {
+      throw new CliError(
+        `${entry.type} is curated: the CLI pins its version (${entry.version}).`,
+        'Drop --node-version; "softr workflows upgrade" moves nodes to the current one.'
+      );
+    }
+    const { type: curatedType, kind, label, version: version2, template } = entry;
+    return { type: curatedType, kind, label, version: version2, template: structuredClone(template), curated: true };
+  }
+  const otherKind = catalogEntryOrNull(type);
+  if (otherKind) {
+    throw new CliError(
+      `${otherKind.type} is curated as ${article(otherKind.kind)}, not ${article(choice.kind ?? "action")}.`,
+      `Curated ${choice.kind ?? "action"}s: ${catalogEntries(choice.kind ?? "action").map((candidate) => candidate.type).join(", ")}.`
+    );
+  }
+  const wanted = type.trim().toUpperCase();
+  if (!choice.version) {
+    throw new CliError(
+      `"${wanted}" is not in the CLI's curated set, so pass --node-version <v>: the node version the service runs.`,
+      uncuratedGuidance(type)
+    );
+  }
+  return {
+    type: wanted,
+    kind: choice.kind ?? "action",
+    label: labelOf(wanted),
+    version: choice.version,
+    template: {},
+    curated: false
+  };
+}
+function article(kind) {
+  return kind === "action" ? "an action" : "a trigger";
+}
+function labelOf(type) {
+  const words = type.toLowerCase().split("_");
+  return [words[0].charAt(0).toUpperCase() + words[0].slice(1), ...words.slice(1)].join(" ");
+}
 function isTestableType(type) {
   return !NOT_TESTABLE_TYPES.has(type);
 }
@@ -14346,42 +14402,48 @@ function pathsAt(config, pathsPath) {
   return Array.isArray(current2) ? current2 : [];
 }
 function registerEdit(program3) {
-  program3.command("replace").description("Give a node another type: keeps its id, title and paths; inputs start from the new type's template").argument("<nodeId>", "the trigger or action to change").argument("<type>", 'the new type from "spec", of the same kind (trigger or action)').option("--lang <language>", "for CUSTOM_CODE: JAVASCRIPT or PYTHON (default JAVASCRIPT)").option("--dir <path>", "workflow directory (default: the current directory)").action(async (nodeId, type, opts, command) => {
-    const options = globalOptions(command);
-    const dir = await findWorkflowDir(process.cwd(), opts.dir);
-    const config = await readConfig(dir);
-    const location = locateNode(config, nodeId);
-    if (!location) {
-      throw new CliError(`No node "${nodeId}" in softr-workflows.jsonc.`);
-    }
-    const entry = findCatalogEntry(type, location.kind);
-    if (location.node.type === LOOP_TYPE && entry.type !== LOOP_TYPE) {
-      throw new CliError(`"${nodeId}" is a loop with a body; remove it instead of replacing it.`);
-    }
-    const title = location.node.title ?? entry.label;
-    const { inputs, codeFile } = await newNodeInputs(entry, nodeId, title, opts.lang, dir);
-    const node = { ...location.node, type: entry.type, version: entry.version, inputs };
-    delete node["outputSchema"];
-    await editConfig(dir, [{ path: location.path, value: node }]);
-    const oldCode = location.node.type === CUSTOM_CODE_TYPE && isFileRef(location.node.inputs?.["code"]) ? location.node.inputs?.["code"] : void 0;
-    const notes = [
-      oldCode && oldCode !== inputs["code"] ? `The previous code file (${oldCode}) is left in place; delete it when you no longer need it.` : "",
-      entry.kind === "trigger" && (config.triggers?.length ?? 0) > 1 ? "The service accepts one trigger per published workflow for now." : "",
-      `Fill inputs.${Object.keys(entry.template)[0] ?? "\u2026"} etc. in softr-workflows.jsonc (see "spec ${entry.type}"), then push and test ${nodeId}.`
-    ].filter(Boolean);
-    emitWithVersionNote(
-      options,
-      await readConfig(dir),
-      `Replaced "${nodeId}" (${location.node.type}) with ${entry.type}; paths kept.
+  program3.command("replace").description("Give a node another type: keeps its id, title and paths; inputs start from the new type's template").argument("<nodeId>", "the trigger or action to change").argument(
+    "<type>",
+    'the new type from "spec" (same kind: trigger or action), or any type the service knows (with --node-version)'
+  ).option("--lang <language>", "for CUSTOM_CODE: JAVASCRIPT or PYTHON (default JAVASCRIPT)").option("--node-version <version>", "for a type outside the curated set: the node version the service runs").option("--dir <path>", "workflow directory (default: the current directory)").action(
+    async (nodeId, type, opts, command) => {
+      const options = globalOptions(command);
+      const dir = await findWorkflowDir(process.cwd(), opts.dir);
+      const config = await readConfig(dir);
+      const location = locateNode(config, nodeId);
+      if (!location) {
+        throw new CliError(`No node "${nodeId}" in softr-workflows.jsonc.`);
+      }
+      const entry = resolveNodeType(type, { kind: location.kind, version: opts.nodeVersion });
+      if (location.node.type === LOOP_TYPE && entry.type !== LOOP_TYPE) {
+        throw new CliError(`"${nodeId}" is a loop with a body; remove it instead of replacing it.`);
+      }
+      const title = location.node.title ?? entry.label;
+      const { inputs, codeFile } = await newNodeInputs(entry, nodeId, title, opts.lang, dir);
+      const node = { ...location.node, type: entry.type, version: entry.version, inputs };
+      delete node["outputSchema"];
+      await editConfig(dir, [{ path: location.path, value: node }]);
+      const oldCode = location.node.type === CUSTOM_CODE_TYPE && isFileRef(location.node.inputs?.["code"]) ? location.node.inputs?.["code"] : void 0;
+      const notes = [
+        oldCode && oldCode !== inputs["code"] ? `The previous code file (${oldCode}) is left in place; delete it when you no longer need it.` : "",
+        entry.kind === "trigger" && (config.triggers?.length ?? 0) > 1 ? "The service accepts one trigger per published workflow for now." : "",
+        entry.curated ? `Fill inputs.${Object.keys(entry.template)[0] ?? "\u2026"} etc. in softr-workflows.jsonc (see "spec ${entry.type}"), then push and test ${nodeId}.` : `Fill its inputs in softr-workflows.jsonc from its specification ("spec ${entry.type}" says where to find it), then push and test ${nodeId}.`
+      ].filter(Boolean);
+      emitWithVersionNote(
+        options,
+        await readConfig(dir),
+        `Replaced "${nodeId}" (${location.node.type}) with ${entry.type}; paths kept.
 ${notes.join("\n")}`,
-      {
-        id: nodeId,
-        from: location.node.type,
-        to: entry.type,
-        codeFile: codeFile ? path5.relative(process.cwd(), codeFile) : null
-      }
-    );
-  });
+        {
+          id: nodeId,
+          from: location.node.type,
+          to: entry.type,
+          curated: entry.curated,
+          codeFile: codeFile ? path5.relative(process.cwd(), codeFile) : null
+        }
+      );
+    }
+  );
   program3.command("remove").description("Remove a node and every path that leads to or from it (a loop goes with its body)").argument("<nodeId>", "the trigger or action to remove").option("--dir <path>", "workflow directory (default: the current directory)").action(async (nodeId, opts, command) => {
     const options = globalOptions(command);
     const dir = await findWorkflowDir(process.cwd(), opts.dir);
@@ -14430,6 +14492,15 @@ function slug(title, fallback = "workflow") {
 }
 
 // src/commands/add.ts
+function parseKind(kind) {
+  if (kind === void 0) {
+    return void 0;
+  }
+  if (kind === "trigger" || kind === "action") {
+    return kind;
+  }
+  throw new CliError(`--kind takes trigger or action, not "${kind}".`);
+}
 function uniqueId(base, taken) {
   if (!taken.has(base)) {
     return base;
@@ -14465,11 +14536,14 @@ function defaultAfter(config, loopId) {
   );
 }
 function registerAdd(program3) {
-  program3.command("add").description("Add an action after an existing node, or a trigger; custom code gets its own file under actions/").argument("<type>", 'node type from "spec", e.g. CUSTOM_CODE or WEBHOOK').option("--id <id>", "node id, readable and unique (default: derived from the type)").option("--title <title>", "node title shown in the studio (default: the type label)").option("--after <nodeId>", "actions: the node the new one follows (default: the only node without a successor)").option("--to <nodeId>", "triggers: an action the new trigger leads to").option("--in-loop <loopId>", "put the node inside this loop body").option("--lang <language>", "for CUSTOM_CODE: JAVASCRIPT or PYTHON (default JAVASCRIPT)").option("--dir <path>", "workflow directory (default: the current directory)").action(async (type, opts, command) => {
+  program3.command("add").description("Add an action after an existing node, or a trigger; custom code gets its own file under actions/").argument(
+    "<type>",
+    'node type from "spec", e.g. CUSTOM_CODE or WEBHOOK, or any type the service knows (with --node-version)'
+  ).option("--id <id>", "node id, readable and unique (default: derived from the type)").option("--title <title>", "node title shown in the studio (default: the type label)").option("--after <nodeId>", "actions: the node the new one follows (default: the only node without a successor)").option("--to <nodeId>", "triggers: an action the new trigger leads to").option("--in-loop <loopId>", "put the node inside this loop body").option("--lang <language>", "for CUSTOM_CODE: JAVASCRIPT or PYTHON (default JAVASCRIPT)").option("--node-version <version>", "for a type outside the curated set: the node version the service runs").option("--kind <kind>", "for a type outside the curated set: trigger or action (default action)").option("--dir <path>", "workflow directory (default: the current directory)").action(async (type, opts, command) => {
     const options = globalOptions(command);
     const dir = await findWorkflowDir(process.cwd(), opts.dir);
     const config = await readConfig(dir);
-    const entry = findCatalogEntry(type);
+    const entry = resolveNodeType(type, { kind: parseKind(opts.kind), version: opts.nodeVersion });
     const nodes = [...config.triggers ?? [], ...allActions(config.actions)];
     const taken = new Set(nodes.map((node2) => node2.id));
     const id = opts.id ?? uniqueId(entry.kind === "trigger" ? "trigger" : slug(entry.label), taken);
@@ -14509,6 +14583,7 @@ ${notes.join("\n")}`,
           id,
           kind: "trigger",
           type: entry.type,
+          curated: entry.curated,
           to: opts.to ?? null
         }
       );
@@ -14533,6 +14608,7 @@ ${notes.join("\n")}`,
     const next = [
       codeFile ? `Write the function in ${path6.relative(process.cwd(), codeFile)} and map its inputs under inputs.inputData in softr-workflows.jsonc.` : "",
       entry.type === "BRANCH" || entry.type === "FILTER" ? `Add the condition(s) on the path(s) leaving it in softr-workflows.jsonc (see "spec ${entry.type}").` : "",
+      entry.curated ? "" : `Fill its inputs in softr-workflows.jsonc from its specification ("spec ${entry.type}" says where to find it).`,
       `Then: softr workflows push, softr workflows test ${id}.`
     ].filter(Boolean);
     emitWithVersionNote(
@@ -14544,6 +14620,7 @@ ${next.join("\n")}`,
         id,
         kind: "action",
         type: entry.type,
+        curated: entry.curated,
         after,
         loopId: opts.inLoop ?? null,
         codeFile: codeFile ? path6.relative(process.cwd(), codeFile) : null
@@ -15697,7 +15774,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);
@@ -15730,8 +15811,8 @@ async function currentTables(context, fresh) {
   context.cache = await refreshSchemaCache(context.client, context.dir, context.databaseId);
   return context.cache.tables;
 }
-async function findTable(context, reference, fresh = false) {
-  const table = byIdOrName(await currentTables(context, fresh), reference, "table") ?? (context.dir && !fresh ? byIdOrName(await currentTables(context, true), reference, "table") : void 0);
+function tableIn(context, tables, reference) {
+  const table = byIdOrName(tables, reference, "table");
   if (!table) {
     throw new CliError(
       `Database ${context.databaseId} has no table with the id or name "${reference}".`,
@@ -15740,7 +15821,14 @@ async function findTable(context, reference, fresh = false) {
   }
   return table;
 }
-async function findFields(context, table, references, fresh = false) {
+async function findTableOnServer(context, reference) {
+  return tableIn(context, await currentTables(context, true), reference);
+}
+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) {
@@ -15753,8 +15841,8 @@ async function findFields(context, table, references, fresh = false) {
   };
   let current2 = table;
   let fields = resolve(current2);
-  if (fields.size < new Set(references).size && context.dir && !fresh) {
-    current2 = await findTable(context, table.id, true);
+  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));
@@ -15766,9 +15854,34 @@ async function findFields(context, table, references, fresh = false) {
   }
   return { table: current2, fields };
 }
-async function findField(context, tableReference, reference, fresh = false) {
-  const found = await findFields(context, await findTable(context, tableReference, fresh), [reference], fresh);
-  return { table: found.table, field: found.fields.get(reference) };
+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");
+  if (!field) {
+    throw new CliError(
+      `Table ${table.name} has no field with the id or name "${reference}".`,
+      `"softr db tables get ${table.id}" shows its fields.`
+    );
+  }
+  return { table, field };
 }
 async function afterSchemaWrite(context) {
   if (context.dir) {
@@ -15787,6 +15900,21 @@ function parseFieldSpec(spec) {
   }
   return { name, type };
 }
+function parseFieldList(value) {
+  if (!Array.isArray(value)) {
+    throw new CliError(
+      "--fields must be a JSON array of fields.",
+      `For example: [{"name": "Stage", "type": "SELECT", "options": {...}}]`
+    );
+  }
+  return value.map((item, index) => {
+    const field = item;
+    if (!field || typeof field !== "object" || typeof field.name !== "string" || !field.name || typeof field.type !== "string" || !field.type) {
+      throw new CliError(`--fields item ${index + 1} needs a "name" and a "type".`);
+    }
+    return { ...field, name: field.name, type: field.type.toUpperCase() };
+  });
+}
 function renderTables(tables) {
   if (!tables.length) {
     return "The database has no tables. Create one with: softr db tables create <name>";
@@ -15849,7 +15977,7 @@ function registerTables(db2) {
   ).action(async (reference, opts, command) => {
     const options = globalOptions(command);
     const context = await schemaContext(opts);
-    const table = await findTable(context, reference, true);
+    const table = await findTableOnServer(context, reference);
     emit(options, renderTable(table), { table });
   });
   withDatabaseOptions(
@@ -15857,22 +15985,28 @@ function registerTables(db2) {
       "Create a table with at least one field; the first one names a record unless --primary-field says otherwise"
     ).argument("<name>", "the table name").option("--description <text>", "what the table holds").option(
       "--field <name:TYPE>",
-      `a field to create with it, repeatable (types and their options: ${FIELD_REFERENCE_URL}); add fields with options through "softr db fields add"`,
+      "a field of a type without options, repeatable",
       (value, previous) => [...previous, value],
       []
+    ).option(
+      "--fields <json>",
+      `fields as a JSON array of {name, type, options?, description?, allowMultipleEntries?}, @<file> or - for stdin; they follow the --field ones (types and options: ${FIELD_REFERENCE_URL})`
     ).option("--primary-field <name>", "the field that names a record (default: the first field)")
   ).action(
     async (name, opts, command) => {
       const options = globalOptions(command);
-      if (!opts.field.length) {
+      const fields = [
+        ...opts.field.map(parseFieldSpec),
+        ...opts.fields === void 0 ? [] : parseFieldList(await readJsonArgument(opts.fields, "--fields"))
+      ];
+      if (!fields.length) {
         throw new CliError(
-          'A table needs at least one field: pass --field <name>:<TYPE>, for example --field "Name:SINGLE_LINE_TEXT".',
-          "Repeat --field for more; the first one names a record unless --primary-field names another."
+          'A table needs at least one field: pass --field <name>:<TYPE>, for example --field "Name:SINGLE_LINE_TEXT", or --fields with a JSON array.',
+          "The first field names a record unless --primary-field names another."
         );
       }
-      const fields = opts.field.map(parseFieldSpec);
       if (opts.primaryField && !fields.some((field) => field.name === opts.primaryField)) {
-        throw new CliError(`--primary-field "${opts.primaryField}" is not one of the --field names.`);
+        throw new CliError(`--primary-field "${opts.primaryField}" is not one of the fields' names.`);
       }
       const context = await schemaContext(opts);
       const table = await createTable(context.client, context.databaseId, {
@@ -15894,7 +16028,7 @@ function registerTables(db2) {
       }
       const options = globalOptions(command);
       const context = await schemaContext(opts);
-      const current2 = await findTable(context, reference, true);
+      const current2 = await findTableOnServer(context, reference);
       const table = await updateTable(context.client, context.databaseId, current2.id, {
         name: opts.name ?? current2.name,
         description: opts.description ?? current2.description
@@ -15908,7 +16042,7 @@ function registerTables(db2) {
   ).action(async (reference, opts, command) => {
     const options = globalOptions(command);
     const context = await schemaContext(opts);
-    const table = await findTable(context, reference, true);
+    const table = await findTableOnServer(context, reference);
     await deleteTable(context.client, context.databaseId, table.id, opts.force === true);
     await afterSchemaWrite(context);
     emit(options, `Deleted table ${table.name} (${table.id}).`, { deleted: table.id });
@@ -15921,7 +16055,7 @@ function registerFields(db2) {
   ).action(async (tableReference, reference, opts, command) => {
     const options = globalOptions(command);
     const context = await schemaContext(opts);
-    const { table, field } = await findField(context, tableReference, reference, true);
+    const { table, field } = await findField(context, tableReference, reference);
     emit(options, renderField(table, field), { tableId: table.id, field });
   });
   withDatabaseOptions(
@@ -15931,7 +16065,7 @@ function registerFields(db2) {
       const options = globalOptions(command);
       const fieldOptions = await parseOptions(opts.options);
       const context = await schemaContext(opts);
-      const table = await findTable(context, tableReference);
+      const table = await findTableCached(context, tableReference);
       const field = await addField(context.client, context.databaseId, table.id, {
         name,
         type: opts.type.toUpperCase(),
@@ -15959,7 +16093,7 @@ function registerFields(db2) {
       }
       const options = globalOptions(command);
       const context = await schemaContext(opts);
-      const { table, field: current2 } = await findField(context, tableReference, reference, true);
+      const { table, field: current2 } = await findField(context, tableReference, reference);
       const field = await updateField(context.client, context.databaseId, table.id, current2.id, {
         name: opts.name ?? current2.name,
         type: opts.type?.toUpperCase() ?? current2.type,
@@ -15981,7 +16115,7 @@ function registerFields(db2) {
   ).action(async (tableReference, reference, opts, command) => {
     const options = globalOptions(command);
     const context = await schemaContext(opts);
-    const { table, field } = await findField(context, tableReference, reference, true);
+    const { table, field } = await findField(context, tableReference, reference);
     await deleteField(context.client, context.databaseId, table.id, field.id);
     await afterSchemaWrite(context);
     emit(options, `Deleted field ${field.name} (${field.id}) from ${table.name}.`, {
@@ -15997,11 +16131,8 @@ function registerViews(db2) {
   ).action(async (reference, opts, command) => {
     const options = globalOptions(command);
     const context = await schemaContext(opts);
-    const table = await findTable(context, reference, true);
-    const items = await listViews(context.client, context.databaseId, table.id);
-    if (context.dir) {
-      await writeViewsCache(context.dir, table.id, items);
-    }
+    const table = await findTableOnServer(context, reference);
+    const items = await readViews(context, table);
     emit(options, renderViews(items), { tableId: table.id, views: items });
   });
 }
@@ -16101,24 +16232,6 @@ function parseSort(spec) {
   }
   return { field: spec.trim(), sortType: "ASC" };
 }
-async function findView(context, table, reference) {
-  const fresh = async () => {
-    const views = await listViews(context.client, context.databaseId, table.id);
-    if (context.dir) {
-      await writeViewsCache(context.dir, table.id, views);
-    }
-    return views;
-  };
-  const cached = context.dir ? (await readViewsCache(context.dir, table.id))?.views : void 0;
-  const view = (cached ? byIdOrName(cached, reference, "view") : void 0) ?? byIdOrName(await fresh(), 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;
-}
 function withFieldNames(record, table) {
   const names2 = new Map(table.fields.map((field) => [field.id, field.name]));
   return {
@@ -16158,7 +16271,7 @@ function registerRecords(db2) {
       const options = globalOptions(command);
       const pages = paging(opts);
       const context = await schemaContext(opts);
-      const table = await findTable(context, reference);
+      const table = await findTableCached(context, reference);
       const viewId = opts.view ? (await findView(context, table, opts.view)).id : void 0;
       const page = await readPages(
         pages,
@@ -16196,7 +16309,7 @@ function registerRecords(db2) {
       const context = await schemaContext(opts);
       const references = new Set(sorts.map((sort) => sort.field));
       fieldReferences(condition, references);
-      const { table, ids } = await fieldIdsFor(context, await findTable(context, reference), [...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 })) } : {},
@@ -16216,7 +16329,7 @@ function registerRecords(db2) {
   ).action(async (reference, recordId, opts, command) => {
     const options = globalOptions(command);
     const context = await schemaContext(opts);
-    const table = await findTable(context, reference);
+    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 });
   });
@@ -16231,7 +16344,7 @@ function registerRecords(db2) {
     const options = globalOptions(command);
     const fields = asObject(await readJsonArgument(opts.fields, "--fields"), "--fields");
     const context = await schemaContext(opts);
-    const table = await findTable(context, reference);
+    const table = await findTableCached(context, reference);
     const record = await createRecord(
       context.client,
       context.databaseId,
@@ -16256,7 +16369,7 @@ function registerRecords(db2) {
         throw new CliError("Nothing to change: --fields is an empty object.");
       }
       const context = await schemaContext(opts);
-      const table = await findTable(context, reference);
+      const table = await findTableCached(context, reference);
       const record = await updateRecord(
         context.client,
         context.databaseId,
@@ -16273,7 +16386,7 @@ function registerRecords(db2) {
   ).action(async (reference, recordId, opts, command) => {
     const options = globalOptions(command);
     const context = await schemaContext(opts);
-    const table = await findTable(context, reference, true);
+    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 });
   });
@@ -16291,13 +16404,12 @@ function registerRecords(db2) {
         throw new CliError(`Cannot read ${file}.`);
       }
       const context = await schemaContext(opts);
-      const found = await fieldIdsFor(context, await findTable(context, reference), [fieldReference]);
-      const fieldId = found.ids.get(fieldReference);
-      const fieldType = found.table.fields.find((field) => field.id === fieldId)?.type;
-      if (fieldType !== "ATTACHMENT") {
-        throw new CliError(`Field "${fieldReference}" has the type ${fieldType}; upload needs an ATTACHMENT field.`);
+      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, fieldId, {
+      const uploaded = await uploadAttachment(context.client, context.databaseId, found.table.id, recordId, field.id, {
         name: opts.name ?? path12.basename(file),
         content
       });
@@ -17662,7 +17774,8 @@ function renderList() {
   }
   return [
     table.toString(),
-    "This CLI offers only these node types on purpose: code-first workflows use custom code for everything else.",
+    "These are the curated types: documented here, with a template and an example each. Any other node type the",
+    'workflows service knows can be written into softr-workflows.jsonc as well; "softr workflows spec <TYPE>" says how.',
     'Run "softr workflows spec <TYPE>" for the inputs, output and an example of one type.'
   ].join("\n");
 }
@@ -17721,7 +17834,9 @@ ${JSON.stringify(extra.json, null, 2)}`);
   return blocks.join("\n\n");
 }
 function registerSpec(program3) {
-  program3.command("spec").description("List the node types this CLI offers, or show the inputs, output and an example of one").argument("[type]", "a node type such as CUSTOM_CODE").action((type, _opts, command) => {
+  program3.command("spec").description(
+    "List the curated node types, or show the inputs, output and an example of one; any other type: how to add it"
+  ).argument("[type]", "a node type such as CUSTOM_CODE").action((type, _opts, command) => {
     const options = globalOptions(command);
     if (!type) {
       emit(options, renderList(), {
@@ -17735,8 +17850,13 @@ function registerSpec(program3) {
       });
       return;
     }
-    const entry = findCatalogEntry(type);
-    emit(options, renderEntry(entry), { ...entry, testable: isTestableType(entry.type) });
+    const entry = catalogEntryOrNull(type);
+    if (!entry) {
+      const guidance = uncuratedGuidance(type);
+      emit(options, guidance, { type: type.trim().toUpperCase(), curated: false, guidance });
+      return;
+    }
+    emit(options, renderEntry(entry), { ...entry, curated: true, testable: isTestableType(entry.type) });
   });
 }
 
@@ -17963,7 +18083,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.6-se21219.17",
+  version: "0.1.7-se22117.20",
   description: "The Softr command line: build, test and publish Softr workflows from local files, manage Softr Databases; more Softr APIs to come",
   keywords: [
     "softr",

package/package.json

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