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_documentwith data and get the filled file. - App workflows — Steps that update records, generate documents and call connected services, written with
set_workflowand run withrun_app_workflow. - 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.
- Access — Share a table, app or knowledge doc with a member or group; read the audit log.
Five minutes, from nothing
Install the CLI — one command, nothing else required:
curl -fsSL https://lotics.ai/install.sh | bashThen sign this terminal in. The command prints a link and a four-character code; open the link in a browser, sign in or create an account there, by email or with Google, and confirm when the page shows the same code:
lotics auth loginYour tables and apps are two more calls to the same tools your agent uses, each reading a file:
lotics run set_tables @tables.json # every table in one call, all or nothing
lotics run set_app @orders.app.json # one app per call: {"body": {...}}Add --json to a call and it prints a single object instead of text — the ids it made and what it
adopted — which is what you want when an agent is reading the output rather than a person.
Or let your agent work it out
Give your coding agent — Claude Code, Cursor, Codex, whichever you use — the setup prompt: one sentence. It installs this CLI and signs in, reads the getting started guide in the Lotics docs, asks what you manage, builds your tables and apps from what you said, and ends in a workspace you can open in the browser.
lotics docs reference answers with no account, so a table or an app is written before anything is
created.
What you end up with is yours: ordinary tables and ordinary apps, live in your workspace — your agent
edits them from there, and so can you. lotics app pull writes an app’s body for your agent to
change and apply again, and lotics docs build is the sequence for everything after.
Install
macOS, Linux and WSL:
curl -fsSL https://lotics.ai/install.sh | bashWindows, in PowerShell:
irm https://lotics.ai/install.ps1 | iexEither one downloads a single compiled executable and checks it against a published checksum. There is no Node.js, no npm and no package manager involved, nothing is installed system-wide, and deleting the file removes it.
Running inside an agent sandbox or behind a corporate proxy? Three hosts have to be
reachable, and they are three different steps — lotics.ai serves the installer,
downloads.lotics.ai serves the executable it fetches, and api.lotics.ai is what the CLI
talks to afterwards. Allowing only the first gets you a download that stops halfway. Those
three cover building tables and apps as well, because Lotics builds and deploys the apps you set —
registry.npmjs.org is needed only for a custom-code app you build on this machine.
Confirm it worked — this prints a version number:
lotics --versionlotics upgrade updates it in place — it runs whichever installer this copy came from, so
you do not have to remember. Re-running the installer directly does the same thing, and
either is a no-op when you are already current. The CLI says when there is a newer version.
Setting tables and apps needs nothing more either: Lotics deploys every app you set, and nothing lands
on your disk. Node 18+ comes in only for a custom-code app built on this machine —
lotics app create --custom, lotics app pull and lotics app deploy are what need it. Everything
else — signing in, setting tables and apps, working with records and documents — runs
off the executable alone.
Authentication
Sign in
lotics auth login # prints a link and a code, then exits
lotics auth login --wait # stays open until you press Confirm
lotics auth login --local # pins this directory to that org, and waitsUse this to sign a terminal in for the first time, on a new machine, or to add another organization to one that is already signed in — the organization you pick on the page becomes the active one. The command takes no address and sends no mail: it prints a link and a four-character code, then exits. Open the link in a browser, on any device, and sign in to Lotics if it asks. The page names the account you are signed in as — the terminal will act as that account — and shows a code. Press Confirm only if you started this sign-in in your own terminal and the page is showing that same code; then run the command you wanted and this machine picks the sign-in up. The link and the code are good for fifteen minutes — after that, run the command again for a new pair. Nothing to find in Settings and nothing to paste.
With no account, create one on that page, by email and a password or with Google. The page shows the terminal’s code beside the button, and one press creates the account and its first workspace and signs the terminal in. Creating the account accepts the Terms and Privacy Policy. An account with no workspace gets one button that creates the workspace and signs the terminal in. On a private instance people arrive by invitation, and the page asks a signed-out person to sign in.
Access the web app
lotics auth webSends a magic link email to your account’s email address. Click the link to access the web app. Requires an account.
Switch between organizations
Each organization this machine is signed in to is a profile. Switch the active one:
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 sign-in still comes from the global store:
lotics org use acme --local # writes ./.lotics/config.json (a pointer, no credential)
lotics workspace select wks_... # records the workspace in that pinAuth management
lotics auth login # sign in, or create an account — open the link, press Confirm
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 credentialA sign-in is stored once per org as a profile in ~/.lotics/config.json. A directory’s .lotics/config.json is a pin that holds no credential — a pointer to an org whose sign-in comes from the global store. A machine with nobody at it uses an API key instead: see CI / non-interactive.
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 login — sign in, or create an account on the page it opens
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 argumentsAlways inspect the schema (step 4) 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 run set_tables @tables.json Make or change tables: a list, all or nothing
lotics run set_app @app.json Make or change one app (dry_run checks, writes nothing)
lotics docs List this CLI's reference docs
lotics docs reference The tables and apps reference — offline, before an account exists
lotics docs <area> Print one, capped at a page (e.g. lotics docs reference)
lotics docs <area>/<section> One section, or one row of a table doc
lotics docs [<area>] --grep <text> Search the references on the server
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 (organization owner only)
lotics workspace settings Change its name, currency or timezone (workspace admin only)
lotics app <subcommand> Pull and apply an app's body, or create, build and deploy a custom-code app
lotics knowledge <subcommand> Create, read, label and update reference documents
lotics file upload <file|dir...> Upload files (alias: lotics upload)
lotics file download <file_id> Download a file by ID (alias: lotics download)
lotics file list What is in the file store, newest first — one page at a time
lotics report '<json>' Tell us what got in your waylotics --help prints this list with every subcommand and flag, rendered by the binary you have
installed — so it is never behind the version you are running.
Reference docs, matched to your version
This page describes what the CLI is for. The exact contract ships inside the CLI,
and lotics docs prints it:
lotics docs # the references this CLI carries
lotics docs reference # one reference
lotics docs reference/app-node # one section, or one row of a reference that is a tableEvery answer is one page at most. A reference longer than that prints its opening and the addresses that reach into it, so the next command is smaller than the last.
A page newer than your CLI — one an error from Lotics names — is read from Lotics, and so is a search:
lotics docs --grep currency # every reference that says it
lotics docs reference --grep currency # within one referenceAn error names a page in the form your CLI opens: lotics docs <path>, or, on an older CLI,
lotics run docs '{"path":"<path>"}'.
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.
A custom-code app’s SDK reference ships inside @lotics/app-sdk, at
node_modules/@lotics/app-sdk/AGENTS.md in the app.
Building apps
An app is one of two kinds. A JSON app is a body you write once; set_app builds it on Lotics,
and lotics app apply <file> sends a body from a file. A custom-code app is a React project built on your
machine against @lotics/app-sdk: lotics app create <name> --custom registers the app and links your
project’s folder to it, and lotics app deploy builds and ships it. lotics app pull brings the project up to date with the live
version after someone else deployed, and lotics app pull <app_id> <folder> fetches it into a new
folder on another machine. A project with edits of its own is never overwritten: the pull lists the
files you changed.
What an app reads and does is declared on the app itself, live: lotics run set_app
and set_workflow each make a new version of the app, and so does every apply
and deploy. To go back to an earlier one, apply the earlier body again, or deploy the earlier source —
the tables and the records the app wrote meanwhile stay as they are.
Start with lotics docs build, which is the sequence and the reasoning behind its order.
Tables and apps
lotics docs reference prints the reference for a table’s document and an app’s body — offline, before
an account exists.
set_tables takes a list of tables, one or many, and writes them all or none. A table is a document
keyed by alias: its fields are keyed by alias, a link names the table it points at by alias, or by the
ref of another table of the same call, and states whether it holds many rows (multi), and a two-way link
names its partner field with pair on both tables. A table with no id is made; with its id it is edited by a merge patch of its document
(RFC 7396) — what the patch leaves alone stays, and null
deletes. A deletion that would take data with it is refused unless the call carries force.
set_app takes one app per call: a whole body to create it, a merge patch of the body to edit it.
The body is the only home of the app’s name, description, icon and colour. base_version_id, the
version you read, makes the write refuse when the app has moved since. Any member may create an app over the tables and templates they can read. A write stores the pages and
lists the platform composed; edit them like any node, or
state false at a node to turn a default off (lotics docs design). dry_run runs the whole check and writes nothing.
A refusal lists everything wrong with the call at once, so one fix-and-run covers it. Build a new
workspace in one order: a single set_tables call with every table, then each app with set_app.
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.
What the tools cover
lotics tools lists every tool the CLI carries; these are the jobs they do.
| Job | Tools |
|---|---|
| Find your way | get_workspace lists the workspace’s tables, apps, knowledge docs, templates and members, each as a name, an id and one line. Narrow it by kind, or search it for a name, a field, a line of a reference document or a record |
| Tables | get_table reads a table’s document. set_tables creates and edits tables, a list of table documents at a time; set_table_views creates, edits, orders and deletes a table’s saved views; an item with delete: true removes a table and one with restore: true brings it back |
| Records | query_records reads rows, one record by its id, or statistics (aggregate); create_records, update_records and delete_records write them. Fields are addressed by alias. update_records also freezes and releases rows (locked), brings deleted rows back (restore) and, with request_change, asks the people who manage the table to change a locked one. query_audit_logs reads who changed what; to put an edit back, write the earlier value with update_records. Every record read carries comment_count; comments: true returns the thread. Comments are written in Lotics |
| Apps | get_app reads an app and what it can be asked to do. set_app creates and edits one, and removes or restores it. run_app_query and run_app_workflow use it; screenshot_app shows it drawn |
| Workflows | get_workflow lists workflows or reads one, and set_workflow writes and rehearses (dry_run) a table’s workflow, an automation or an app’s workflow, and deletes one. query_workflow_executions and get_workflow_execution read their runs, and set_workflow_execution retries or cancels one |
| Documents | get_template and set_template read and write Word, Excel, PDF and email templates, and set_template also removes or restores one. generate_document fills one with data. set_template with dry_run checks a template, a workbook’s markers included, without storing it, and for a PDF form it and get_template answer where each page’s labels sit |
| Files | upload_file and download_file bring a file in and hand one back; lotics file upload and lotics file download move files from and to disk; delete_file removes one nothing references any more |
| Knowledge | get_workspace lists reference documents and searches them, read_knowledge reads one, set_knowledge creates and edits them, archives one and restores it |
| Workspace | set_workspace changes the workspace’s name, timezone and default currency, the standing instructions every agent in it follows and the daily credit ceilings; it is a workspace admin’s |
| Access | set_access shares a table, app or knowledge doc with a member or group in the workspace, takes the access back, or moves a resource to another owner; sharing with someone outside the workspace is refused until they are added to it |
| People | get_workspace lists the people in the workspace, and the whole organization for a co-owner or the primary owner who asks for all. set_members invites people, adds them to the workspace or takes them out of it, sets their role there and keeps the workspace’s member groups; it is a workspace admin’s. Renaming, removing and restoring people, co-ownership and accounts without an email are done in Settings → Members. A member’s tool list does not carry it |
Flags
| Flag | Description |
|---|---|
--json |
Full JSON output (default is human-readable text) |
--timeout <ms> |
Stop each wait for the server’s answer after this many milliseconds (a whole number from 1 to 2147483647; default: wait for the server). A wait ends without an answer when --timeout passes or no answer arrives from the server. A read with no answer changed nothing: the command exits non-zero, printing the request id. A write with no answer exits non-zero, printing the request id (with error_code: "outcome_unknown" under --json), because it cannot say whether the call took effect: read before running it again. The download from a signed storage link is the one fetch outside this: it has no request id, and --timeout stops it too. Under --json every error is one JSON object on stdout |
-o <path> |
On download, the directory to save into. On run, the directory every signed link the answer carries is saved into. On knowledge get, the file to write |
--as <name> |
Override upload filename |
--api-key <key> |
API key for one command (overrides the saved sign-in 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:
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_document '{"..."}' --json
lotics download <file_id> ./bao_cao.xlsx # the file to write
lotics download <file_id> -o ./output/ # the directory to save into, under the stored nameThe path argument is the file, -o is the directory — the same split cp and curl -o use.
Name one or the other, not both. The written path goes to stdout, so a download pipes into
whatever opens it next.
Upload files before referencing them in tool args:
lotics upload ./data.csv ./report.pdf ./documents/
lotics run create_records '{"table_id":"tbl_...","records":[{"contract":["fil_..."]}]}'Stdin and files
Pipe JSON arguments via stdin instead of inline, or pass a file with a leading @. A trailing -
is what asks for stdin — without it the tool runs with no arguments and answers at once, which is
what a tool taking none should do:
echo '{"table_id":"tbl_..."}' | lotics run query_records -
lotics run query_records @args.jsonIn PowerShell, use the file form. Quotes inside an inline argument are consumed by the shell
before lotics sees them, and the CLI then reports the JSON it received with its quotes gone.
CI / non-interactive
A person’s terminal signs in. An API key is for a machine with nobody to press Confirm: a CI job, a scheduled automation, a cloud session. An admin creates one in the Lotics web app under Settings → API Keys, and it belongs to one organization.
export LOTICS_API_KEY=ltk_...
lotics run get_workspace '{}'
# Or target a saved org/workspace without changing the active one:
LOTICS_ORG=acme LOTICS_WORKSPACE=wks_... lotics run get_workspace '{}'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("get_workspace", {});
// 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. Sign in once — the sign-in is saved per org
lotics auth login # open the link it prints, sign in or create an account, press Confirm
# 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 set_tables
# 3. Make the tables, all of them in one call: {"tables": [...]}, written from
# the schema printed above.
lotics run set_tables @tables.json
# 4. Read the table back — its document names every field and select option by alias
lotics run get_table '{"table_id": "tbl_..."}'
# 5. Write, addressing fields and options by those aliases
lotics run create_records '{
"table_id": "tbl_...",
"records": [{"company": "Acme Corp", "status": ["open"]}]
}'Documents, 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.