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 代理 — 参见命令 → MCP Server。

认证流程

CLI 支持两种认证方法：

1. API Key（凭证以 sk- 或 api_ 开头）：

直接传递给 SDK：new ImbraceClient({ apiKey: credential })
按原样存储在本地配置中

2. 邮箱 + 密码（返回 JWT 令牌）：

SDK：client.login(email, password) 返回用户所属的组织；CLI 随后调用 client.selectOrganization(orgId) 获取绑定组织的令牌
多组织账户：传入 --org-id（单组织自动选择，多组织在 TTY 中提示）
绑定组织的 JWT 作为凭证存储

凭证存储

凭证和各环境设置通过 conf npm 包存储在 profile 中，projectName: "imbrace"。

操作系统	配置文件路径
macOS	`~/Library/Preferences/imbrace-nodejs/config.json`
Linux	`~/.config/imbrace-nodejs/config.json`
Windows	`%APPDATA%\imbrace-nodejs\Config\config.json`

每个 profile 存储：

字段	类型	说明
`credential`	string	API key 或 JWT 令牌
`method`	`"api-key"` \| `"password"`	认证方法
`email`	string?	邮箱（用于密码认证）
`env`	`"stable"` \| `"sandbox"` \| `"develop"` \| `"prodv2"`?	SDK 环境预设
`base_url`	string?	覆盖网关 Base URL
`organization_id`	string?	组织 ID
`timeout`	number?	请求超时（毫秒）
`services`	object?	按服务覆盖 URL
`check_health`	boolean?	客户端初始化时执行健康检查

profile 的解析顺序：--profile 参数 > IMBRACE_PROFILE 环境变量 > active_profile 配置 > "default"。

资源命令（ai-agent、data-board、document-ai、guardrail、orchestrator、workflow）继承 BaseCommand，后者在初始化时调用 ensureLoggedIn()。如果在解析出的 profile 中未找到凭证，它会交互式提示用户选择登录方式（API Key 或邮箱 + 密码）。认证和 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。