Lotics CLI

Giao diện dòng lệnh cho trợ lý AI tương tác với Lotics -- hệ thống lưu trữ với dữ liệu có cấu trúc, tạo chứng từ, tự động hóa quy trình và giao diện web tích hợp.

Thông qua CLI này, trợ lý của bạn có thể:

• Bảng & Bản ghi -- Tạo bảng với trường có kiểu dữ liệu (văn bản, số, ngày, chọn, liên kết bản ghi, công thức, file). Ghi, truy vấn, cập nhật và tổng hợp bản ghi. Người dùng xem và chỉnh sửa cùng dữ liệu trong giao diện web dạng bảng tính với chế độ xem, bộ lọc và sắp xếp.
• Tạo chứng từ -- Mẫu Excel, Word và PDF với biến. Gọi generate_excel_from_template với dữ liệu và nhận file .xlsx đã điền. Không cần xử lý thư viện. Mẫu tạo một lần, dùng mãi.
• Tự động hóa -- Quy trình hướng sự kiện: khi bản ghi được tạo, khi trường thay đổi, theo lịch. Chuỗi các bước: cập nhật bản ghi, gửi email, gọi webhook, chạy AI. Thiết lập qua CLI -- chúng chạy mà không cần trợ lý trực tuyến.
• File -- Tải lên, đính kèm vào bản ghi, tải xuống. PDF, hình ảnh, bảng tính.
• Ứng dụng -- Xây dựng giao diện dữ liệu chuyên biệt với chế độ xem, bộ lọc và hành động được cấu hình. Không cần code frontend.
• Kiến thức -- Tài liệu tham khảo dài mà trợ lý có thể tìm kiếm và đọc.
• Quản trị -- Thành viên, nhóm, quyền hạn dựa trên vai trò, nhật ký kiểm tra.

Cài đặt

npm install -g @lotics/cli

Yêu cầu Node.js 18+. Cập nhật bằng npm install -g @lotics/cli@latest. CLI kiểm tra cập nhật hàng ngày.

Xác thực

Tạo tài khoản mới

lotics auth signup                                       # nhắc tương tác
lotics auth signup agent@co.com --name "My Agent"        # không tương tác

Cờ đăng ký:

• --name <name> -- tên hiển thị (mặc định là tiền tố email)
• --timezone <tz> -- múi giờ không gian làm việc (mặc định UTC, ví dụ: Asia/Ho_Chi_Minh)

Đăng ký tạo tài khoản, tổ chức, không gian làm việc và khóa API trong một bước. Email magic link được gửi để bạn truy cập ứng dụng web — không cần mật khẩu.

Truy cập ứng dụng web

lotics auth web

Gửi email magic link đến địa chỉ email tài khoản của bạn. Nhấn vào link để truy cập ứng dụng web. Yêu cầu đã đăng ký hoặc thiết lập trước đó.

Sử dụng khóa API hiện có

lotics auth api-key                      # nhắc tương tác
lotics auth api-key ltk_...              # đăng ký tổ chức của khóa thành một hồ sơ

Khóa API được tạo trong ứng dụng web Lotics tại Cài đặt -> Khóa API. Một khóa thuộc về một tổ chức, nên lệnh này đăng ký tổ chức đó thành một hồ sơ có tên — chạy một lần cho mỗi tổ chức. Đăng ký thêm khóa sẽ thêm hồ sơ; không bao giờ ghi đè hồ sơ đã có.

Chuyển đổi giữa các tổ chức

Mỗi khóa đã lưu là một hồ sơ. Chuyển tổ chức hoạt động mà không cần dán lại khóa:

lotics org                          # liệt kê tổ chức đã lưu (đánh dấu tổ chức hoạt động)
lotics org use acme                 # chuyển tổ chức theo tên (hoặc ID tổ chức)

Để làm việc nhiều tổ chức cùng lúc, ghim một thư mục (ví dụ git worktree) vào tổ chức riêng để việc chuyển đổi ở nơi khác không ảnh hưởng — khóa vẫn lấy từ kho chung:

lotics org use acme --local         # ghi ./.lotics/config.json (con trỏ, không chứa khóa)
lotics workspace select wks_...     # lưu không gian vào ghim đó

Quản lý xác thực

lotics auth web                     # gửi email magic link để truy cập ứng dụng web
lotics auth whoami                  # hiển thị tài khoản, tổ chức, không gian hoạt động và nguồn
lotics auth logout [<name|id>]      # xóa một hồ sơ (mặc định: tổ chức hoạt động), hoặc bỏ ghim thư mục
lotics auth logout --all            # xóa toàn bộ thông tin đăng nhập đã lưu

Khóa được lưu một lần cho mỗi tổ chức dưới dạng hồ sơ tại ~/.lotics/config.json. File .lotics/config.json của một thư mục là một ghim không chứa khóa — con trỏ tới tổ chức, khóa lấy từ kho chung. Cho CI hoặc dùng tạm thời, đặt LOTICS_API_KEY thay vì lưu file.

Thứ tự ưu tiên (cao nhất trước): cờ --api-key > biến môi trường LOTICS_API_KEY > biến môi trường LOTICS_ORG > file .lotics/config.json cục bộ > hồ sơ hoạt động chung. LOTICS_WORKSPACE (hoặc --workspace) ghi đè không gian làm việc.

Quy trình làm việc

1. lotics auth signup                   — tạo tài khoản hoặc xác thực
2. lotics workspace                    — liệt kê không gian (chọn nếu có nhiều)
3. lotics tools                        — liệt kê công cụ có sẵn theo danh mục
4. lotics tools <name>                 — hiển thị mô tả công cụ + schema đầu vào đầy đủ
5. lotics run <tool> '<json>'          — thực thi công cụ với tham số JSON

Luôn kiểm tra schema (bước 3) trước khi gọi công cụ. Công cụ được nhóm theo danh mục. Công cụ truy vấn trả về ID (ID bảng, ID bản ghi, ID file) được dùng làm tham số cho công cụ khác.

Các lệnh

lotics tools                         Liệt kê tất cả công cụ có sẵn
lotics tools <name>                  Hiển thị mô tả và schema đầu vào của công cụ
lotics run <tool> '<json>'           Thực thi công cụ
lotics upload <file|dir...>          Tải file lên (thư mục mở rộng thành các file trực tiếp bên trong)
lotics download <file_id>            Tải file xuống theo ID
lotics org                           Liệt kê tổ chức đã lưu (đánh dấu hoạt động)
lotics org use <name|id> [--local]   Chuyển tổ chức hoạt động (--local ghim thư mục này)
lotics workspace                     Liệt kê không gian trong tổ chức hoạt động (đánh dấu hiện tại)
lotics workspace select <id>         Chuyển không gian hoạt động
lotics workspace create <name>       Tạo không gian mới (chỉ admin)

Danh mục công cụ

Cờ

Đầu ra

Đầu ra mặc định là tóm tắt văn bản dễ đọc. Sử dụng --json cho JSON có cấu trúc để sử dụng lập trình.

Thông báo trạng thái (xác thực, xác nhận tải xuống, lỗi) xuất ra stderr. Đầu ra công cụ xuất ra stdout. Điều này cho phép piping sạch:

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

Lỗi in ra stderr và thoát với mã 1.

File

Một số công cụ tạo file và trả về { file_id, url, filename }. Tải xuống bằng:

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

Tải file lên trước khi tham chiếu trong tham số công cụ:

lotics upload ./data.csv ./report.pdf ./documents/
lotics run create_records '{"table_id":"tbl_...","records":[{"fld_file":["fil_..."]}]}'

Stdin

Pipe tham số JSON qua stdin thay vì inline:

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

CI / không tương tác

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

# Hoặc nhắm tới tổ chức/không gian đã lưu mà không đổi tổ chức hoạt động:
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/");

Ví dụ quy trình làm việc

Mỗi công cụ có schema đầu vào riêng. Luôn chạy lotics tools <name> trước để xem chính xác các trường, kiểu dữ liệu và định dạng trước khi xây dựng tham số. Các ví dụ dưới đây cho thấy các mẫu chung -- khóa trường thực tế (fld_xxx), khóa tùy chọn (opt_xxx) và ID là riêng theo từng không gian làm việc.

Thiết lập không gian làm việc từ đầu

# 1. Tạo tài khoản
lotics auth signup agent@co.com --name "Ops Agent"

# 2. Tạo bảng với trường có kiểu dữ liệu
#    Loại trường: text, number, date, boolean, select, select_record_link, files, formula, rollup, lookup
#    Tùy chọn chọn nằm trong config: { "options": [{ "name": "Draft" }, { "name": "Sent" }] }
lotics tools create_table              # xem schema add_fields đầy đủ
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. Kiểm tra bảng đã tạo để lấy khóa trường (fld_xxx) và khóa tùy chọn (opt_xxx)
lotics run get_table '{"table_id": "tbl_..."}'

# 4. Ghi bản ghi sử dụng khóa trường từ bước 3
#    Giá trị chọn luôn là mảng khóa tùy chọn: ["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. Truy vấn bản ghi — bộ lọc sử dụng cấu trúc cây với node_type
lotics tools query_records             # xem schema bộ lọc đầy đủ
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"]
}'

Khám phá và điều hướng dữ liệu hiện có

# Liệt kê tất cả bảng trong không gian làm việc
lotics run query_tables '{}'

# Lấy schema đầy đủ của bảng — khóa trường, kiểu dữ liệu, khóa tùy chọn
lotics run get_table '{"table_id": "tbl_..."}'

# Truy vấn bản ghi với phân trang (tối đa 50 mỗi trang)
lotics run query_records '{
  "table_id": "tbl_...",
  "pagination": {"offset": 0, "limit": 50}
}'

# Truy vấn với bộ lọc — bộ lọc sử dụng cấu trúc cây
# Điều kiện đơn:
lotics run query_records '{
  "table_id": "tbl_...",
  "filters": {"node_type": "condition", "field_key": "fld_status", "operator": "is", "value": "opt_paid"}
}'

# Nhóm AND/OR:
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}
    ]
  }
}'

# Tổng hợp bản ghi
lotics tools aggregate_records         # xem các thao tác có sẵn
lotics run aggregate_records '{
  "table_id": "tbl_...",
  "aggregate_option": {"operation": "sum", "field_key": "fld_amount"}
}'

Cập nhật bản ghi

# Cập nhật đồng nhất — đặt cùng giá trị cho nhiều bản ghi
lotics run update_records '{
  "table_id": "tbl_...",
  "record_ids": ["rec_...", "rec_..."],
  "set": {"fld_status": ["opt_paid"]}
}'

# Cập nhật theo điều kiện thay vì liệt kê ID bản ghi
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"]}
}'

# Cập nhật từng bản ghi — giá trị khác nhau cho mỗi bản ghi sử dụng rows (mảng song song)
lotics run update_records '{
  "table_id": "tbl_...",
  "record_ids": ["rec_aaa", "rec_bbb"],
  "field_keys": ["fld_amount"],
  "rows": [[3000], [4500]]
}'

Tạo chế độ xem

# Tạo chế độ xem có bộ lọc
lotics run create_view '{
  "table_id": "tbl_...",
  "name": "Unpaid Invoices",
  "filters": {"node_type": "condition", "field_key": "fld_status", "operator": "is_not", "value": "opt_paid"}
}'

# Liệt kê chế độ xem
lotics run query_views '{"table_id": "tbl_..."}'

Tạo chứng từ từ mẫu

# 1. Tải lên mẫu Excel (.xlsx với ký hiệu {{placeholder}})
lotics upload ./invoice_template.xlsx

# 2. Tạo mẫu — template_file_id là ID file từ tải lên
lotics tools create_excel_template     # xem schema đầy đủ
lotics run create_excel_template '{
  "name": "Invoice Template",
  "template_file_id": "fil_..."
}'

# 3. Tạo chứng từ đã điền — document_template_id là ID mẫu từ bước 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. Tải xuống file đã tạo
lotics download <file_id> -o ./output/

Nhập dữ liệu từ Excel

# 1. Tải lên bảng tính
lotics upload ./contacts.xlsx

# 2. Nhập vào bảng — tự động ánh xạ cột theo tên, column_map ghi đè
lotics tools import_from_excel         # xem schema đầy đủ
lotics run import_from_excel '{
  "table_id": "tbl_...",
  "file_id": "fil_..."
}'

Tải file lên và đính kèm vào bản ghi

# 1. Tải file lên
lotics upload ./contract.pdf ./photo.jpg

# 2. Đính kèm vào trường file của bản ghi
lotics run add_files_to_record '{
  "table_id": "tbl_...",
  "record_id": "rec_...",
  "field_key": "fld_attachments",
  "file_ids": ["fil_...", "fil_..."]
}'