@lotics/cli 0.47.0 → 0.49.0

package/README.md

@@ -102,7 +102,10 @@ lotics tools query_records      # show full description + input schema
 lotics run query_tables '{}'
 lotics run query_records '{"table_id":"tbl_...","field_keys":["name"]}'
 
-# Pipe args via stdin
+# Large args (a knowledge-doc `content`, a bulk update) exceed the OS arg limit —
+# read them from a file or stdin instead of an inline arg:
+lotics run create_knowledge @args.json
+cat args.json | lotics run create_knowledge
 echo '{"table_id":"tbl_..."}' | lotics run query_records
 
 # Upload files (multiple files and directories supported)

package/dist/cli.js

@@ -54,6 +54,8 @@ COMMANDS
   lotics tools                         List all available tools
   lotics tools <name>                  Show tool description and input schema
   lotics run <tool> '<json>'           Execute a tool
+  lotics run <tool> @args.json         Read JSON args from a file (large payloads)
+  cat args.json | lotics run <tool>    Read JSON args from stdin (large payloads)
   lotics upload <file|dir...>          Upload files (directories expand to their immediate files)
   lotics download <file_id>            Download a file by ID
   lotics download record <record_id> <field_key>
@@ -533,7 +535,9 @@ async function main() {
         process.exit(1);
     }
     if (command === "run" && !subcommand) {
-        console.error('Usage: lotics run <tool> \'<json_args>\'');
+        console.error("Usage: lotics run <tool> '<json_args>'\n" +
+            "       lotics run <tool> @args.json   (read args from a file — for large payloads)\n" +
+            "       cat args.json | lotics run <tool>   (read args from stdin)");
         console.error('Run "lotics tools" to see available tools.');
         process.exit(1);
     }
@@ -779,7 +783,23 @@ async function main() {
     if (command === "run") {
         const toolName = subcommand;
         let rawArgs = toolArgs;
-        if (!rawArgs && !process.stdin.isTTY) {
+        if (rawArgs && rawArgs.startsWith("@")) {
+            // `@<path>` — read the JSON args from a local file. JSON args always
+            // start with `{`, so a leading `@` is unambiguous. This (and piped
+            // stdin below) carries payloads too large for an inline arg, which the
+            // OS caps (ARG_MAX) — e.g. a knowledge doc's `content` or a bulk update.
+            // Reads only a file the caller explicitly named; no new trust boundary.
+            const argsPath = rawArgs.slice(1);
+            try {
+                rawArgs = fs.readFileSync(argsPath, "utf-8");
+            }
+            catch (err) {
+                console.error(`Cannot read args file "${argsPath}": ${err instanceof Error ? err.message : String(err)}`);
+                process.exit(1);
+            }
+        }
+        else if (!rawArgs && !process.stdin.isTTY) {
+            // Piped/redirected stdin — `… | lotics run <tool>` or `< file.json`.
             rawArgs = await readStdin();
         }
         let args = {};

package/dist/client.d.ts

@@ -183,6 +183,21 @@ export declare class LoticsClient {
             image: string | null;
         }>;
     }>;
+    /**
+     * Resolve the full option set (key, label, color) of a named query's select
+     * columns — the picker companion to `appQuery`. Mirrors
+     * POST /v1/apps/{app_id}/field-options.
+     */
+    appFieldOptions(app_id: string, alias: string): Promise<{
+        fields: Record<string, {
+            label: string;
+            options: Array<{
+                key: string;
+                label: string;
+                color: string;
+            }>;
+        }>;
+    }>;
     /**
      * Execute a workflow by alias declared in package.json#lotics.workflows.
      * Mirrors POST /v1/apps/{app_id}/workflows/{alias}/execute.

package/dist/client.js

@@ -187,6 +187,14 @@ export class LoticsClient {
         const qs = group_id ? `?group_id=${encodeURIComponent(group_id)}` : "";
         return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/members${qs}`);
     }
+    /**
+     * Resolve the full option set (key, label, color) of a named query's select
+     * columns — the picker companion to `appQuery`. Mirrors
+     * POST /v1/apps/{app_id}/field-options.
+     */
+    async appFieldOptions(app_id, alias) {
+        return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/field-options`, { alias });
+    }
     /**
      * Execute a workflow by alias declared in package.json#lotics.workflows.
      * Mirrors POST /v1/apps/{app_id}/workflows/{alias}/execute.

package/dist/dev/rpc_handler.d.ts

@@ -6,7 +6,7 @@
  * { message }. Same shape as the production iframe-host's error path.
  */
 import { LoticsClient } from "../client.js";
-export type RpcOp = "query" | "workflow" | "members" | "context" | "upload_url" | "upload_complete" | "comments.list" | "comments.create" | "comments.update" | "comments.delete" | "comments.counts";
+export type RpcOp = "query" | "field_options" | "workflow" | "members" | "context" | "upload_url" | "upload_complete" | "comments.list" | "comments.create" | "comments.update" | "comments.delete" | "comments.counts";
 export interface RpcRequest {
     app_id: string;
     op: RpcOp;

package/dist/dev/rpc_handler.js

@@ -7,6 +7,7 @@
  */
 const SUPPORTED_OPS = new Set([
     "query",
+    "field_options",
     "workflow",
     "members",
     "context",
@@ -52,6 +53,13 @@ export async function dispatchRpc(client, body, opts) {
                 count: p.count,
             });
         }
+        case "field_options": {
+            const p = body.payload;
+            if (!p || typeof p.alias !== "string") {
+                throw new Error("field_options payload must include `alias`");
+            }
+            return client.appFieldOptions(body.app_id, p.alias);
+        }
         case "workflow": {
             const p = body.payload;
             if (!p || typeof p.alias !== "string") {

package/dist/dev/rpc_handler.test.js

@@ -27,6 +27,27 @@ describe("dispatchRpc — context op", () => {
         await expect(dispatchRpc(client, { app_id: "app_x", op: "bogus", payload: {} })).rejects.toThrow(/Unknown RPC op/);
     });
 });
+describe("dispatchRpc — field_options op", () => {
+    it("forwards the alias to appFieldOptions and returns its { fields } shape", async () => {
+        const fields = {
+            status: {
+                label: "Status",
+                options: [{ key: "opt_open", label: "Open", color: "blue" }],
+            },
+        };
+        const client = mockClient({ appFieldOptions: async () => ({ fields }) });
+        const result = await dispatchRpc(client, {
+            app_id: "app_x",
+            op: "field_options",
+            payload: { alias: "records" },
+        });
+        expect(result).toEqual({ fields });
+    });
+    it("requires an alias in the payload", async () => {
+        const client = mockClient({ appFieldOptions: async () => ({ fields: {} }) });
+        await expect(dispatchRpc(client, { app_id: "app_x", op: "field_options", payload: {} })).rejects.toThrow(/alias/);
+    });
+});
 describe("dispatchRpc — comment ops", () => {
     it("comments.list forwards to appGetRecordComments, wrapped as { comments }", async () => {
         const comments = [{ id: "cmt_1", content: "hi" }];

package/dist/src/cli.js

@@ -29772,6 +29772,14 @@ var LoticsClient = class {
     const qs = group_id ? `?group_id=${encodeURIComponent(group_id)}` : "";
     return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/members${qs}`);
   }
+  /**
+   * Resolve the full option set (key, label, color) of a named query's select
+   * columns — the picker companion to `appQuery`. Mirrors
+   * POST /v1/apps/{app_id}/field-options.
+   */
+  async appFieldOptions(app_id, alias) {
+    return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/field-options`, { alias });
+  }
   /**
    * Execute a workflow by alias declared in package.json#lotics.workflows.
    * Mirrors POST /v1/apps/{app_id}/workflows/{alias}/execute.
@@ -30720,6 +30728,7 @@ import { spawn } from "node:child_process";
 // src/dev/rpc_handler.ts
 var SUPPORTED_OPS = /* @__PURE__ */ new Set([
   "query",
+  "field_options",
   "workflow",
   "members",
   "context",
@@ -30761,6 +30770,13 @@ async function dispatchRpc(client, body, opts) {
         count: p.count
       });
     }
+    case "field_options": {
+      const p = body.payload;
+      if (!p || typeof p.alias !== "string") {
+        throw new Error("field_options payload must include `alias`");
+      }
+      return client.appFieldOptions(body.app_id, p.alias);
+    }
     case "workflow": {
       const p = body.payload;
       if (!p || typeof p.alias !== "string") {
@@ -47578,6 +47594,8 @@ COMMANDS
   lotics tools                         List all available tools
   lotics tools <name>                  Show tool description and input schema
   lotics run <tool> '<json>'           Execute a tool
+  lotics run <tool> @args.json         Read JSON args from a file (large payloads)
+  cat args.json | lotics run <tool>    Read JSON args from stdin (large payloads)
   lotics upload <file|dir...>          Upload files (directories expand to their immediate files)
   lotics download <file_id>            Download a file by ID
   lotics download record <record_id> <field_key>
@@ -48022,7 +48040,9 @@ async function main() {
     process.exit(1);
   }
   if (command === "run" && !subcommand) {
-    console.error("Usage: lotics run <tool> '<json_args>'");
+    console.error(
+      "Usage: lotics run <tool> '<json_args>'\n       lotics run <tool> @args.json   (read args from a file \u2014 for large payloads)\n       cat args.json | lotics run <tool>   (read args from stdin)"
+    );
     console.error('Run "lotics tools" to see available tools.');
     process.exit(1);
   }
@@ -48254,7 +48274,17 @@ ${JSON.stringify(info.input_schema, null, 2)}`);
   if (command === "run") {
     const toolName = subcommand;
     let rawArgs = toolArgs;
-    if (!rawArgs && !process.stdin.isTTY) {
+    if (rawArgs && rawArgs.startsWith("@")) {
+      const argsPath = rawArgs.slice(1);
+      try {
+        rawArgs = fs7.readFileSync(argsPath, "utf-8");
+      } catch (err2) {
+        console.error(
+          `Cannot read args file "${argsPath}": ${err2 instanceof Error ? err2.message : String(err2)}`
+        );
+        process.exit(1);
+      }
+    } else if (!rawArgs && !process.stdin.isTTY) {
       rawArgs = await readStdin();
     }
     let args = {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/cli",
-  "version": "0.47.0",
+  "version": "0.49.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {