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.
• 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 [email protected] --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ụ 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 docs                          Liệt kê tài liệu tham khảo của các gói đã cài
lotics docs <area>                   In một tài liệu (ví dụ: lotics docs queries)
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)
lotics app <subcommand>              Xây dựng, chạy và triển khai ứng dụng mã tùy chỉnh
lotics knowledge <subcommand>        Tạo, đọc và cập nhật tài liệu tham khảo
lotics install <package_id>          Cài một gói đã phát hành vào không gian này
lotics upgrade                       Nâng gói đã cài lên phiên bản kế tiếp
lotics file upload <file|dir...>     Tải file lên (bí danh: lotics upload)
lotics file download <file_id>       Tải file xuống theo ID (bí danh: lotics download)
lotics xlsx <subcommand>             Đọc và sửa file .xlsx ngay trên máy bạn
lotics docx <subcommand>             Đọc và sửa file .docx ngay trên máy bạn
lotics report '<json>'               Cho chúng tôi biết điều gì đang cản trở bạn

lotics --help in đầy đủ danh sách này kèm mọi lệnh con và cờ, và nó được sinh ra từ chính bảng mà CLI dùng để điều phối lệnh — nên nó không bao giờ lạc hậu so với bản bạn đang cài.

Tài liệu tham khảo, khớp với phiên bản bạn dùng

Trang này mô tả CLI dùng để làm gì. Còn hợp đồng chính xác — một truy vấn được phép biểu đạt điều gì, thân quy trình được viết ra sao, một thành phần nhận những props nào — nằm bên trong các gói bạn cài, và lotics docs in ra chúng:

lotics docs                     # những gì đang cài ở đây, kèm phiên bản từng gói
lotics docs queries             # một tài liệu
lotics docs ui/templates        # khi hai gói trùng tên khu vực

Trang này chỉ có một bản duy nhất và không mang phiên bản — điều đó đúng cho việc mô tả sản phẩm nhưng sai cho việc mô tả hợp đồng: dự án của bạn ghim một phiên bản, còn một bản sao đặt trên web sẽ trả lời thay cho phiên bản khác.

Chạy từ thư mục chưa cài gói nào, nó chỉ biết tài liệu của riêng CLI. Sau lotics app create — lệnh này cài SDK và bộ giao diện — nó phân giải được tất cả.

Xây dựng ứng dụng

Một ứng dụng là dự án Vite + React + TypeScript thật, bạn dựng ở máy mình rồi triển khai thành một phiên bản. CLI mang trọn vòng lặp đó: lotics app create tạo khung, lotics app dev chạy ứng dụng với dữ liệu thật kèm hot reload, lotics app check chạy mọi bước kiểm tra tiền triển khai mà không phát hành gì, và lotics app deploy đưa nó lên. Quy trình và agent AI gắn với ứng dụng cũng được viết theo cách đó — là file trên đĩa, đẩy lên và được máy chủ xác minh.

Bắt đầu từ lotics docs building_an_app — tài liệu này trình bày trình tự và lý do của trình tự đó.

Gói cài sẵn

Gói là một ứng dụng hoặc bộ chứng từ đã được phát hành theo phiên bản. lotics install <package_id> đưa nó vào không gian của bạn — bảng, ứng dụng, quy trình và tài liệu kèm theo — còn lotics upgrade nâng lên phiên bản kế tiếp: xem trước rồi từ chối những gì cần bạn quyết định, thay vì tự đoán nên bỏ đi thay đổi nào của bạn.

Báo cho chúng tôi điều gì đang cản trở

lotics report là kênh dành cho những thứ không có gì khác ghi nhận được: một khả năng chưa tồn tại, một lệnh chạy thành công nhưng làm sai việc, một thông báo lỗi không nói được cách khắc phục. Nó nhận một khung ngắn thay vì một đoạn văn — bạn đang định làm gì, và điều gì đã xảy ra — bởi vì điều bạn đang định làm là thứ duy nhất không nhật ký nào dựng lại được. Chạy lệnh không kèm tham số để xem khung đó.

Danh mục công cụ

Cờ

Đầu ra

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/");

Một phiên làm việc trông như thế nào

Sau bước xác thực, mọi thứ đều lặp lại đúng ba động tác: xem schema, chạy công cụ, dùng các ID mà nó trả về.

# 1. Xác thực một lần — khóa được lưu theo từng tổ chức
lotics auth signup [email protected] --name "Ops Agent"

# 2. Xem schema trước khi gọi. Lệnh này in ra schema của đúng phiên bản bạn đang
#    cài, sinh ra từ mã nguồn — đừng đoán tên tham số từ một trang như trang này.
lotics tools create_table

# 3. Tạo bảng. Thuộc tính của trường nằm PHẲNG ngay trên đối tượng trường.
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. Đọc lại các khóa vừa sinh — fld_… cho trường, opt_… cho lựa chọn
lotics run get_table '{"table_id": "tbl_..."}'

# 5. Ghi dữ liệu theo các khóa đó. Giá trị select luôn là mảng khóa lựa chọn.
lotics run create_records '{
  "table_id": "tbl_...",
  "records": [{"fld_...": "Acme Corp", "fld_...": ["opt_..."]}]
}'

Chứng từ, tự động hóa, ứng dụng và file đều đi theo vòng lặp này, chỉ đổi công cụ. Schema tham số được cố ý không chép lại vào trang này — lotics tools <name> in ra đúng schema của phiên bản bạn đã cài, còn một bản chép ở đây sẽ mô tả một phiên bản khác cho người đọc kế tiếp.