Tổng quan CLI

Imbrace CLI (@imbrace/cli) là một công cụ dòng lệnh để tương tác với nền tảng Imbrace. Các lệnh gọi trực tiếp đến nền tảng Imbrace thông qua gói @imbrace/sdk. Nguồn: imbrace-co/imbrace-cli.

Phiên bản hiện tại: v0.8.2

imbrace (CLI) → https://app-gatewayv2.imbrace.co (Nền tảng Imbrace)

Ngoài các lệnh resource, CLI còn chạy được như một MCP server (imbrace mcp), mở toàn bộ API Imbrace thành tool cho AI agent — xem Commands → MCP Server.

Luồng xác thực

CLI hỗ trợ hai phương thức xác thực:

1. API Key (thông tin xác thực bắt đầu bằng sk- hoặc api_):

Được truyền trực tiếp đến SDK: new ImbraceClient({ apiKey: credential })
Được lưu nguyên trạng trong cấu hình cục bộ

2. Email + Mật khẩu (trả về JWT token):

SDK: client.login(email, password) trả về danh sách tổ chức của user; CLI sau đó gọi client.selectOrganization(orgId) để lấy token gắn theo tổ chức
Tài khoản nhiều tổ chức: truyền --org-id (một tổ chức thì tự chọn, nhiều tổ chức sẽ hỏi trong TTY)
JWT gắn theo tổ chức được lưu làm thông tin xác thực

Lưu trữ thông tin xác thực

Thông tin xác thực và cấu hình theo từng môi trường được lưu trong các profile qua gói npm conf với projectName: "imbrace".

Hệ điều hành	Đường dẫn cấu hình
macOS	`~/Library/Preferences/imbrace-nodejs/config.json`
Linux	`~/.config/imbrace-nodejs/config.json`
Windows	`%APPDATA%\imbrace-nodejs\Config\config.json`

Mỗi profile lưu:

Trường	Kiểu	Mô tả
`credential`	string	API key hoặc JWT token
`method`	`"api-key"` \| `"password"`	Phương thức xác thực
`email`	string?	Email (khi xác thực bằng mật khẩu)
`env`	`"stable"` \| `"sandbox"` \| `"develop"` \| `"prodv2"`?	Preset môi trường SDK
`base_url`	string?	Ghi đè base URL của gateway
`organization_id`	string?	ID tổ chức
`timeout`	number?	Thời gian chờ request (ms)
`services`	object?	Ghi đè URL theo từng service
`check_health`	boolean?	Ping health khi khởi tạo client

Thứ tự ưu tiên khi chọn profile: cờ --profile > biến môi trường IMBRACE_PROFILE > cấu hình active_profile > "default".

Các lệnh tài nguyên (ai-agent, data-board, document-ai, guardrail, orchestrator, workflow) kế thừa BaseCommand, lớp này gọi ensureLoggedIn() khi khởi tạo. Nếu không tìm thấy thông tin xác thực cho profile đã xác định, nó sẽ hỏi người dùng (ở chế độ tương tác) để chọn phương thức đăng nhập (API Key hoặc Email + Mật khẩu). Các lệnh xác thực và quản lý profile (login, logout, whoami, docs, profile/*) kế thừa trực tiếp Command và không tự động yêu cầu đăng nhập.

Mọi lệnh đều chấp nhận cờ toàn cục --profile để chọn một profile cụ thể, ghi đè biến môi trường IMBRACE_PROFILE và thiết lập active_profile.

Cấu trúc dự án

imbrace-cli/
└── cli/                     ← oclif CLI
    └── src/
        ├── base-command.ts       ← Tự động đăng nhập
        ├── config.ts             ← Lưu trữ thông tin xác thực (conf)
        └── commands/
            ├── login.ts / logout.ts / whoami.ts / docs.ts
            ├── profile/      (6 lệnh: create, delete, list, rename, show, use)
            ├── data-board/    (8 lệnh)
            ├── ai-agent/      (9 lệnh)
            ├── document-ai/   (7 lệnh)
            ├── orchestrator/  (4 lệnh)
            ├── guardrail/     (5 lệnh)
            └── workflow/      (32 lệnh)

Kiến trúc Workflow Node

Workflows sử dụng cấu trúc danh sách liên kết thông qua con trỏ nextAction:

{
  version: {
    trigger: {
      name: "trigger",
      type: "PIECE_TRIGGER" | "EMPTY" | "PIECE" | "ROUTER" | "LOOP_ON_ITEMS" | "CODE",
      settings: { pieceName, pieceVersion, input, ... },
      nextAction: { ... },
      children?: any[],          // ROUTER branches
      firstLoopAction?: any,     // LOOP_ON_ITEMS body
    }
  }
}

Tất cả các thao tác node đều sử dụng applyFlowOperation() với các loại: UPDATE_TRIGGER, ADD_ACTION, UPDATE_ACTION, DELETE_ACTION, LOCK_AND_PUBLISH, CHANGE_STATUS, CHANGE_FOLDER.