@lotics/cli 0.10.0 → 0.12.0

package/dist/src/cli.js

@@ -38,6 +38,8 @@ COMMANDS
   lotics run <tool> '<json>'           Execute a tool
   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>
+                                       Download all files on a record file field
 
 FLAGS
   --json             Full JSON output (default is human-readable text)
@@ -48,9 +50,10 @@ FLAGS
   --version          Show version
 
 OUTPUT
-  Default output is a human-readable text summary. Use --json to get
-  structured JSON for programmatic use. Errors print to stderr and
-  exit with code 1.
+  Default output is a compact text summary optimized for AI agents —
+  use it directly, no parsing needed. --json returns raw structured
+  JSON for machine-to-machine pipelines (scripts, CI). Errors print
+  to stderr and exit with code 1.
 
 FILES
   Some tools generate files and return { file_id, url, filename }.
@@ -406,10 +409,17 @@ async function main() {
         process.exit(1);
     }
     if (command === "download" && !subcommand) {
-        console.error('Usage: lotics download <file_id> [-o <dir>]');
+        console.error('Usage:');
+        console.error('  lotics download <file_id> [-o <dir>]');
+        console.error('  lotics download record <record_id> <field_key> [-o <dir>]');
         console.error('File IDs come from upload results or generate_* tool output (--json).');
         process.exit(1);
     }
+    if (command === "download" && subcommand === "record" && (!toolArgs || restArgs.length === 0)) {
+        console.error('Usage: lotics download record <record_id> <field_key> [-o <dir>]');
+        console.error('Downloads every file on the given file field into the output dir.');
+        process.exit(1);
+    }
     const client = requireClient(flags);
     // lotics workspace / lotics workspace list / lotics workspace select <id>
     if (command === "workspace") {
@@ -536,7 +546,23 @@ async function main() {
         return;
     }
     // lotics download <file_id> [-o <path>]
+    // lotics download record <record_id> <field_key> [-o <path>]
     if (command === "download") {
+        if (subcommand === "record") {
+            const recordId = toolArgs;
+            const fieldKey = restArgs[0];
+            const files = await client.downloadRecordFiles(recordId, fieldKey, flags.output);
+            if (flags.json) {
+                console.log(JSON.stringify(files, null, 2));
+            }
+            else {
+                for (const f of files) {
+                    console.log(`${f.file_id}  ${f.path}  ${f.filename}`);
+                }
+                console.error(`Downloaded ${files.length} file${files.length === 1 ? "" : "s"} from ${recordId}.${fieldKey}`);
+            }
+            return;
+        }
         const { path: filePath, filename } = await client.downloadFileById(subcommand, flags.output);
         console.error(`Downloaded: ${filePath} (${filename})`);
         return;

package/dist/src/client.d.ts

@@ -67,10 +67,17 @@ export declare class LoticsClient {
         timeoutMs?: number;
     }): Promise<ToolExecuteResult>;
     downloadFile(url: string, outputPath: string): Promise<string>;
-    downloadFileById(fileId: string, outputDir?: string): Promise<{
+    downloadFileById(fileId: string, outputDir?: string, options?: {
+        reserved?: Set<string>;
+    }): Promise<{
         path: string;
         filename: string;
     }>;
+    downloadRecordFiles(recordId: string, fieldKey: string, outputDir?: string): Promise<Array<{
+        path: string;
+        filename: string;
+        file_id: string;
+    }>>;
     uploadFiles(filePaths: string[], options?: {
         filenames?: string[];
     }): Promise<FileUploadResult>;

package/dist/src/client.js

@@ -1,5 +1,29 @@
 import fs from "node:fs";
 import path from "node:path";
+function findAvailableFilename(dir, filename, reserved) {
+    // `reserved` tracks absolute paths claimed by in-flight downloads in the same
+    // batch — required for parallel callers because the file may not be on disk
+    // yet when a peer call races to pick a name.
+    const isTaken = (name) => {
+        const full = path.join(dir, name);
+        if (reserved?.has(full))
+            return true;
+        return fs.existsSync(full);
+    };
+    const claim = (name) => {
+        reserved?.add(path.join(dir, name));
+        return name;
+    };
+    if (!isTaken(filename))
+        return claim(filename);
+    const lastDot = filename.lastIndexOf(".");
+    const base = lastDot > 0 ? filename.slice(0, lastDot) : filename;
+    const ext = lastDot > 0 ? filename.slice(lastDot) : "";
+    let n = 2;
+    while (isTaken(`${base}_${n}${ext}`))
+        n++;
+    return claim(`${base}_${n}${ext}`);
+}
 const MIME_MAP = {
     ".jpg": "image/jpeg",
     ".jpeg": "image/jpeg",
@@ -125,7 +149,7 @@ export class LoticsClient {
         await fs.promises.writeFile(absolutePath, buffer);
         return absolutePath;
     }
-    async downloadFileById(fileId, outputDir) {
+    async downloadFileById(fileId, outputDir, options) {
         const url = `${this.baseUrl}/v1/files/${encodeURIComponent(fileId)}/download`;
         const response = await fetch(url, {
             headers: this.buildHeaders(),
@@ -134,13 +158,35 @@ export class LoticsClient {
             await this.throwResponseError(response);
         const disposition = response.headers.get("content-disposition") ?? "";
         const match = disposition.match(/filename="?([^";\n]+)"?/);
-        const filename = match?.[1] ?? fileId;
+        const originalFilename = match?.[1] ?? fileId;
         const buffer = Buffer.from(await response.arrayBuffer());
         const dir = outputDir ? path.resolve(outputDir) : process.cwd();
+        const filename = findAvailableFilename(dir, originalFilename, options?.reserved);
         const absolutePath = path.join(dir, filename);
         await fs.promises.writeFile(absolutePath, buffer);
         return { path: absolutePath, filename };
     }
+    async downloadRecordFiles(recordId, fieldKey, outputDir) {
+        const result = await this.execute("get_record", { record_id: recordId }, { format: "text" });
+        if (result.error)
+            throw new Error(result.error);
+        const record = result.result;
+        const files = record?.data?.[fieldKey];
+        if (!Array.isArray(files)) {
+            throw new Error(`Field ${fieldKey} on ${recordId} is not a file field or has no value`);
+        }
+        const fileIds = files.map((f, i) => {
+            if (typeof f !== "object" || f === null || !("id" in f) || typeof f.id !== "string") {
+                throw new Error(`Invalid file entry [${i}] in ${recordId}.${fieldKey}: ${JSON.stringify(f)}`);
+            }
+            return f.id;
+        });
+        const reserved = new Set();
+        return Promise.all(fileIds.map(async (fileId) => {
+            const res = await this.downloadFileById(fileId, outputDir, { reserved });
+            return { ...res, file_id: fileId };
+        }));
+    }
     async uploadFiles(filePaths, options) {
         const formData = new FormData();
         for (let i = 0; i < filePaths.length; i++) {

package/package.json

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