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_documentvới dữ liệu và nhận tệp đã điền. - Quy trình của ứng dụng – Các bước cập nhật bản ghi, tạo chứng từ và gọi dịch vụ đã kết nối, viết bằng
set_workflowvà chạy bằngrun_app_workflow. - 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.
- Quyền truy cập – Chia sẻ một bảng, ứng dụng hoặc tài liệu kiến thức cho một thành viên hay nhóm; đọc nhật ký kiểm tra.
Năm phút, từ con số không
Cài CLI — một lệnh, không cần gì thêm:
curl -fsSL https://lotics.ai/install.sh | bashSau đó đăng nhập dòng lệnh này. Lệnh in ra một liên kết cùng một mã bốn ký tự; mở liên kết trong trình duyệt, đăng nhập hoặc tạo tài khoản ngay tại đó, bằng email hoặc bằng Google, rồi xác nhận khi trang hiện đúng mã đó:
lotics auth loginCác bảng và ứng dụng của bạn là hai lệnh nữa, gọi đúng những công cụ mà trợ lý của bạn dùng, mỗi lệnh đọc từ một tệp:
lotics run set_tables @tables.json # mọi bảng trong một lệnh, làm trọn hoặc không làm gì
lotics run set_app @orders.app.json # mỗi lệnh một ứng dụng: {"body": {...}}Thêm --json vào một lệnh thì nó in ra đúng một đối tượng thay vì văn bản — các mã nó đã tạo và
những gì nó đã tự chọn — đây là dạng bạn cần khi người đọc kết quả là một trợ lý chứ không phải con
người.
Hoặc để trợ lý tự tìm hiểu rồi dựng
Đưa cho trợ lý lập trình của bạn — Claude Code, Cursor, Codex, hay bất kỳ công cụ nào bạn dùng — lời nhắc thiết lập: chỉ một câu. Nó tự cài CLI này và đăng nhập, đọc hướng dẫn bắt đầu trong tài liệu Lotics, hỏi bạn quản lý cái gì, dựng các bảng và ứng dụng từ chính lời bạn kể, và kết thúc ở một không gian làm việc bạn mở được ngay trong trình duyệt.
lotics docs reference chạy được khi chưa có tài khoản, nên một bảng hay một ứng dụng được viết xong trước khi có bất cứ thứ gì được tạo ra.
Những gì bạn nhận được là của bạn: bảng bình thường và ứng dụng bình thường, chạy ngay trong không
gian làm việc của bạn — trợ lý của bạn sửa tiếp từ đó, và bạn cũng sửa được. lotics app pull ghi
ra phần thân của một ứng dụng để trợ lý của bạn sửa rồi áp lại, còn
lotics docs build là trình tự cho mọi việc sau đó.
Cài đặt
Trên macOS, Linux và WSL:
curl -fsSL https://lotics.ai/install.sh | bashTrên Windows, mở PowerShell rồi chạy:
irm https://lotics.ai/install.ps1 | iexCả hai đều tải về đúng một tệp chạy đã biên dịch sẵn và đối chiếu với mã kiểm tra đã công bố. Không dính đến Node.js, npm hay bất kỳ trình quản lý gói nào, không cài gì ở phạm vi toàn hệ thống, và xoá tệp đó là gỡ sạch.
Chạy trong môi trường sandbox của một trợ lý AI, hoặc sau proxy của công ty? Cần mở cho ba tên
miền, và đó là ba bước khác nhau: lotics.ai phục vụ trình cài đặt, downloads.lotics.ai phục vụ
tệp chạy mà nó tải về, còn api.lotics.ai là nơi CLI làm việc sau đó. Chỉ mở tên miền đầu thì tải
được nửa chừng rồi dừng. Ba tên miền đó đủ cho cả việc đặt bảng và ứng dụng, vì các ứng dụng được dựng
và triển khai bên Lotics — chỉ một ứng dụng viết mã mà bạn tự dựng trên máy này mới cần thêm
registry.npmjs.org.
Kiểm tra đã cài được chưa — lệnh này in ra số phiên bản:
lotics --versionlotics upgrade cập nhật ngay tại chỗ — lệnh này tự chạy đúng trình cài đặt mà bản CLI
này đến từ đó, nên bạn không cần nhớ. Chạy thẳng lệnh cài đặt cũng cho kết quả như vậy, và
cả hai đều không làm gì nếu bạn đang ở bản mới nhất. CLI sẽ báo khi có phiên bản mới.
Đặt bảng và ứng dụng cũng không cần thêm gì: Lotics triển khai mọi ứng dụng bạn đặt, và không có
gì rơi xuống đĩa của bạn. Node 18+ chỉ cần cho một ứng dụng viết mã dựng trên máy này —
lotics app create --custom, lotics app pull và lotics app deploy mới là chỗ cần nó. Mọi việc
còn lại — đăng nhập, đặt bảng và ứng dụng, làm việc với bản ghi và chứng từ —
chỉ cần tệp chạy đó là đủ.
Xác thực
Đăng nhập
lotics auth login # in ra một liên kết và một mã, rồi thoát
lotics auth login --wait # ở lại chờ tới khi bạn bấm Xác nhận
lotics auth login --local # ghim thư mục này vào tổ chức đó, và chờDùng lệnh này để đăng nhập dòng lệnh lần đầu, trên máy mới, hoặc để thêm một tổ chức khác vào máy đã đăng nhập — tổ chức bạn chọn trên trang sẽ thành tổ chức đang hoạt động. Lệnh không nhận địa chỉ nào và không gửi thư: nó in ra một liên kết cùng một mã bốn ký tự, rồi thoát. Mở liên kết trong trình duyệt, trên thiết bị nào cũng được, và đăng nhập Lotics nếu được hỏi. Trang ghi rõ tài khoản bạn đang đăng nhập — dòng lệnh sẽ thay mặt tài khoản đó — và hiện một mã. Chỉ bấm Xác nhận khi chính bạn vừa bắt đầu lần đăng nhập này trên dòng lệnh của mình và trang hiện đúng mã đó; sau đó chạy lệnh bạn đang cần và máy này tự nhận phiên đăng nhập. Liên kết và mã chỉ dùng được trong mười lăm phút — quá hạn thì chạy lại lệnh để lấy cặp mới. Không phải tìm gì trong phần Cài đặt, cũng không phải dán gì.
Chưa có tài khoản thì tạo ngay trên trang đó, bằng email và mật khẩu hoặc bằng Google. Trang hiện mã của dòng lệnh bên cạnh nút bấm, và một lần bấm tạo tài khoản cùng không gian làm việc đầu tiên rồi đăng nhập luôn dòng lệnh. Việc tạo tài khoản đồng nghĩa với chấp nhận Điều khoản và Chính sách quyền riêng tư. Tài khoản chưa có không gian làm việc thì thấy một nút tạo không gian làm việc và đăng nhập dòng lệnh. Trên bản triển khai riêng, mọi người vào bằng lời mời, và trang yêu cầu người chưa đăng nhập đăng nhập trước.
Truy cập ứng dụng web
lotics auth webGử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 đã có tài khoản.
Chuyển đổi giữa các tổ chức
Mỗi tổ chức mà máy này đã đăng nhập là một hồ sơ. Chuyển tổ chức đang hoạt động:
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 — phiên đăng nhập vẫn lấy từ kho chung:
lotics org use acme --local # ghi ./.lotics/config.json (con trỏ, không chứa thông tin đăng nhập)
lotics workspace select wks_... # lưu không gian vào ghim đóQuản lý xác thực
lotics auth login # đăng nhập, hoặc tạo tài khoản — mở liên kết, bấm Xác nhận
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ưuPhiên đăng nhập đượ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 thông tin đăng nhập — con trỏ tới tổ chức, phiên đăng nhập lấy từ kho chung. Máy không có người ngồi trước thì dùng khóa API: xem CI / không tương tác.
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 login — đăng nhập, hoặc tạo tài khoản trên trang lệnh mở ra
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ố JSONLuôn kiểm tra schema (bước 4) 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 run set_tables @tables.json Tạo hoặc sửa bảng: một danh sách, làm trọn hoặc không làm gì
lotics run set_app @app.json Tạo hoặc sửa một ứng dụng (dry_run để kiểm, không ghi gì)
lotics docs Liệt kê tài liệu tham khảo mà CLI này mang theo
lotics docs reference Tài liệu về bảng và ứng dụng — chạy không cần mạng, không cần tài khoản
lotics docs <area> In một tài liệu, tối đa một trang (ví dụ: lotics docs reference)
lotics docs <area>/<section> Một mục, hoặc một dòng của tài liệu dạng bảng
lotics docs [<area>] --grep <text> Tìm trong các tài liệu tham khảo trên máy chủ
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ỉ đồng chủ sở hữu hoặc chủ sở hữu chính)
lotics workspace settings Đổi tên, tiền tệ hay múi giờ của không gian (chỉ quản trị viên không gian)
lotics app <subcommand> Tạo ứng dụng viết mã, rồi dựng và triển khai nó
lotics knowledge <subcommand> Tạo, đọc, gắn nhãn và cập nhật tài liệu tham khảo
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 file list Kho file có gì, mới nhất trước — mỗi lần một trang
lotics report '<json>' Cho chúng tôi biết điều gì đang cản trở bạnlotics --help in đầy đủ danh sách này kèm mọi lệnh con và cờ, do chính bản CLI bạn đang cài in
ra — nên nó không bao giờ lạc hậu so với bản đó.
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 nằm bên trong chính CLI, và
lotics docs in ra nó:
lotics docs # các tài liệu mà CLI này mang theo
lotics docs reference # một tài liệu
lotics docs reference/app-node # một mục, hoặc một dòng của tài liệu dạng bảngMỗi lần in ra nhiều nhất một trang. Tài liệu dài hơn thế sẽ in phần mở đầu cùng các địa chỉ dẫn vào bên trong, nên lệnh kế tiếp luôn nhỏ hơn lệnh trước.
Một trang mới hơn bản CLI của bạn — trang mà một thông báo lỗi từ Lotics nhắc tới — được đọc từ Lotics, và việc tìm kiếm cũng vậy:
lotics docs --grep currency # mọi tài liệu nhắc tới nó
lotics docs reference --grep currency # trong một tài liệuThông báo lỗi luôn ghi trang theo cách bản CLI của bạn mở được: lotics docs <path>, hoặc với bản
CLI cũ hơn là lotics run docs '{"path":"<path>"}'.
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.
Tài liệu SDK của một ứng dụng viết mã nằm trong gói @lotics/app-sdk, ở
node_modules/@lotics/app-sdk/AGENTS.md trong thư mục ứng dụng.
Xây dựng ứng dụng
Một ứng dụng thuộc một trong hai loại. Ứng dụng JSON là một phần thân bạn viết một lần; set_app
dựng nó ngay bên Lotics, còn lotics app apply <tệp> gửi phần thân từ một tệp. Ứng dụng viết mã là một dự án React
dựng trên máy bạn với @lotics/app-sdk: lotics app create <tên> --custom đăng ký ứng dụng và liên kết
thư mục dự án của bạn với nó, còn lotics app deploy dựng rồi đưa nó lên. lotics app pull cập nhật dự án theo phiên bản đang chạy
sau khi người khác vừa đưa một bản lên, còn lotics app pull <app_id> <thư mục> tải nó về một thư
mục mới trên máy khác. Một dự án có chỗ sửa của riêng bạn không bao giờ bị ghi đè: lệnh pull liệt
kê các tệp bạn đã đổi.
Những gì một ứng dụng đọc và làm được khai ngay trên ứng dụng, có hiệu lực liền: lotics run set_app và set_workflow mỗi lệnh tạo một phiên bản mới của ứng dụng,
mỗi lần đặt ứng dụng hay triển khai cũng vậy. Muốn quay về một phiên bản trước, hãy áp lại nội dung
cũ, hoặc triển khai lại mã nguồn cũ — các bảng và những bản ghi ứng dụng đã ghi trong lúc đó vẫn giữ nguyên.
Bắt đầu từ lotics docs build — tài liệu này trình bày trình tự và lý do của trình tự đó.
Bảng và ứng dụng
lotics docs reference in ra tài liệu về văn bản mô tả một bảng và phần thân một ứng dụng — chạy được
khi không có mạng và khi chưa có tài khoản nào.
set_tables nhận một danh sách bảng, một hay nhiều, và ghi hết hoặc không ghi gì. Một bảng là một
văn bản đặt theo bí danh: các trường của nó đặt theo bí danh, một liên kết chỉ ra bảng nó trỏ tới
bằng bí danh, hoặc bằng ref của một bảng khác trong cùng lệnh, và nêu rõ nó chứa nhiều dòng hay một (multi),
còn liên kết hai chiều gọi tên trường đối ứng bằng pair ở cả hai bảng. Bảng không kèm mã thì được tạo; kèm mã thì được sửa bằng một bản vá gộp của
văn bản đó (RFC 7396) — phần bản vá không nhắc tới thì giữ
nguyên, còn null là xoá. Việc xoá kéo theo mất dữ liệu bị từ chối, trừ khi lệnh mang force.
set_app nhận mỗi lệnh một ứng dụng: nguyên phần thân để tạo, một bản vá gộp của phần thân để sửa.
Phần thân là nơi duy nhất giữ tên, mô tả, biểu tượng và màu của ứng dụng. base_version_id, phiên
bản bạn vừa đọc, làm lệnh bị từ chối nếu ứng dụng đã đổi kể từ đó. Thành viên nào cũng tạo được ứng dụng trên các bảng và mẫu mà họ đọc được. Một lần ghi lưu các trang và
danh sách mà nền tảng đã dựng; sửa chúng như mọi nút khác,
hoặc đặt false ở một nút để tắt mặc định (lotics docs design). dry_run chạy trọn bước kiểm và không ghi gì.
Lời từ chối chỉ ra mọi chỗ sai của lệnh cùng lúc, nên sửa một lượt là đủ. Dựng một không gian làm
việc mới theo đúng thứ tự: một lệnh set_tables với mọi bảng, rồi từng ứng dụng bằng set_app.
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 đó.
Công cụ làm được gì
lotics tools liệt kê mọi công cụ CLI mang theo; dưới đây là các việc chúng làm.
| Việc | Công cụ |
|---|---|
| Tìm đường trong không gian | get_workspace liệt kê bảng, ứng dụng, tài liệu kiến thức, mẫu và thành viên của không gian, mỗi mục gồm tên, id và một dòng mô tả. Thu hẹp theo loại, hoặc tìm theo tên, trường, từng dòng của tài liệu tham khảo và bản ghi |
| Bảng | get_table đọc tài liệu của một bảng. set_tables tạo và sửa bảng, mỗi lần một danh sách tài liệu bảng; set_table_views tạo, sửa, sắp xếp và xóa các khung nhìn đã lưu của một bảng; một mục có delete: true xóa bảng, có restore: true thì khôi phục bảng |
| Bản ghi | query_records đọc các dòng, một bản ghi theo id, hoặc số liệu thống kê (aggregate); create_records, update_records và delete_records ghi chúng. Trường được gọi bằng bí danh (alias). update_records còn khóa và mở khóa các dòng (locked), khôi phục dòng đã xóa (restore) và, với request_change, nhờ người quản lý bảng đổi một dòng đã khóa. query_audit_logs đọc ai đã đổi gì; muốn trả lại một lần sửa, hãy ghi lại giá trị cũ bằng update_records. Mỗi lần đọc bản ghi đều có comment_count; comments: true trả cả chuỗi bình luận. Bình luận được viết trong Lotics |
| Ứng dụng | get_app đọc một ứng dụng và những gì có thể yêu cầu nó làm. set_app tạo, sửa, xóa và khôi phục ứng dụng. run_app_query và run_app_workflow dùng ứng dụng; screenshot_app chụp ứng dụng đã vẽ |
| Quy trình | get_workflow liệt kê các quy trình hoặc đọc một quy trình, còn set_workflow ghi và chạy thử (dry_run) quy trình của một bảng, một tự động hóa hay quy trình của một ứng dụng, và xóa một quy trình. query_workflow_executions và get_workflow_execution đọc các lần chạy của chúng, còn set_workflow_execution chạy lại hoặc hủy một lần chạy |
| Chứng từ | get_template và set_template đọc và ghi mẫu Word, Excel, PDF và email, còn set_template cũng xóa hoặc khôi phục một mẫu. generate_document điền dữ liệu vào một mẫu. set_template với dry_run kiểm tra một mẫu, kể cả các chỗ đánh dấu của bảng tính Excel, mà không lưu gì; với mẫu PDF dạng biểu mẫu, nó và get_template trả về vị trí các nhãn trên từng trang |
| File | upload_file và download_file đưa một file vào và trả một file về; lotics file upload và lotics file download chuyển file từ và về đĩa; delete_file xóa một file không còn nơi nào dùng đến |
| Kiến thức | get_workspace liệt kê và tìm tài liệu tham khảo, read_knowledge đọc một tài liệu, set_knowledge tạo, sửa, lưu trữ và khôi phục tài liệu |
| Không gian làm việc | set_workspace đổi tên, múi giờ, tiền tệ mặc định, các chỉ dẫn thường trực mà mọi agent trong không gian làm việc phải theo và mức trần tín dụng mỗi ngày; công cụ này thuộc về quản trị viên không gian |
| Quyền truy cập | set_access chia sẻ một bảng, ứng dụng hoặc tài liệu kiến thức cho một thành viên hay nhóm trong không gian, thu quyền lại, hoặc chuyển một tài nguyên cho người sở hữu khác; chia sẻ với người ngoài không gian bị từ chối cho tới khi họ được thêm vào |
| Con người | get_workspace liệt kê những người trong không gian, và cả tổ chức khi đồng chủ sở hữu hoặc chủ sở hữu chính yêu cầu tất cả. set_members mời người, thêm họ vào hoặc đưa họ ra khỏi không gian, đặt vai trò của họ ở đó và quản lý các nhóm thành viên của không gian; công cụ này thuộc về quản trị viên không gian. Đổi tên, xóa và khôi phục người, đồng chủ sở hữu và tài khoản không có email được thực hiện trong Cài đặt → Thành viên. Danh sách công cụ của thành viên không có nó |
Cờ
| Cờ | Mô tả |
|---|---|
--json |
Xuất JSON đầy đủ (mặc định là văn bản dễ đọc) |
--timeout <ms> |
Ngừng mỗi lần chờ câu trả lời của máy chủ sau số mili giây này (số nguyên từ 1 đến 2147483647; mặc định: chờ máy chủ). Lần chờ kết thúc mà không có câu trả lời khi --timeout hết hoặc khi máy chủ không trả lời. Lệnh đọc không có câu trả lời thì không thay đổi gì: lệnh thoát với mã khác 0 và in mã yêu cầu. Lệnh ghi không có câu trả lời thì thoát với mã khác 0 và in mã yêu cầu (kèm error_code: "outcome_unknown" khi dùng --json), vì không biết lệnh gọi đã có hiệu lực chưa: hãy đọc lại trước khi chạy lại. Tải về từ đường dẫn lưu trữ đã ký là lần gọi duy nhất nằm ngoài quy tắc này: nó không có mã yêu cầu, và --timeout cũng dừng nó. Khi dùng --json, mọi lỗi là một đối tượng JSON trên stdout |
-o <path> |
Với download là thư mục để lưu vào. Với run là thư mục lưu mọi liên kết có chữ ký trong kết quả. Với knowledge get là file để ghi ra |
--as <name> |
Ghi đè tên file khi tải lên |
--api-key <key> |
Khóa API cho một lệnh (ghi đè phiên đăng nhập đã lưu và biến môi trường LOTICS_API_KEY) |
--workspace <id> |
Ghi đè không gian làm việc cho một lệnh (bí danh: -w) |
--version |
Hiển thị phiên bản CLI |
Đầ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_document '{"..."}' --json
lotics download <file_id> ./bao_cao.xlsx # file cần ghi ra
lotics download <file_id> -o ./output/ # thư mục cần lưu vào, giữ tên đã lưu trên hệ thốngĐường dẫn đứng sau là file, -o là thư mục — đúng cách cp và curl -o phân biệt. Chỉ nêu
một trong hai, không nêu cả hai. Đường dẫn đã ghi xuất ra stdout, nên có thể nối thẳng lệnh tải
xuống vào lệnh mở file kế tiếp.
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":[{"contract":["fil_..."]}]}'Stdin và tệp
Pipe tham số JSON qua stdin thay vì inline, hoặc truyền một tệp với dấu @ ở đầu. Dấu - ở cuối
là cách xin đọc stdin — không có nó thì lệnh chạy công cụ với tham số rỗng và trả lời ngay, đúng
như một công cụ không cần tham số nên làm:
echo '{"table_id":"tbl_..."}' | lotics run query_records -
lotics run query_records @args.jsonTrong PowerShell, hãy dùng dạng tệp. Dấu nháy bên trong một tham số inline bị shell nuốt trước khi
lotics nhận được, và CLI sẽ báo lại chuỗi JSON đã mất dấu nháy.
CI / không tương tác
Dòng lệnh của một người thì đăng nhập. Khóa API dành cho máy không có ai bấm Xác nhận: một job CI, một tự động hóa chạy theo lịch, một phiên trên đám mây. Quản trị viên tạo khóa trong ứng dụng web Lotics tại Cài đặt → Khóa API, và mỗi khóa thuộc về một tổ chức.
export LOTICS_API_KEY=ltk_...
lotics run get_workspace '{}'
# 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 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/");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. Đăng nhập một lần — phiên đăng nhập được lưu theo từng tổ chức
lotics auth login # mở liên kết lệnh in ra, đăng nhập hoặc tạo tài khoản, bấm Xác nhận
# 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 set_tables
# 3. Tạo các bảng, mọi bảng trong một lệnh: {"tables": [...]}, viết theo
# schema vừa in ở trên.
lotics run set_tables @tables.json
# 4. Đọc lại bảng — tài liệu của nó gọi mỗi trường và mỗi lựa chọn bằng bí danh (alias)
lotics run get_table '{"table_id": "tbl_..."}'
# 5. Ghi dữ liệu theo các bí danh đó
lotics run create_records '{
"table_id": "tbl_...",
"records": [{"company": "Acme Corp", "status": ["open"]}]
}'Chứng từ, ứ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.