@lotics/cli 0.9.0 → 0.12.0

package/README.md

@@ -25,27 +25,27 @@ The CLI checks for updates once per day and prompts when a new version is availa
 
 ## Authentication
 
-**`lotics signup`** — Creates a new Lotics account, organization, workspace, and API key in one step. Sends a magic link email so you can access the web app.
+**`lotics auth signup`** — Creates a new Lotics account, organization, workspace, and API key in one step. Sends a magic link email so you can access the web app.
 
 ```bash
-lotics signup                                        # interactive prompts
-lotics signup --email a@b.com --name "Agent"         # non-interactive
+lotics auth signup                                   # interactive prompts
+lotics auth signup a@b.com --name "Agent"            # non-interactive
 ```
 
-**`lotics login`** — Send a magic link email to access the web app (requires prior signup or setup).
+**`lotics auth web`** — Send a magic link email to access the web app (requires prior signup or setup).
 
 ```bash
-lotics login
+lotics auth web
 ```
 
-**`lotics setup`** — Saves an existing API key directly (e.g. one created in the Lotics web app).
+**`lotics auth api-key`** — Saves an existing API key directly (e.g. one created in the Lotics web app).
 
 ```bash
-lotics setup                    # interactive prompt
-lotics setup ltk_...            # non-interactive
+lotics auth api-key                  # interactive prompt
+lotics auth api-key ltk_...          # non-interactive
 ```
 
-API key is saved to `~/.lotics/config.json`. Run `lotics logout` to remove saved credentials.
+API key is saved to `~/.lotics/config.json`. Run `lotics auth logout` to remove saved credentials.
 
 Auth priority: `--api-key` flag > `LOTICS_API_KEY` env > `~/.lotics/config.json`.
 

package/dist/src/cli.js

@@ -15,23 +15,11 @@ Lotics is an AI-powered operations platform. Through this CLI you can:
   - Create and manage apps, knowledge docs, and files
 
 AUTHENTICATION
-  lotics signup                        Create account, org, workspace, and API key
-  lotics login                         Send a magic link email to access the web app
-  lotics setup [api_key]               Save an existing API key (e.g. from the web app)
-  lotics whoami                        Show the email of the current account
-  lotics logout                        Remove saved credentials
-
-  Signup flags:
-    --email <email>        Email (required; prompted if omitted)
-    --name <name>          Display name (defaults to email prefix)
-    --timezone <timezone>  Workspace timezone (defaults to UTC, e.g. Asia/Ho_Chi_Minh)
-
-  Signup sends a magic link email so you can access the Lotics web app.
-  Use lotics login to request a new magic link at any time.
-  Setup priority: --api-key flag > LOTICS_API_KEY env > saved config.
+  lotics auth                          Show auth help
+  lotics auth signup <email>           Create account (run "lotics auth" for details)
 
 USAGE
-  1. lotics signup (or lotics setup)   Create account or set up API key
+  1. lotics auth signup <email>        Create account or authenticate
   2. lotics workspace                  Check current workspace (auto-selects if only one)
   3. lotics tools                      List available tools by category
   4. lotics tools <name>               Show tool description and full input schema
@@ -50,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)
@@ -60,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 }.
@@ -81,6 +72,23 @@ STDIN
 
     echo '{"table_id":"tbl_..."}' | lotics run query_records`);
 }
+function printAuthHelp() {
+    console.log(`Authentication commands:
+
+  lotics auth signup <email>           Create account, org, workspace, and API key
+  lotics auth api-key [key]            Save an existing API key (e.g. from the web app)
+  lotics auth web                      Send a magic link email to access the web app
+  lotics auth whoami                   Show the email of the current account
+  lotics auth logout                   Remove saved credentials
+
+Signup flags:
+  --name <name>          Display name (defaults to email prefix)
+  --timezone <timezone>  Workspace timezone (defaults to UTC, e.g. Asia/Ho_Chi_Minh)
+
+Signup sends a magic link email so you can access the Lotics web app.
+Use lotics auth web to request a new magic link at any time.
+Auth priority: --api-key flag > LOTICS_API_KEY env > saved config.`);
+}
 function parseArgs(argv) {
     const flags = {
         json: false,
@@ -88,7 +96,6 @@ function parseArgs(argv) {
         output: undefined,
         as: undefined,
         apiKey: undefined,
-        email: undefined,
         name: undefined,
         timezone: undefined,
         version: false,
@@ -118,9 +125,6 @@ function parseArgs(argv) {
             case "--api-key":
                 flags.apiKey = argv[++i];
                 break;
-            case "--email":
-                flags.email = argv[++i];
-                break;
             case "--name":
                 flags.name = argv[++i];
                 break;
@@ -183,10 +187,10 @@ async function publicPost(path, body) {
     const data = await response.json();
     return { ok: response.ok, status: response.status, data };
 }
-async function handleSignup(flags) {
-    const email = flags.email ?? (process.stdin.isTTY ? await prompt("Email: ") : "");
+async function handleSignup(positionalEmail, flags) {
+    const email = positionalEmail ?? (process.stdin.isTTY ? await prompt("Email: ") : "");
     if (!email) {
-        console.error("Email is required. Use --email or run interactively.");
+        console.error("Email is required. Usage: lotics auth signup <email>");
         process.exit(1);
     }
     const name = flags.name ?? (process.stdin.isTTY ? await prompt("Name (enter to use email): ") : undefined);
@@ -198,7 +202,7 @@ async function handleSignup(flags) {
     const { ok, status, data } = await publicPost("/v1/cli/signup", body);
     if (!ok) {
         if (status === 409) {
-            console.error("An account with this email already exists. Use: lotics setup");
+            console.error("An account with this email already exists. Use: lotics auth api-key");
         }
         else if (status === 429) {
             console.error("Too many signup attempts. Try again later.");
@@ -218,7 +222,7 @@ async function handleSignup(flags) {
     console.error(`Account created. You can now use the CLI.`);
     console.error(`  Email: ${data.email}`);
     console.error(`\nCheck your email for a magic link to access the Lotics web app.`);
-    console.error(`Run "lotics login" to request a new link at any time.`);
+    console.error(`Run "lotics auth web" to request a new link at any time.`);
 }
 async function handleSetup(providedKey) {
     const apiKey = providedKey ?? await prompt("Enter your API key: ");
@@ -260,7 +264,7 @@ async function handleSetup(providedKey) {
 function requireClient(flags) {
     const auth = resolveAuth(flags);
     if (!auth) {
-        console.error('Not authenticated. Run "lotics setup" or set LOTICS_API_KEY.');
+        console.error('Not authenticated. Run "lotics auth signup" or set LOTICS_API_KEY.');
         process.exit(1);
     }
     const config = loadConfig();
@@ -334,51 +338,58 @@ async function main() {
         console.log(VERSION);
         return;
     }
-    // --- Commands that don't require auth ---
-    if (command === "signup") {
-        await handleSignup(flags);
-        return;
-    }
-    if (command === "setup") {
-        await handleSetup(subcommand ?? flags.apiKey);
-        return;
-    }
-    if (command === "whoami") {
-        const config = loadConfig();
-        if (config?.email) {
-            console.log(config.email);
+    // --- lotics auth <subcommand> ---
+    if (command === "auth") {
+        if (subcommand === "signup") {
+            await handleSignup(toolArgs, flags);
             return;
         }
-        // No email cached — try fetching from API
-        const auth = resolveAuth(flags);
-        if (!auth) {
-            console.error('Not authenticated. Run "lotics setup" or set LOTICS_API_KEY.');
-            process.exit(1);
+        if (subcommand === "api-key") {
+            await handleSetup(toolArgs ?? flags.apiKey);
+            return;
         }
-        const client = new LoticsClient({ apiKey: auth.apiKey });
-        try {
-            const info = await client.whoami();
-            // Cache for next time
-            const existing = loadConfig() ?? {};
-            saveConfig({ ...existing, email: info.email });
-            console.log(info.email);
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            console.error(`Failed to fetch account info: ${message}`);
-            process.exit(1);
+        if (subcommand === "whoami") {
+            const config = loadConfig();
+            if (config?.email) {
+                console.log(config.email);
+                return;
+            }
+            // No email cached — try fetching from API
+            const auth = resolveAuth(flags);
+            if (!auth) {
+                console.error('Not authenticated. Run "lotics auth signup" or set LOTICS_API_KEY.');
+                process.exit(1);
+            }
+            const client = new LoticsClient({ apiKey: auth.apiKey });
+            try {
+                const info = await client.whoami();
+                // Cache for next time
+                const existing = loadConfig() ?? {};
+                saveConfig({ ...existing, email: info.email });
+                console.log(info.email);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                console.error(`Failed to fetch account info: ${message}`);
+                process.exit(1);
+            }
+            return;
         }
-        return;
-    }
-    if (command === "logout") {
-        deleteConfig();
-        console.error("Logged out. Credentials removed.");
-        return;
-    }
-    if (command === "login") {
-        const client = requireClient(flags);
-        const { email } = await client.login();
-        console.error(`Magic link sent to ${email}. Check your email to access the Lotics web app.`);
+        if (subcommand === "logout") {
+            deleteConfig();
+            console.error("Logged out. Credentials removed.");
+            return;
+        }
+        if (subcommand === "web") {
+            const client = requireClient(flags);
+            const { email } = await client.login();
+            console.error(`Magic link sent to ${email}. Check your email to access the Lotics web app.`);
+            return;
+        }
+        if (subcommand) {
+            console.error(`Unknown auth subcommand: ${subcommand}\n`);
+        }
+        printAuthHelp();
         return;
     }
     // --- Validate command before auth ---
@@ -398,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") {
@@ -528,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.9.0",
+  "version": "0.12.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {