---
title: "Lotics CLI & SDK | AI Agent Interface for Structured Data, Documents, and Workflows"
description: "Install the Lotics CLI to give your AI coding agent access to tables, records, document generation, workflow automation, and file management. npm install -g @lotics/cli."
---

# 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

```bash
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

```bash
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

```bash
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

```bash
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:

```bash
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:

```bash
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

```bash
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:

```bash
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

| Category | What it covers |
|---|---|
| Tables | Query, create, update, delete, clone tables. Add fields with types (text, number, date, select, linked records, formulas). Add validations |
| Records | Query with filters, create, update, delete records. Aggregate (count, sum, avg). Import/export Excel. Lock/unlock. Restore deleted |
| Views | Saved perspectives: filters, sorts, field visibility, color rules. Export to Excel |
| Files | Read file contents, attach files to records, remove attachments |
| Templates | List, inspect, and delete templates of any type (Excel, Word, PDF) |
| Excel Templates | Create Excel templates with named placeholders in the cells, inject data, generate filled `.xlsx` files. Find/update cells |
| Word Templates | Create Word templates with variables, loops (`{%for%}`), conditionals. Generate filled `.docx` |
| PDF Templates | Create HTML/CSS or fillable PDF templates. Generate filled PDFs. Analyze PDF structure |
| Automations | Create event-driven workflows: triggers (record created, field changed, schedule, webhook) + steps (update records, send email, AI actions). Search available step types and triggers |
| Apps | Create dedicated data interfaces with configured views and action buttons |
| Knowledge | Create, update, search, and read reference documents for workspace context |
| Admin | Query members, groups, audit logs |

## Flags

| Flag | Description |
|---|---|
| `--json` | Full JSON output (default is human-readable text) |
| `--timeout <ms>` | Timeout for tool execution (default: 60000) |
| `-o <path>` | Output directory for downloads |
| `--as <name>` | Override upload filename |
| `--api-key <key>` | API key (overrides saved config and LOTICS_API_KEY env) |
| `--workspace <id>` | Workspace override for one command (alias: `-w`) |
| `--version` | Show CLI version |

## Output

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

```bash
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:

```bash
lotics run generate_excel_from_template '{"..."}' --json
lotics download <file_id> -o ./output/
```

Upload files before referencing them in tool args:

```bash
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:

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

## CI / non-interactive

```bash
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)

```typescript
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.

```bash
# 1. Authenticate once — the key is saved per org
lotics auth signup agent@company.com --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.