CLI 概覽

Imbrace CLI（@imbrace/cli）是一個用於與 Imbrace 平台互動的終端工具。指令透過 @imbrace/sdk 套件直接呼叫 Imbrace 平台。原始碼：imbrace-co/imbrace-cli。

目前版本： v0.8.2

imbrace (CLI) → https://app-gatewayv2.imbrace.co (Imbrace Platform)

除了資源指令外，CLI 也可以作為 MCP 伺服器（imbrace mcp）執行，將整個 Imbrace API 作為工具提供給 AI agent — 請參閱指令 → MCP Server。

認證流程

CLI 支援兩種認證方式：

1. API 金鑰（憑證以 sk- 或 api_ 開頭）：

直接傳遞給 SDK：new ImbraceClient({ apiKey: credential })
以原始形式儲存在本機設定中

2. 電子郵件 + 密碼（回傳 JWT 權杖）：

SDK：client.login(email, password) 回傳使用者所屬的組織；CLI 隨後呼叫 client.selectOrganization(orgId) 取得綁定組織的權杖
多組織帳戶：傳入 --org-id（單組織自動選擇，多組織在 TTY 中提示）
綁定組織的 JWT 作為憑證儲存

憑證儲存

憑證與各環境設定透過 conf npm 套件（projectName: "imbrace"）儲存在 profile 中。

作業系統	設定檔路徑
macOS	`~/Library/Preferences/imbrace-nodejs/config.json`
Linux	`~/.config/imbrace-nodejs/config.json`
Windows	`%APPDATA%\imbrace-nodejs\Config\config.json`

每個 profile 儲存：

欄位	類型	說明
`credential`	string	API 金鑰或 JWT 權杖
`method`	`"api-key"` \| `"password"`	認證方式
`email`	string?	電子郵件（密碼認證用）
`env`	`"stable"` \| `"sandbox"` \| `"develop"` \| `"prodv2"`?	SDK 環境預設集（preset）
`base_url`	string?	覆寫閘道 base URL
`organization_id`	string?	組織 ID
`timeout`	number?	請求逾時（毫秒）
`services`	object?	各服務的 URL 覆寫
`check_health`	boolean?	用戶端初始化時 ping 健康檢查

選擇 profile 的解析順序：--profile 標誌 > IMBRACE_PROFILE 環境變數 > active_profile 設定 > "default"。

資源指令（ai-agent、data-board、document-ai、guardrail、orchestrator、workflow）繼承 BaseCommand，其在初始化時會呼叫 ensureLoggedIn()。如果解析出的 profile 找不到憑證，它會以互動方式提示使用者選擇登入方式（API 金鑰或電子郵件 + 密碼）。認證與 profile 管理指令（login、logout、whoami、docs、profile/*）直接繼承 Command，不會自動提示。

所有指令都接受全域 --profile 標誌以指定特定 profile，其優先於 IMBRACE_PROFILE 環境變數與 active_profile 設定。

專案結構

imbrace-cli/
└── cli/                     ← oclif CLI
    └── src/
        ├── base-command.ts       ← 自動登入
        ├── config.ts             ← 憑證儲存 (conf)
        └── commands/
            ├── login.ts / logout.ts / whoami.ts / docs.ts
            ├── profile/      (6 個指令：create、delete、list、rename、show、use)
            ├── data-board/    (8 個指令)
            ├── ai-agent/      (9 個指令)
            ├── document-ai/   (7 個指令)
            ├── orchestrator/  (4 個指令)
            ├── guardrail/     (5 個指令)
            └── workflow/      (32 個指令)

工作流程節點架構

工作流程使用透過 nextAction 指標的鏈結串列結構：

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

所有節點操作都使用 applyFlowOperation()，類型包括：UPDATE_TRIGGER、ADD_ACTION、UPDATE_ACTION、DELETE_ACTION、LOCK_AND_PUBLISH、CHANGE_STATUS、CHANGE_FOLDER。