Lập trình

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_document vớ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_workflow và chạy bằng run_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:

Bash
curl -fsSL https://lotics.ai/install.sh | bash

Sau đó đă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ã đó:

Bash
lotics auth login

Cá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:

Bash
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:

Bash
curl -fsSL https://lotics.ai/install.sh | bash

Trên Windows, mở PowerShell rồi chạy:

PowerShell
irm https://lotics.ai/install.ps1 | iex

Cả 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:

Bash
lotics --version

lotics 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

Bash
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

Bash
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 đã 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:

Bash
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:

Bash
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

Bash
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ưu

Phiê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ố JSON

Luô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ạn

lotics --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ó:

Bash
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ảng

Mỗ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:

Bash
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ệu

Thô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:

Bash
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:

Bash
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ụ:

Bash
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:

Bash
echo '{"table_id":"tbl_..."}' | lotics run query_records -
lotics run query_records @args.json

Trong 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.

Bash
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)

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("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ề.

Bash
# 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.

Đăng ký dùng Lotics

Chúng tôi sẽ liên hệ trong vòng 1 ngày.