@lotics/cli 0.1.0 → 0.3.0

package/README.md

@@ -2,6 +2,13 @@
 
 CLI and SDK for AI agents to interact with Lotics.
 
+Lotics is an AI-powered operations platform. Through this CLI you can:
+
+- Manage tables, records, and views (structured data with typed fields)
+- Generate documents from templates (Excel, Word, PDF)
+- Build and run automations (event-driven workflows)
+- Create and manage apps, knowledge docs, and files
+
 ## Install
 
 ```bash
@@ -23,25 +30,22 @@ The CLI checks for updates once per day and prompts when a new version is availa
 lotics auth
 
 # 2. Discover tools
-lotics tools                    # list all tool names
-lotics tools query_records      # show description + input schema
+lotics tools                    # list tools by category with descriptions
+lotics tools query_records      # show full description + input schema
 
 # 3. Execute
 lotics run query_tables '{}'
 lotics run query_records '{"table_id":"tbl_...","field_keys":["name"]}'
-lotics run query_records --json '{"table_id":"tbl_..."}'
 
 # Pipe args via stdin
 echo '{"table_id":"tbl_..."}' | lotics run query_records
 
-# Upload a file
-lotics upload ./report.pdf
-lotics upload ./photo.jpg --as cover.jpg
+# Upload files (multiple files and directories supported)
+lotics upload ./report.pdf ./data.csv ./documents/
 
 # Generate a file, then download it
-lotics run generate_excel_from_template '{"..."}' --json
-# → {"file_id":"fil_...","url":"...","filename":"report.xlsx",...}
-lotics download fil_... -o ./reports/
+lotics run generate_excel_from_template '{"..."}'
+lotics download <file_id> -o ./reports/
 
 # CI / non-interactive
 LOTICS_API_KEY=ltk_... lotics run query_tables '{}'
@@ -52,14 +56,11 @@ LOTICS_API_KEY=ltk_... lotics run query_tables '{}'
 ```typescript
 import { LoticsClient } from "@lotics/cli";
 
-const client = new LoticsClient({
-  apiKey: "ltk_...",
-  baseUrl: "https://api.lotics.com",
-});
+const client = new LoticsClient({ apiKey: "ltk_..." });
 
 const { result } = await client.execute("query_tables", {});
-const upload = await client.uploadFile("./report.pdf");
+const upload = await client.uploadFiles(["./report.pdf", "./data.csv"]);
 await client.downloadFile(url, "./output.xlsx");
-const { tools } = await client.listTools();
+const { tools, categories } = await client.listTools();
 const info = await client.getTool("query_records");
 ```

package/dist/src/cli.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
 import readline from "node:readline";
 import { LoticsClient } from "./client.js";
 import { resolveAuth, loadConfig, saveConfig, deleteConfig, getConfigPath, checkForUpdate } from "./config.js";
@@ -6,37 +8,63 @@ import { VERSION } from "./version.js";
 function printHelp() {
     console.log(`Lotics CLI v${VERSION} — AI agent interface for Lotics
 
-Lotics is an AI-powered operations platform for structured data,
-document generation, automations, and knowledge management.
+Lotics is an AI-powered operations platform. Through this CLI you can:
+  - Manage tables, records, and views (structured data with typed fields)
+  - Generate documents from templates (Excel, Word, PDF)
+  - Build and run automations (event-driven workflows)
+  - Create and manage apps, knowledge docs, and files
+
+USAGE
+  1. lotics auth                       Authenticate (saves key to ~/.lotics/config.json)
+  2. lotics tools                      List available tools by category
+  3. lotics tools <name>               Show tool description and full input schema
+  4. lotics run <tool> '<json>'        Execute a tool with JSON arguments
+
+  Always inspect the schema (step 3) before calling a tool.
+  Tools are grouped by category (tables, records, views, etc.).
+  Query tools return IDs used as arguments to other tools.
 
 COMMANDS
-  lotics auth                    Save API key (interactive)
-  lotics logout                  Remove saved credentials
-  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> --json       Full JSON output instead of compact text
-  lotics upload <file>           Upload a local file
-  lotics download <file_id>      Download a file by ID
+  lotics auth                          Save API key (interactive)
+  lotics logout                        Remove saved credentials
+  lotics tools                         List all available tools
+  lotics tools <name>                  Show tool description and input schema
+  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
 
 FLAGS
-  --json             Full JSON output
+  --json             Full JSON output (default is human-readable text)
   --timeout <ms>     Timeout for tool execution (default: 60000)
   -o <path>          Output dir for downloads
   --as <name>        Override upload filename
-  --api-key <key>    API key (for CI/agents)
-  --api-url <url>    API URL override
+  --api-key <key>    API key (overrides saved config and LOTICS_API_KEY)
   --version          Show version
 
-WORKFLOW
-  1. lotics auth                 Authenticate once
-  2. lotics tools                See what's available
-  3. lotics tools <name>         Read the schema before calling
-  4. lotics run <tool> '<json>'  Execute with correct args
+  For non-interactive use, set LOTICS_API_KEY in the environment
+  instead of running lotics auth.
+
+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.
+
+FILES
+  Some tools generate files and return { file_id, url, filename }.
+  Use lotics download to save locally:
+
+    lotics run generate_excel_from_template '{"..."}'
+    lotics download <file_id> -o ./output/
+
+  Upload files before referencing them in tool args:
+
+    lotics upload ./data.csv ./report.pdf ./documents/
+    lotics run create_records '{"table_id":"tbl_...","records":[{"fld_file":["fil_..."]}]}'
+
+STDIN
+  Pipe JSON arguments via stdin instead of inline:
 
-ENVIRONMENT
-  LOTICS_API_KEY    API key (overrides saved config)
-  LOTICS_API_URL    API URL (overrides saved config)`);
+    echo '{"table_id":"tbl_..."}' | lotics run query_records`);
 }
 function parseArgs(argv) {
     const flags = {
@@ -45,13 +73,13 @@ function parseArgs(argv) {
         output: undefined,
         as: undefined,
         apiKey: undefined,
-        apiUrl: undefined,
         version: false,
         help: false,
     };
     let command;
     let subcommand;
     let toolArgs;
+    const restArgs = [];
     let i = 0;
     while (i < argv.length) {
         const arg = argv[i];
@@ -72,9 +100,6 @@ function parseArgs(argv) {
             case "--api-key":
                 flags.apiKey = argv[++i];
                 break;
-            case "--api-url":
-                flags.apiUrl = argv[++i];
-                break;
             case "--version":
             case "-v":
                 flags.version = true;
@@ -93,11 +118,14 @@ function parseArgs(argv) {
                 else if (!toolArgs) {
                     toolArgs = arg;
                 }
+                else {
+                    restArgs.push(arg);
+                }
                 break;
         }
         i++;
     }
-    return { command, subcommand, toolArgs, flags };
+    return { command, subcommand, toolArgs, restArgs, flags };
 }
 function readStdin() {
     return new Promise((resolve, reject) => {
@@ -119,15 +147,13 @@ function prompt(question) {
         });
     });
 }
-async function handleAuth(flags) {
+async function handleAuth() {
     const apiKey = await prompt("Enter your API key: ");
     if (!apiKey) {
         console.error("No API key provided.");
         process.exit(1);
     }
-    const apiUrlInput = flags.apiUrl ?? (await prompt("API URL (default: https://api.lotics.com): "));
-    const apiUrl = apiUrlInput || "https://api.lotics.com";
-    const client = new LoticsClient({ apiKey, baseUrl: apiUrl });
+    const client = new LoticsClient({ apiKey });
     try {
         await client.listTools();
     }
@@ -137,7 +163,7 @@ async function handleAuth(flags) {
         process.exit(1);
     }
     const existing = loadConfig() ?? {};
-    saveConfig({ ...existing, api_key: apiKey, api_url: apiUrl });
+    saveConfig({ ...existing, api_key: apiKey });
     console.error(`Authenticated. Config saved to ${getConfigPath()}`);
 }
 function requireClient(flags) {
@@ -146,10 +172,32 @@ function requireClient(flags) {
         console.error('Not authenticated. Run "lotics auth" or set LOTICS_API_KEY.');
         process.exit(1);
     }
-    return new LoticsClient({ apiKey: auth.apiKey, baseUrl: auth.apiUrl });
+    return new LoticsClient({ apiKey: auth.apiKey });
+}
+/**
+ * Resolve upload paths: files pass through, directories expand to their immediate files.
+ */
+function resolveUploadPaths(rawPaths) {
+    const result = [];
+    for (const p of rawPaths) {
+        const resolved = path.resolve(p);
+        const stat = fs.statSync(resolved);
+        if (stat.isDirectory()) {
+            const entries = fs.readdirSync(resolved, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.isFile()) {
+                    result.push(path.join(resolved, entry.name));
+                }
+            }
+        }
+        else {
+            result.push(resolved);
+        }
+    }
+    return result;
 }
 async function main() {
-    const { command, subcommand, toolArgs, flags } = parseArgs(process.argv.slice(2));
+    const { command, subcommand, toolArgs, restArgs, flags } = parseArgs(process.argv.slice(2));
     if (flags.help || (!command && !flags.version)) {
         printHelp();
         return;
@@ -160,7 +208,7 @@ async function main() {
     }
     // --- Commands that don't require auth ---
     if (command === "auth") {
-        await handleAuth(flags);
+        await handleAuth();
         return;
     }
     if (command === "logout") {
@@ -180,8 +228,8 @@ async function main() {
         process.exit(1);
     }
     if (command === "upload" && !subcommand) {
-        console.error('Usage: lotics upload <file> [--as <name>]');
-        console.error('Uploads a local file and returns its file_id.');
+        console.error('Usage: lotics upload <file|dir...> [--as <name>]');
+        console.error('Uploads files and returns their file_ids. Directories expand to their immediate files.');
         process.exit(1);
     }
     if (command === "download" && !subcommand) {
@@ -194,28 +242,58 @@ async function main() {
     if (command === "tools") {
         if (subcommand) {
             const info = await client.getTool(subcommand);
-            console.log(JSON.stringify(info, null, 2));
+            if (flags.json) {
+                console.log(JSON.stringify(info, null, 2));
+            }
+            else {
+                console.log(`${info.name}\n\n${info.description}\n\nInput schema:\n${JSON.stringify(info.input_schema, null, 2)}`);
+            }
         }
         else {
             const { categories } = await client.listTools();
-            for (const [category, names] of Object.entries(categories)) {
-                console.log(`\n${category}`);
-                console.log(`  ${names.join("  ")}`);
+            if (flags.json) {
+                console.log(JSON.stringify(categories, null, 2));
+            }
+            else {
+                for (const [category, { description, tools }] of Object.entries(categories)) {
+                    console.log(description ? `\n## ${category} — ${description}` : `\n## ${category}`);
+                    console.log(`  ${tools.join(", ")}`);
+                }
+                console.log("");
             }
-            console.log("");
         }
         return;
     }
-    // lotics upload <file> [--as <name>]
+    // lotics upload <file|dir...> [--as <name>]
     if (command === "upload") {
-        const upload = await client.uploadFile(subcommand, {
-            filename: flags.as,
+        const rawPaths = [subcommand, ...(toolArgs ? [toolArgs] : []), ...restArgs];
+        const filePaths = resolveUploadPaths(rawPaths);
+        if (filePaths.length === 0) {
+            console.error("No files found in the specified paths.");
+            process.exit(1);
+        }
+        if (flags.as && filePaths.length > 1) {
+            console.error("Cannot use --as with multiple files.");
+            process.exit(1);
+        }
+        const upload = await client.uploadFiles(filePaths, {
+            filenames: flags.as ? [flags.as] : undefined,
         });
-        if (upload.errors.length > 0) {
-            console.error(`Upload failed: ${upload.errors[0].error}`);
+        if (upload.files.length === 0 && upload.errors.length > 0) {
+            console.error(`Upload failed: ${upload.errors.map((e) => `${e.filename}: ${e.error}`).join(", ")}`);
             process.exit(1);
         }
-        console.log(JSON.stringify(upload.files[0], null, 2));
+        if (flags.json) {
+            console.log(JSON.stringify({ files: upload.files, errors: upload.errors }, null, 2));
+        }
+        else {
+            for (const file of upload.files) {
+                console.log(`${file.id}  ${file.filename}  ${file.mime_type}`);
+            }
+            for (const error of upload.errors) {
+                console.error(`FAILED  ${error.filename}  ${error.error}`);
+            }
+        }
         return;
     }
     // lotics download <file_id> [-o <path>]
@@ -241,18 +319,22 @@ async function main() {
                 process.exit(1);
             }
         }
-        const format = flags.json ? "json" : "text";
         const timeoutMs = flags.timeout ?? 60000;
-        const result = await client.execute(toolName, args, { format, timeoutMs });
+        // Always request text format so model_output is available; --json only affects CLI output
+        const result = await client.execute(toolName, args, { format: "text", timeoutMs });
         if (result.error) {
             console.error(result.error);
             console.error(`\nHint: run "lotics tools ${toolName}" to see the expected input schema.`);
             process.exit(1);
         }
-        if (format === "text" && result.model_output) {
+        if (flags.json) {
+            console.log(JSON.stringify(result.result, null, 2));
+        }
+        else if (result.model_output) {
             console.log(result.model_output);
         }
         else {
+            // Fallback: compact JSON when no text output is available
             console.log(JSON.stringify(result.result, null, 2));
         }
         return;
@@ -264,7 +346,6 @@ main()
     const message = error instanceof Error ? error.message : String(error);
     if (message.includes("fetch failed") || message.includes("ECONNREFUSED")) {
         console.error("Could not connect to the Lotics API.");
-        console.error('Check your API URL or run "lotics auth" to reconfigure.');
     }
     else if (message.includes("ENOENT")) {
         const pathMatch = message.match(/open '([^']+)'/);

package/dist/src/client.d.ts

@@ -1,6 +1,5 @@
 export interface LoticsClientOptions {
     apiKey: string;
-    baseUrl?: string;
 }
 export interface ToolExecuteResult {
     result: unknown;
@@ -30,10 +29,11 @@ export declare class LoticsClient {
     private throwResponseError;
     private request;
     listTools(): Promise<{
-        tools: Array<{
-            name: string;
+        tools: string[];
+        categories: Record<string, {
+            description: string;
+            tools: string[];
         }>;
-        categories: Record<string, string[]>;
     }>;
     getTool(name: string): Promise<ToolInfo>;
     execute(tool: string, args: Record<string, unknown>, options?: {
@@ -45,7 +45,7 @@ export declare class LoticsClient {
         path: string;
         filename: string;
     }>;
-    uploadFile(filePath: string, options?: {
-        filename?: string;
+    uploadFiles(filePaths: string[], options?: {
+        filenames?: string[];
     }): Promise<FileUploadResult>;
 }

package/dist/src/client.js

@@ -26,7 +26,7 @@ export class LoticsClient {
     baseUrl;
     constructor(options) {
         this.apiKey = options.apiKey;
-        this.baseUrl = (options.baseUrl ?? "https://api.lotics.com").replace(/\/$/, "");
+        this.baseUrl = "https://api.lotics.ai";
     }
     async throwResponseError(response) {
         const text = await response.text();
@@ -116,14 +116,16 @@ export class LoticsClient {
         await fs.promises.writeFile(absolutePath, buffer);
         return { path: absolutePath, filename };
     }
-    async uploadFile(filePath, options) {
-        const absolutePath = path.resolve(filePath);
-        const buffer = await fs.promises.readFile(absolutePath);
-        const filename = options?.filename ?? path.basename(absolutePath);
-        const mimeType = getMimeType(filename);
-        const blob = new Blob([buffer], { type: mimeType });
+    async uploadFiles(filePaths, options) {
         const formData = new FormData();
-        formData.append("file", blob, filename);
+        for (let i = 0; i < filePaths.length; i++) {
+            const absolutePath = path.resolve(filePaths[i]);
+            const buffer = await fs.promises.readFile(absolutePath);
+            const filename = options?.filenames?.[i] ?? path.basename(absolutePath);
+            const mimeType = getMimeType(filename);
+            const blob = new Blob([buffer], { type: mimeType });
+            formData.append("file", blob, filename);
+        }
         const url = `${this.baseUrl}/v1/files`;
         const response = await fetch(url, {
             method: "POST",

package/dist/src/config.d.ts

@@ -1,6 +1,5 @@
 export interface LoticsConfig {
     api_key?: string;
-    api_url?: string;
     last_update_check?: number;
     latest_version?: string;
 }
@@ -15,13 +14,11 @@ export declare function getConfigPath(): string;
  */
 export declare function checkForUpdate(currentVersion: string): void;
 /**
- * Resolve API key and URL from flags, env vars, or config file.
- * Priority: flag > env > config file > default.
+ * Resolve API key from flags, env vars, or config file.
+ * Priority: flag > env > config file.
  */
 export declare function resolveAuth(flags: {
     apiKey?: string;
-    apiUrl?: string;
 }): {
     apiKey: string;
-    apiUrl: string;
 } | null;

package/dist/src/config.js

@@ -75,17 +75,13 @@ function printUpdateWarning(current, latest) {
     console.error(`Run: npm i -g @lotics/cli\n`);
 }
 /**
- * Resolve API key and URL from flags, env vars, or config file.
- * Priority: flag > env > config file > default.
+ * Resolve API key from flags, env vars, or config file.
+ * Priority: flag > env > config file.
  */
 export function resolveAuth(flags) {
     const config = loadConfig();
     const apiKey = flags.apiKey ?? process.env.LOTICS_API_KEY ?? config?.api_key;
     if (!apiKey)
         return null;
-    const apiUrl = flags.apiUrl ??
-        process.env.LOTICS_API_URL ??
-        config?.api_url ??
-        "https://api.lotics.com";
-    return { apiKey, apiUrl };
+    return { apiKey };
 }

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.1.0";
+export declare const VERSION: string;

package/dist/src/version.js

@@ -1 +1,6 @@
-export const VERSION = "0.1.0";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+const pkgPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../package.json");
+const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+export const VERSION = pkg.version;

package/package.json

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