` | No | — | conversation title | | `--model <model>` | No | — | runtime model override | --draft and --live are mutually exclusive. With neither flag, the new conversation uses Live. <a id="cai-agent-conversation-status"></a> ### cai agent conversation status Read the conversation mode, adopted version, model and status. ```sh cai agent conversation status [options] <conversationId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`agent_conversation_status`](/reference/mcp-tools/#agent_conversation_status) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<conversationId>` | Yes | Conversation ID from cai agent conversation list or create. | <a id="cai-agent-conversation-history"></a> ### cai agent conversation history Read persisted messages, events, and pending permission requests. ```sh cai agent conversation history [options] <conversationId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`agent_conversation_history`](/reference/mcp-tools/#agent_conversation_history) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<conversationId>` | Yes | Conversation ID from cai agent conversation list or create. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--last` | No | — | aggregates the assistant turn: status, text, tool-call summary, cost | <a id="cai-agent-conversation-approve"></a> ### cai agent conversation approve Approve one pending tool request and resume the active conversation. ```sh cai agent conversation approve [options] <conversationId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`agent_conversation_approve`](/reference/mcp-tools/#agent_conversation_approve) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<conversationId>` | Yes | Conversation ID from cai agent conversation list or create. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--request <requestId>` | Yes | — | exact requestId from conversation history | | `--tool <toolName>` | No | — | normally unnecessary; server knows the tool; if needed, pass exact mcp__controllerai__tool_<id> name | <a id="cai-agent-conversation-deny"></a> ### cai agent conversation deny Deny one pending tool request and resume the active conversation. ```sh cai agent conversation deny [options] <conversationId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`agent_conversation_deny`](/reference/mcp-tools/#agent_conversation_deny) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<conversationId>` | Yes | Conversation ID from cai agent conversation list or create. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--request <requestId>` | Yes | — | exact requestId from conversation history | | `--tool <toolName>` | No | — | normally unnecessary; server knows the tool; if needed, pass exact mcp__controllerai__tool_<id> name | | `--message <reason>` | No | — | reason returned to the agent | <a id="cai-agent-conversation-send"></a> ### cai agent conversation send Send a message, optionally waiting for a verifiable persisted reply. ```sh cai agent conversation send [options] <conversationId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`agent_conversation_send`](/reference/mcp-tools/#agent_conversation_send) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<conversationId>` | Yes | Conversation ID from cai agent conversation list or create. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--message <text>` | Yes | — | message to send | | `--wait` | No | `false` | wait for the next completed persisted assistant reply | | `--timeout <seconds>` | No | `"300"` | Reply wait in seconds, greater than 0 and at most 600; checked only with --wait. | <a id="cai-agent-test"></a> ### cai agent test Create a Test conversation by default, send a message and verify its persisted reply; pass --live for the published version. ```sh cai agent test [options] <agentId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`agent_test`](/reference/mcp-tools/#agent_test) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<agentId>` | Yes | Agent ID from cai agent list. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--message <text>` | Yes | — | verification prompt | | `--draft` | No | — | owner-only Test: current agent draft and workflow development heads (default) | | `--live` | No | — | Live: latest published agent and workflow releases | | `--title <title>` | No | `"CLI verification"` | conversation title | | `--model <model>` | No | — | runtime model override | | `--timeout <seconds>` | No | `"300"` | Reply wait in seconds, greater than 0 and at most 600. | --draft and --live are mutually exclusive. Each invocation creates a persisted conversation and executes real tools with usage charges; inspect that conversation before retrying. <a id="cai-use"></a> ### cai use Pin a default workflow so --workflow can be omitted. ```sh cai use [options] <workflowId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | Local CLI | — | Omitted from MCP. Persists a local workflow pin; every typed workflow call carries an explicit id. | | Argument | Required | Meaning | | --- | --- | --- | | `<workflowId>` | Yes | workflow id to pin as the default | <a id="cai-workflow"></a> ### cai workflow Create, inspect, test and publish workflows. Subcommands: [`list`](#cai-workflow-list), [`create`](#cai-workflow-create), [`get`](#cai-workflow-get), [`rename`](#cai-workflow-rename), [`set-description`](#cai-workflow-set-description), [`duplicate`](#cai-workflow-duplicate), [`delete`](#cai-workflow-delete), [`versions`](#cai-workflow-versions), [`releases`](#cai-workflow-releases), [`history`](#cai-workflow-history), [`restore`](#cai-workflow-restore), [`save`](#cai-workflow-save), [`document`](#cai-workflow-document), [`state`](#cai-workflow-state), [`outline`](#cai-workflow-outline), [`status`](#cai-workflow-status), [`validate`](#cai-workflow-validate), [`publish`](#cai-workflow-publish). <a id="cai-workflow-list"></a> ### cai workflow list List workflows visible to this account. ```sh cai workflow list [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`workflow_list`](/reference/mcp-tools/#workflow_list) | Direct. Typed counterpart; use its input schema. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--limit <n>` | No | `"25"` | max rows | <a id="cai-workflow-create"></a> ### cai workflow create Create and select a named workflow. ```sh cai workflow create [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`workflow_create`](/reference/mcp-tools/#workflow_create) | Direct. Typed counterpart; use its input schema. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--name <name>` | Yes | — | workflow name | <a id="cai-workflow-get"></a> ### cai workflow get Fetch one workflow. ```sh cai workflow get [options] [workflowId] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`workflow_get`](/reference/mcp-tools/#workflow_get) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `[workflowId]` | No | workflow id (defaults to the pinned one) | <a id="cai-workflow-rename"></a> ### cai workflow rename Rename a workflow (PATCH /workflow/:id). ```sh cai workflow rename [options] [workflowId] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`workflow_rename`](/reference/mcp-tools/#workflow_rename) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `[workflowId]` | No | workflow id (defaults to the pinned one) | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--name <name>` | Yes | — | new workflow name | <a id="cai-workflow-set-description"></a> ### cai workflow set-description Set a workflow’s description. ```sh cai workflow set-description [options] [workflowId] ``` Aliases: `describe`. | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`workflow_description_set`](/reference/mcp-tools/#workflow_description_set) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `[workflowId]` | No | workflow id (defaults to the pinned one) | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--description <text>` | Yes | — | new description ("" clears it) | <a id="cai-workflow-duplicate"></a> ### cai workflow duplicate Copy the workflow definition into a new unpublished workflow. Records are not copied, and flow and node IDs are preserved. ```sh cai workflow duplicate [options] [workflowId] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`workflow_duplicate`](/reference/mcp-tools/#workflow_duplicate) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `[workflowId]` | No | workflow id (defaults to the pinned one) | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--use` | No | `false` | pin the copy as the default workflow | Select the returned copy ID before editing: flow and node IDs are only unique within a workflow, so stale workflow context edits the original. --use selects the copy as the configured default. <a id="cai-workflow-delete"></a> ### cai workflow delete Delete a workflow after detaching dependent draft and Live agent tools. ```sh cai workflow delete [options] <workflowId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`workflow_delete`](/reference/mcp-tools/#workflow_delete) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<workflowId>` | Yes | workflow id — required explicitly, never the pinned default | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--yes` | Yes | — | confirm soft deletion and deployed-trigger teardown | | `--force` | No | `false` | deprecated compatibility flag; ignored because agent dependents must be detached first | The deprecated --force flag is ignored. Both draft and Live agent dependencies block deletion. The soft delete commits before external trigger teardown: a teardown error can mean the workflow is already deleted and cleanup remains. There is no public undelete. <a id="cai-workflow-versions"></a> ### cai workflow versions Read the development and live versions of a workflow. ```sh cai workflow versions [options] [workflowId] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`workflow_version_list`](/reference/mcp-tools/#workflow_version_list) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `[workflowId]` | No | workflow id (defaults to the pinned one) | <a id="cai-workflow-releases"></a> ### cai workflow releases Published release checkpoints. ```sh cai workflow releases [options] [workflowId] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`workflow_release_list`](/reference/mcp-tools/#workflow_release_list) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `[workflowId]` | No | workflow id (defaults to the pinned one) | <a id="cai-workflow-history"></a> ### cai workflow history Version-state history — the ids `cai workflow restore` takes. ```sh cai workflow history [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`workflow_history`](/reference/mcp-tools/#workflow_history) | Direct. Typed counterpart; use its input schema. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--version <workflowVersionId>` | No | — | defaults to the current development version | | `--group <groupId>` | No | — | expand one group into its individual states | <a id="cai-workflow-restore"></a> ### cai workflow restore Restore an earlier saved definition into the development version. ```sh cai workflow restore [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`workflow_state_restore`](/reference/mcp-tools/#workflow_state_restore) | Direct. Typed counterpart; use its input schema. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--state <workflowVersionStateId>` | Yes | — | state id from `cai workflow history` | | `--version <workflowVersionId>` | No | — | defaults to the current development version | Use --state with a saved state ID, not a history-group ID or positional argument. Restore creates a new development head and retains newer history. A listed state can be outside the plan’s restore window. Live, records and external effects remain unchanged; enabled Live triggers keep using the current release until publication. <a id="cai-workflow-save"></a> ### cai workflow save Save a NAMED development snapshot you can restore to later. ```sh cai workflow save [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`workflow_state_save`](/reference/mcp-tools/#workflow_state_save) | Direct. Typed counterpart; use its input schema. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--name <name>` | Yes | — | label for this checkpoint | <a id="cai-workflow-document"></a> ### cai workflow document Complete JSON document for the development head or one historical state. ```sh cai workflow document [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`workflow_document_get`](/reference/mcp-tools/#workflow_document_get) | Direct. Typed counterpart; use its input schema. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--state <workflowVersionStateId>` | No | — | read a historical state from `cai workflow history` instead of the head | <a id="cai-workflow-state"></a> ### cai workflow state Bounded development-state metadata and per-flow summaries. ```sh cai workflow state [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`workflow_state_get`](/reference/mcp-tools/#workflow_state_get) | Direct. Typed counterpart; use its input schema. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--state <workflowVersionStateId>` | No | — | read a historical state from `cai workflow history` instead of the head | | `--flow <flowId>` | No | — | include node and edge detail for one exact flow id | <a id="cai-workflow-outline"></a> ### cai workflow outline Compact orientation map: flows, inputs/outputs, nodes with deps, triggers, data types. ```sh cai workflow outline [options] [workflowId] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`workflow_outline`](/reference/mcp-tools/#workflow_outline) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `[workflowId]` | No | workflow id (defaults to the pinned one) | <a id="cai-workflow-status"></a> ### cai workflow status Publish state: is development ahead of live, do triggers fire. ```sh cai workflow status [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`workflow_status`](/reference/mcp-tools/#workflow_status) | Direct. Typed counterpart; use its input schema. | <a id="cai-workflow-validate"></a> ### cai workflow validate Deep-validate the development workflow: required props, connections, wiring, expressions, types, subflows, branches, triggers. ```sh cai workflow validate [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`workflow_validate`](/reference/mcp-tools/#workflow_validate) | Direct. Typed counterpart; use its input schema. | Invalid validation exits 1 while the JSON result still has ok: true and data.valid: false. Read the validation fields as well as the exit code. <a id="cai-workflow-publish"></a> ### cai workflow publish Publish the development version as a live release. ```sh cai workflow publish [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`workflow_publish`](/reference/mcp-tools/#workflow_publish) | Direct. Typed counterpart; use its input schema. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--name <name>` | No | — | release name | | `--acknowledge-dual-dispatch` | No | — | publish even though armed test events can run one real event in both development and live | | `--acknowledge-validation-errors` | No | — | Publish despite validation errors — only after the user explicitly approved the listed issues. | Publication copies the development definition and schemas, activates enabled Live triggers, and refreshes following Live agent conversations. Development records are never copied; agent workflow tools follow the new release without an agent republish. Inspect warnings for interface changes or failed conversation refreshes. Validation-error and dual-dispatch acknowledgements are separate flags. <a id="cai-file"></a> ### cai file Hand files back to the user inside the build chat. Subcommands: [`share`](#cai-file-share). <a id="cai-file-share"></a> ### cai file share Share one file with the user as a downloadable card in this build chat. Use it to deliver reports, exports, or other artifacts you produced. ```sh cai file share [options] <path> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | Hosted-only CLI | [`file_share`](/reference/mcp-tools/#file_share) | Hosted replacement. Stores inline bytes as a private artifact and returns its browser-openable link. | | Argument | Required | Meaning | | --- | --- | --- | | `<path>` | Yes | Regular local file path to share with the build chat. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--name <displayName>` | No | — | name shown on the file card (defaults to the file name) | Hosted-only CLI operation: requires a builder-session credential. It accepts a regular local file up to 25 × 1024 × 1024 bytes. Check sharedInChat to confirm delivery. <a id="cai-flow"></a> ### cai flow Flows — a workflow has many canvases. Subcommands: [`list`](#cai-flow-list), [`get`](#cai-flow-get), [`create`](#cai-flow-create), [`rename`](#cai-flow-rename), [`delete`](#cai-flow-delete), [`outputs`](#cai-flow-outputs), [`duplicate`](#cai-flow-duplicate), [`layout`](#cai-flow-layout), [`reorder`](#cai-flow-reorder), [`output`](#cai-flow-output), [`for-each`](#cai-flow-for-each), [`input`](#cai-flow-input). <a id="cai-flow-list"></a> ### cai flow list List the flows on this workflow. ```sh cai flow list [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`flow_list`](/reference/mcp-tools/#flow_list) | Direct. Typed counterpart; use its input schema. | <a id="cai-flow-get"></a> ### cai flow get Nodes, edges and inputs of one flow. ```sh cai flow get [options] <flowId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`flow_get`](/reference/mcp-tools/#flow_get) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<flowId>` | Yes | Flow ID from cai flow list in the selected workflow. | <a id="cai-flow-create"></a> ### cai flow create Create a new flow canvas. ```sh cai flow create [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`flow_create`](/reference/mcp-tools/#flow_create) | Direct. Typed counterpart; use its input schema. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--name <name>` | Yes | — | Name for the new flow, such as Check invoice. | <a id="cai-flow-rename"></a> ### cai flow rename Rename a flow. ```sh cai flow rename [options] <flowId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`flow_rename`](/reference/mcp-tools/#flow_rename) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<flowId>` | Yes | Flow ID from cai flow list in the selected workflow. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--name <name>` | Yes | — | Replacement flow name. | <a id="cai-flow-delete"></a> ### cai flow delete Delete a flow. ```sh cai flow delete [options] <flowId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`flow_delete`](/reference/mcp-tools/#flow_delete) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<flowId>` | Yes | Flow ID from cai flow list in the selected workflow. | <a id="cai-flow-outputs"></a> ### cai flow outputs Declared outputs of a flow. ```sh cai flow outputs [options] <flowId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`flow_output_list`](/reference/mcp-tools/#flow_output_list) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<flowId>` | Yes | Flow ID from cai flow list in the selected workflow. | <a id="cai-flow-duplicate"></a> ### cai flow duplicate Copy a flow with fresh ids for every node and edge. ```sh cai flow duplicate [options] <flowId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`flow_duplicate`](/reference/mcp-tools/#flow_duplicate) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<flowId>` | Yes | Flow ID from cai flow list in the selected workflow. | <a id="cai-flow-layout"></a> ### cai flow layout Deterministically tidy positions after headless builds; an open builder auto-tidies while you build. ```sh cai flow layout [options] <flowId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`flow_layout`](/reference/mcp-tools/#flow_layout) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<flowId>` | Yes | Flow ID from cai flow list in the selected workflow. | <a id="cai-flow-reorder"></a> ### cai flow reorder Reorder the workflow’s flows (presentation order, not execution order). ```sh cai flow reorder [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`flow_reorder`](/reference/mcp-tools/#flow_reorder) | Direct. Typed counterpart; use its input schema. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--order <flowIds>` | Yes | — | every flow id, comma-separated, in the new order | <a id="cai-flow-output"></a> ### cai flow output Flow outputs — declare these BEFORE adding a Return response node. Subcommands: [`add`](#cai-flow-output-add), [`update`](#cai-flow-output-update), [`delete`](#cai-flow-output-delete). <a id="cai-flow-output-add"></a> ### cai flow output add Declare an output a flow returns. ```sh cai flow output add [options] <flowId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`flow_output_add`](/reference/mcp-tools/#flow_output_add) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<flowId>` | Yes | Flow ID from cai flow list in the selected workflow. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--display <name>` | Yes | — | human-readable output label | | `--type <ctype>` | Yes | — | e.g. text / number / list.text / custom.invoice | | `--name <name>` | No | — | internal snake_case name (generated from --display when omitted) | | `--description <text>` | No | — | Description of the returned value. | <a id="cai-flow-output-update"></a> ### cai flow output update Update a flow output (Return response props are kept in sync). ```sh cai flow output update [options] <flowId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`flow_output_update`](/reference/mcp-tools/#flow_output_update) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<flowId>` | Yes | Flow ID from cai flow list in the selected workflow. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--output <id>` | Yes | — | flow output id | | `--name <name>` | No | — | internal snake_case payload key callers read; a --display rename regenerates it unless --name is set | | `--display <name>` | No | — | human label | | `--type <ctype>` | No | — | Replacement output data type, such as text or number. | | `--description <text>` | No | — | Replacement description of the returned value. | Supply at least one of --name, --display, --type or --description. An empty --description clears this output description. <a id="cai-flow-output-delete"></a> ### cai flow output delete Remove a flow output (its Return response prop goes too). ```sh cai flow output delete [options] <flowId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`flow_output_delete`](/reference/mcp-tools/#flow_output_delete) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<flowId>` | Yes | Flow ID from cai flow list in the selected workflow. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--output <id>` | Yes | — | Output ID from cai flow outputs for this flow. | <a id="cai-flow-for-each"></a> ### cai flow for-each Build the for-each pattern; the core scaffold is atomic and maxItems is verified afterward. ```sh cai flow for-each [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`flow_for_each_scaffold`](/reference/mcp-tools/#flow_for_each_scaffold) | Direct. Typed counterpart; use its input schema. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--flow <flowId>` | Yes | — | parent flow holding the list-producing node | | `--from <nodeId>` | No | — | node whose output carries the list; optional with --list-js | | `--source-output <outputId>` | No | — | exact opaque outputs[].id from `cai node get <nodeId> --json`; never a label | | `--name <bodyFlowName>` | Yes | — | name for the new per-item flow | | `--item-type <type>` | Yes | — | one item: a primitive (text\|number\|date\|boolean), an existing/new custom.* type, or a dataRecord.custom.* record | | `--item-field <id:type[:display]>` | No | — | field of a NEW custom item type; repeatable. Omit to reuse an existing custom type | | `--list-js <expr>` | No | — | JS selecting the list from the wired input | | `--js-file <path\|->` | No | — | read the list-selection JS from a UTF-8 file or stdin | | `--list-field <path>` | No | — | nested list field under the source output; builds the exact inputs.<binding>.data path | | `--max-items <n>` | No | — | runtime list cap, 1..10000 (default when omitted: 500) | | `--item-name <displayName>` | No | — | display name of the item flow input | | `--continue-on-error` | No | `false` | keep looping when one iteration fails | <a id="cai-flow-input"></a> ### cai flow input Flow inputs. Subcommands: [`add`](#cai-flow-input-add), [`update`](#cai-flow-input-update), [`delete`](#cai-flow-input-delete). <a id="cai-flow-input-add"></a> ### cai flow input add Add a flow input. ```sh cai flow input add [options] <flowId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`flow_input_add`](/reference/mcp-tools/#flow_input_add) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<flowId>` | Yes | Flow ID from cai flow list in the selected workflow. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--name <displayName>` | No | — | legacy alias for --display; the server derives compiler-current jsBinding | | `--type <ctype>` | Yes | — | data type, e.g. text / number / custom.invoice | | `--display <name>` | No | — | human label used to derive compiler-current jsBinding; legacyBinding is diagnostic | | `--list` | No | `false` | the input is a list of --type | | `--optional` | No | `false` | input is optional | | `--description <text>` | No | — | Description of the value the caller supplies. | <a id="cai-flow-input-update"></a> ### cai flow input update Update a flow input. ```sh cai flow input update [options] <flowId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`flow_input_update`](/reference/mcp-tools/#flow_input_update) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<flowId>` | Yes | Flow ID from cai flow list in the selected workflow. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--input <id>` | Yes | — | flow input id | | `--name <displayName>` | No | — | legacy alias for --display; display changes recompute compiler-current jsBinding | | `--display <name>` | No | — | new human label; recomputes jsBinding while legacyBinding stays diagnostic | | `--type <ctype>` | No | — | Replacement input data type, such as text or number. | | `--description <text>` | No | — | Set a non-empty description. An empty string is treated as absent and cannot clear it. | | `--optional` | No | — | the input can be omitted by callers | | `--required` | No | — | the input must be supplied by callers | | `--default-value <literal>` | No | — | stored default metadata (JSON when it parses, else a string); an omitted optional input still resolves to null at run time | Supply at least one non-empty --display (or its --name alias), --type, --description, --optional/--required, or --default-value. --optional and --required are mutually exclusive. An empty description is ignored, so it cannot clear the field. Renaming the display changes the current expression binding; read the flow again afterward. <a id="cai-flow-input-delete"></a> ### cai flow input delete Delete a flow input. ```sh cai flow input delete [options] <flowId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`flow_input_delete`](/reference/mcp-tools/#flow_input_delete) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<flowId>` | Yes | Flow ID from cai flow list in the selected workflow. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--input <id>` | Yes | — | Input ID from cai flow get for this flow. | <a id="cai-integration"></a> ### cai integration Discover integrations and the actions they publish. Subcommands: [`search`](#cai-integration-search), [`actions`](#cai-integration-actions), [`action`](#cai-integration-action). <a id="cai-integration-search"></a> ### cai integration search Search provider integrations and native registry nodes in one ranked list. ```sh cai integration search [options] <query> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`integration_search`](/reference/mcp-tools/#integration_search) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<query>` | Yes | integration, native node, or capability to find | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--actions` | No | — | only integrations that publish actions | | `--events` | No | — | only integrations that publish trigger events | | `--agent-attachable` | No | — | only integrations with actions attachable to agents | | `--limit <n>` | No | `"20"` | maximum ranked integrations to return | <a id="cai-integration-actions"></a> ### cai integration actions List one integration’s actions or search exact action pairs across the catalog. ```sh cai integration actions [options] [query] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`integration_action_list`](/reference/mcp-tools/#integration_action_list) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `[query]` | No | action intent to rank across one or all integrations | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--integration <slug>` | No | — | restrict results to one exact integration slug | | `--agent-attachable` | No | — | only actions attachable directly to agents | | `--limit <n>` | No | `"50"` | maximum ranked actions to return | <a id="cai-integration-action"></a> ### cai integration action Read the full static prop schema of one action before adding or attaching it. ```sh cai integration action [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`integration_action_get`](/reference/mcp-tools/#integration_action_get) | Direct. Typed counterpart; use its input schema. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--integration <slug>` | Yes | — | exact integration slug | | `--key <key>` | Yes | — | exact action key paired with that integration | <a id="cai-node"></a> ### cai node Placed workflow nodes — add, configure, wire. Subcommands: [`add`](#cai-node-add), [`duplicate`](#cai-node-duplicate), [`set-flow`](#cai-node-set-flow), [`get`](#cai-node-get), [`declare-output`](#cai-node-declare-output), [`props`](#cai-node-props), [`reload`](#cai-node-reload), [`status`](#cai-node-status), [`set`](#cai-node-set), [`set-connection`](#cai-node-set-connection), [`connect`](#cai-node-connect), [`disconnect`](#cai-node-disconnect), [`only-when`](#cai-node-only-when), [`optional-props`](#cai-node-optional-props), [`enable-prop`](#cai-node-enable-prop), [`disable-prop`](#cai-node-disable-prop), [`options`](#cai-node-options), [`continue-on-error`](#cai-node-continue-on-error), [`rename`](#cai-node-rename), [`delete`](#cai-node-delete). <a id="cai-node-add"></a> ### cai node add Initialize a discovered integration action with its connection, wiring, optional props, and values. ```sh cai node add [options] ``` Aliases: `init`. | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`node_add`](/reference/mcp-tools/#node_add) | Direct. Typed counterpart; use its input schema. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--flow <flowId>` | Yes | — | Destination flow ID from cai flow list. | | `--key <componentKey>` | Yes | — | exact action key from `cai integration actions` | | `--node <slug>` | No | — | exact integration slug paired with --key (inferred when omitted) | | `--name <displayName>` | No | — | display name; also the outgoing connection label | | `--after <nodeId>` | No | — | wire this upstream node into the new node at creation | | `--output <main\|error>` | No | `"main"` | which system output --after connects from | | `--connection <id>` | No | — | bind an existing connection | | `--props <jsonOrFile>` | No | — | initial prop map; direct values become {value:...}, advanced per-prop writes pass through | | `--enable-prop <names...>` | No | — | optional prop names to materialize at creation | <a id="cai-node-duplicate"></a> ### cai node duplicate Copy a node into the same flow (offset position, no incoming edges). ```sh cai node duplicate [options] <nodeId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`node_duplicate`](/reference/mcp-tools/#node_duplicate) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. | <a id="cai-node-set-flow"></a> ### cai node set-flow Point a subflow node at a flow; its input props are generated from that flow. ```sh cai node set-flow [options] <nodeId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`node_subflow_set`](/reference/mcp-tools/#node_subflow_set) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<nodeId>` | Yes | a Run flow / Run flow on list node | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--flow <flowId>` | Yes | — | target flow to call | <a id="cai-node-get"></a> ### cai node get Full node record: component, inputs, outputs, connection. ```sh cai node get [options] <nodeId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`node_get`](/reference/mcp-tools/#node_get) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. | <a id="cai-node-declare-output"></a> ### cai node declare-output Declare an unverified dynamic output contract from documented response data. ```sh cai node declare-output [options] <nodeId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`node_output_type_declare`](/reference/mcp-tools/#node_output_type_declare) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--sample-file <file\|->` | Yes | — | documented provider response data: a JSON object or a non-empty JSON array of items; `-` reads stdin | <a id="cai-node-props"></a> ### cai node props Visible + catalog props with current values and decompiled valueJs. ```sh cai node props [options] <nodeId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`node_prop_list`](/reference/mcp-tools/#node_prop_list) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. | <a id="cai-node-reload"></a> ### cai node reload Reload and reconcile dependent props, then report the readiness change. ```sh cai node reload [options] <nodeId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`node_prop_reload`](/reference/mcp-tools/#node_prop_reload) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. | <a id="cai-node-status"></a> ### cai node status Return deterministic configuration readiness and exact blockers. ```sh cai node status [options] <nodeId> ``` Aliases: `output`. | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`node_status`](/reference/mcp-tools/#node_status) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. | <a id="cai-node-set"></a> ### cai node set Set a prop, selecting and verifying the correct storage shape automatically. ```sh cai node set [options] <nodeId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`node_prop_set`](/reference/mcp-tools/#node_prop_set) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--prop <name>` | Yes | — | prop key from `cai node props` | | `--value <literal>` | No | — | static value (JSON string literals are decoded; other JSON is parsed for non-text props and preserved for text props) | | `--js <src>` | No | — | expression DSL source, compiled server-side before writing | | `--js-file <path\|->` | No | — | read expression DSL source from a UTF-8 file or stdin | | `--raw-expression-json <path\|->` | No | — | raw expression object as JSON from a UTF-8 file or stdin, written verbatim — the escape hatch for advanced constraints, injected chips, and loop traversals the DSL cannot author | | `--label <labels...>` | No | — | live option label(s), one per value; used to search providers that do not index opaque ids | | `--expression` | No | `false` | deprecated compatibility flag; storage is selected automatically | Choose exactly one of --value, --js, --js-file or --raw-expression-json. The deprecated --expression flag does not select how the value is stored. <a id="cai-node-set-connection"></a> ### cai node set-connection Bind a connection to an action node. ```sh cai node set-connection [options] <nodeId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`node_connection_set`](/reference/mcp-tools/#node_connection_set) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--connection <id>` | Yes | — | connection id from `cai connection list` | <a id="cai-node-connect"></a> ### cai node connect Wire two nodes; the source output becomes an input on the target. ```sh cai node connect [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`node_connect`](/reference/mcp-tools/#node_connect) | Direct. Typed counterpart; use its input schema. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--from <nodeId>` | Yes | — | upstream node | | `--to <nodeId>` | Yes | — | downstream node | | `--flow <flowId>` | Yes | — | flow containing both nodes | | `--output <main\|error>` | No | `"main"` | which system output to wire from | <a id="cai-node-disconnect"></a> ### cai node disconnect Remove an edge. ```sh cai node disconnect [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`node_disconnect`](/reference/mcp-tools/#node_disconnect) | Direct. Typed counterpart; use its input schema. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--edge <edgeId>` | Yes | — | Edge ID from cai flow get for the connected canvas. | <a id="cai-node-only-when"></a> ### cai node only-when Set or clear a node’s conditional-execution rule. ```sh cai node only-when [options] <nodeId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`node_only_when_set`](/reference/mcp-tools/#node_only_when_set) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--js <expr>` | No | — | boolean expression; the node runs only when it is true | | `--js-file <path\|->` | No | — | read the boolean expression from a UTF-8 file or stdin | | `--groups-json <json>` | No | — | condition string[][]: expressions in each row are AND-ed; rows are OR-ed | | `--clear` | No | `false` | remove all conditions | Choose --js/--js-file, --groups-json or --clear; these forms are mutually exclusive. In --groups-json, each row combines its expressions with AND, and rows combine with OR. <a id="cai-node-optional-props"></a> ### cai node optional-props List togglable optional props. ```sh cai node optional-props [options] <nodeId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`node_optional_prop_list`](/reference/mcp-tools/#node_optional_prop_list) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. | <a id="cai-node-enable-prop"></a> ### cai node enable-prop Enable an optional prop so it becomes settable. ```sh cai node enable-prop [options] <nodeId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`node_optional_prop_set`](/reference/mcp-tools/#node_optional_prop_set) | Merged. The explicit enabled boolean replaces the separate enabling command. | | Argument | Required | Meaning | | --- | --- | --- | | `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--prop <name>` | Yes | — | Optional property name from cai node optional-props. | <a id="cai-node-disable-prop"></a> ### cai node disable-prop Disable an optional prop and remove its stored value. Reload-dependent fields are recalculated when the prop controls them. ```sh cai node disable-prop [options] <nodeId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`node_optional_prop_set`](/reference/mcp-tools/#node_optional_prop_set) | Merged. The explicit enabled boolean replaces the separate disabling command. | | Argument | Required | Meaning | | --- | --- | --- | | `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--prop <name>` | Yes | — | enabled optional prop key from `cai node props` | <a id="cai-node-options"></a> ### cai node options Resolved remote dropdown options for a prop. ```sh cai node options [options] <nodeId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`node_prop_options`](/reference/mcp-tools/#node_prop_options) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--prop <name>` | Yes | — | Property name from cai node props whose choices you want. | | `--query <q>` | No | — | search term — strongly preferred over paging | | `--page <n>` | No | — | 0-based page when not searching | | `--prev-context <json>` | No | — | pagination context returned by a previous options response | | `--for <prop>=<value>` | No | — | override an earlier prop value for option resolution; JSON literals are accepted, bare text is passed as a string; repeatable | <a id="cai-node-continue-on-error"></a> ### cai node continue-on-error Set continue-on-error to an explicit enabled or disabled state. ```sh cai node continue-on-error [options] <nodeId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`node_continue_on_error_set`](/reference/mcp-tools/#node_continue_on_error_set) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--enable` | No | — | Enable continue-on-error. | | `--disable` | No | — | Disable continue-on-error. | Pass exactly one of --enable or --disable. Disabling removes edges from the Error output. <a id="cai-node-rename"></a> ### cai node rename Rename a node (also renames its outgoing connection label). ```sh cai node rename [options] <nodeId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`node_rename`](/reference/mcp-tools/#node_rename) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--name <displayName>` | Yes | — | Replacement node display name. | <a id="cai-node-delete"></a> ### cai node delete Delete a node. ```sh cai node delete [options] <nodeId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`node_delete`](/reference/mcp-tools/#node_delete) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. | <a id="cai-expr"></a> ### cai expr The expression surface. Subcommands: [`context`](#cai-expr-context), [`validate`](#cai-expr-validate), [`set`](#cai-expr-set), [`ops`](#cai-expr-ops), [`decompile`](#cai-expr-decompile). <a id="cai-expr-context"></a> ### cai expr context MANDATORY before writing any --js. Lists every in-scope binding. ```sh cai expr context [options] <nodeId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`expr_context`](/reference/mcp-tools/#expr_context) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--prop <name>` | No | — | the destination prop — adds its expected type and mode | | `--methods` | No | `false` | include the full method catalog (large) | <a id="cai-expr-validate"></a> ### cai expr validate Compile an expression against the node’s real scope. Side-effect free. ```sh cai expr validate [options] <nodeId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`expr_validate`](/reference/mcp-tools/#expr_validate) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--js <src>` | No | — | expression DSL source | | `--js-file <path\|->` | No | — | read expression DSL source from a UTF-8 file or stdin | | `--prop <name>` | No | — | destination prop — validates against its real type and mode | | `--mode <text\|expression\|onlyWhen>` | No | — | compile target when --prop is unknown | <a id="cai-expr-set"></a> ### cai expr set Context-check, compile, persist to the correct channel, and verify readback. ```sh cai expr set [options] <nodeId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`node_prop_set`](/reference/mcp-tools/#node_prop_set) | Merged. node_prop_set exposes the same expression write alongside literal and raw-expression forms. | | Argument | Required | Meaning | | --- | --- | --- | | `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--prop <name>` | Yes | — | destination prop | | `--js <src>` | No | — | expression DSL source | | `--js-file <path\|->` | No | — | read expression DSL source from a UTF-8 file or stdin | | `--force` | No | `false` | overwrite a stored expression the JS DSL cannot fully express, losing those constructs | <a id="cai-expr-ops"></a> ### cai expr ops The method catalog: which operations exist per data type. ```sh cai expr ops [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`expr_operation_list`](/reference/mcp-tools/#expr_operation_list) | Direct. Typed counterpart; use its input schema. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--type <ctype>` | No | — | restrict to one data type; results are cataloged by base type (for example list.custom.video_calendar -> list) | <a id="cai-expr-decompile"></a> ### cai expr decompile Read a stored expression as JavaScript-like source. ```sh cai expr decompile [options] <nodeId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`expr_decompile`](/reference/mcp-tools/#expr_decompile) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--prop <name>` | Yes | — | Property name from cai node props whose expression you want to read. | <a id="cai-run"></a> ### cai run Run nodes and flows. Integration actions execute against their connected accounts. Subcommands: [`node`](#cai-run-node), [`flow`](#cai-run-flow), [`inputs`](#cai-run-inputs), [`discover`](#cai-run-discover). <a id="cai-run-node"></a> ### cai run node Run one node in isolation on the development version and return its resolvedConfigs. ```sh cai run node [options] <nodeId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`run_node`](/reference/mcp-tools/#run_node) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--inputs <json\|file\|->` | No | — | inline JSON or a JSON file; `-` reads stdin | | `--timeout <ms>` | No | `"120000"` | how long to wait for the run to finish | This executes real integration actions against connected accounts and spends usage. An isolated run does not execute upstream nodes. Only completed is success; pause, another terminal status or timeout exits nonzero with error.detail.workflowExecutionId and lastSnapshot. Inspect that existing execution instead of dispatching another run. <a id="cai-run-flow"></a> ### cai run flow Run one flow end-to-end on the development or published live version. ```sh cai run flow [options] <flowId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`run_flow`](/reference/mcp-tools/#run_flow) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<flowId>` | Yes | Flow ID from cai flow list in the selected workflow. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--inputs <json\|file\|->` | No | — | inline JSON or a JSON file; `-` reads stdin | | `--target <dev\|live>` | No | `"dev"` | Development version or published live release. | | `--confirm-live` | No | `false` | acknowledge LIVE run side effects and usage | | `--timeout <ms>` | No | `"300000"` | how long to wait for the run to finish | --target live requires --confirm-live. Both targets execute real integration actions and spend usage when the flow contains them. Only completed is success; paused, completed_with_error, failed, cancelled or timeout exits nonzero with error.detail.workflowExecutionId and lastSnapshot. Inspect that execution instead of redispatching; a polling timeout does not stop it. <a id="cai-run-inputs"></a> ### cai run inputs Show inputs for a node, or pass --flow to inspect a flow before run flow. ```sh cai run inputs [options] <nodeIdOrFlowId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`run_inputs`](/reference/mcp-tools/#run_inputs) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<nodeIdOrFlowId>` | Yes | Node ID from cai flow get, or flow ID from cai flow list when using --flow. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--flow` | No | `false` | treat the argument as a flow id | <a id="cai-run-discover"></a> ### cai run discover Probe a component output with a temporary node. Connected actions can have real effects. ```sh cai run discover [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`run_discover`](/reference/mcp-tools/#run_discover) | Direct. Typed counterpart; use its input schema. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--node <slug>` | Yes | — | integration node slug | | `--key <componentKey>` | Yes | — | exact action key from `cai integration actions` | | `--connection <id\|none>` | Yes | — | connection id, or "none" for a component that needs no auth | | `--props <json\|file\|->` | No | — | prop values, same per-prop shape as `node add` | | `--enable <prop>` | No | — | optional prop to enable first; repeatable | | `--keep` | No | `false` | keep the scratch node instead of deleting it | | `--timeout <ms>` | No | — | poll budget, backend caps at 55000 | <a id="cai-exec"></a> ### cai exec Read execution history. Subcommands: [`list`](#cai-exec-list), [`get`](#cai-exec-get), [`flow`](#cai-exec-flow), [`node`](#cai-exec-node), [`tree`](#cai-exec-tree). <a id="cai-exec-list"></a> ### cai exec list Recent workflow executions. ```sh cai exec list [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`execution_list`](/reference/mcp-tools/#execution_list) | Direct. Typed counterpart; use its input schema. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--limit <n>` | No | `"10"` | max rows | <a id="cai-exec-get"></a> ### cai exec get One workflow execution with its flat node executions. ```sh cai exec get [options] <workflowExecutionId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`execution_get`](/reference/mcp-tools/#execution_get) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<workflowExecutionId>` | Yes | Workflow execution ID from cai run node, cai run flow or cai exec list. | Returns at most the 200 newest node executions, with nodeExecutionsTruncated when more exist. Use cai exec tree to page through the nodes. <a id="cai-exec-flow"></a> ### cai exec flow Node-by-node detail of one flow execution (includes resolvedConfigs). ```sh cai exec flow [options] <flowExecutionId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`execution_flow_get`](/reference/mcp-tools/#execution_flow_get) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<flowExecutionId>` | Yes | Flow execution ID from cai exec tree. | <a id="cai-exec-node"></a> ### cai exec node One node execution: status, output, and resolvedConfigs. ```sh cai exec node [options] <nodeExecutionId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`execution_node_get`](/reference/mcp-tools/#execution_node_get) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<nodeExecutionId>` | Yes | Node execution ID from cai exec tree or cai exec get. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--full` | No | `false` | print the untruncated output blob | <a id="cai-exec-tree"></a> ### cai exec tree Paginated node-by-node status rows across a workflow execution. ```sh cai exec tree [options] <workflowExecutionId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`execution_tree`](/reference/mcp-tools/#execution_tree) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<workflowExecutionId>` | Yes | Workflow execution ID from cai run node, cai run flow or cai exec list. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--limit <n>` | No | — | maximum rows to return (1-200; default 50) | | `--cursor <opaque>` | No | — | continue from a returned execution-tree cursor | | `--status <status...>` | No | — | filter by one or more statuses: pending, running, completed, completed_with_error, failed, skipped, cancelled | | `--flow <flowId>` | No | — | filter by one exact workflow flow id | If any node-detail read fails, the command exits nonzero and returns successfully read rows in error.detail.partialData. A cursor belongs to one execution and cannot be reused with a different limit or filters. <a id="cai-connection"></a> ### cai connection Existing user connections. Subcommands: [`list`](#cai-connection-list), [`update`](#cai-connection-update), [`delete`](#cai-connection-delete), [`request`](#cai-connection-request), [`connect`](#cai-connection-connect). <a id="cai-connection-list"></a> ### cai connection list List account connections without requiring workflow context. ```sh cai connection list [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`connection_list`](/reference/mcp-tools/#connection_list) | Direct. Typed counterpart; use its input schema. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--integration <slug>` | No | — | only connections for this integration | | `--node <slug>` | No | — | legacy alias for --integration | <a id="cai-connection-update"></a> ### cai connection update Rename a connection or change whether it is the integration default. ```sh cai connection update [options] <connectionId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`connection_update`](/reference/mcp-tools/#connection_update) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<connectionId>` | Yes | connection id from `cai connection list` | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--name <displayName>` | No | — | new display name | | `--default` | No | — | make this the default connection for its integration | | `--no-default` | No | — | clear this connection’s default flag | Supply at least one of --name, --default or --no-default. --default and --no-default are mutually exclusive. Changing the default does not rebind existing nodes or agent tools. <a id="cai-connection-delete"></a> ### cai connection delete Delete a connection; nodes and agent tools bound to this connection lose their authorization immediately. ```sh cai connection delete [options] <connectionId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`connection_delete`](/reference/mcp-tools/#connection_delete) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<connectionId>` | Yes | connection id from `cai connection list` | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--yes` | Yes | — | confirm deletion and immediate authorization loss | <a id="cai-connection-request"></a> ### cai connection request Ask the user to connect an integration: places a connect card in the build chat and returns immediately. ```sh cai connection request [options] <nodeSlug> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI with build-chat presentation | — | Omitted from MCP. Posts a connect card into build chat; connection_connect_url supplies the hosted outcome. | | Argument | Required | Meaning | | --- | --- | --- | | `<nodeSlug>` | Yes | integration slug that needs a connected account | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--for-node <nodeId>` | No | — | workflow node that needs this connection (context only) | | `--reason <text>` | No | — | one short user-facing sentence shown on the card | A build chat is needed for a connect card. When requestedInChat is false, use the returned connectUrl. <a id="cai-connection-connect"></a> ### cai connection connect Open the Controller AI browser flow for a missing integration, optionally waiting for completion. ```sh cai connection connect [options] <nodeSlug> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`connection_connect_url`](/reference/mcp-tools/#connection_connect_url) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<nodeSlug>` | Yes | integration slug reported by `cai integration search` | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--no-open` | No | — | headless/remote mode: print the URL without opening a browser | | `--wait` | No | `false` | wait for a newly created connection for this integration | | `--timeout <seconds>` | No | `"300"` | maximum time to wait for the new connection | <a id="cai-branch"></a> ### cai branch Router routes and If/Else branches — create, condition, wire, order. Subcommands: [`list`](#cai-branch-list), [`add`](#cai-branch-add), [`update`](#cai-branch-update), [`delete`](#cai-branch-delete), [`connect`](#cai-branch-connect), [`reorder`](#cai-branch-reorder). <a id="cai-branch-list"></a> ### cai branch list Routes/branches in evaluation order, with conditions and wired targets. ```sh cai branch list [options] <nodeId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`branch_list`](/reference/mcp-tools/#branch_list) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<nodeId>` | Yes | Router or If/Else node id | <a id="cai-branch-add"></a> ### cai branch add Add a Router route or an If/Else condition branch (inserted before Else). ```sh cai branch add [options] <nodeId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`branch_add`](/reference/mcp-tools/#branch_add) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<nodeId>` | Yes | Router or If/Else node id | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--name <displayName>` | No | — | route/branch label | | `--js <expr>` | No | — | boolean condition, one expression | | `--js-file <path\|->` | No | — | read one boolean condition from a UTF-8 file or stdin | | `--condition-json <json>` | No | — | condition as string[][] — OR of AND-rows | | `--allow-duplicate` | No | `false` | add even when a route/branch already carries --name | <a id="cai-branch-update"></a> ### cai branch update Rename a route/branch and/or replace its condition. ```sh cai branch update [options] <nodeId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`branch_update`](/reference/mcp-tools/#branch_update) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<nodeId>` | Yes | Router or If/Else node id | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--route <id>` | No | — | route id (Router) or branch id (If/Else) | | `--branch <id>` | No | — | alias for --route | | `--name <displayName>` | No | — | new label | | `--js <expr>` | No | — | new boolean condition, one expression | | `--js-file <path\|->` | No | — | read one boolean condition from a UTF-8 file or stdin | | `--condition-json <json>` | No | — | new condition as string[][] — OR of AND-rows | <a id="cai-branch-delete"></a> ### cai branch delete Delete a route/branch and its branch edge. ```sh cai branch delete [options] <nodeId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`branch_delete`](/reference/mcp-tools/#branch_delete) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<nodeId>` | Yes | Router or If/Else node id | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--route <id>` | No | — | route id (Router) or branch id (If/Else) | | `--branch <id>` | No | — | alias for --route | <a id="cai-branch-connect"></a> ### cai branch connect Connect a branch output to a target node. ```sh cai branch connect [options] <nodeId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`branch_connect`](/reference/mcp-tools/#branch_connect) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<nodeId>` | Yes | Router or If/Else node id | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--route <id>` | No | — | route id (Router) or branch id (If/Else) | | `--branch <id>` | No | — | alias for --route | | `--to <nodeId>` | Yes | — | target node the branch runs | | `--flow <flowId>` | No | — | flow containing both nodes (resolved when omitted) | <a id="cai-branch-reorder"></a> ### cai branch reorder Reorder If/Else condition branches — first match wins, so order is semantics. ```sh cai branch reorder [options] <nodeId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`branch_reorder`](/reference/mcp-tools/#branch_reorder) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<nodeId>` | Yes | If/Else node id | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--order <ids>` | Yes | — | every condition branch id, comma-separated, in new order | <a id="cai-data"></a> ### cai data Workflow data store — collections and records (development and live stores are separate). Subcommands: [`collections`](#cai-data-collections), [`fields`](#cai-data-fields), [`query`](#cai-data-query), [`get`](#cai-data-get), [`create`](#cai-data-create), [`update`](#cai-data-update), [`delete`](#cai-data-delete), [`delete-many`](#cai-data-delete-many), [`import`](#cai-data-import), [`copy-to-live`](#cai-data-copy-to-live), [`collection`](#cai-data-collection). <a id="cai-data-collections"></a> ### cai data collections Collections in one record store, with row counts. ```sh cai data collections [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`data_collection_list`](/reference/mcp-tools/#data_collection_list) | Direct. Typed counterpart; use its input schema. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--env <dev\|live>` | No | `"dev"` | record store to read | <a id="cai-data-fields"></a> ### cai data fields Field id ⇄ display mapping — writes go by id, reads come back by display. ```sh cai data fields [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`data_field_list`](/reference/mcp-tools/#data_field_list) | Direct. Typed counterpart; use its input schema. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--type <dataType>` | Yes | — | collection data type, e.g. custom.invoice | <a id="cai-data-query"></a> ### cai data query Records in one collection. ```sh cai data query [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`data_record_query`](/reference/mcp-tools/#data_record_query) | Direct. Typed counterpart; use its input schema. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--type <dataType>` | Yes | — | collection data type, e.g. custom.invoice | | `--env <dev\|live>` | No | `"dev"` | record store to read | | `--query <text>` | No | — | plain-text search — NOT field-aware filtering | | `--limit <n>` | No | — | page size (backend caps at 100) | | `--offset <n>` | No | — | pagination offset | <a id="cai-data-get"></a> ### cai data get One record by id. ```sh cai data get [options] <recordId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`data_record_get`](/reference/mcp-tools/#data_record_get) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<recordId>` | Yes | record id, e.g. rec_… | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--type <dataType>` | Yes | — | Custom data type name from cai data collections for the selected environment. | | `--env <dev\|live>` | No | `"dev"` | record store to read | <a id="cai-data-create"></a> ### cai data create Create a record (validated against the collection schema). ```sh cai data create [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`data_record_create`](/reference/mcp-tools/#data_record_create) | Direct. Typed counterpart; use its input schema. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--type <dataType>` | Yes | — | Custom data type name from cai data collections for the selected environment. | | `--fields <json\|file\|->` | Yes | — | field values keyed by field id | | `--env <dev\|live>` | No | `"dev"` | record store to write | <a id="cai-data-update"></a> ### cai data update Patch a record — omitted fields are left alone. ```sh cai data update [options] <recordId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`data_record_update`](/reference/mcp-tools/#data_record_update) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<recordId>` | Yes | Record ID from cai data query for this data type and environment. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--type <dataType>` | Yes | — | Custom data type name from cai data collections for the selected environment. | | `--fields <json\|file\|->` | Yes | — | fields to patch, keyed by field id | | `--env <dev\|live>` | No | `"dev"` | record store to write | <a id="cai-data-delete"></a> ### cai data delete Soft-delete a record. ```sh cai data delete [options] <recordId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`data_record_delete`](/reference/mcp-tools/#data_record_delete) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<recordId>` | Yes | Record ID from cai data query for this data type and environment. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--type <dataType>` | Yes | — | Custom data type name from cai data collections for the selected environment. | | `--env <dev\|live>` | No | `"dev"` | record store to write | <a id="cai-data-delete-many"></a> ### cai data delete-many Bulk-delete records from the development or live store (soft delete; no undo). ```sh cai data delete-many [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`data_record_delete_many`](/reference/mcp-tools/#data_record_delete_many) | Direct. Typed counterpart; use its input schema. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--type <dataType>` | Yes | — | Custom data type name from cai data collections for the selected environment. | | `--records <id,id,…>` | No | — | record ids to delete | | `--all` | No | `false` | delete every record in the collection | | `--yes` | No | `false` | confirm deleting every record when used with --all | | `--env <dev\|live>` | No | `"dev"` | record store to delete from; live changes affect the published workflow immediately | Choose non-empty --records or --all, never both; --all also requires --yes. There is no public record undo. <a id="cai-data-import"></a> ### cai data import Validate or import CSV records in the development or live store (commits append). ```sh cai data import [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`data_record_import_commit`](/reference/mcp-tools/#data_record_import_commit)<br>[`data_record_import_validate`](/reference/mcp-tools/#data_record_import_validate) | Split. Choose the tool for the intended operation. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--type <dataType>` | Yes | — | Custom data type name from cai data collections for the selected environment. | | `--file <path>` | Yes | — | CSV file to import | | `--env <dev\|live>` | No | `"dev"` | record store to validate or write; live commits affect the published workflow immediately | | `--mode <dryRun\|commit>` | No | `"dryRun"` | validate only, or actually write | CSV headers use field display names. --mode dryRun writes nothing. Commit validates again, appends valid rows and skips invalid rows; rerunning appends the valid rows again. Inspect imported and rejected counts, then query the same store before retrying. <a id="cai-data-copy-to-live"></a> ### cai data copy-to-live Upsert active development records into the matching published Live collection by record key. ```sh cai data copy-to-live [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`data_copy_to_live`](/reference/mcp-tools/#data_copy_to_live) | Direct. Typed counterpart; use its input schema. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--type <dataType>` | Yes | — | collection to copy from development to live | Requires a matching, current published schema. Matching record keys are overwritten or revived, Live-only rows remain, and an empty development source changes nothing. There is no dry run. <a id="cai-data-collection"></a> ### cai data collection Collection lifecycle (collections are synced from `custom.*` schemas). Subcommands: [`create`](#cai-data-collection-create). <a id="cai-data-collection-create"></a> ### cai data collection create Create a collection by defining its schema; equivalent to cai schema create. ```sh cai data collection create [options] <dataType> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`schema_type_create`](/reference/mcp-tools/#schema_type_create) | Merged. The collection command shares the schema-creation tool. | | Argument | Required | Meaning | | --- | --- | --- | | `<dataType>` | Yes | collection data type — must start with "custom." | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--display <label>` | No | — | Human-readable name of the new data type. | | `--field <id:type[:display]>` | No | — | field spec; repeatable | | `--from-json <file\|->` | No | — | full {display, fields} definition | Provide at least one --field or --from-json, following the same definition rules as cai schema create. <a id="cai-deps"></a> ### cai deps Dependency map: which agents and workflows depend on this workflow (or the whole account). ```sh cai deps [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`dependency_map`](/reference/mcp-tools/#dependency_map) | Direct. Typed counterpart; use its input schema. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--account` | No | `false` | account-wide resource map instead of the current workflow | <a id="cai-events"></a> ### cai events Account activity feed, newest first: connections, workflow edits/publishes/runs, agents, org members. ```sh cai events [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`event_list`](/reference/mcp-tools/#event_list) | Direct. Typed counterpart; use its input schema. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--type <types>` | No | `[]` | only these event types (comma-separated or repeated) | | `--since <when>` | No | — | ISO timestamp or relative like 30m, 2h, 7d | | `--cursor <cursor>` | No | — | opaque cursor from a previous page; returns strictly older events | | `--for-workflow <id>` | No | — | only events about this workflow | | `--limit <n>` | No | — | events per page (default 50, max 200) | <a id="cai-schema"></a> ### cai schema Per-workflow custom data types (`custom.*`) — the data store’s schemas. Subcommands: [`list`](#cai-schema-list), [`get`](#cai-schema-get), [`resolve`](#cai-schema-resolve), [`create`](#cai-schema-create), [`update`](#cai-schema-update), [`delete`](#cai-schema-delete). <a id="cai-schema-list"></a> ### cai schema list Every data type defined in this workflow. ```sh cai schema list [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`schema_type_list`](/reference/mcp-tools/#schema_type_list) | Direct. Typed counterpart; use its input schema. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--all` | No | `false` | include the engine-derived custom.__* integration schemas | <a id="cai-schema-get"></a> ### cai schema get One data type with its field ids, displays and types. ```sh cai schema get [options] <name> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`schema_type_get`](/reference/mcp-tools/#schema_type_get) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<name>` | Yes | schema name, e.g. custom.invoice | <a id="cai-schema-resolve"></a> ### cai schema resolve Read a type name, fields and whether it is a list. ```sh cai schema resolve [options] <typeId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`schema_type_resolve`](/reference/mcp-tools/#schema_type_resolve) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<typeId>` | Yes | e.g. text, custom.invoice, list.custom.invoice, node.<nodeId> | <a id="cai-schema-create"></a> ### cai schema create Create a custom data type (this is also what creates a data collection). ```sh cai schema create [options] <name> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`schema_type_create`](/reference/mcp-tools/#schema_type_create) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<name>` | Yes | schema name — must start with "custom." | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--display <label>` | No | — | human label (defaults to the name without the prefix) | | `--field <id:type[:display]>` | No | — | field spec; repeatable | | `--from-json <file\|->` | No | — | full {display, fields} definition instead of --field | Provide at least one --field or --from-json. JSON must contain fields with id and type; an omitted field display defaults to its ID. When both forms are supplied, --from-json supplies the definition. <a id="cai-schema-update"></a> ### cai schema update Update a data type definition. --field or --from-json replaces the complete field list and removes omitted fields; a display-only update preserves fields. ```sh cai schema update [options] <name> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`schema_type_update`](/reference/mcp-tools/#schema_type_update) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<name>` | Yes | schema name, e.g. custom.invoice | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--display <label>` | No | — | new human label | | `--field <id:type[:display]>` | No | — | Repeat for each field. Replaces the complete field list. | | `--from-json <file\|->` | No | — | full {display, fields} definition instead of --field | Supply --display, at least one --field, or --from-json. A field replacement removes omitted fields from the schema without converting stored values; a display-only edit preserves fields. <a id="cai-schema-delete"></a> ### cai schema delete Remove the development type and deactivate its collection without deleting stored rows. ```sh cai schema delete [options] <name> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`schema_type_delete`](/reference/mcp-tools/#schema_type_delete) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<name>` | Yes | schema name, e.g. custom.invoice | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--yes` | Yes | — | confirm deleting the type and removing fields on other types that reference it | Recreating the same type and field IDs reactivates stored values. Fields removed from other types because they referenced this type are not restored automatically. <a id="cai-trigger"></a> ### cai trigger Inspect trigger sources, captured events and development or live dispatch. Subcommands: [`list`](#cai-trigger-list), [`audit`](#cai-trigger-audit), [`get`](#cai-trigger-get), [`test-events`](#cai-trigger-test-events), [`search`](#cai-trigger-search), [`props`](#cai-trigger-props), [`options`](#cai-trigger-options), [`create`](#cai-trigger-create), [`events`](#cai-trigger-events), [`event`](#cai-trigger-event), [`select-event`](#cai-trigger-select-event), [`replay`](#cai-trigger-replay), [`set-enabled`](#cai-trigger-set-enabled), [`rename`](#cai-trigger-rename), [`delete`](#cai-trigger-delete). <a id="cai-trigger-list"></a> ### cai trigger list Trigger lifecycle rows: ids, development state, readiness and issues. ```sh cai trigger list [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`trigger_list`](/reference/mcp-tools/#trigger_list) | Direct. Typed counterpart; use its input schema. | <a id="cai-trigger-audit"></a> ### cai trigger audit Pre-publish trigger coverage, development dispatch and double-run risk. ```sh cai trigger audit [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`trigger_audit`](/reference/mcp-tools/#trigger_audit) | Direct. Typed counterpart; use its input schema. | <a id="cai-trigger-get"></a> ### cai trigger get Full lifecycle for one trigger: capture, deployment, verification and issues. ```sh cai trigger get [options] <triggerId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`trigger_get`](/reference/mcp-tools/#trigger_get) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<triggerId>` | Yes | canvas trigger id from `cai trigger list` | <a id="cai-trigger-test-events"></a> ### cai trigger test-events Set ambient development test-event dispatch (routine tests should use replay). ```sh cai trigger test-events [options] <triggerId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`trigger_test_events_set`](/reference/mcp-tools/#trigger_test_events_set) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<triggerId>` | Yes | canvas trigger id from `cai trigger list` | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--allow` | No | — | arm ambient real-event dispatch against the development canvas | | `--disallow` | No | — | turn ambient development dispatch off | | `--acknowledge-dual-run` | No | — | when arming, acknowledge that one real event can execute more than once | Choose --allow or --disallow. Enabling requires --acknowledge-dual-run because one event can start development and live executions. <a id="cai-trigger-search"></a> ### cai trigger search Nodes that can trigger a flow, and the --event keys each one publishes. ```sh cai trigger search [options] [query] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`trigger_search`](/reference/mcp-tools/#trigger_search) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `[query]` | No | search term, plain English | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--node <slug>` | No | — | also return this node’s full event list | | `--limit <n>` | No | `"20"` | max nodes | | `--events-per-node <n>` | No | `"6"` | event rows listed per node (raise to see them all) | <a id="cai-trigger-props"></a> ### cai trigger props Configurable props for a trigger event; returns the dynamicPropsId to reuse. ```sh cai trigger props [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`trigger_component_props`](/reference/mcp-tools/#trigger_component_props) | Direct. Typed counterpart; use its input schema. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--node <slug>` | Yes | — | trigger node slug | | `--event <eventKey>` | Yes | — | event key from `cai trigger search` — never guess it | | `--connection <id>` | No | — | connection id when the trigger needs auth | | `--configured <json\|file\|->` | No | — | already-set prop values, for dependent dynamic props | | `--dynamic-props-id <id>` | No | — | dynamicPropsId from a previous call, to reload | <a id="cai-trigger-options"></a> ### cai trigger options Resolve exact values for one trigger dropdown prop before trigger creation. ```sh cai trigger options [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`trigger_prop_options`](/reference/mcp-tools/#trigger_prop_options) | Direct. Typed counterpart; use its input schema. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--node <slug>` | Yes | — | trigger node slug | | `--event <eventKey>` | Yes | — | event key from `cai trigger search` | | `--prop <name>` | Yes | — | option-backed prop name from `cai trigger props` | | `--connection <id>` | No | — | connection id when the trigger needs auth | | `--configured <json\|file\|->` | No | — | already-set trigger prop values | | `--dynamic-props-id <id>` | No | — | dynamicPropsId from `cai trigger props` | | `--query <text>` | No | — | search by human option label | | `--page <n>` | No | — | 0-based option page when not searching | | `--prev-context <json\|file\|->` | No | — | context returned by a previous options page | <a id="cai-trigger-create"></a> ### cai trigger create Create a trigger source and its canvas. ```sh cai trigger create [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`trigger_create`](/reference/mcp-tools/#trigger_create) | Direct. Typed counterpart; use its input schema. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--flow <flowId>` | Yes | — | flow this trigger runs (a trigger targets exactly one) | | `--node <slug>` | Yes | — | trigger node slug | | `--event <eventKey>` | Yes | — | event key from `cai trigger search` — never guess it | | `--source-basis <basis>` | Yes | — | one of explicit-in-request \| user-answer \| inferred-from-existing-workflow | | `--connection <id>` | No | — | connection id when the trigger needs auth | | `--props <json\|file\|->` | No | — | configured prop values | | `--dynamic-props-id <id>` | No | — | dynamicPropsId from `cai trigger props` | Creation deploys a real source and starts traffic capture immediately. Captured events run the workflow after publication, during armed development dispatch, or through replay. <a id="cai-trigger-events"></a> ### cai trigger events Captured events for a trigger source — compact payload previews. ```sh cai trigger events [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`trigger_event_list`](/reference/mcp-tools/#trigger_event_list) | Direct. Typed counterpart; use its input schema. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--trigger <backendTriggerId>` | Yes | — | the NUMERIC backendTriggerId, not the canvas id | | `--limit <n>` | No | — | newest-first page size (default 5, max 50) | <a id="cai-trigger-event"></a> ### cai trigger event One captured event with its full payload. ```sh cai trigger event [options] <eventId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`trigger_event_get`](/reference/mcp-tools/#trigger_event_get) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<eventId>` | Yes | captured event id from `cai trigger events` | <a id="cai-trigger-select-event"></a> ### cai trigger select-event Adopt a captured event as the trigger’s sample, defining its output schema. ```sh cai trigger select-event [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`trigger_event_select`](/reference/mcp-tools/#trigger_event_select) | Direct. Typed counterpart; use its input schema. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--node <triggerNodeId>` | Yes | — | trigger node id from `cai trigger create` | | `--event <eventId>` | Yes | — | captured event id | <a id="cai-trigger-replay"></a> ### cai trigger replay Replay a captured event or supplied payload. The default target is development; actions have real effects. ```sh cai trigger replay [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`trigger_replay`](/reference/mcp-tools/#trigger_replay) | Direct. Typed counterpart; use its input schema. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--trigger <backendTriggerId>` | Yes | — | the NUMERIC backendTriggerId | | `--event <eventId>` | No | — | captured event to replay (exclusive with --payload) | | `--payload <json\|file\|->` | No | — | custom raw payload (exclusive with --event) | | `--target <dev\|live>` | No | `"dev"` | development pre-publish or LIVE post-publish verification | | `--confirm-live` | No | `false` | acknowledge LIVE replay side effects and usage | Choose exactly one of --event or --payload. --target live requires --confirm-live. <a id="cai-trigger-set-enabled"></a> ### cai trigger set-enabled Set a trigger to an explicit enabled or disabled state. ```sh cai trigger set-enabled [options] <triggerId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`trigger_set_enabled`](/reference/mcp-tools/#trigger_set_enabled) | Merged. The explicit enabled boolean combines the mutually exclusive enable and disable flags. | | Argument | Required | Meaning | | --- | --- | --- | | `<triggerId>` | Yes | canvas trigger id | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--enable` | No | — | set the trigger enabled | | `--disable` | No | — | set the trigger disabled | Pass exactly one of --enable or --disable. This changes development and armed development dispatch immediately; the published trigger keeps its prior state until workflow publication. <a id="cai-trigger-rename"></a> ### cai trigger rename Rename a trigger. ```sh cai trigger rename [options] <triggerId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`trigger_rename`](/reference/mcp-tools/#trigger_rename) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<triggerId>` | Yes | canvas trigger id | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--name <name>` | Yes | — | Replacement trigger name. | <a id="cai-trigger-delete"></a> ### cai trigger delete Delete a trigger and its canvas. ```sh cai trigger delete [options] <triggerId> ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`trigger_delete`](/reference/mcp-tools/#trigger_delete) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `<triggerId>` | Yes | canvas trigger id | Deletes the development trigger and stops its armed development dispatch immediately. The prior Live trigger continues until workflow publication. <a id="cai-template-setup"></a> ### cai template-setup Inspect and complete the assisted template setup bound to this build thread. Subcommands: [`status`](#cai-template-setup-status), [`complete`](#cai-template-setup-complete). <a id="cai-template-setup-status"></a> ### cai template-setup status Read the assisted template setup state for this build thread. ```sh cai template-setup status [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | — | Omitted from MCP. Assisted template setup runs inside the builder sandbox from its injected brief, not through the hosted MCP. | <a id="cai-template-setup-complete"></a> ### cai template-setup complete Verify every expected workflow release and tool binding, then complete setup. ```sh cai template-setup complete [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | — | Omitted from MCP. Assisted template setup runs inside the builder sandbox from its injected brief, not through the hosted MCP. | <a id="cai-label"></a> ### cai label Workflow and agent labels; rename or delete account labels in the UI. Subcommands: [`list`](#cai-label-list), [`set`](#cai-label-set). <a id="cai-label-list"></a> ### cai label list Every label you own. ```sh cai label list [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`label_list`](/reference/mcp-tools/#label_list) | Direct. Typed counterpart; use its input schema. | Account-wide label renaming and deletion are app operations. <a id="cai-label-set"></a> ### cai label set Set the exact labels on one workflow or one agent by name. ```sh cai label set [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`label_set`](/reference/mcp-tools/#label_set) | Direct. Typed counterpart; use its input schema. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--agent <agentId>` | No | — | agent id to label | | `--labels <name,...>` | No | — | comma-separated label names | | `--label <name>` | No | — | one label name; repeat for more than one | | `--none` | No | — | remove every label from the target | Pass exactly one explicit target: --workflow <workflowId> or --agent <agentId>; a pinned workflow alone is not accepted here. Choose --labels and/or repeat --label, or use --none alone. This replaces all labels on the target and creates missing account labels. Account-wide label renaming and deletion are app operations.

# CLI Command Reference Source: https://docs.getcontroller.ai/reference/cli/ Which command, flag and result should an assistant use? This reference gives the supported CLI 0.2.24 command tree from the frozen snapshot, including required arguments, option defaults and corresponding MCP tools. Use the [CLI guide](/for-ai-agents/cli/) for installation, workflow selection and interpreting a command that is still running. For the **Invoice intake** example, first find the workflow and its **Check invoice** flow. In the app, open **Workflows**, choose the workflow, select its flow, then use **Test current flow** when you are ready to test it. With an assistant, start with `cai workflow list --json`; its `data.items` entries supply the workflow IDs and names. The example below selects the matching IDs from that inventory before reading the flow's accepted inputs. It assumes you already built the [first workflow](/start/first-workflow/). Angle brackets mark values to replace; square brackets mark optional arguments in the syntax summaries. In option tables, **Required** means Commander requires the flag. Additional flag combinations appear beside the affected entries. A dash in the default column means the command definition supplies no explicit default. Examples here assume no pinned workflow and pass `--workflow ` when needed. Keep the displayed units: run timeouts use milliseconds, while connection and conversation waits use seconds. MCP links name typed tools, including commands that split into separate tools or share one tool. A **hosted replacement** runs in the MCP server with the inputs in its linked contract. Follow that contract when switching from a terminal to MCP. ## Find the invoice flow List workflows and note the `data.items` entry named **Invoice intake**; its `id` is `` below. ```sh cai workflow list --json ``` List that workflow’s flows, then note the `data.items` entry named **Check invoice**; its `id` is ``. ```sh cai flow list --workflow --json ``` Read that flow’s accepted inputs before choosing values for a run. ```sh cai run inputs --flow --workflow --json ``` The MCP counterpart [`run_inputs`](/reference/mcp-tools/#run_inputs) takes `workflowId`, `nodeIdOrFlowId: ""` and `flow: true`. ## Read global options and results `--json`, `--workflow` and `--api-url` work before or after a subcommand. | Option | Meaning | | --- | --- | | `-V, --version` | output the version number | | `--json` | machine-readable output on stdout | | `--workflow ` | workflow id (overrides `cai use` and CAI_WORKFLOW) | | `--api-url ` | backend base URL (overrides CAI_API_URL) | | `--id ` | positional id, for ids that begin with "-" | | `-h, --help` | Display command help. | Workflow selection is `--workflow` → `CAI_WORKFLOW` → `.cai.json` in the current directory → the configured default. `--id` carries a positional ID that starts with a hyphen. Normal JSON results contain `ok`, `command` and `data`; most failures contain `ok: false` and `error`, including its `code` and `message`. An invalid `workflow validate --json` exits 1 with `ok: true` and `data.valid: false`. Warnings also go to stderr. Interactive authorization can emit newline-delimited JSON events before the final result; after those events, the final result occupies the last stdout line. | Exit code | Meaning | | --- | --- | | `0` | Successful CLI result, including acceptance of asynchronous work before it finishes. Help and version requests also use zero. | | `1` | Input, validation, action or unexpected local CLI error; inspect `error.code`. A dispatched run also exits 1 on pause, failure or timeout. | | `2` | State conflict. | | `3` | Authentication or authorization failure. | | `4` | Transport, server, protocol-response or approval-poll error. | An accepted message is not a completed reply: `agent conversation send` without `--wait` returns `accepted`. For run and approval waits, follow the [CLI result guidance](/for-ai-agents/cli/#read-the-whole-result) before repeating a write. ## Supply files and structured input | Input form | Accepted content | | --- | --- | | `run node --inputs`, `run flow --inputs` | Inline JSON, a JSON file path, or `-` for stdin. | | `--js-file` on expression-writing commands | UTF-8 file path or `-` for stdin; mutually exclusive with the inline expression flag. | | `schema create/update --from-json`, `data collection create --from-json` | JSON file path or `-` for stdin. | | `data create/update --fields` | Inline JSON object, file path or `-` for stdin; keys are field IDs. | | `data import --file` | CSV file path; `--mode dryRun` validates and `--mode commit` writes. | | `agent create/update --instructions-file`, `agent add-file --file`, `file share ` | Local file paths. These do not use `-` as a stdin shortcut. | ## Choose a command group | Group | Direct children | | --- | --- | | `cai` | [`auth`](#cai-auth), [`approval`](#cai-approval), [`signup`](#cai-signup), [`connect`](#cai-connect), [`skills`](#cai-skills), [`docs`](#cai-docs), [`upgrade`](#cai-upgrade), [`config`](#cai-config), [`doctor`](#cai-doctor), [`agent`](#cai-agent), [`use`](#cai-use), [`workflow`](#cai-workflow), [`file`](#cai-file), [`flow`](#cai-flow), [`integration`](#cai-integration), [`node`](#cai-node), [`expr`](#cai-expr), [`run`](#cai-run), [`exec`](#cai-exec), [`connection`](#cai-connection), [`branch`](#cai-branch), [`data`](#cai-data), [`deps`](#cai-deps), [`events`](#cai-events), [`schema`](#cai-schema), [`trigger`](#cai-trigger), [`template-setup`](#cai-template-setup), [`label`](#cai-label) | | `cai auth` | [`login`](#cai-auth-login), [`password`](#cai-auth-password), [`token`](#cai-auth-token), [`key`](#cai-auth-key), [`logout`](#cai-auth-logout), [`status`](#cai-auth-status) | | `cai approval` | [`resume`](#cai-approval-resume) | | `cai signup` | [`email`](#cai-signup-email), [`verify`](#cai-signup-verify) | | `cai skills` | [`install`](#cai-skills-install), [`update`](#cai-skills-update), [`status`](#cai-skills-status) | | `cai config` | [`reset`](#cai-config-reset) | | `cai agent` | [`setup`](#cai-agent-setup), [`list`](#cai-agent-list), [`get`](#cai-agent-get), [`create`](#cai-agent-create), [`update`](#cai-agent-update), [`delete`](#cai-agent-delete), [`visibility`](#cai-agent-visibility), [`add-workflow`](#cai-agent-add-workflow), [`add-action`](#cai-agent-add-action), [`update-tool`](#cai-agent-update-tool), [`remove-tool`](#cai-agent-remove-tool), [`files`](#cai-agent-files), [`add-file`](#cai-agent-add-file), [`tools`](#cai-agent-tools), [`publish-preflight`](#cai-agent-publish-preflight), [`publish`](#cai-agent-publish), [`present`](#cai-agent-present), [`versions`](#cai-agent-versions), [`conversation`](#cai-agent-conversation), [`test`](#cai-agent-test) | | `cai agent conversation` | [`list`](#cai-agent-conversation-list), [`create`](#cai-agent-conversation-create), [`status`](#cai-agent-conversation-status), [`history`](#cai-agent-conversation-history), [`approve`](#cai-agent-conversation-approve), [`deny`](#cai-agent-conversation-deny), [`send`](#cai-agent-conversation-send) | | `cai workflow` | [`list`](#cai-workflow-list), [`create`](#cai-workflow-create), [`get`](#cai-workflow-get), [`rename`](#cai-workflow-rename), [`set-description`](#cai-workflow-set-description), [`duplicate`](#cai-workflow-duplicate), [`delete`](#cai-workflow-delete), [`versions`](#cai-workflow-versions), [`releases`](#cai-workflow-releases), [`history`](#cai-workflow-history), [`restore`](#cai-workflow-restore), [`save`](#cai-workflow-save), [`document`](#cai-workflow-document), [`state`](#cai-workflow-state), [`outline`](#cai-workflow-outline), [`status`](#cai-workflow-status), [`validate`](#cai-workflow-validate), [`publish`](#cai-workflow-publish) | | `cai file` | [`share`](#cai-file-share) | | `cai flow` | [`list`](#cai-flow-list), [`get`](#cai-flow-get), [`create`](#cai-flow-create), [`rename`](#cai-flow-rename), [`delete`](#cai-flow-delete), [`outputs`](#cai-flow-outputs), [`duplicate`](#cai-flow-duplicate), [`layout`](#cai-flow-layout), [`reorder`](#cai-flow-reorder), [`output`](#cai-flow-output), [`for-each`](#cai-flow-for-each), [`input`](#cai-flow-input) | | `cai flow output` | [`add`](#cai-flow-output-add), [`update`](#cai-flow-output-update), [`delete`](#cai-flow-output-delete) | | `cai flow input` | [`add`](#cai-flow-input-add), [`update`](#cai-flow-input-update), [`delete`](#cai-flow-input-delete) | | `cai integration` | [`search`](#cai-integration-search), [`actions`](#cai-integration-actions), [`action`](#cai-integration-action) | | `cai node` | [`add`](#cai-node-add), [`duplicate`](#cai-node-duplicate), [`set-flow`](#cai-node-set-flow), [`get`](#cai-node-get), [`declare-output`](#cai-node-declare-output), [`props`](#cai-node-props), [`reload`](#cai-node-reload), [`status`](#cai-node-status), [`set`](#cai-node-set), [`set-connection`](#cai-node-set-connection), [`connect`](#cai-node-connect), [`disconnect`](#cai-node-disconnect), [`only-when`](#cai-node-only-when), [`optional-props`](#cai-node-optional-props), [`enable-prop`](#cai-node-enable-prop), [`disable-prop`](#cai-node-disable-prop), [`options`](#cai-node-options), [`continue-on-error`](#cai-node-continue-on-error), [`rename`](#cai-node-rename), [`delete`](#cai-node-delete) | | `cai expr` | [`context`](#cai-expr-context), [`validate`](#cai-expr-validate), [`set`](#cai-expr-set), [`ops`](#cai-expr-ops), [`decompile`](#cai-expr-decompile) | | `cai run` | [`node`](#cai-run-node), [`flow`](#cai-run-flow), [`inputs`](#cai-run-inputs), [`discover`](#cai-run-discover) | | `cai exec` | [`list`](#cai-exec-list), [`get`](#cai-exec-get), [`flow`](#cai-exec-flow), [`node`](#cai-exec-node), [`tree`](#cai-exec-tree) | | `cai connection` | [`list`](#cai-connection-list), [`update`](#cai-connection-update), [`delete`](#cai-connection-delete), [`request`](#cai-connection-request), [`connect`](#cai-connection-connect) | | `cai branch` | [`list`](#cai-branch-list), [`add`](#cai-branch-add), [`update`](#cai-branch-update), [`delete`](#cai-branch-delete), [`connect`](#cai-branch-connect), [`reorder`](#cai-branch-reorder) | | `cai data` | [`collections`](#cai-data-collections), [`fields`](#cai-data-fields), [`query`](#cai-data-query), [`get`](#cai-data-get), [`create`](#cai-data-create), [`update`](#cai-data-update), [`delete`](#cai-data-delete), [`delete-many`](#cai-data-delete-many), [`import`](#cai-data-import), [`copy-to-live`](#cai-data-copy-to-live), [`collection`](#cai-data-collection) | | `cai data collection` | [`create`](#cai-data-collection-create) | | `cai schema` | [`list`](#cai-schema-list), [`get`](#cai-schema-get), [`resolve`](#cai-schema-resolve), [`create`](#cai-schema-create), [`update`](#cai-schema-update), [`delete`](#cai-schema-delete) | | `cai trigger` | [`list`](#cai-trigger-list), [`audit`](#cai-trigger-audit), [`get`](#cai-trigger-get), [`test-events`](#cai-trigger-test-events), [`search`](#cai-trigger-search), [`props`](#cai-trigger-props), [`options`](#cai-trigger-options), [`create`](#cai-trigger-create), [`events`](#cai-trigger-events), [`event`](#cai-trigger-event), [`select-event`](#cai-trigger-select-event), [`replay`](#cai-trigger-replay), [`set-enabled`](#cai-trigger-set-enabled), [`rename`](#cai-trigger-rename), [`delete`](#cai-trigger-delete) | | `cai template-setup` | [`status`](#cai-template-setup-status), [`complete`](#cai-template-setup-complete) | | `cai label` | [`list`](#cai-label-list), [`set`](#cai-label-set) | ## Check catalog provenance Generated for CLI **0.2.24** from the frozen Commander snapshot rooted at `buildProgram()`. Generator checking compares this page with the frozen snapshot; it does not verify sibling repositories for newer code. The catalog contains **164 supported operations** and **25 command groups**, counting the root `cai` group. `cai signup` is both an operation and a group. `cai run workflow` is excluded: its handler always fails with `NOT_IMPLEMENTED`; use `cai run flow` with a chosen flow. CLI source: all 26 command files plus shared command, argument, configuration and result code. Help comparison: `marketing/docs/scripts/cli-help-0.2.24.txt`. The export omits 14 third-level help sections; the captured Commander definitions supply them. MCP counterparts come from the **149-tool** typed registry, its operation dispositions and the generated command map. Catalog version: `ac0cbaace014`. The **MCP disposition** column distinguishes direct tools, split tools, merged commands, hosted replacements and commands omitted from MCP. Local commands run on the assistant’s machine; build-chat presentation requires an in-product chat for its card. ### cai auth Authenticate this machine with Controller AI. Subcommands: [`login`](#cai-auth-login), [`password`](#cai-auth-password), [`token`](#cai-auth-token), [`key`](#cai-auth-key), [`logout`](#cai-auth-logout), [`status`](#cai-auth-status). ### cai auth login Open a browser and authorize a revocable Controller AI CLI credential. ```sh cai auth login [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | Local CLI | — | Omitted from MCP. Starts a local device-code login even though the MCP request is already OAuth-authorized. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--no-open` | No | — | headless/remote mode: print the URL without opening a browser | | `--timeout ` | No | — | maximum time to wait for browser approval | The wait defaults to the device authorization expiry returned by the server. A supplied --timeout is capped at that expiry. ### cai auth password Development fallback: exchange explicit email/password flags for a JWT. ```sh cai auth password [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | Local CLI | — | Omitted from MCP. Accepts a development email/password credential on the local machine. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--email ` | Yes | — | account email | | `--password ` | Yes | — | account password | ### cai auth token Persist a credential you already hold (cai_, caib_, JWT, or sk- API key). ```sh cai auth token [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | Local CLI | — | Omitted from MCP. Writes a bearer token into local CLI configuration. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--token ` | Yes | — | bearer credential | ### cai auth key Migration/development only: mint a legacy API key using a browser JWT. ```sh cai auth key [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | Local CLI | — | Omitted from MCP. Mints a long-lived local credential and is not an MCP account operation. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--name ` | No | `"cai"` | label for the key | ### cai auth logout Remove the locally stored credential. ```sh cai auth logout [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | Local CLI | — | Omitted from MCP. Deletes local CLI credentials; it is not integration connection revocation. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--revoke` | No | `false` | revoke the current CLI credential before removing it locally | ### cai auth status Show the current account, backend, credential kind, and workflow. ```sh cai auth status [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | Local CLI | [`account_status`](/reference/mcp-tools/#account_status) | Hosted replacement. The host reports the authenticated grant and combines it with server health facts. | ### cai approval Resume polling a durable browser-approved operation. Subcommands: [`resume`](#cai-approval-resume). ### cai approval resume Resume an existing approval by ID without dispatching its gated command again. ```sh cai approval resume [options] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | CLI | [`approval_resume`](/reference/mcp-tools/#approval_resume) | Direct. Typed counterpart; use its input schema. | | Argument | Required | Meaning | | --- | --- | --- | | `` | Yes | approval intent ID printed by the interrupted command | ### cai signup Create a Controller AI workspace without a browser account. ```sh cai signup [options] [command] ``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | Local CLI | — | Omitted from MCP. The OAuth-authorized caller already has a provisioned account; root signup is local bootstrap. | | Option | Required | Explicit default | Meaning | | --- | --- | --- | --- | | `--name ` | No | — | display name for the agent-created account | | `--force` | No | `false` | replace an existing valid credential after signup succeeds | ### cai signup email Send a verification code to the account owner. ```sh cai signup email [options]

``` | CLI surface | MCP counterpart | MCP disposition | | --- | --- | --- | | Local CLI | [`account_claim_start`](/reference/mcp-tools/#account_claim_start) | Hosted replacement. Uses the OAuth grant durable email-claim adapter instead of local CLI credential replacement. | | Argument | Required | Meaning | | --- | --- | --- | | `

` | Yes | Owner’s email address to claim the current agent account. | ### cai signup verify Verify the account owner email with its 6-digit code. ```sh cai signup verify [options]


```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| Local CLI | [`account_claim_verify`](/reference/mcp-tools/#account_claim_verify) | Hosted replacement. Uses the OAuth grant durable email verification adapter. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `` | Yes | Verification code sent to that email by cai signup email. |



### cai connect



Install skills, authorize this machine, and verify the complete setup.

```sh
cai connect [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| Local CLI | — | Omitted from MCP. Installs local skills, opens a browser, and verifies a local project. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--target ` | No | `"auto"` | auto, agents, codex, claude, cursor, copilot, all, or project |
| `--project-dir ` | No | — | project root for the open-standard project target |
| `--force` | No | `false` | replace existing unmanaged Controller AI skill folders |
| `--no-open` | No | — | headless/remote mode: print the URL without opening a browser |
| `--timeout ` | No | — | maximum time to wait for browser approval |

Its browser-authorization wait defaults to the device authorization expiry returned by the server.  A supplied --timeout is capped at that expiry.



### cai skills



Install and update Controller AI guidance for your agent.

Subcommands: [`install`](#cai-skills-install), [`update`](#cai-skills-update), [`status`](#cai-skills-status).



### cai skills install



Install the verified skill set bundled with this CLI.

```sh
cai skills install [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| Local CLI | — | Omitted from MCP. Writes guidance into a caller local project, which the hosted server cannot access. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--target ` | No | `"auto"` | auto, agents, codex, claude, cursor, copilot, all, or project |
| `--project-dir ` | No | — | project root for the open-standard project target |
| `--force` | No | `false` | replace an existing unmanaged skill with the same name |



### cai skills update



Fetch, verify, and install the latest hosted Controller AI skill set.

```sh
cai skills update [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| Local CLI | — | Omitted from MCP. Updates guidance files in a caller local project. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--target ` | No | `"auto"` | auto, agents, codex, claude, cursor, copilot, all, or project |
| `--project-dir ` | No | — | project root for the open-standard project target |
| `--force` | No | `false` | replace an existing unmanaged skill with the same name |



### cai skills status



Verify installed Controller AI skills, versions, and digests.

```sh
cai skills status [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| Local CLI | [`guide_get`](/reference/mcp-tools/#guide_get)
[`guide_list`](/reference/mcp-tools/#guide_list) | Hosted replacement. guide_list and guide_get serve the bundled server guidance without inspecting a local project. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--target ` | No | `"all"` | auto, agents, codex, claude, cursor, copilot, all, or project |
| `--project-dir ` | No | — | project root for the open-standard project target |



### cai docs



Read Controller AI documentation as Markdown in the terminal.

```sh
cai docs [options] [path]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| Local CLI | — | Omitted from MCP. Fetches documentation into a local terminal; hosted clients read guide_get or the docs site. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `[path]` | No | documentation path, for example for-ai-agents/codex |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--list` | No | `false` | print the top-level documentation index from llms.txt |

With no path, fetches for-ai-agents.  --list fetches llms.txt; a supplied page path is fetched as Markdown.



### cai upgrade



Show the CLI upgrade command and update skills for detected assistants.

```sh
cai upgrade [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| Local CLI | — | Omitted from MCP. Prints the local CLI upgrade command and updates local skills; nothing to do on a hosted server. |



### cai config



Inspect and reset CLI configuration.

Subcommands: [`reset`](#cai-config-reset).



### cai config reset



Clear workflow pins while preserving credentials and other settings.

```sh
cai config reset [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| Local CLI | — | Omitted from MCP. Clears a local workflow pin; typed MCP calls are stateless. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--local` | No | — | clear only the exact-cwd .cai.json workflow pin |
| `--global` | No | — | clear only the workflow pin in the configured config file |



### cai doctor



Verify authentication, API access, workflow pin, runtime, and installed skills.

```sh
cai doctor [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| Local CLI | [`account_status`](/reference/mcp-tools/#account_status) | Hosted replacement. Local runtime checks do not apply; useful account and version facts are in account_status. |



### cai agent



Build and test mutable agent drafts, then publish immutable live versions.

Subcommands: [`setup`](#cai-agent-setup), [`list`](#cai-agent-list), [`get`](#cai-agent-get), [`create`](#cai-agent-create), [`update`](#cai-agent-update), [`delete`](#cai-agent-delete), [`visibility`](#cai-agent-visibility), [`add-workflow`](#cai-agent-add-workflow), [`add-action`](#cai-agent-add-action), [`update-tool`](#cai-agent-update-tool), [`remove-tool`](#cai-agent-remove-tool), [`files`](#cai-agent-files), [`add-file`](#cai-agent-add-file), [`tools`](#cai-agent-tools), [`publish-preflight`](#cai-agent-publish-preflight), [`publish`](#cai-agent-publish), [`present`](#cai-agent-present), [`versions`](#cai-agent-versions), [`conversation`](#cai-agent-conversation), [`test`](#cai-agent-test).



### cai agent setup



Set up Controller AI end to end for installed coding assistants.

```sh
cai agent setup [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| Local CLI | — | Omitted from MCP. Configures local coding assistants on the user machine; nothing to do on a hosted server. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--client ` | No | `"all"` | claude-code, codex, cursor, or all |
| `--status` | No | `false` | show installed state and the action plan without changing anything |
| `--yes` | No | `false` | approve setup actions without prompting |
| `--skills-scope ` | No | `"global"` | global or project |



### cai agent list



List agents visible to the current account.

```sh
cai agent list [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`agent_list`](/reference/mcp-tools/#agent_list) | Direct. Typed counterpart; use its input schema. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--search ` | No | — | filter by name |
| `--ownership ` | No | `"mine"` | ownership filter |



### cai agent get



Inspect the agent configuration visible to this account and its version status.

```sh
cai agent get [options] 
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`agent_get`](/reference/mcp-tools/#agent_get) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `` | Yes | Agent ID from cai agent list. |



### cai agent create



Create a private draft agent; nothing becomes live until publish.

```sh
cai agent create [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`agent_create`](/reference/mcp-tools/#agent_create) | Direct. Typed counterpart; use its input schema. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--name ` | Yes | — | agent display name |
| `--instructions ` | No | — | agent instructions |
| `--instructions-file ` | No | — | read agent instructions from a UTF-8 file |
| `--disabled` | No | `false` | create the draft disabled |



### cai agent update



Update draft configuration or agent runtime state (in separate commands).

```sh
cai agent update [options] 
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`agent_set_enabled`](/reference/mcp-tools/#agent_set_enabled)
[`agent_update`](/reference/mcp-tools/#agent_update) | Split. Choose the tool for the intended operation. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `` | Yes | Agent ID from cai agent list. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--name ` | No | — | new display name |
| `--instructions ` | No | — | new agent instructions |
| `--instructions-file ` | No | — | read instructions from a UTF-8 file |
| `--disabled` | No | — | disable the agent and pause its runtime immediately |
| `--enabled` | No | — | enable the agent immediately |



### cai agent delete



Soft-delete an agent, revoke live access, and attempt to stop active sessions.

```sh
cai agent delete [options] 
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`agent_delete`](/reference/mcp-tools/#agent_delete) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `` | Yes | Agent ID from cai agent list. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--confirm` | No | `false` | confirm soft deletion, live-access revocation, and best-effort active-session termination |



### cai agent visibility



Change live agent access (organization requires publishing the agent first; no public mode).

```sh
cai agent visibility [options] 
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`agent_visibility_set`](/reference/mcp-tools/#agent_visibility_set) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `` | Yes | Agent ID from cai agent list. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--value ` | Yes | — | private revokes organization access; organization shares the published version |



### cai agent add-workflow



Add a follow-live workflow tool with a backend-generated name to the draft.

```sh
cai agent add-workflow [options] 
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`agent_tool_workflow_add`](/reference/mcp-tools/#agent_tool_workflow_add) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `` | Yes | Agent ID from cai agent list. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--workflow-id ` | Yes | — | workflow containing the tool flow |
| `--flow ` | Yes | — | flow exposed to the agent |
| `--description ` | No | — | description the model uses when choosing the tool |
| `--require-confirmation` | No | `false` | pause every invocation for an explicit user approval before the workflow runs |
| `--slack-connection ` | No | — | your active Slack connection; requires --slack-channel and --require-confirmation |
| `--slack-channel ` | No | — | approval channel; requires --slack-connection |
| `--slack-channel-name ` | No | — | optional approval channel display name |
| `--slack-approver ` | No | — | who can approve in Slack; repeat for 1–8 users; requires --slack-channel; without it anyone in the channel can approve |



### cai agent add-action



Attach one ready integration action to the draft; explicitly review its confirmation policy.

```sh
cai agent add-action [options] 
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`agent_tool_action_add`](/reference/mcp-tools/#agent_tool_action_add) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `` | Yes | Agent ID from cai agent list. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--integration ` | Yes | — | exact slug from `cai integration search` |
| `--action ` | Yes | — | exact action key from `cai integration actions` |
| `--connection ` | No | — | active connection when this integration requires auth |
| `--description ` | No | — | when the agent should choose this action |
| `--require-confirmation` | No | `false` | require approval before each run; default is no approval, so decide for writes or spend |
| `--slack-connection ` | No | — | your active Slack connection; requires --slack-channel and --require-confirmation |
| `--slack-channel ` | No | — | approval channel; requires --slack-connection |
| `--slack-channel-name ` | No | — | optional approval channel display name |
| `--slack-approver ` | No | — | who can approve in Slack; repeat for 1–8 users; requires --slack-channel; without it anyone in the channel can approve |



### cai agent update-tool



Update a draft tool; action connection grants apply immediately without publishing.

```sh
cai agent update-tool [options] 
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`agent_tool_update`](/reference/mcp-tools/#agent_tool_update) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `` | Yes | Agent ID from cai agent list. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--tool ` | Yes | — | draft tool id |
| `--description ` | No | — | new routing description |
| `--connection ` | No | — | rebind a ready integration action to another connection |
| `--require-confirmation` | No | — | require approval before every invocation |
| `--no-confirmation` | No | — | run without approval; use only after reviewing writes, messages, deletion, and spend |
| `--slack-connection ` | No | — | your active Slack connection; requires --slack-channel and an approval-requiring tool |
| `--slack-channel ` | No | — | approval channel; requires --slack-connection |
| `--slack-channel-name ` | No | — | optional approval channel display name |
| `--slack-approver ` | No | — | who can approve in Slack; repeat for 1–8 users; requires --slack-channel; without it anyone in the channel can approve |
| `--no-slack` | No | — | remove Slack approval routing from the draft tool |



### cai agent remove-tool



Remove a draft tool; direct-action detachment revokes live authorization immediately.

```sh
cai agent remove-tool [options] 
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`agent_tool_remove`](/reference/mcp-tools/#agent_tool_remove) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `` | Yes | Agent ID from cai agent list. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--tool ` | Yes | — | draft tool id |



### cai agent files



List reference and runtime files.  Non-managers receive the published view regardless of the requested view.

```sh
cai agent files [options] 
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`agent_file_list`](/reference/mcp-tools/#agent_file_list) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `` | Yes | Agent ID from cai agent list. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--space ` | No | — | knowledge = agent reference material (draft, publishes); shared = runtime workspace files seen live; runtime is an alias for shared |
| `--environment ` | No | — | shared runtime environment; not valid for knowledge |
| `--live` | No | — | request published-live instead of owner-current; non-managers receive published-live regardless |
| `--search ` | No | — | filter by file name or path |
| `--folder-prefix ` | No | — | filter to a folder path and its descendants |
| `--cursor ` | No | — | opaque cursor from the previous page; repeat identical filters |
| `--limit ` | No | `"50"` | files per page (default 50, max 200) |



### cai agent add-file



Add a reference file to the draft or a runtime file to the shared workspace.

```sh
cai agent add-file [options] 
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`agent_knowledge_file_add`](/reference/mcp-tools/#agent_knowledge_file_add)
[`agent_workspace_file_add`](/reference/mcp-tools/#agent_workspace_file_add) | Split. Choose the tool for the intended operation. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `` | Yes | Agent ID from cai agent list. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--file ` | Yes | — | local file to add |
| `--name ` | No | — | name visible to the agent |
| `--type ` | No | — | txt, md, json, csv, html, or xml |
| `--space ` | No | `"knowledge"` | knowledge: reference material in the draft; shared: runtime workspace files; runtime is an alias for shared. |

Knowledge files update the draft and require publication for Live.  Shared/runtime files are available without publication and apply when enabled or on the next turn.  Every successful add creates another file; read the returned file identity or list files before retrying.



### cai agent tools



List draft tools for an owner or published tools for a shared user.

```sh
cai agent tools [options] 
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`agent_tool_list`](/reference/mcp-tools/#agent_tool_list) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `` | Yes | Agent ID from cai agent list. |



### cai agent publish-preflight



Check the agent draft and every attached tool before publishing.

```sh
cai agent publish-preflight [options] 
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`agent_publish_preflight`](/reference/mcp-tools/#agent_publish_preflight) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `` | Yes | Agent ID from cai agent list. |



### cai agent publish



Snapshot the draft and move every existing live conversation to the new version.

```sh
cai agent publish [options] 
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`agent_publish`](/reference/mcp-tools/#agent_publish) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `` | Yes | Agent ID from cai agent list. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--name ` | No | — | optional release name |

The new immutable snapshot replaces the version used by existing Live conversations.  Publication stops in-flight Live sessions and expires unexecuted approvals; resolve them first.  There is no rollback: fix the draft and publish again.



### cai agent present



Return an agent summary and app link, and request a card when a build chat is available.

```sh
cai agent present [options] 
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI with build-chat presentation | [`agent_present`](/reference/mcp-tools/#agent_present) | Hosted replacement. Returns a hosted agent summary and app link for the MCP host to present. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `` | Yes | Agent ID from cai agent list. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--description ` | No | — | one-line user-facing summary shown on the card |
| `--updated` | No | `false` | this re-presents an agent changed by a follow-up request |

A build chat is needed for the card.  Check presentedInChat and cardDeliveryFailed; appUrl is still returned when it can be resolved.



### cai agent versions



List immutable published versions.

```sh
cai agent versions [options] 
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`agent_version_list`](/reference/mcp-tools/#agent_version_list) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `` | Yes | Agent ID from cai agent list. |



### cai agent conversation



Verify owner-only Test/draft or latest-published Live agent conversations.

Subcommands: [`list`](#cai-agent-conversation-list), [`create`](#cai-agent-conversation-create), [`status`](#cai-agent-conversation-status), [`history`](#cai-agent-conversation-history), [`approve`](#cai-agent-conversation-approve), [`deny`](#cai-agent-conversation-deny), [`send`](#cai-agent-conversation-send).



### cai agent conversation list



List verification conversations for an agent.

```sh
cai agent conversation list [options] 
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`agent_conversation_list`](/reference/mcp-tools/#agent_conversation_list) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `` | Yes | Agent ID from cai agent list. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--mode ` | No | — | Filter to Test (draft) or Live conversations. |



### cai agent conversation create



Create a Live conversation by default; pass --draft for an owner-only Test conversation.

```sh
cai agent conversation create [options] 
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`agent_conversation_create`](/reference/mcp-tools/#agent_conversation_create) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `` | Yes | Agent ID from cai agent list. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--draft` | No | — | owner-only Test: current agent draft and workflow development heads |
| `--live` | No | — | Live: latest published agent and workflow releases (default) |
| `--title ` | No | — | conversation title |
| `--model <model>` | No | — | runtime model override |

--draft and --live are mutually exclusive.  With neither flag, the new conversation uses Live.

<a id="cai-agent-conversation-status"></a>

### cai agent conversation status



Read the conversation mode, adopted version, model and status.

```sh
cai agent conversation status [options] <conversationId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`agent_conversation_status`](/reference/mcp-tools/#agent_conversation_status) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<conversationId>` | Yes | Conversation ID from cai agent conversation list or create. |

<a id="cai-agent-conversation-history"></a>

### cai agent conversation history



Read persisted messages, events, and pending permission requests.

```sh
cai agent conversation history [options] <conversationId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`agent_conversation_history`](/reference/mcp-tools/#agent_conversation_history) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<conversationId>` | Yes | Conversation ID from cai agent conversation list or create. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--last` | No | — | aggregates the assistant turn: status, text, tool-call summary, cost |

<a id="cai-agent-conversation-approve"></a>

### cai agent conversation approve



Approve one pending tool request and resume the active conversation.

```sh
cai agent conversation approve [options] <conversationId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`agent_conversation_approve`](/reference/mcp-tools/#agent_conversation_approve) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<conversationId>` | Yes | Conversation ID from cai agent conversation list or create. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--request <requestId>` | Yes | — | exact requestId from conversation history |
| `--tool <toolName>` | No | — | normally unnecessary; server knows the tool; if needed, pass exact mcp__controllerai__tool_<id> name |

<a id="cai-agent-conversation-deny"></a>

### cai agent conversation deny



Deny one pending tool request and resume the active conversation.

```sh
cai agent conversation deny [options] <conversationId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`agent_conversation_deny`](/reference/mcp-tools/#agent_conversation_deny) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<conversationId>` | Yes | Conversation ID from cai agent conversation list or create. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--request <requestId>` | Yes | — | exact requestId from conversation history |
| `--tool <toolName>` | No | — | normally unnecessary; server knows the tool; if needed, pass exact mcp__controllerai__tool_<id> name |
| `--message <reason>` | No | — | reason returned to the agent |

<a id="cai-agent-conversation-send"></a>

### cai agent conversation send



Send a message, optionally waiting for a verifiable persisted reply.

```sh
cai agent conversation send [options] <conversationId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`agent_conversation_send`](/reference/mcp-tools/#agent_conversation_send) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<conversationId>` | Yes | Conversation ID from cai agent conversation list or create. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--message <text>` | Yes | — | message to send |
| `--wait` | No | `false` | wait for the next completed persisted assistant reply |
| `--timeout <seconds>` | No | `"300"` | Reply wait in seconds, greater than 0 and at most 600; checked only with --wait. |

<a id="cai-agent-test"></a>

### cai agent test



Create a Test conversation by default, send a message and verify its persisted reply; pass --live for the published version.

```sh
cai agent test [options] <agentId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`agent_test`](/reference/mcp-tools/#agent_test) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<agentId>` | Yes | Agent ID from cai agent list. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--message <text>` | Yes | — | verification prompt |
| `--draft` | No | — | owner-only Test: current agent draft and workflow development heads (default) |
| `--live` | No | — | Live: latest published agent and workflow releases |
| `--title <title>` | No | `"CLI verification"` | conversation title |
| `--model <model>` | No | — | runtime model override |
| `--timeout <seconds>` | No | `"300"` | Reply wait in seconds, greater than 0 and at most 600. |

--draft and --live are mutually exclusive.  Each invocation creates a persisted conversation and executes real tools with usage charges; inspect that conversation before retrying.

<a id="cai-use"></a>

### cai use



Pin a default workflow so --workflow can be omitted.

```sh
cai use [options] <workflowId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| Local CLI | — | Omitted from MCP. Persists a local workflow pin; every typed workflow call carries an explicit id. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<workflowId>` | Yes | workflow id to pin as the default |

<a id="cai-workflow"></a>

### cai workflow



Create, inspect, test and publish workflows.

Subcommands: [`list`](#cai-workflow-list), [`create`](#cai-workflow-create), [`get`](#cai-workflow-get), [`rename`](#cai-workflow-rename), [`set-description`](#cai-workflow-set-description), [`duplicate`](#cai-workflow-duplicate), [`delete`](#cai-workflow-delete), [`versions`](#cai-workflow-versions), [`releases`](#cai-workflow-releases), [`history`](#cai-workflow-history), [`restore`](#cai-workflow-restore), [`save`](#cai-workflow-save), [`document`](#cai-workflow-document), [`state`](#cai-workflow-state), [`outline`](#cai-workflow-outline), [`status`](#cai-workflow-status), [`validate`](#cai-workflow-validate), [`publish`](#cai-workflow-publish).

<a id="cai-workflow-list"></a>

### cai workflow list



List workflows visible to this account.

```sh
cai workflow list [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`workflow_list`](/reference/mcp-tools/#workflow_list) | Direct. Typed counterpart; use its input schema. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--limit <n>` | No | `"25"` | max rows |

<a id="cai-workflow-create"></a>

### cai workflow create



Create and select a named workflow.

```sh
cai workflow create [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`workflow_create`](/reference/mcp-tools/#workflow_create) | Direct. Typed counterpart; use its input schema. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--name <name>` | Yes | — | workflow name |

<a id="cai-workflow-get"></a>

### cai workflow get



Fetch one workflow.

```sh
cai workflow get [options] [workflowId]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`workflow_get`](/reference/mcp-tools/#workflow_get) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `[workflowId]` | No | workflow id (defaults to the pinned one) |

<a id="cai-workflow-rename"></a>

### cai workflow rename



Rename a workflow (PATCH /workflow/:id).

```sh
cai workflow rename [options] [workflowId]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`workflow_rename`](/reference/mcp-tools/#workflow_rename) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `[workflowId]` | No | workflow id (defaults to the pinned one) |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--name <name>` | Yes | — | new workflow name |

<a id="cai-workflow-set-description"></a>

### cai workflow set-description



Set a workflow’s description.

```sh
cai workflow set-description [options] [workflowId]
```


Aliases: `describe`.

| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`workflow_description_set`](/reference/mcp-tools/#workflow_description_set) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `[workflowId]` | No | workflow id (defaults to the pinned one) |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--description <text>` | Yes | — | new description ("" clears it) |

<a id="cai-workflow-duplicate"></a>

### cai workflow duplicate



Copy the workflow definition into a new unpublished workflow.  Records are not copied, and flow and node IDs are preserved.

```sh
cai workflow duplicate [options] [workflowId]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`workflow_duplicate`](/reference/mcp-tools/#workflow_duplicate) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `[workflowId]` | No | workflow id (defaults to the pinned one) |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--use` | No | `false` | pin the copy as the default workflow |

Select the returned copy ID before editing: flow and node IDs are only unique within a workflow, so stale workflow context edits the original.  --use selects the copy as the configured default.

<a id="cai-workflow-delete"></a>

### cai workflow delete



Delete a workflow after detaching dependent draft and Live agent tools.

```sh
cai workflow delete [options] <workflowId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`workflow_delete`](/reference/mcp-tools/#workflow_delete) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<workflowId>` | Yes | workflow id — required explicitly, never the pinned default |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--yes` | Yes | — | confirm soft deletion and deployed-trigger teardown |
| `--force` | No | `false` | deprecated compatibility flag; ignored because agent dependents must be detached first |

The deprecated --force flag is ignored.  Both draft and Live agent dependencies block deletion.  The soft delete commits before external trigger teardown: a teardown error can mean the workflow is already deleted and cleanup remains.  There is no public undelete.

<a id="cai-workflow-versions"></a>

### cai workflow versions



Read the development and live versions of a workflow.

```sh
cai workflow versions [options] [workflowId]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`workflow_version_list`](/reference/mcp-tools/#workflow_version_list) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `[workflowId]` | No | workflow id (defaults to the pinned one) |

<a id="cai-workflow-releases"></a>

### cai workflow releases



Published release checkpoints.

```sh
cai workflow releases [options] [workflowId]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`workflow_release_list`](/reference/mcp-tools/#workflow_release_list) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `[workflowId]` | No | workflow id (defaults to the pinned one) |

<a id="cai-workflow-history"></a>

### cai workflow history



Version-state history — the ids `cai workflow restore` takes.

```sh
cai workflow history [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`workflow_history`](/reference/mcp-tools/#workflow_history) | Direct. Typed counterpart; use its input schema. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--version <workflowVersionId>` | No | — | defaults to the current development version |
| `--group <groupId>` | No | — | expand one group into its individual states |

<a id="cai-workflow-restore"></a>

### cai workflow restore



Restore an earlier saved definition into the development version.

```sh
cai workflow restore [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`workflow_state_restore`](/reference/mcp-tools/#workflow_state_restore) | Direct. Typed counterpart; use its input schema. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--state <workflowVersionStateId>` | Yes | — | state id from `cai workflow history` |
| `--version <workflowVersionId>` | No | — | defaults to the current development version |

Use --state with a saved state ID, not a history-group ID or positional argument.  Restore creates a new development head and retains newer history.  A listed state can be outside the plan’s restore window.  Live, records and external effects remain unchanged; enabled Live triggers keep using the current release until publication.

<a id="cai-workflow-save"></a>

### cai workflow save



Save a NAMED development snapshot you can restore to later.

```sh
cai workflow save [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`workflow_state_save`](/reference/mcp-tools/#workflow_state_save) | Direct. Typed counterpart; use its input schema. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--name <name>` | Yes | — | label for this checkpoint |

<a id="cai-workflow-document"></a>

### cai workflow document



Complete JSON document for the development head or one historical state.

```sh
cai workflow document [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`workflow_document_get`](/reference/mcp-tools/#workflow_document_get) | Direct. Typed counterpart; use its input schema. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--state <workflowVersionStateId>` | No | — | read a historical state from `cai workflow history` instead of the head |

<a id="cai-workflow-state"></a>

### cai workflow state



Bounded development-state metadata and per-flow summaries.

```sh
cai workflow state [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`workflow_state_get`](/reference/mcp-tools/#workflow_state_get) | Direct. Typed counterpart; use its input schema. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--state <workflowVersionStateId>` | No | — | read a historical state from `cai workflow history` instead of the head |
| `--flow <flowId>` | No | — | include node and edge detail for one exact flow id |

<a id="cai-workflow-outline"></a>

### cai workflow outline



Compact orientation map: flows, inputs/outputs, nodes with deps, triggers, data types.

```sh
cai workflow outline [options] [workflowId]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`workflow_outline`](/reference/mcp-tools/#workflow_outline) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `[workflowId]` | No | workflow id (defaults to the pinned one) |

<a id="cai-workflow-status"></a>

### cai workflow status



Publish state: is development ahead of live, do triggers fire.

```sh
cai workflow status [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`workflow_status`](/reference/mcp-tools/#workflow_status) | Direct. Typed counterpart; use its input schema. |

<a id="cai-workflow-validate"></a>

### cai workflow validate



Deep-validate the development workflow: required props, connections, wiring, expressions, types, subflows, branches, triggers.

```sh
cai workflow validate [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`workflow_validate`](/reference/mcp-tools/#workflow_validate) | Direct. Typed counterpart; use its input schema. |

Invalid validation exits 1 while the JSON result still has ok: true and data.valid: false.  Read the validation fields as well as the exit code.

<a id="cai-workflow-publish"></a>

### cai workflow publish



Publish the development version as a live release.

```sh
cai workflow publish [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`workflow_publish`](/reference/mcp-tools/#workflow_publish) | Direct. Typed counterpart; use its input schema. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--name <name>` | No | — | release name |
| `--acknowledge-dual-dispatch` | No | — | publish even though armed test events can run one real event in both development and live |
| `--acknowledge-validation-errors` | No | — | Publish despite validation errors — only after the user explicitly approved the listed issues. |

Publication copies the development definition and schemas, activates enabled Live triggers, and refreshes following Live agent conversations.  Development records are never copied; agent workflow tools follow the new release without an agent republish.  Inspect warnings for interface changes or failed conversation refreshes.  Validation-error and dual-dispatch acknowledgements are separate flags.

<a id="cai-file"></a>

### cai file



Hand files back to the user inside the build chat.

Subcommands: [`share`](#cai-file-share).

<a id="cai-file-share"></a>

### cai file share



Share one file with the user as a downloadable card in this build chat.  Use it to deliver reports, exports, or other artifacts you produced.

```sh
cai file share [options] <path>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| Hosted-only CLI | [`file_share`](/reference/mcp-tools/#file_share) | Hosted replacement. Stores inline bytes as a private artifact and returns its browser-openable link. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<path>` | Yes | Regular local file path to share with the build chat. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--name <displayName>` | No | — | name shown on the file card (defaults to the file name) |

Hosted-only CLI operation: requires a builder-session credential.  It accepts a regular local file up to 25 × 1024 × 1024 bytes.  Check sharedInChat to confirm delivery.

<a id="cai-flow"></a>

### cai flow



Flows — a workflow has many canvases.

Subcommands: [`list`](#cai-flow-list), [`get`](#cai-flow-get), [`create`](#cai-flow-create), [`rename`](#cai-flow-rename), [`delete`](#cai-flow-delete), [`outputs`](#cai-flow-outputs), [`duplicate`](#cai-flow-duplicate), [`layout`](#cai-flow-layout), [`reorder`](#cai-flow-reorder), [`output`](#cai-flow-output), [`for-each`](#cai-flow-for-each), [`input`](#cai-flow-input).

<a id="cai-flow-list"></a>

### cai flow list



List the flows on this workflow.

```sh
cai flow list [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`flow_list`](/reference/mcp-tools/#flow_list) | Direct. Typed counterpart; use its input schema. |

<a id="cai-flow-get"></a>

### cai flow get



Nodes, edges and inputs of one flow.

```sh
cai flow get [options] <flowId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`flow_get`](/reference/mcp-tools/#flow_get) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<flowId>` | Yes | Flow ID from cai flow list in the selected workflow. |

<a id="cai-flow-create"></a>

### cai flow create



Create a new flow canvas.

```sh
cai flow create [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`flow_create`](/reference/mcp-tools/#flow_create) | Direct. Typed counterpart; use its input schema. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--name <name>` | Yes | — | Name for the new flow, such as Check invoice. |

<a id="cai-flow-rename"></a>

### cai flow rename



Rename a flow.

```sh
cai flow rename [options] <flowId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`flow_rename`](/reference/mcp-tools/#flow_rename) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<flowId>` | Yes | Flow ID from cai flow list in the selected workflow. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--name <name>` | Yes | — | Replacement flow name. |

<a id="cai-flow-delete"></a>

### cai flow delete



Delete a flow.

```sh
cai flow delete [options] <flowId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`flow_delete`](/reference/mcp-tools/#flow_delete) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<flowId>` | Yes | Flow ID from cai flow list in the selected workflow. |

<a id="cai-flow-outputs"></a>

### cai flow outputs



Declared outputs of a flow.

```sh
cai flow outputs [options] <flowId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`flow_output_list`](/reference/mcp-tools/#flow_output_list) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<flowId>` | Yes | Flow ID from cai flow list in the selected workflow. |

<a id="cai-flow-duplicate"></a>

### cai flow duplicate



Copy a flow with fresh ids for every node and edge.

```sh
cai flow duplicate [options] <flowId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`flow_duplicate`](/reference/mcp-tools/#flow_duplicate) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<flowId>` | Yes | Flow ID from cai flow list in the selected workflow. |

<a id="cai-flow-layout"></a>

### cai flow layout



Deterministically tidy positions after headless builds; an open builder auto-tidies while you build.

```sh
cai flow layout [options] <flowId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`flow_layout`](/reference/mcp-tools/#flow_layout) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<flowId>` | Yes | Flow ID from cai flow list in the selected workflow. |

<a id="cai-flow-reorder"></a>

### cai flow reorder



Reorder the workflow’s flows (presentation order, not execution order).

```sh
cai flow reorder [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`flow_reorder`](/reference/mcp-tools/#flow_reorder) | Direct. Typed counterpart; use its input schema. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--order <flowIds>` | Yes | — | every flow id, comma-separated, in the new order |

<a id="cai-flow-output"></a>

### cai flow output



Flow outputs — declare these BEFORE adding a Return response node.

Subcommands: [`add`](#cai-flow-output-add), [`update`](#cai-flow-output-update), [`delete`](#cai-flow-output-delete).

<a id="cai-flow-output-add"></a>

### cai flow output add



Declare an output a flow returns.

```sh
cai flow output add [options] <flowId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`flow_output_add`](/reference/mcp-tools/#flow_output_add) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<flowId>` | Yes | Flow ID from cai flow list in the selected workflow. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--display <name>` | Yes | — | human-readable output label |
| `--type <ctype>` | Yes | — | e.g. text / number / list.text / custom.invoice |
| `--name <name>` | No | — | internal snake_case name (generated from --display when omitted) |
| `--description <text>` | No | — | Description of the returned value. |

<a id="cai-flow-output-update"></a>

### cai flow output update



Update a flow output (Return response props are kept in sync).

```sh
cai flow output update [options] <flowId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`flow_output_update`](/reference/mcp-tools/#flow_output_update) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<flowId>` | Yes | Flow ID from cai flow list in the selected workflow. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--output <id>` | Yes | — | flow output id |
| `--name <name>` | No | — | internal snake_case payload key callers read; a --display rename regenerates it unless --name is set |
| `--display <name>` | No | — | human label |
| `--type <ctype>` | No | — | Replacement output data type, such as text or number. |
| `--description <text>` | No | — | Replacement description of the returned value. |

Supply at least one of --name, --display, --type or --description.  An empty --description clears this output description.

<a id="cai-flow-output-delete"></a>

### cai flow output delete



Remove a flow output (its Return response prop goes too).

```sh
cai flow output delete [options] <flowId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`flow_output_delete`](/reference/mcp-tools/#flow_output_delete) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<flowId>` | Yes | Flow ID from cai flow list in the selected workflow. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--output <id>` | Yes | — | Output ID from cai flow outputs for this flow. |

<a id="cai-flow-for-each"></a>

### cai flow for-each



Build the for-each pattern; the core scaffold is atomic and maxItems is verified afterward.

```sh
cai flow for-each [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`flow_for_each_scaffold`](/reference/mcp-tools/#flow_for_each_scaffold) | Direct. Typed counterpart; use its input schema. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--flow <flowId>` | Yes | — | parent flow holding the list-producing node |
| `--from <nodeId>` | No | — | node whose output carries the list; optional with --list-js |
| `--source-output <outputId>` | No | — | exact opaque outputs[].id from `cai node get <nodeId> --json`; never a label |
| `--name <bodyFlowName>` | Yes | — | name for the new per-item flow |
| `--item-type <type>` | Yes | — | one item: a primitive (text\|number\|date\|boolean), an existing/new custom.* type, or a dataRecord.custom.* record |
| `--item-field <id:type[:display]>` | No | — | field of a NEW custom item type; repeatable. Omit to reuse an existing custom type |
| `--list-js <expr>` | No | — | JS selecting the list from the wired input |
| `--js-file <path\|->` | No | — | read the list-selection JS from a UTF-8 file or stdin |
| `--list-field <path>` | No | — | nested list field under the source output; builds the exact inputs.<binding>.data path |
| `--max-items <n>` | No | — | runtime list cap, 1..10000 (default when omitted: 500) |
| `--item-name <displayName>` | No | — | display name of the item flow input |
| `--continue-on-error` | No | `false` | keep looping when one iteration fails |

<a id="cai-flow-input"></a>

### cai flow input



Flow inputs.

Subcommands: [`add`](#cai-flow-input-add), [`update`](#cai-flow-input-update), [`delete`](#cai-flow-input-delete).

<a id="cai-flow-input-add"></a>

### cai flow input add



Add a flow input.

```sh
cai flow input add [options] <flowId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`flow_input_add`](/reference/mcp-tools/#flow_input_add) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<flowId>` | Yes | Flow ID from cai flow list in the selected workflow. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--name <displayName>` | No | — | legacy alias for --display; the server derives compiler-current jsBinding |
| `--type <ctype>` | Yes | — | data type, e.g. text / number / custom.invoice |
| `--display <name>` | No | — | human label used to derive compiler-current jsBinding; legacyBinding is diagnostic |
| `--list` | No | `false` | the input is a list of --type |
| `--optional` | No | `false` | input is optional |
| `--description <text>` | No | — | Description of the value the caller supplies. |

<a id="cai-flow-input-update"></a>

### cai flow input update



Update a flow input.

```sh
cai flow input update [options] <flowId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`flow_input_update`](/reference/mcp-tools/#flow_input_update) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<flowId>` | Yes | Flow ID from cai flow list in the selected workflow. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--input <id>` | Yes | — | flow input id |
| `--name <displayName>` | No | — | legacy alias for --display; display changes recompute compiler-current jsBinding |
| `--display <name>` | No | — | new human label; recomputes jsBinding while legacyBinding stays diagnostic |
| `--type <ctype>` | No | — | Replacement input data type, such as text or number. |
| `--description <text>` | No | — | Set a non-empty description. An empty string is treated as absent and cannot clear it. |
| `--optional` | No | — | the input can be omitted by callers |
| `--required` | No | — | the input must be supplied by callers |
| `--default-value <literal>` | No | — | stored default metadata (JSON when it parses, else a string); an omitted optional input still resolves to null at run time |

Supply at least one non-empty --display (or its --name alias), --type, --description, --optional/--required, or --default-value.  --optional and --required are mutually exclusive.  An empty description is ignored, so it cannot clear the field.  Renaming the display changes the current expression binding; read the flow again afterward.

<a id="cai-flow-input-delete"></a>

### cai flow input delete



Delete a flow input.

```sh
cai flow input delete [options] <flowId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`flow_input_delete`](/reference/mcp-tools/#flow_input_delete) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<flowId>` | Yes | Flow ID from cai flow list in the selected workflow. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--input <id>` | Yes | — | Input ID from cai flow get for this flow. |

<a id="cai-integration"></a>

### cai integration



Discover integrations and the actions they publish.

Subcommands: [`search`](#cai-integration-search), [`actions`](#cai-integration-actions), [`action`](#cai-integration-action).

<a id="cai-integration-search"></a>

### cai integration search



Search provider integrations and native registry nodes in one ranked list.

```sh
cai integration search [options] <query>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`integration_search`](/reference/mcp-tools/#integration_search) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<query>` | Yes | integration, native node, or capability to find |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--actions` | No | — | only integrations that publish actions |
| `--events` | No | — | only integrations that publish trigger events |
| `--agent-attachable` | No | — | only integrations with actions attachable to agents |
| `--limit <n>` | No | `"20"` | maximum ranked integrations to return |

<a id="cai-integration-actions"></a>

### cai integration actions



List one integration’s actions or search exact action pairs across the catalog.

```sh
cai integration actions [options] [query]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`integration_action_list`](/reference/mcp-tools/#integration_action_list) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `[query]` | No | action intent to rank across one or all integrations |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--integration <slug>` | No | — | restrict results to one exact integration slug |
| `--agent-attachable` | No | — | only actions attachable directly to agents |
| `--limit <n>` | No | `"50"` | maximum ranked actions to return |

<a id="cai-integration-action"></a>

### cai integration action



Read the full static prop schema of one action before adding or attaching it.

```sh
cai integration action [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`integration_action_get`](/reference/mcp-tools/#integration_action_get) | Direct. Typed counterpart; use its input schema. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--integration <slug>` | Yes | — | exact integration slug |
| `--key <key>` | Yes | — | exact action key paired with that integration |

<a id="cai-node"></a>

### cai node



Placed workflow nodes — add, configure, wire.

Subcommands: [`add`](#cai-node-add), [`duplicate`](#cai-node-duplicate), [`set-flow`](#cai-node-set-flow), [`get`](#cai-node-get), [`declare-output`](#cai-node-declare-output), [`props`](#cai-node-props), [`reload`](#cai-node-reload), [`status`](#cai-node-status), [`set`](#cai-node-set), [`set-connection`](#cai-node-set-connection), [`connect`](#cai-node-connect), [`disconnect`](#cai-node-disconnect), [`only-when`](#cai-node-only-when), [`optional-props`](#cai-node-optional-props), [`enable-prop`](#cai-node-enable-prop), [`disable-prop`](#cai-node-disable-prop), [`options`](#cai-node-options), [`continue-on-error`](#cai-node-continue-on-error), [`rename`](#cai-node-rename), [`delete`](#cai-node-delete).

<a id="cai-node-add"></a>

### cai node add



Initialize a discovered integration action with its connection, wiring, optional props, and values.

```sh
cai node add [options]
```


Aliases: `init`.

| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`node_add`](/reference/mcp-tools/#node_add) | Direct. Typed counterpart; use its input schema. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--flow <flowId>` | Yes | — | Destination flow ID from cai flow list. |
| `--key <componentKey>` | Yes | — | exact action key from `cai integration actions` |
| `--node <slug>` | No | — | exact integration slug paired with --key (inferred when omitted) |
| `--name <displayName>` | No | — | display name; also the outgoing connection label |
| `--after <nodeId>` | No | — | wire this upstream node into the new node at creation |
| `--output <main\|error>` | No | `"main"` | which system output --after connects from |
| `--connection <id>` | No | — | bind an existing connection |
| `--props <jsonOrFile>` | No | — | initial prop map; direct values become {value:...}, advanced per-prop writes pass through |
| `--enable-prop <names...>` | No | — | optional prop names to materialize at creation |

<a id="cai-node-duplicate"></a>

### cai node duplicate



Copy a node into the same flow (offset position, no incoming edges).

```sh
cai node duplicate [options] <nodeId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`node_duplicate`](/reference/mcp-tools/#node_duplicate) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. |

<a id="cai-node-set-flow"></a>

### cai node set-flow



Point a subflow node at a flow; its input props are generated from that flow.

```sh
cai node set-flow [options] <nodeId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`node_subflow_set`](/reference/mcp-tools/#node_subflow_set) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<nodeId>` | Yes | a Run flow / Run flow on list node |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--flow <flowId>` | Yes | — | target flow to call |

<a id="cai-node-get"></a>

### cai node get



Full node record: component, inputs, outputs, connection.

```sh
cai node get [options] <nodeId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`node_get`](/reference/mcp-tools/#node_get) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. |

<a id="cai-node-declare-output"></a>

### cai node declare-output



Declare an unverified dynamic output contract from documented response data.

```sh
cai node declare-output [options] <nodeId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`node_output_type_declare`](/reference/mcp-tools/#node_output_type_declare) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--sample-file <file\|->` | Yes | — | documented provider response data: a JSON object or a non-empty JSON array of items; `-` reads stdin |

<a id="cai-node-props"></a>

### cai node props



Visible + catalog props with current values and decompiled valueJs.

```sh
cai node props [options] <nodeId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`node_prop_list`](/reference/mcp-tools/#node_prop_list) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. |

<a id="cai-node-reload"></a>

### cai node reload



Reload and reconcile dependent props, then report the readiness change.

```sh
cai node reload [options] <nodeId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`node_prop_reload`](/reference/mcp-tools/#node_prop_reload) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. |

<a id="cai-node-status"></a>

### cai node status



Return deterministic configuration readiness and exact blockers.

```sh
cai node status [options] <nodeId>
```


Aliases: `output`.

| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`node_status`](/reference/mcp-tools/#node_status) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. |

<a id="cai-node-set"></a>

### cai node set



Set a prop, selecting and verifying the correct storage shape automatically.

```sh
cai node set [options] <nodeId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`node_prop_set`](/reference/mcp-tools/#node_prop_set) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--prop <name>` | Yes | — | prop key from `cai node props` |
| `--value <literal>` | No | — | static value (JSON string literals are decoded; other JSON is parsed for non-text props and preserved for text props) |
| `--js <src>` | No | — | expression DSL source, compiled server-side before writing |
| `--js-file <path\|->` | No | — | read expression DSL source from a UTF-8 file or stdin |
| `--raw-expression-json <path\|->` | No | — | raw expression object as JSON from a UTF-8 file or stdin, written verbatim — the escape hatch for advanced constraints, injected chips, and loop traversals the DSL cannot author |
| `--label <labels...>` | No | — | live option label(s), one per value; used to search providers that do not index opaque ids |
| `--expression` | No | `false` | deprecated compatibility flag; storage is selected automatically |

Choose exactly one of --value, --js, --js-file or --raw-expression-json.  The deprecated --expression flag does not select how the value is stored.

<a id="cai-node-set-connection"></a>

### cai node set-connection



Bind a connection to an action node.

```sh
cai node set-connection [options] <nodeId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`node_connection_set`](/reference/mcp-tools/#node_connection_set) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--connection <id>` | Yes | — | connection id from `cai connection list` |

<a id="cai-node-connect"></a>

### cai node connect



Wire two nodes; the source output becomes an input on the target.

```sh
cai node connect [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`node_connect`](/reference/mcp-tools/#node_connect) | Direct. Typed counterpart; use its input schema. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--from <nodeId>` | Yes | — | upstream node |
| `--to <nodeId>` | Yes | — | downstream node |
| `--flow <flowId>` | Yes | — | flow containing both nodes |
| `--output <main\|error>` | No | `"main"` | which system output to wire from |

<a id="cai-node-disconnect"></a>

### cai node disconnect



Remove an edge.

```sh
cai node disconnect [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`node_disconnect`](/reference/mcp-tools/#node_disconnect) | Direct. Typed counterpart; use its input schema. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--edge <edgeId>` | Yes | — | Edge ID from cai flow get for the connected canvas. |

<a id="cai-node-only-when"></a>

### cai node only-when



Set or clear a node’s conditional-execution rule.

```sh
cai node only-when [options] <nodeId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`node_only_when_set`](/reference/mcp-tools/#node_only_when_set) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--js <expr>` | No | — | boolean expression; the node runs only when it is true |
| `--js-file <path\|->` | No | — | read the boolean expression from a UTF-8 file or stdin |
| `--groups-json <json>` | No | — | condition string[][]: expressions in each row are AND-ed; rows are OR-ed |
| `--clear` | No | `false` | remove all conditions |

Choose --js/--js-file, --groups-json or --clear; these forms are mutually exclusive.  In --groups-json, each row combines its expressions with AND, and rows combine with OR.

<a id="cai-node-optional-props"></a>

### cai node optional-props



List togglable optional props.

```sh
cai node optional-props [options] <nodeId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`node_optional_prop_list`](/reference/mcp-tools/#node_optional_prop_list) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. |

<a id="cai-node-enable-prop"></a>

### cai node enable-prop



Enable an optional prop so it becomes settable.

```sh
cai node enable-prop [options] <nodeId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`node_optional_prop_set`](/reference/mcp-tools/#node_optional_prop_set) | Merged. The explicit enabled boolean replaces the separate enabling command. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--prop <name>` | Yes | — | Optional property name from cai node optional-props. |

<a id="cai-node-disable-prop"></a>

### cai node disable-prop



Disable an optional prop and remove its stored value.  Reload-dependent fields are recalculated when the prop controls them.

```sh
cai node disable-prop [options] <nodeId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`node_optional_prop_set`](/reference/mcp-tools/#node_optional_prop_set) | Merged. The explicit enabled boolean replaces the separate disabling command. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--prop <name>` | Yes | — | enabled optional prop key from `cai node props` |

<a id="cai-node-options"></a>

### cai node options



Resolved remote dropdown options for a prop.

```sh
cai node options [options] <nodeId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`node_prop_options`](/reference/mcp-tools/#node_prop_options) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--prop <name>` | Yes | — | Property name from cai node props whose choices you want. |
| `--query <q>` | No | — | search term — strongly preferred over paging |
| `--page <n>` | No | — | 0-based page when not searching |
| `--prev-context <json>` | No | — | pagination context returned by a previous options response |
| `--for <prop>=<value>` | No | — | override an earlier prop value for option resolution; JSON literals are accepted, bare text is passed as a string; repeatable |

<a id="cai-node-continue-on-error"></a>

### cai node continue-on-error



Set continue-on-error to an explicit enabled or disabled state.

```sh
cai node continue-on-error [options] <nodeId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`node_continue_on_error_set`](/reference/mcp-tools/#node_continue_on_error_set) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--enable` | No | — | Enable continue-on-error. |
| `--disable` | No | — | Disable continue-on-error. |

Pass exactly one of --enable or --disable.  Disabling removes edges from the Error output.

<a id="cai-node-rename"></a>

### cai node rename



Rename a node (also renames its outgoing connection label).

```sh
cai node rename [options] <nodeId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`node_rename`](/reference/mcp-tools/#node_rename) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--name <displayName>` | Yes | — | Replacement node display name. |

<a id="cai-node-delete"></a>

### cai node delete



Delete a node.

```sh
cai node delete [options] <nodeId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`node_delete`](/reference/mcp-tools/#node_delete) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. |

<a id="cai-expr"></a>

### cai expr



The expression surface.

Subcommands: [`context`](#cai-expr-context), [`validate`](#cai-expr-validate), [`set`](#cai-expr-set), [`ops`](#cai-expr-ops), [`decompile`](#cai-expr-decompile).

<a id="cai-expr-context"></a>

### cai expr context



MANDATORY before writing any --js.  Lists every in-scope binding.

```sh
cai expr context [options] <nodeId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`expr_context`](/reference/mcp-tools/#expr_context) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--prop <name>` | No | — | the destination prop — adds its expected type and mode |
| `--methods` | No | `false` | include the full method catalog (large) |

<a id="cai-expr-validate"></a>

### cai expr validate



Compile an expression against the node’s real scope.  Side-effect free.

```sh
cai expr validate [options] <nodeId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`expr_validate`](/reference/mcp-tools/#expr_validate) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--js <src>` | No | — | expression DSL source |
| `--js-file <path\|->` | No | — | read expression DSL source from a UTF-8 file or stdin |
| `--prop <name>` | No | — | destination prop — validates against its real type and mode |
| `--mode <text\|expression\|onlyWhen>` | No | — | compile target when --prop is unknown |

<a id="cai-expr-set"></a>

### cai expr set



Context-check, compile, persist to the correct channel, and verify readback.

```sh
cai expr set [options] <nodeId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`node_prop_set`](/reference/mcp-tools/#node_prop_set) | Merged. node_prop_set exposes the same expression write alongside literal and raw-expression forms. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--prop <name>` | Yes | — | destination prop |
| `--js <src>` | No | — | expression DSL source |
| `--js-file <path\|->` | No | — | read expression DSL source from a UTF-8 file or stdin |
| `--force` | No | `false` | overwrite a stored expression the JS DSL cannot fully express, losing those constructs |

<a id="cai-expr-ops"></a>

### cai expr ops



The method catalog: which operations exist per data type.

```sh
cai expr ops [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`expr_operation_list`](/reference/mcp-tools/#expr_operation_list) | Direct. Typed counterpart; use its input schema. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--type <ctype>` | No | — | restrict to one data type; results are cataloged by base type (for example list.custom.video_calendar -> list) |

<a id="cai-expr-decompile"></a>

### cai expr decompile



Read a stored expression as JavaScript-like source.

```sh
cai expr decompile [options] <nodeId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`expr_decompile`](/reference/mcp-tools/#expr_decompile) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--prop <name>` | Yes | — | Property name from cai node props whose expression you want to read. |

<a id="cai-run"></a>

### cai run



Run nodes and flows.  Integration actions execute against their connected accounts.

Subcommands: [`node`](#cai-run-node), [`flow`](#cai-run-flow), [`inputs`](#cai-run-inputs), [`discover`](#cai-run-discover).

<a id="cai-run-node"></a>

### cai run node



Run one node in isolation on the development version and return its resolvedConfigs.

```sh
cai run node [options] <nodeId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`run_node`](/reference/mcp-tools/#run_node) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<nodeId>` | Yes | Node ID from cai flow get in the selected workflow. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--inputs <json\|file\|->` | No | — | inline JSON or a JSON file; `-` reads stdin |
| `--timeout <ms>` | No | `"120000"` | how long to wait for the run to finish |

This executes real integration actions against connected accounts and spends usage.  An isolated run does not execute upstream nodes.  Only completed is success; pause, another terminal status or timeout exits nonzero with error.detail.workflowExecutionId and lastSnapshot.  Inspect that existing execution instead of dispatching another run.

<a id="cai-run-flow"></a>

### cai run flow



Run one flow end-to-end on the development or published live version.

```sh
cai run flow [options] <flowId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`run_flow`](/reference/mcp-tools/#run_flow) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<flowId>` | Yes | Flow ID from cai flow list in the selected workflow. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--inputs <json\|file\|->` | No | — | inline JSON or a JSON file; `-` reads stdin |
| `--target <dev\|live>` | No | `"dev"` | Development version or published live release. |
| `--confirm-live` | No | `false` | acknowledge LIVE run side effects and usage |
| `--timeout <ms>` | No | `"300000"` | how long to wait for the run to finish |

--target live requires --confirm-live.  Both targets execute real integration actions and spend usage when the flow contains them.  Only completed is success; paused, completed_with_error, failed, cancelled or timeout exits nonzero with error.detail.workflowExecutionId and lastSnapshot.  Inspect that execution instead of redispatching; a polling timeout does not stop it.

<a id="cai-run-inputs"></a>

### cai run inputs



Show inputs for a node, or pass --flow to inspect a flow before run flow.

```sh
cai run inputs [options] <nodeIdOrFlowId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`run_inputs`](/reference/mcp-tools/#run_inputs) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<nodeIdOrFlowId>` | Yes | Node ID from cai flow get, or flow ID from cai flow list when using --flow. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--flow` | No | `false` | treat the argument as a flow id |

<a id="cai-run-discover"></a>

### cai run discover



Probe a component output with a temporary node.  Connected actions can have real effects.

```sh
cai run discover [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`run_discover`](/reference/mcp-tools/#run_discover) | Direct. Typed counterpart; use its input schema. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--node <slug>` | Yes | — | integration node slug |
| `--key <componentKey>` | Yes | — | exact action key from `cai integration actions` |
| `--connection <id\|none>` | Yes | — | connection id, or "none" for a component that needs no auth |
| `--props <json\|file\|->` | No | — | prop values, same per-prop shape as `node add` |
| `--enable <prop>` | No | — | optional prop to enable first; repeatable |
| `--keep` | No | `false` | keep the scratch node instead of deleting it |
| `--timeout <ms>` | No | — | poll budget, backend caps at 55000 |

<a id="cai-exec"></a>

### cai exec



Read execution history.

Subcommands: [`list`](#cai-exec-list), [`get`](#cai-exec-get), [`flow`](#cai-exec-flow), [`node`](#cai-exec-node), [`tree`](#cai-exec-tree).

<a id="cai-exec-list"></a>

### cai exec list



Recent workflow executions.

```sh
cai exec list [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`execution_list`](/reference/mcp-tools/#execution_list) | Direct. Typed counterpart; use its input schema. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--limit <n>` | No | `"10"` | max rows |

<a id="cai-exec-get"></a>

### cai exec get



One workflow execution with its flat node executions.

```sh
cai exec get [options] <workflowExecutionId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`execution_get`](/reference/mcp-tools/#execution_get) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<workflowExecutionId>` | Yes | Workflow execution ID from cai run node, cai run flow or cai exec list. |

Returns at most the 200 newest node executions, with nodeExecutionsTruncated when more exist.  Use cai exec tree to page through the nodes.

<a id="cai-exec-flow"></a>

### cai exec flow



Node-by-node detail of one flow execution (includes resolvedConfigs).

```sh
cai exec flow [options] <flowExecutionId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`execution_flow_get`](/reference/mcp-tools/#execution_flow_get) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<flowExecutionId>` | Yes | Flow execution ID from cai exec tree. |

<a id="cai-exec-node"></a>

### cai exec node



One node execution: status, output, and resolvedConfigs.

```sh
cai exec node [options] <nodeExecutionId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`execution_node_get`](/reference/mcp-tools/#execution_node_get) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<nodeExecutionId>` | Yes | Node execution ID from cai exec tree or cai exec get. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--full` | No | `false` | print the untruncated output blob |

<a id="cai-exec-tree"></a>

### cai exec tree



Paginated node-by-node status rows across a workflow execution.

```sh
cai exec tree [options] <workflowExecutionId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`execution_tree`](/reference/mcp-tools/#execution_tree) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<workflowExecutionId>` | Yes | Workflow execution ID from cai run node, cai run flow or cai exec list. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--limit <n>` | No | — | maximum rows to return (1-200; default 50) |
| `--cursor <opaque>` | No | — | continue from a returned execution-tree cursor |
| `--status <status...>` | No | — | filter by one or more statuses: pending, running, completed, completed_with_error, failed, skipped, cancelled |
| `--flow <flowId>` | No | — | filter by one exact workflow flow id |

If any node-detail read fails, the command exits nonzero and returns successfully read rows in error.detail.partialData.  A cursor belongs to one execution and cannot be reused with a different limit or filters.

<a id="cai-connection"></a>

### cai connection



Existing user connections.

Subcommands: [`list`](#cai-connection-list), [`update`](#cai-connection-update), [`delete`](#cai-connection-delete), [`request`](#cai-connection-request), [`connect`](#cai-connection-connect).

<a id="cai-connection-list"></a>

### cai connection list



List account connections without requiring workflow context.

```sh
cai connection list [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`connection_list`](/reference/mcp-tools/#connection_list) | Direct. Typed counterpart; use its input schema. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--integration <slug>` | No | — | only connections for this integration |
| `--node <slug>` | No | — | legacy alias for --integration |

<a id="cai-connection-update"></a>

### cai connection update



Rename a connection or change whether it is the integration default.

```sh
cai connection update [options] <connectionId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`connection_update`](/reference/mcp-tools/#connection_update) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<connectionId>` | Yes | connection id from `cai connection list` |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--name <displayName>` | No | — | new display name |
| `--default` | No | — | make this the default connection for its integration |
| `--no-default` | No | — | clear this connection’s default flag |

Supply at least one of --name, --default or --no-default.  --default and --no-default are mutually exclusive.  Changing the default does not rebind existing nodes or agent tools.

<a id="cai-connection-delete"></a>

### cai connection delete



Delete a connection; nodes and agent tools bound to this connection lose their authorization immediately.

```sh
cai connection delete [options] <connectionId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`connection_delete`](/reference/mcp-tools/#connection_delete) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<connectionId>` | Yes | connection id from `cai connection list` |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--yes` | Yes | — | confirm deletion and immediate authorization loss |

<a id="cai-connection-request"></a>

### cai connection request



Ask the user to connect an integration: places a connect card in the build chat and returns immediately.

```sh
cai connection request [options] <nodeSlug>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI with build-chat presentation | — | Omitted from MCP. Posts a connect card into build chat; connection_connect_url supplies the hosted outcome. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<nodeSlug>` | Yes | integration slug that needs a connected account |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--for-node <nodeId>` | No | — | workflow node that needs this connection (context only) |
| `--reason <text>` | No | — | one short user-facing sentence shown on the card |

A build chat is needed for a connect card.  When requestedInChat is false, use the returned connectUrl.

<a id="cai-connection-connect"></a>

### cai connection connect



Open the Controller AI browser flow for a missing integration, optionally waiting for completion.

```sh
cai connection connect [options] <nodeSlug>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`connection_connect_url`](/reference/mcp-tools/#connection_connect_url) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<nodeSlug>` | Yes | integration slug reported by `cai integration search` |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--no-open` | No | — | headless/remote mode: print the URL without opening a browser |
| `--wait` | No | `false` | wait for a newly created connection for this integration |
| `--timeout <seconds>` | No | `"300"` | maximum time to wait for the new connection |

<a id="cai-branch"></a>

### cai branch



Router routes and If/Else branches — create, condition, wire, order.

Subcommands: [`list`](#cai-branch-list), [`add`](#cai-branch-add), [`update`](#cai-branch-update), [`delete`](#cai-branch-delete), [`connect`](#cai-branch-connect), [`reorder`](#cai-branch-reorder).

<a id="cai-branch-list"></a>

### cai branch list



Routes/branches in evaluation order, with conditions and wired targets.

```sh
cai branch list [options] <nodeId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`branch_list`](/reference/mcp-tools/#branch_list) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<nodeId>` | Yes | Router or If/Else node id |

<a id="cai-branch-add"></a>

### cai branch add



Add a Router route or an If/Else condition branch (inserted before Else).

```sh
cai branch add [options] <nodeId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`branch_add`](/reference/mcp-tools/#branch_add) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<nodeId>` | Yes | Router or If/Else node id |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--name <displayName>` | No | — | route/branch label |
| `--js <expr>` | No | — | boolean condition, one expression |
| `--js-file <path\|->` | No | — | read one boolean condition from a UTF-8 file or stdin |
| `--condition-json <json>` | No | — | condition as string[][] — OR of AND-rows |
| `--allow-duplicate` | No | `false` | add even when a route/branch already carries --name |

<a id="cai-branch-update"></a>

### cai branch update



Rename a route/branch and/or replace its condition.

```sh
cai branch update [options] <nodeId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`branch_update`](/reference/mcp-tools/#branch_update) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<nodeId>` | Yes | Router or If/Else node id |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--route <id>` | No | — | route id (Router) or branch id (If/Else) |
| `--branch <id>` | No | — | alias for --route |
| `--name <displayName>` | No | — | new label |
| `--js <expr>` | No | — | new boolean condition, one expression |
| `--js-file <path\|->` | No | — | read one boolean condition from a UTF-8 file or stdin |
| `--condition-json <json>` | No | — | new condition as string[][] — OR of AND-rows |

<a id="cai-branch-delete"></a>

### cai branch delete



Delete a route/branch and its branch edge.

```sh
cai branch delete [options] <nodeId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`branch_delete`](/reference/mcp-tools/#branch_delete) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<nodeId>` | Yes | Router or If/Else node id |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--route <id>` | No | — | route id (Router) or branch id (If/Else) |
| `--branch <id>` | No | — | alias for --route |

<a id="cai-branch-connect"></a>

### cai branch connect



Connect a branch output to a target node.

```sh
cai branch connect [options] <nodeId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`branch_connect`](/reference/mcp-tools/#branch_connect) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<nodeId>` | Yes | Router or If/Else node id |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--route <id>` | No | — | route id (Router) or branch id (If/Else) |
| `--branch <id>` | No | — | alias for --route |
| `--to <nodeId>` | Yes | — | target node the branch runs |
| `--flow <flowId>` | No | — | flow containing both nodes (resolved when omitted) |

<a id="cai-branch-reorder"></a>

### cai branch reorder



Reorder If/Else condition branches — first match wins, so order is semantics.

```sh
cai branch reorder [options] <nodeId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`branch_reorder`](/reference/mcp-tools/#branch_reorder) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<nodeId>` | Yes | If/Else node id |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--order <ids>` | Yes | — | every condition branch id, comma-separated, in new order |

<a id="cai-data"></a>

### cai data



Workflow data store — collections and records (development and live stores are separate).

Subcommands: [`collections`](#cai-data-collections), [`fields`](#cai-data-fields), [`query`](#cai-data-query), [`get`](#cai-data-get), [`create`](#cai-data-create), [`update`](#cai-data-update), [`delete`](#cai-data-delete), [`delete-many`](#cai-data-delete-many), [`import`](#cai-data-import), [`copy-to-live`](#cai-data-copy-to-live), [`collection`](#cai-data-collection).

<a id="cai-data-collections"></a>

### cai data collections



Collections in one record store, with row counts.

```sh
cai data collections [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`data_collection_list`](/reference/mcp-tools/#data_collection_list) | Direct. Typed counterpart; use its input schema. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--env <dev\|live>` | No | `"dev"` | record store to read |

<a id="cai-data-fields"></a>

### cai data fields



Field id ⇄ display mapping — writes go by id, reads come back by display.

```sh
cai data fields [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`data_field_list`](/reference/mcp-tools/#data_field_list) | Direct. Typed counterpart; use its input schema. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--type <dataType>` | Yes | — | collection data type, e.g. custom.invoice |

<a id="cai-data-query"></a>

### cai data query



Records in one collection.

```sh
cai data query [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`data_record_query`](/reference/mcp-tools/#data_record_query) | Direct. Typed counterpart; use its input schema. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--type <dataType>` | Yes | — | collection data type, e.g. custom.invoice |
| `--env <dev\|live>` | No | `"dev"` | record store to read |
| `--query <text>` | No | — | plain-text search — NOT field-aware filtering |
| `--limit <n>` | No | — | page size (backend caps at 100) |
| `--offset <n>` | No | — | pagination offset |

<a id="cai-data-get"></a>

### cai data get



One record by id.

```sh
cai data get [options] <recordId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`data_record_get`](/reference/mcp-tools/#data_record_get) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<recordId>` | Yes | record id, e.g. rec_… |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--type <dataType>` | Yes | — | Custom data type name from cai data collections for the selected environment. |
| `--env <dev\|live>` | No | `"dev"` | record store to read |

<a id="cai-data-create"></a>

### cai data create



Create a record (validated against the collection schema).

```sh
cai data create [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`data_record_create`](/reference/mcp-tools/#data_record_create) | Direct. Typed counterpart; use its input schema. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--type <dataType>` | Yes | — | Custom data type name from cai data collections for the selected environment. |
| `--fields <json\|file\|->` | Yes | — | field values keyed by field id |
| `--env <dev\|live>` | No | `"dev"` | record store to write |

<a id="cai-data-update"></a>

### cai data update



Patch a record — omitted fields are left alone.

```sh
cai data update [options] <recordId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`data_record_update`](/reference/mcp-tools/#data_record_update) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<recordId>` | Yes | Record ID from cai data query for this data type and environment. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--type <dataType>` | Yes | — | Custom data type name from cai data collections for the selected environment. |
| `--fields <json\|file\|->` | Yes | — | fields to patch, keyed by field id |
| `--env <dev\|live>` | No | `"dev"` | record store to write |

<a id="cai-data-delete"></a>

### cai data delete



Soft-delete a record.

```sh
cai data delete [options] <recordId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`data_record_delete`](/reference/mcp-tools/#data_record_delete) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<recordId>` | Yes | Record ID from cai data query for this data type and environment. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--type <dataType>` | Yes | — | Custom data type name from cai data collections for the selected environment. |
| `--env <dev\|live>` | No | `"dev"` | record store to write |

<a id="cai-data-delete-many"></a>

### cai data delete-many



Bulk-delete records from the development or live store (soft delete; no undo).

```sh
cai data delete-many [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`data_record_delete_many`](/reference/mcp-tools/#data_record_delete_many) | Direct. Typed counterpart; use its input schema. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--type <dataType>` | Yes | — | Custom data type name from cai data collections for the selected environment. |
| `--records <id,id,…>` | No | — | record ids to delete |
| `--all` | No | `false` | delete every record in the collection |
| `--yes` | No | `false` | confirm deleting every record when used with --all |
| `--env <dev\|live>` | No | `"dev"` | record store to delete from; live changes affect the published workflow immediately |

Choose non-empty --records or --all, never both; --all also requires --yes.  There is no public record undo.

<a id="cai-data-import"></a>

### cai data import



Validate or import CSV records in the development or live store (commits append).

```sh
cai data import [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`data_record_import_commit`](/reference/mcp-tools/#data_record_import_commit)<br>[`data_record_import_validate`](/reference/mcp-tools/#data_record_import_validate) | Split. Choose the tool for the intended operation. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--type <dataType>` | Yes | — | Custom data type name from cai data collections for the selected environment. |
| `--file <path>` | Yes | — | CSV file to import |
| `--env <dev\|live>` | No | `"dev"` | record store to validate or write; live commits affect the published workflow immediately |
| `--mode <dryRun\|commit>` | No | `"dryRun"` | validate only, or actually write |

CSV headers use field display names.  --mode dryRun writes nothing.  Commit validates again, appends valid rows and skips invalid rows; rerunning appends the valid rows again.  Inspect imported and rejected counts, then query the same store before retrying.

<a id="cai-data-copy-to-live"></a>

### cai data copy-to-live



Upsert active development records into the matching published Live collection by record key.

```sh
cai data copy-to-live [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`data_copy_to_live`](/reference/mcp-tools/#data_copy_to_live) | Direct. Typed counterpart; use its input schema. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--type <dataType>` | Yes | — | collection to copy from development to live |

Requires a matching, current published schema.  Matching record keys are overwritten or revived, Live-only rows remain, and an empty development source changes nothing.  There is no dry run.

<a id="cai-data-collection"></a>

### cai data collection



Collection lifecycle (collections are synced from `custom.*` schemas).

Subcommands: [`create`](#cai-data-collection-create).

<a id="cai-data-collection-create"></a>

### cai data collection create



Create a collection by defining its schema; equivalent to cai schema create.

```sh
cai data collection create [options] <dataType>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`schema_type_create`](/reference/mcp-tools/#schema_type_create) | Merged. The collection command shares the schema-creation tool. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<dataType>` | Yes | collection data type — must start with "custom." |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--display <label>` | No | — | Human-readable name of the new data type. |
| `--field <id:type[:display]>` | No | — | field spec; repeatable |
| `--from-json <file\|->` | No | — | full {display, fields} definition |

Provide at least one --field or --from-json, following the same definition rules as cai schema create.

<a id="cai-deps"></a>

### cai deps



Dependency map: which agents and workflows depend on this workflow (or the whole account).

```sh
cai deps [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`dependency_map`](/reference/mcp-tools/#dependency_map) | Direct. Typed counterpart; use its input schema. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--account` | No | `false` | account-wide resource map instead of the current workflow |

<a id="cai-events"></a>

### cai events



Account activity feed, newest first: connections, workflow edits/publishes/runs, agents, org members.

```sh
cai events [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`event_list`](/reference/mcp-tools/#event_list) | Direct. Typed counterpart; use its input schema. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--type <types>` | No | `[]` | only these event types (comma-separated or repeated) |
| `--since <when>` | No | — | ISO timestamp or relative like 30m, 2h, 7d |
| `--cursor <cursor>` | No | — | opaque cursor from a previous page; returns strictly older events |
| `--for-workflow <id>` | No | — | only events about this workflow |
| `--limit <n>` | No | — | events per page (default 50, max 200) |

<a id="cai-schema"></a>

### cai schema



Per-workflow custom data types (`custom.*`) — the data store’s schemas.

Subcommands: [`list`](#cai-schema-list), [`get`](#cai-schema-get), [`resolve`](#cai-schema-resolve), [`create`](#cai-schema-create), [`update`](#cai-schema-update), [`delete`](#cai-schema-delete).

<a id="cai-schema-list"></a>

### cai schema list



Every data type defined in this workflow.

```sh
cai schema list [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`schema_type_list`](/reference/mcp-tools/#schema_type_list) | Direct. Typed counterpart; use its input schema. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--all` | No | `false` | include the engine-derived custom.__* integration schemas |

<a id="cai-schema-get"></a>

### cai schema get



One data type with its field ids, displays and types.

```sh
cai schema get [options] <name>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`schema_type_get`](/reference/mcp-tools/#schema_type_get) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<name>` | Yes | schema name, e.g. custom.invoice |

<a id="cai-schema-resolve"></a>

### cai schema resolve



Read a type name, fields and whether it is a list.

```sh
cai schema resolve [options] <typeId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`schema_type_resolve`](/reference/mcp-tools/#schema_type_resolve) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<typeId>` | Yes | e.g. text, custom.invoice, list.custom.invoice, node.<nodeId> |

<a id="cai-schema-create"></a>

### cai schema create



Create a custom data type (this is also what creates a data collection).

```sh
cai schema create [options] <name>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`schema_type_create`](/reference/mcp-tools/#schema_type_create) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<name>` | Yes | schema name — must start with "custom." |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--display <label>` | No | — | human label (defaults to the name without the prefix) |
| `--field <id:type[:display]>` | No | — | field spec; repeatable |
| `--from-json <file\|->` | No | — | full {display, fields} definition instead of --field |

Provide at least one --field or --from-json.  JSON must contain fields with id and type; an omitted field display defaults to its ID.  When both forms are supplied, --from-json supplies the definition.

<a id="cai-schema-update"></a>

### cai schema update



Update a data type definition.  --field or --from-json replaces the complete field list and removes omitted fields; a display-only update preserves fields.

```sh
cai schema update [options] <name>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`schema_type_update`](/reference/mcp-tools/#schema_type_update) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<name>` | Yes | schema name, e.g. custom.invoice |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--display <label>` | No | — | new human label |
| `--field <id:type[:display]>` | No | — | Repeat for each field. Replaces the complete field list. |
| `--from-json <file\|->` | No | — | full {display, fields} definition instead of --field |

Supply --display, at least one --field, or --from-json.  A field replacement removes omitted fields from the schema without converting stored values; a display-only edit preserves fields.

<a id="cai-schema-delete"></a>

### cai schema delete



Remove the development type and deactivate its collection without deleting stored rows.

```sh
cai schema delete [options] <name>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`schema_type_delete`](/reference/mcp-tools/#schema_type_delete) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<name>` | Yes | schema name, e.g. custom.invoice |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--yes` | Yes | — | confirm deleting the type and removing fields on other types that reference it |

Recreating the same type and field IDs reactivates stored values.  Fields removed from other types because they referenced this type are not restored automatically.

<a id="cai-trigger"></a>

### cai trigger



Inspect trigger sources, captured events and development or live dispatch.

Subcommands: [`list`](#cai-trigger-list), [`audit`](#cai-trigger-audit), [`get`](#cai-trigger-get), [`test-events`](#cai-trigger-test-events), [`search`](#cai-trigger-search), [`props`](#cai-trigger-props), [`options`](#cai-trigger-options), [`create`](#cai-trigger-create), [`events`](#cai-trigger-events), [`event`](#cai-trigger-event), [`select-event`](#cai-trigger-select-event), [`replay`](#cai-trigger-replay), [`set-enabled`](#cai-trigger-set-enabled), [`rename`](#cai-trigger-rename), [`delete`](#cai-trigger-delete).

<a id="cai-trigger-list"></a>

### cai trigger list



Trigger lifecycle rows: ids, development state, readiness and issues.

```sh
cai trigger list [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`trigger_list`](/reference/mcp-tools/#trigger_list) | Direct. Typed counterpart; use its input schema. |

<a id="cai-trigger-audit"></a>

### cai trigger audit



Pre-publish trigger coverage, development dispatch and double-run risk.

```sh
cai trigger audit [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`trigger_audit`](/reference/mcp-tools/#trigger_audit) | Direct. Typed counterpart; use its input schema. |

<a id="cai-trigger-get"></a>

### cai trigger get



Full lifecycle for one trigger: capture, deployment, verification and issues.

```sh
cai trigger get [options] <triggerId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`trigger_get`](/reference/mcp-tools/#trigger_get) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<triggerId>` | Yes | canvas trigger id from `cai trigger list` |

<a id="cai-trigger-test-events"></a>

### cai trigger test-events



Set ambient development test-event dispatch (routine tests should use replay).

```sh
cai trigger test-events [options] <triggerId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`trigger_test_events_set`](/reference/mcp-tools/#trigger_test_events_set) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<triggerId>` | Yes | canvas trigger id from `cai trigger list` |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--allow` | No | — | arm ambient real-event dispatch against the development canvas |
| `--disallow` | No | — | turn ambient development dispatch off |
| `--acknowledge-dual-run` | No | — | when arming, acknowledge that one real event can execute more than once |

Choose --allow or --disallow.  Enabling requires --acknowledge-dual-run because one event can start development and live executions.

<a id="cai-trigger-search"></a>

### cai trigger search



Nodes that can trigger a flow, and the --event keys each one publishes.

```sh
cai trigger search [options] [query]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`trigger_search`](/reference/mcp-tools/#trigger_search) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `[query]` | No | search term, plain English |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--node <slug>` | No | — | also return this node’s full event list |
| `--limit <n>` | No | `"20"` | max nodes |
| `--events-per-node <n>` | No | `"6"` | event rows listed per node (raise to see them all) |

<a id="cai-trigger-props"></a>

### cai trigger props



Configurable props for a trigger event; returns the dynamicPropsId to reuse.

```sh
cai trigger props [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`trigger_component_props`](/reference/mcp-tools/#trigger_component_props) | Direct. Typed counterpart; use its input schema. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--node <slug>` | Yes | — | trigger node slug |
| `--event <eventKey>` | Yes | — | event key from `cai trigger search` — never guess it |
| `--connection <id>` | No | — | connection id when the trigger needs auth |
| `--configured <json\|file\|->` | No | — | already-set prop values, for dependent dynamic props |
| `--dynamic-props-id <id>` | No | — | dynamicPropsId from a previous call, to reload |

<a id="cai-trigger-options"></a>

### cai trigger options



Resolve exact values for one trigger dropdown prop before trigger creation.

```sh
cai trigger options [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`trigger_prop_options`](/reference/mcp-tools/#trigger_prop_options) | Direct. Typed counterpart; use its input schema. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--node <slug>` | Yes | — | trigger node slug |
| `--event <eventKey>` | Yes | — | event key from `cai trigger search` |
| `--prop <name>` | Yes | — | option-backed prop name from `cai trigger props` |
| `--connection <id>` | No | — | connection id when the trigger needs auth |
| `--configured <json\|file\|->` | No | — | already-set trigger prop values |
| `--dynamic-props-id <id>` | No | — | dynamicPropsId from `cai trigger props` |
| `--query <text>` | No | — | search by human option label |
| `--page <n>` | No | — | 0-based option page when not searching |
| `--prev-context <json\|file\|->` | No | — | context returned by a previous options page |

<a id="cai-trigger-create"></a>

### cai trigger create



Create a trigger source and its canvas.

```sh
cai trigger create [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`trigger_create`](/reference/mcp-tools/#trigger_create) | Direct. Typed counterpart; use its input schema. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--flow <flowId>` | Yes | — | flow this trigger runs (a trigger targets exactly one) |
| `--node <slug>` | Yes | — | trigger node slug |
| `--event <eventKey>` | Yes | — | event key from `cai trigger search` — never guess it |
| `--source-basis <basis>` | Yes | — | one of explicit-in-request \| user-answer \| inferred-from-existing-workflow |
| `--connection <id>` | No | — | connection id when the trigger needs auth |
| `--props <json\|file\|->` | No | — | configured prop values |
| `--dynamic-props-id <id>` | No | — | dynamicPropsId from `cai trigger props` |

Creation deploys a real source and starts traffic capture immediately.  Captured events run the workflow after publication, during armed development dispatch, or through replay.

<a id="cai-trigger-events"></a>

### cai trigger events



Captured events for a trigger source — compact payload previews.

```sh
cai trigger events [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`trigger_event_list`](/reference/mcp-tools/#trigger_event_list) | Direct. Typed counterpart; use its input schema. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--trigger <backendTriggerId>` | Yes | — | the NUMERIC backendTriggerId, not the canvas id |
| `--limit <n>` | No | — | newest-first page size (default 5, max 50) |

<a id="cai-trigger-event"></a>

### cai trigger event



One captured event with its full payload.

```sh
cai trigger event [options] <eventId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`trigger_event_get`](/reference/mcp-tools/#trigger_event_get) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<eventId>` | Yes | captured event id from `cai trigger events` |

<a id="cai-trigger-select-event"></a>

### cai trigger select-event



Adopt a captured event as the trigger’s sample, defining its output schema.

```sh
cai trigger select-event [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`trigger_event_select`](/reference/mcp-tools/#trigger_event_select) | Direct. Typed counterpart; use its input schema. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--node <triggerNodeId>` | Yes | — | trigger node id from `cai trigger create` |
| `--event <eventId>` | Yes | — | captured event id |

<a id="cai-trigger-replay"></a>

### cai trigger replay



Replay a captured event or supplied payload.  The default target is development; actions have real effects.

```sh
cai trigger replay [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`trigger_replay`](/reference/mcp-tools/#trigger_replay) | Direct. Typed counterpart; use its input schema. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--trigger <backendTriggerId>` | Yes | — | the NUMERIC backendTriggerId |
| `--event <eventId>` | No | — | captured event to replay (exclusive with --payload) |
| `--payload <json\|file\|->` | No | — | custom raw payload (exclusive with --event) |
| `--target <dev\|live>` | No | `"dev"` | development pre-publish or LIVE post-publish verification |
| `--confirm-live` | No | `false` | acknowledge LIVE replay side effects and usage |

Choose exactly one of --event or --payload.  --target live requires --confirm-live.

<a id="cai-trigger-set-enabled"></a>

### cai trigger set-enabled



Set a trigger to an explicit enabled or disabled state.

```sh
cai trigger set-enabled [options] <triggerId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`trigger_set_enabled`](/reference/mcp-tools/#trigger_set_enabled) | Merged. The explicit enabled boolean combines the mutually exclusive enable and disable flags. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<triggerId>` | Yes | canvas trigger id |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--enable` | No | — | set the trigger enabled |
| `--disable` | No | — | set the trigger disabled |

Pass exactly one of --enable or --disable.  This changes development and armed development dispatch immediately; the published trigger keeps its prior state until workflow publication.

<a id="cai-trigger-rename"></a>

### cai trigger rename



Rename a trigger.

```sh
cai trigger rename [options] <triggerId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`trigger_rename`](/reference/mcp-tools/#trigger_rename) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<triggerId>` | Yes | canvas trigger id |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--name <name>` | Yes | — | Replacement trigger name. |

<a id="cai-trigger-delete"></a>

### cai trigger delete



Delete a trigger and its canvas.

```sh
cai trigger delete [options] <triggerId>
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`trigger_delete`](/reference/mcp-tools/#trigger_delete) | Direct. Typed counterpart; use its input schema. |

| Argument | Required | Meaning |
| --- | --- | --- |
| `<triggerId>` | Yes | canvas trigger id |

Deletes the development trigger and stops its armed development dispatch immediately.  The prior Live trigger continues until workflow publication.

<a id="cai-template-setup"></a>

### cai template-setup



Inspect and complete the assisted template setup bound to this build thread.

Subcommands: [`status`](#cai-template-setup-status), [`complete`](#cai-template-setup-complete).

<a id="cai-template-setup-status"></a>

### cai template-setup status



Read the assisted template setup state for this build thread.

```sh
cai template-setup status [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | — | Omitted from MCP. Assisted template setup runs inside the builder sandbox from its injected brief, not through the hosted MCP. |

<a id="cai-template-setup-complete"></a>

### cai template-setup complete



Verify every expected workflow release and tool binding, then complete setup.

```sh
cai template-setup complete [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | — | Omitted from MCP. Assisted template setup runs inside the builder sandbox from its injected brief, not through the hosted MCP. |

<a id="cai-label"></a>

### cai label



Workflow and agent labels; rename or delete account labels in the UI.

Subcommands: [`list`](#cai-label-list), [`set`](#cai-label-set).

<a id="cai-label-list"></a>

### cai label list



Every label you own.

```sh
cai label list [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`label_list`](/reference/mcp-tools/#label_list) | Direct. Typed counterpart; use its input schema. |

Account-wide label renaming and deletion are app operations.

<a id="cai-label-set"></a>

### cai label set



Set the exact labels on one workflow or one agent by name.

```sh
cai label set [options]
```


| CLI surface | MCP counterpart | MCP disposition |
| --- | --- | --- |
| CLI | [`label_set`](/reference/mcp-tools/#label_set) | Direct. Typed counterpart; use its input schema. |

| Option | Required | Explicit default | Meaning |
| --- | --- | --- | --- |
| `--agent <agentId>` | No | — | agent id to label |
| `--labels <name,...>` | No | — | comma-separated label names |
| `--label <name>` | No | — | one label name; repeat for more than one |
| `--none` | No | — | remove every label from the target |

Pass exactly one explicit target: --workflow <workflowId> or --agent <agentId>; a pinned workflow alone is not accepted here.  Choose --labels and/or repeat --label, or use --none alone.  This replaces all labels on the target and creates missing account labels.  Account-wide label renaming and deletion are app operations.