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.
• 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 [email protected] --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_...              # registers the key's org as a profile

API keys are created in the Lotics web app under Settings → API Keys. A key belongs to one organization, so this registers that org as a named profile — run it once per org. Registering another key adds a profile; it never overwrites an existing one.

Switch between organizations

Each saved key is a profile. Switch the active org with no re-pasting:

lotics org                          # list saved orgs (marks the active one)
lotics org use acme                 # switch active org by name (or org id)

To work in several orgs at once, pin a directory (e.g. a git worktree) to its own org so a switch elsewhere never disturbs it — the key still comes from the global store:

lotics org use acme --local         # writes ./.lotics/config.json (a pointer, no key)
lotics workspace select wks_...     # records the workspace in that pin

Auth management

lotics auth web                     # send magic link email for web app access
lotics auth whoami                  # show active account, org, workspace, and source
lotics auth logout [<name|id>]      # remove a profile (default: active), or unpin a directory
lotics auth logout --all            # remove every saved credential

Keys are stored once per org as profiles in ~/.lotics/config.json. A directory's .lotics/config.json is a keyless pin — a pointer to an org whose key comes from the global store. For ephemeral or CI use, set LOTICS_API_KEY instead of saving anything.

Resolution precedence (highest first): --api-key flag > LOTICS_API_KEY env > LOTICS_ORG env > local .lotics/config.json > global active profile. LOTICS_WORKSPACE (or --workspace) overrides the workspace.

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. 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 docs                          List the reference docs of the installed packages
lotics docs <area>                   Print one (e.g. lotics docs queries)
lotics org                           List saved orgs (marks active)
lotics org use <name|id> [--local]   Switch active org (--local pins this directory)
lotics workspace                     List workspaces in the active org (marks current)
lotics workspace select <id>         Switch active workspace
lotics workspace create <name>       Create a new workspace (admin only)
lotics app <subcommand>              Build, run and deploy a custom-code app
lotics knowledge <subcommand>        Create, read and update reference documents
lotics install <package_id>          Install a published package into this workspace
lotics upgrade                       Take the installed package's next version
lotics file upload <file|dir...>     Upload files (alias: lotics upload)
lotics file download <file_id>       Download a file by ID (alias: lotics download)
lotics xlsx <subcommand>             Read and edit .xlsx files on your own machine
lotics docx <subcommand>             Read and edit .docx files on your own machine
lotics report '<json>'               Tell us what got in your way

lotics --help prints this list with every subcommand and flag, and it is generated from the same table the CLI dispatches on — so it is never behind the binary you have installed.

Reference docs, matched to your version

This page describes what the CLI is for. The exact contract — what a query may express, what a workflow body may say, which props a component takes — ships inside the packages you install, and lotics docs prints it:

lotics docs                     # what is installed here, with each package's version
lotics docs queries             # one reference
lotics docs ui/templates        # when two packages share an area name

This page has one live copy and no version, which is right for describing a product and wrong for describing a contract: your project pins a version, and a hosted copy would answer for a different one.

Run from a directory with no packages installed, it knows only the CLI's own reference. After lotics app create — which installs the SDK and the UI kit — it resolves all of them.

Building apps

An app is a real Vite + React + TypeScript project you build locally and deploy as a version. The CLI carries the whole loop: lotics app create scaffolds one, lotics app dev runs it against real data with hot reload, lotics app check runs every pre-flight a deploy would without shipping anything, and lotics app deploy ships it. Workflows and AI agents bound to the app are authored the same way — as files on disk, pushed and verified server-side.

Start with lotics docs building_an_app, which is the sequence and the reasoning behind its order.

Packages

A package is a versioned app or document set someone has published. lotics install <package_id> materializes one into your workspace — tables, the app, its workflows and its knowledge — and lotics upgrade takes the next version, previewing first and refusing anything that needs a decision rather than guessing which of your edits to discard.

Telling us what got in your way

lotics report is the channel for the things nothing else records: a capability that does not exist, a command that succeeded and did the wrong thing, an error whose message did not say how to fix it. It takes a small frame rather than a paragraph — what you were trying to do, and what happened instead — because what you were trying to do is the one thing no log can reconstruct. Run it with no arguments to see the frame.

Tool categories

Flags

Output

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 '{}'

# Or target a saved org/workspace without changing the active one:
LOTICS_ORG=acme LOTICS_WORKSPACE=wks_... 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/");

What a session looks like

Everything past authentication is the same three moves: inspect a schema, run a tool, use the IDs it hands back.

# 1. Authenticate once — the key is saved per org
lotics auth signup [email protected] --name "Ops Agent"

# 2. Inspect before calling. This prints the schema for the version you have
#    installed, generated from the code — never guess argument names from a page
#    like this one.
lotics tools create_table

# 3. Create a table. Field properties sit FLAT on the field object.
lotics run create_table '{
  "name": "Invoices",
  "add_fields": [
    {"name": "Customer", "type": "text"},
    {"name": "Amount", "type": "number", "format": "currency", "currency": "USD"},
    {"name": "Status", "type": "select", "options": [{"name": "Draft"}, {"name": "Sent"}]},
    {"name": "Due Date", "type": "date"}
  ]
}'

# 4. Read back the generated keys — fld_… per field, opt_… per select option
lotics run get_table '{"table_id": "tbl_..."}'

# 5. Write, addressing fields by those keys. A select value is an array of option keys.
lotics run create_records '{
  "table_id": "tbl_...",
  "records": [{"fld_...": "Acme Corp", "fld_...": ["opt_..."]}]
}'

Documents, automations, apps and files follow the same loop with different tools. The argument schemas are deliberately not reproduced on this page — lotics tools <name> prints the exact one for the version you installed, and a copy here would describe some other version to whoever read it next.