Lotics CLI

Command-line interface for AI agents to interact with Lotics — a system of record with structured data, document generation, workflow automation, and a built-in web UI.

Through this CLI your agent can:

• Tables & Records — Create tables with typed fields (text, number, date, select, record links, formulas, files). Write, query, update, and aggregate records. Users see and edit the same data in a spreadsheet-like web UI with views, filters, and sorting.
• Document generation — Excel, Word, and PDF templates with variables. Call generate_excel_from_template with data and get a filled .xlsx. No library wrangling. Templates are created once, reused forever.
• Automations — Event-driven workflows: when a record is created, when a field changes, on a schedule. Chain steps: update records, send emails, call webhooks, run AI. Set up via CLI — they run without the agent being online.
• Files — Upload, attach to records, download. PDFs, images, spreadsheets.
• Apps — Build dedicated data interfaces with configured views, filters, and actions. No frontend code.
• Knowledge — Long-form reference documents the agent can search and read.
• Admin — Members, groups, role-based permissions, audit logs.

Install

npm install -g @lotics/cli

Requires Node.js 18+. Update with npm install -g @lotics/cli@latest. The CLI checks for updates daily.

Authentication

Create a new account

lotics auth signup                                       # interactive prompts
lotics auth signup agent@co.com --name "My Agent"        # non-interactive

Signup flags:

• --name <name> — display name (defaults to email prefix)
• --timezone <tz> — workspace timezone (defaults to UTC, e.g. Asia/Ho_Chi_Minh)

Signup creates an account, organization, workspace, and API key in one step. A magic link email is sent so you can access the web app — no password needed.

Access the web app

lotics auth web

Sends a magic link email to your account's email address. Click the link to access the web app. Requires a prior signup or setup.

Use an existing API key

lotics auth api-key                      # interactive prompt
lotics auth api-key ltk_...              # non-interactive

API keys can be created in the Lotics web app under Settings → API Keys.

Auth management

lotics auth web                     # send magic link email for web app access
lotics auth whoami                  # print current account email
lotics auth logout                  # remove saved credentials

API key saved to ~/.lotics/config.json. Auth priority: --api-key flag > LOTICS_API_KEY env > saved config.

Workflow

1. lotics auth signup                — create account or authenticate
2. lotics workspace                  — list workspaces (select one if multiple)
3. lotics tools                      — list available tools by category
4. lotics tools <name>               — show tool description + full input schema
5. 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. Query tools return IDs (table IDs, record IDs, file IDs) used as arguments to other tools.

Commands

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
lotics workspace                     List workspaces (marks current)
lotics workspace select <id>         Switch active workspace
lotics workspace create <name>       Create a new workspace (admin only)

Tool categories

Flags

Output

Default output is a human-readable text summary. Use --json for structured JSON for programmatic use.

Status messages (auth, download confirmations, errors) go to stderr. Tool output goes to stdout. This enables clean piping:

lotics run query_records '{"table_id":"tbl_..."}' --json | jq '.records[].name'

Errors print to stderr and exit with code 1.

Files

Some tools generate files and return { file_id, url, filename }. Download with:

lotics run generate_excel_from_template '{"..."}' --json
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:

echo '{"table_id":"tbl_..."}' | lotics run query_records

CI / non-interactive

export LOTICS_API_KEY=ltk_...
lotics run query_tables '{}'

SDK (Node.js)

import { LoticsClient } from "@lotics/cli";
const client = new LoticsClient({ apiKey: "ltk_..." });

// Discover tools
const { categories } = await client.listTools();
const info = await client.getTool("query_records");

// Execute tools
const { result } = await client.execute("query_tables", {});

// File operations
const upload = await client.uploadFiles(["./report.pdf", "./data.csv"]);
await client.downloadFile(url, "./output.xlsx");
await client.downloadFileById(fileId, "./downloads/");

Workflow examples

Every tool has a unique input schema. Always run lotics tools <name> first to see the exact fields, types, and format before constructing arguments. The examples below show the general patterns — actual field keys (fld_xxx), option keys (opt_xxx), and IDs are workspace-specific.

Set up a workspace from scratch

# 1. Create account
lotics auth signup agent@co.com --name "Ops Agent"

# 2. Create a table with typed fields
#    Field types: text, number, date, boolean, select, select_record_link, files, formula, rollup, lookup
#    Select options go in config: { "options": [{ "name": "Draft" }, { "name": "Sent" }] }
lotics tools create_table              # see full add_fields schema
lotics run create_table '{
  "name": "Invoices",
  "add_fields": [
    {"name": "Customer", "type": "text"},
    {"name": "Amount", "type": "number", "config": {"format": "currency", "currency": "USD"}},
    {"name": "Status", "type": "select", "config": {"options": [{"name": "Draft"}, {"name": "Sent"}, {"name": "Paid"}]}},
    {"name": "Due Date", "type": "date"},
    {"name": "Attachments", "type": "files"}
  ]
}'

# 3. Inspect the created table to get field keys (fld_xxx) and option keys (opt_xxx)
lotics run get_table '{"table_id": "tbl_..."}'

# 4. Write records using field keys from step 3
#    Select values are always arrays of option keys: ["opt_xxx"]
lotics run create_records '{
  "table_id": "tbl_...",
  "records": [
    {"fld_customer": "Acme Corp", "fld_amount": 2500, "fld_status": ["opt_draft"]},
    {"fld_customer": "Globex Inc", "fld_amount": 1800, "fld_status": ["opt_sent"]}
  ]
}'

# 5. Query records — filters use a tree structure with node_type
lotics tools query_records             # see full filter schema
lotics run query_records '{
  "table_id": "tbl_...",
  "filters": {"node_type": "condition", "field_key": "fld_status", "operator": "is", "value": "opt_draft"},
  "field_keys": ["fld_customer", "fld_amount", "fld_status"]
}'

Discover and navigate existing data

# List all tables in the workspace
lotics run query_tables '{}'

# Get a table's full schema — field keys, types, option keys
lotics run get_table '{"table_id": "tbl_..."}'

# Query records with pagination (max 50 per page)
lotics run query_records '{
  "table_id": "tbl_...",
  "pagination": {"offset": 0, "limit": 50}
}'

# Query with filters — filters use a tree structure
# Single condition:
lotics run query_records '{
  "table_id": "tbl_...",
  "filters": {"node_type": "condition", "field_key": "fld_status", "operator": "is", "value": "opt_paid"}
}'

# AND/OR groups:
lotics run query_records '{
  "table_id": "tbl_...",
  "filters": {
    "node_type": "group",
    "logic": "and",
    "children": [
      {"node_type": "condition", "field_key": "fld_status", "operator": "is", "value": "opt_draft"},
      {"node_type": "condition", "field_key": "fld_amount", "operator": "greater_than", "value": 1000}
    ]
  }
}'

# Aggregate records
lotics tools aggregate_records         # see available operations
lotics run aggregate_records '{
  "table_id": "tbl_...",
  "aggregate_option": {"operation": "sum", "field_key": "fld_amount"}
}'

Update records

# Uniform update — set the same values on multiple records
lotics run update_records '{
  "table_id": "tbl_...",
  "record_ids": ["rec_...", "rec_..."],
  "set": {"fld_status": ["opt_paid"]}
}'

# Update by condition instead of listing record IDs
lotics run update_records '{
  "table_id": "tbl_...",
  "condition": {"node_type": "condition", "field_key": "fld_status", "operator": "is", "value": "opt_draft"},
  "set": {"fld_status": ["opt_sent"]}
}'

# Per-record update — different values per record using rows (parallel arrays)
lotics run update_records '{
  "table_id": "tbl_...",
  "record_ids": ["rec_aaa", "rec_bbb"],
  "field_keys": ["fld_amount"],
  "rows": [[3000], [4500]]
}'

Create views

# Create a filtered view
lotics run create_view '{
  "table_id": "tbl_...",
  "name": "Unpaid Invoices",
  "filters": {"node_type": "condition", "field_key": "fld_status", "operator": "is_not", "value": "opt_paid"}
}'

# List views
lotics run query_views '{"table_id": "tbl_..."}'

Generate documents from templates

# 1. Upload an Excel template (.xlsx with {{placeholder}} markers)
lotics upload ./invoice_template.xlsx

# 2. Create a template — template_file_id is the file ID from upload
lotics tools create_excel_template     # see full schema
lotics run create_excel_template '{
  "name": "Invoice Template",
  "template_file_id": "fil_..."
}'

# 3. Generate a filled document — document_template_id is the template ID from step 2
lotics tools generate_excel_from_template
lotics run generate_excel_from_template '{
  "document_template_id": "dtl_...",
  "filename": "invoice_acme_2026",
  "data": {"customer": "Acme Corp", "amount": "2,500.00"}
}' --json

# 4. Download the generated file
lotics download <file_id> -o ./output/

Import data from Excel

# 1. Upload a spreadsheet
lotics upload ./contacts.xlsx

# 2. Import into a table — auto-maps columns by name, column_map overrides
lotics tools import_from_excel         # see full schema
lotics run import_from_excel '{
  "table_id": "tbl_...",
  "file_id": "fil_..."
}'

Upload files and attach to records

# 1. Upload files
lotics upload ./contract.pdf ./photo.jpg

# 2. Attach to a record's file field
lotics run add_files_to_record '{
  "table_id": "tbl_...",
  "record_id": "rec_...",
  "field_key": "fld_attachments",
  "file_ids": ["fil_...", "fil_..."]
}'