@lotics/cli 0.1.0 → 0.2.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
 
 # 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");
 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

@@ -6,37 +6,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>                 Upload a local file
+  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/
 
-ENVIRONMENT
-  LOTICS_API_KEY    API key (overrides saved config)
-  LOTICS_API_URL    API URL (overrides saved config)`);
+  Upload files before referencing them in tool args:
+
+    lotics upload ./data.csv
+    lotics run create_records '{"file_id":"fil_..."}'
+
+STDIN
+  Pipe JSON arguments via stdin instead of inline:
+
+    echo '{"table_id":"tbl_..."}' | lotics run query_records`);
 }
 function parseArgs(argv) {
     const flags = {
@@ -45,7 +71,6 @@ function parseArgs(argv) {
         output: undefined,
         as: undefined,
         apiKey: undefined,
-        apiUrl: undefined,
         version: false,
         help: false,
     };
@@ -72,9 +97,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;
@@ -119,15 +141,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 +157,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,7 +166,7 @@ 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 });
 }
 async function main() {
     const { command, subcommand, toolArgs, flags } = parseArgs(process.argv.slice(2));
@@ -160,7 +180,7 @@ async function main() {
     }
     // --- Commands that don't require auth ---
     if (command === "auth") {
-        await handleAuth(flags);
+        await handleAuth();
         return;
     }
     if (command === "logout") {
@@ -198,9 +218,9 @@ async function main() {
         }
         else {
             const { categories } = await client.listTools();
-            for (const [category, names] of Object.entries(categories)) {
-                console.log(`\n${category}`);
-                console.log(`  ${names.join("  ")}`);
+            for (const [category, { description, tools }] of Object.entries(categories)) {
+                console.log(description ? `\n## ${category} — ${description}` : `\n## ${category}`);
+                console.log(`  ${tools.join(", ")}`);
             }
             console.log("");
         }
@@ -264,7 +284,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?: {

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();

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.2.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {