CLI 指令

Data Board

一個 board 就是一個 CRM 管道 — 潛在客戶、交易、任務或任何結構化資料。

列出 Boards

imbrace data-board list [--json]

建立 Board

imbrace data-board create [--name <name>] [--json]

如果不使用 --json，指令在輸入名稱後會以互動方式提示輸入自由格式的鍵值對。

建立欄位

imbrace data-board create-field <boardId> --name <fieldName> --type <fieldType> [--json]

有效的欄位類型（16 種）：ShortText、LongText、Number、Date、Email、Phone、Currency、SingleSelection、MultipleSelection、Checkbox、Assignee、MultipleAssignee、Link、Notes、Origin、Priority。

建立項目

imbrace data-board create-item <boardId> --fields '<json>' [--json]

--fields 是 { board_field_id, value } 物件的 JSON 陣列：

imbrace data-board create-item <boardId> --fields '[
  {"board_field_id": "<fieldId>", "value": "Acme Corp"},
  {"board_field_id": "<fieldId>", "value": "50000"}
]' --json

列出項目

imbrace data-board list-items --board-id <boardId> [--limit 20] [--skip 0] [--q <search>] [--json]

更新項目

imbrace data-board update-item <boardId> <itemId> --data '<json>' [--json]

--data 是 { key, value } 物件的 JSON 陣列。

刪除項目

imbrace data-board delete-item <boardId> <itemId> [--yes] [--json]

匯出為 CSV

imbrace data-board export-csv --board-id <boardId> [--out ./board.csv]

如果不使用 --out，則將 CSV 輸出至標準輸出。

AI Agent

一個 AI agent 是一個設定好的助手（LLM + 提示詞 + 行為）。建立一個 agent 會同時佈建助理、網頁頻道和使用案例範本。

探索

imbrace ai-agent list [--json]
imbrace ai-agent list-providers [--json]
imbrace ai-agent list-models --provider-id <providerId> [--json]
imbrace ai-agent list-folders [--search <query>] [--json]
imbrace ai-agent list-files --folder-id <folderId> [--json]

取得 / 刪除

imbrace ai-agent get <agentId> [--json]
imbrace ai-agent delete <agentId> [--yes] [--json]

建立 / 更新標誌

create 和 update 接受相同的標誌。update 透過 PUT-merge 保留未變更的欄位。

標誌	對應至	備註
身份
`--name` / `-n`	`name` + `title`	建立時必填
`--description` / `-d`	`description` + `short_description`	顯示在標題下方
`--instructions` / `-i`	`instructions`	系統提示詞
模型
`--model`	`model_id`	預設 `Default`（系統提供者）
`--provider-id`	`provider_id`	UUID，預設 `system`
`--mode`	`mode`	`standard` / `advanced`
`--temperature`	`temperature`	0.0–2.0，預設 0.1
行為設定
`--personality`	`personality_role`
`--core-task`	`core_task`
`--tone`	`tone_and_style`
`--response-length`	`response_length`	`short` / `medium` / `long`
`--banned-words`	`banned_words`	逗號分隔的輸出過濾器
`--category`	`category`	`Support` / `Sales` / `Marketing` / `Team` / `Other`
`--guardrail-id`	`guardrail_id`	附加護欄
`--preload-information`	`preload_information`	上下文中的靜態資訊
知識支援
`--folder-ids`	`folder_ids`	逗號分隔的 KH 資料夾 ID
`--default-folder-id`	`default_folder_id`
`--knowledge-hubs`	`knowledge_hubs`	逗號分隔的 KH ID
`--board-ids`	`board_ids`	逗號分隔的資料 board ID
`--file-ids`	`file_ids`	逗號分隔的檔案 ID
執行時期開關（支援 `--no-X`）
`--show-thinking`	`show_thinking_process`	預設 false
`--streaming`	`streaming`	預設 true
`--use-memory`	`use_memory`	預設 true
輸出
`--yes` / `-y`	—	刪除時跳過確認
`--json`	—	機器可讀輸出
`--id-only`	—	僅列印新 agent ID

完整建立範例

imbrace ai-agent create \
  --name "Customer Support Specialist" \
  --description "Senior AI customer support agent" \
  --instructions "You are a senior customer support specialist..." \
  --personality "Friendly and professional" \
  --core-task "Answer product inquiries, help track orders" \
  --tone "Polite, professional, warm" \
  --response-length "medium" \
  --banned-words "stupid, idiot" \
  --category "Support" \
  --provider-id "e2629292-7e9f-4d55-ba18-6827747eab33" \
  --model "gpt-4o-mini" \
  --temperature 0.3 \
  --folder-ids "69bb82faa2cc764639bc6bdb" \
  --board-ids "brd_e5450d76-84d4-4c34-8b13-3d0f1873b53b" \
  --json

Agent 類型

平台在 agent_type 中儲存 4 種不同的 agent 類型。CLI 透過專用主題或 --agent-type 標誌來使用它們：

UI 建立選項	CLI 指令	後端 `agent_type`
AI AGENT	`imbrace ai-agent create`	`agent`（預設）
ORCHESTRATOR	`imbrace orchestrator create`	`team_lead`
DOCUMENT AI	`imbrace document-ai create`	`document_ai`
GUARD RAIL	`imbrace guardrail create`	（非 agent — 獨立資源）

ai-agent create 上的 --agent-type 標誌接受 agent、assistant、conversational 或 workflow。對於 Document AI，請使用專用的 document-ai 主題。對於 Orchestrator，請使用 orchestrator 主題。

Document AI

Document AI agent 從非結構化文件（PDF、圖片、掃描表單）中提取結構化 JSON。每個 agent 都有一個定義提取欄位的結構定義、引導 LLM 的指示，以及一個模型 + 提供者。儲存為 agent_type: "document_ai" 的 AI Agent。

CRUD

imbrace document-ai list [--search <q>] [--all] [--json]
imbrace document-ai get <agentId> [--json]
imbrace document-ai create -n "<name>" -i "<instructions>" --model <id> \
  (--schema '<json>' | --schema-file <path>) \
  [--provider-id <uuid>] [--description <text>] [--workflow-name <name>] \
  [--json] [--id-only]
imbrace document-ai update <agentId> [--name | --instructions | --model | --provider-id | --schema | --schema-file | --description | --workflow-name] [--json]
imbrace document-ai delete <agentId> [--yes] [--json]

list 預設會過濾 documentAiOnly: true。傳遞 --all 以包含一般 agent。

處理文件

imbrace document-ai process \
  --url <pdf-or-image-url> \
  --org-id <orgId> \
  [--agent-id <id>] [--model <id>] [--instructions <text>] \
  [--board-id <boardId>] [--language <lang>] \
  [--additional-instructions <text>] \
  [--chunk-size <n>] [--max-concurrent <n>] [--max-retries <n>] \
  [--no-enhanced-processing] [--json]

必須提供 --agent-id（使用 agent 儲存的模型 + 指示）或 --model（覆蓋）。

建議結構定義

imbrace document-ai suggest-schema --url <url> --org-id <orgId> [--model <id>] [--json]

要求 LLM 檢查範例文件並提出提取結構定義。

結構定義範例

{
  "invoice_number": { "type": "string", "description": "Invoice ID" },
  "total_amount":   { "type": "number" },
  "due_date":       { "type": "string", "format": "date" }
}

Orchestrator

Orchestrator 是一個以 agent_type: "team_lead" 儲存的 AI Agent，負責將工作委派給 sub_agents / team_leads。對應 UI 建立對話方塊中的 ORCHESTRATOR 選項。

imbrace orchestrator list [--json]
imbrace orchestrator get <id> [--json]
imbrace orchestrator create -n "<name>" -i "<routing instructions>" \
  --sub-agents <id1>,<id2> [--team-leads <id3>,<id4>] \
  [--description <text>] [--model <id>] [--provider-id <uuid>] [--temperature <0-2>] \
  [--json] [--id-only]
imbrace orchestrator delete <id> [--yes] [--json]

後端特殊行為（自動處理）

CLI 會處理三個平台行為，因此呼叫者無需了解它們 — 但在除錯原始 SDK 回應時很有用：

agent_type: "team_lead" 是 orchestrator 標記 — 沒有獨立的 is_orchestrator 布林值。webapp 也做同樣的轉換。
sub_agents / team_leads 必須是助理 ID（UUID），而不是使用案例 ID（uc_*）。 CLI 會自動將您傳入的任何 uc_* 透過 client.agent.get() 查詢解析。
createUseCase 在助理酬載中設定上述兩個欄位時會靜默丟棄它們。 CLI 分兩步驟：建立 → chatAi.updateAiAgent PUT 來套用它們。

get 會擷取底層的助理，以便 sub_agents / team_leads 正確顯示（它們存在於助理上，而非使用案例上）。

Guard Rail

Guard Rail 是一個內容安全 / 合規層，透過 ai-agent create 上的 --guardrail-id 附加到 AI Agent。對應 UI 建立對話方塊中的 GUARD RAIL 選項。

imbrace guardrail list [--json]
imbrace guardrail get <id> [--json]
imbrace guardrail create -n "<name>" -i "<rules>" \
  [--model nim-nemo|model-armor] \
  [--guardrail-provider-id <uuid>] [--org-id <orgId>] \
  [--description <text>] \
  [--unsafe-categories "violence,hate,sexual"] \
  [--custom-unsafe-patterns "regex1,regex2"] \
  [--competitor-keywords "X,Y"] \
  [--json] [--id-only]
imbrace guardrail update <id> -n -i --model [partial flags] [--json]
imbrace guardrail delete <id> [--yes] [--json]

後端特殊行為（自動處理）

org_id 是必填，但 SDK 型別標記為選填。如果您未傳遞 --org-id，CLI 會透過 client.account.getAccount() 自動擷取。
model 不是一般的 LLM 名稱 — 它是護欄模型：
- nim-nemo（NVIDIA NIM Nemo）— CLI 預設
- model-armor（Google）
- 或搭配 --guardrail-provider-id 使用的任何自訂護欄提供者模型
model-armor 會忽略 instructions、custom_unsafe_patterns 和 competitor_keywords。 CLI 會自動移除它們。
後端回傳 guardrails_config_id，而非 _id。 CLI 會正規化此行為，使 --id-only 和 get <id> 如預期運作。

Workflow

一個工作流程是一串節點：觸發條件觸發，然後動作依序執行。

節點類型

類型	角色	CLI 支援
`PIECE_TRIGGER`	流程何時執行	`node add --type trigger`
`PIECE`	之後執行什麼	`node add --type action`
`EMPTY`	設定觸發條件前的佔位符	唯讀
`ROUTER`	多條件分支	`node add-raw`
`LOOP_ON_ITEMS`	在陣列上迴圈	`node add-raw`
`CODE`	內嵌 JavaScript	`node add-raw`

流程 CRUD

imbrace workflow list [--folder-id <id|NULL>] [--json]
imbrace workflow get <id> [--json]
imbrace workflow create --name "<name>" [--folder-id <id>] [--json] [--id-only]
imbrace workflow move <flowId> --folder-id <id|NULL> [--json]
imbrace workflow delete <id> [--yes] [--json]

節點管理

imbrace workflow node list <flowId> [--json]
imbrace workflow node add <flowId> \
  --type trigger --piece <pieceName> \
  --trigger-name <triggerId> [--input '<json>'] [--json]
imbrace workflow node add <flowId> \
  --type action --piece <pieceName> \
  --action-name <actionId> \
  [--after <parentStep>] [--input '<json>'] [--json]
imbrace workflow node update <flowId> <nodeName> \
  [--input '<json>'] [--display-name <name>] [--json]
imbrace workflow node delete <flowId> <nodeName> [--yes] [--json]
imbrace workflow node add-raw <flowId> (--op-file <path> | --op '<json>' | --stdin) [--json]

元件探索

imbrace workflow piece list [--search <query>] [--json]
imbrace workflow piece detail <pieceName> [--only actions|triggers] [--json]

連線

imbrace workflow conn list [--json]
imbrace workflow conn get <connId> [--json]
imbrace workflow conn create \
  --piece <pieceName> \
  --type SECRET_TEXT|OAUTH2|CLOUD_OAUTH2|BASIC_AUTH|CUSTOM_AUTH \
  --value "<token-or-json>" \
  [--display-name <name>] [--external-id <id>] [--json] [--id-only]
imbrace workflow conn delete <connId> [--yes] [--json]

資料夾（分類）

imbrace workflow folder list [--json]
imbrace workflow folder get <folderId> [--json]
imbrace workflow folder create --name "<name>" [--json] [--id-only]
imbrace workflow folder update <folderId> --name "<newName>" [--json]
imbrace workflow folder delete <folderId> [--yes] [--json]

平台會自動建立 4 個系統資料夾：

UI 分類	API 資料夾名稱
Channel Workflow	`Channel Workflow`
Board Automation	`Board Automation`
AI Agent Skills	`AI Agent Capabilities`
Others	`Others`

MCP 伺服器

imbrace workflow mcp list [--json]
imbrace workflow mcp get <mcpId> [--json]
imbrace workflow mcp create --name "<name>" [--json] [--id-only]
imbrace workflow mcp delete <mcpId> [--yes] [--json]
imbrace workflow mcp rotate-token <mcpId> [--yes] [--json]

生命週期與執行

imbrace workflow publish <flowId> [--json]
imbrace workflow enable <flowId> [--json]
imbrace workflow disable <flowId> [--json]
imbrace workflow run <flowId> [--payload '<json>'] [--sync] [--json]
imbrace workflow runs [--limit 10] [--json]
imbrace workflow run-detail <runId> [--json]

變數語法

表達式	意義
`{{trigger.body.X}}`	Webhook 酬載中的欄位 X
`{{trigger.X}}`	頂層觸發條件欄位
`{{step_1.output.Y}}`	step_1 的輸出欄位 Y
`{{connections.<id>.access_token}}`	連線欄位

工具

列印 LLM 參考

imbrace docs [--path] [--json]

列印捆綁的 llms.txt — 一份完整的指令參考，設計用於饋入程式碼代理工具的上下文（Claude、Cursor 等）。

標誌	行為
(無)	將完整參考列印至標準輸出
`--path`	僅列印 `llms.txt` 的絕對路徑
`--json`	以 JSON 格式輸出 `{ path, content }`

imbrace docs > /tmp/imbrace-llms.txt   # 為 AI agent 儲存

已知問題

欄位類型 Dropdown — 後端會拒絕。請改用 SingleSelection。
Provider ID 與 _id — 使用 UUID provider_id，而非 MongoDB _id。
僅限英文內容 — AI agent 內容必須使用英文。
workflow run --sync 逾時 — 可能在大約 60 秒時逾時。請改用 workflow runs + run-detail。
先發佈再啟用 — workflow enable 需要先執行 workflow publish。
AI Connector prompt 欄位 — 必須為 { prompt: { prompt: "text" } }。
流程鎖定 — 如果流程在瀏覽器中開啟，CLI 更新可能會被拒絕。
建立時的 --no-use-memory — 可能無法持久。請在建立後更新。
系統提供者模型 — 只有 Default。其他名稱會使 UI 下拉選單為空。