@getfrontline/cli 1.0.4 → 1.0.5

package/dist/skills/frontline-agents/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: frontline-agents
-description: List, filter, and inspect Frontline AI agents using the Frontline CLI. Use when the user asks about their agents, wants to see agent status, flows, or analytics.
+description: List, filter, inspect, and manage Frontline AI agents and their flows using the Frontline CLI. Use when the user asks about agents, flow CRUD, flow graph nodes/edges, status, or analytics.
 ---
 
 ## Prerequisites
@@ -10,6 +10,94 @@ description: List, filter, and inspect Frontline AI agents using the Frontline C
 
 ## Commands
 
+## Agent Builder
+
+Create an agent and store it as the active agent:
+
+```bash
+frontline agents create --name "Support Agent"
+frontline agents describe
+frontline agents update --name "Support Agent v2"
+frontline agents deploy --offline false
+```
+
+Use `--no-use` on `create` if you do not want to change the active agent. Use
+`--agent-id <id>` on scoped commands to override the active agent in scripts.
+
+Delete uses the public API soft-delete flow:
+
+```bash
+frontline agents delete
+frontline agents delete --agent-id <agentId>
+```
+
+Manage core agent settings with JSON payloads validated by the API:
+
+```bash
+frontline ai-models list --type TEXT --table
+frontline agents agent-setting get
+frontline agents agent-setting update --data '{"instructions":"Answer concisely.","temperature":0.2,"aiModelId":1}'
+frontline agents agent-setting update --data '{"customToolIds":[123,456],"instructions":"Use the selected tools when needed.","temperature":0.2,"aiModelId":1}'
+```
+
+Create API call tools first with `frontline tools create`; then assign them by
+ID through `customToolIds`.
+Use TEXT AI model IDs from `frontline ai-models list --type TEXT` as
+`aiModelId`. The CLI validates referenced IDs in the same
+`agents agent-setting update` command when the Public API exposes the referenced
+resource, including `aiModelId`, `customToolIds`, and `selectedTables[].id`.
+The backend is still the source of truth for every existence and ownership
+check.
+
+Manage theme fields. Image upload is not part of this public CLI surface; pass
+existing image URLs or `null`.
+
+```bash
+frontline agents theme get
+frontline agents theme update --data '{"title":"Support","initialMessage":"Hi! How can I help?","placeholder":"Type your message...","avatar":null,"bubbleImage":null,"bubbleColor":"#111827","userMessageColor":"#2563eb","agentMessageColor":"#f3f4f6","bubbleAlignment":"RIGHT","progressIndicator":"DYNAMIC","verticalPositionInPixels":24}'
+```
+
+Manage channel settings:
+
+```bash
+frontline agents settings get
+frontline agents settings get livechat
+frontline agents settings update whatsapp --data '{"splitMessages":true,"splitCharacterLimit":500,"conversationClose":"NEVER","closeAfter":null,"timeUnit":null,"sendCloseMessage":false,"closeMessageType":"STATIC","closeMessage":null,"closeInstruction":null}'
+frontline agents settings list-channels --table
+```
+
+Mutating commands require a USER API key.
+
+## Variables And Intents
+
+Agent-scoped variables and intents use the active agent by default. Override with
+`--agent-id <id>` in scripts.
+
+```bash
+frontline agents variables list --table
+frontline agents variables all
+frontline agents variables create --name customer_name --description "Customer name"
+frontline agents variables describe 123
+frontline agents variables update 123 --name customer_name --pattern "^[A-Za-z ]+$"
+frontline agents variables delete 123
+frontline agents variables check-name customer_name
+
+frontline agents intents list --table
+frontline agents intents all
+frontline agents intents create --name cancellation --phrases '["cancel order","stop subscription"]'
+frontline agents intents describe 10
+frontline agents intents update 10 --name cancellation --phrases '[{"id":1,"phrase":"cancel order"},{"phrase":"stop order"}]'
+frontline agents intents delete 10
+frontline agents intents generate-phrases --name cancellation --samples '["cancel order"]' --amount 5
+```
+
+Use variables inside flow text fields as `{VARIABLE_NAME}`. The name must match
+the saved variable name exactly. Flow fields with variable replacement include
+API `url`, `headers[].value`, `parameters[].value`, `body`; Say AI `message` and
+`prompt`; Response AI `instructions`; Tools AI `instructions`; Conditional
+Routing AI `conditions[].expression`; and Dynamic Tables `rowId`, `search`, and
+`rowData` values.
+
 ### List all agents
 
 ```bash
@@ -39,12 +127,13 @@ frontline agents list --json
 ### Get flows for a specific agent
 
 ```bash
-frontline agents flows <agentId> [--status <status>] [--json] [--debug]
+frontline agents flows [agentId] [--agent-id <id>] [--status <status>] [--json] [--debug]
 ```
 
 | Flag                | Description                            |
 | ------------------- | -------------------------------------- |
-| `<agentId>`         | **(required)** The agent ID            |
+| `<agentId>`         | Optional agent ID                      |
+| `--agent-id <id>`   | Override the active agent              |
 | `--status <status>` | Filter by flow status                  |
 | `--json`            | Output raw JSON                        |
 | `--api-key <key>`   | Override API key                       |
@@ -63,6 +152,66 @@ frontline agents flows abc-123 --status active --json
 
 **Output columns:** `id`, `name`, `status`, `runCount`, `createdAt`
 
+## Flow CRUD And Context
+
+Select an agent once:
+
+```bash
+frontline agents use <agentId>
+```
+
+Then manage its flows:
+
+```bash
+frontline agents flows list
+frontline agents flows create --name "Order Routing" --description "Routes order questions"
+frontline agents flows use <flowId>
+frontline agents flows describe --include-nodes
+frontline agents flows update --name "Order Routing v2" --status ACTIVE
+frontline agents flows delete
+```
+
+`create` selects the new flow by default. Use `--agent-id` and `--flow-id` to
+override saved context in scripts.
+
+## Flow Graphs
+
+Inspect before changing:
+
+```bash
+frontline agents flows graph --table
+frontline agents flows nodes list
+```
+
+Create a minimal flow:
+
+```bash
+frontline agents flows nodes create --data '{"nodeId":"start_1","type":"START","position":{"positionX":0,"positionY":0}}'
+frontline agents flows nodes create --data '{"nodeId":"say_1","type":"SAY_AI","position":{"positionX":320,"positionY":0},"data":{"type":"SAY_AI","sayWithAi":false,"message":"Hello!"}}'
+frontline agents flows edges add --source start_1 --source-handle default --target say_1 --target-handle default
+```
+
+Update and delete:
+
+```bash
+frontline agents flows nodes update say_1 --data '{"alias":"Greeting"}'
+frontline agents flows nodes delete say_1
+frontline agents flows edges remove --source start_1 --source-handle default --target say_1 --target-handle default
+```
+
+Supported flow node types:
+
+`START`, `TRIGGER_INTENT`, `SAY_AI`, `RESPONSE_AI`, `TOOLS_AI`, `API`,
+`CONDITIONAL_ROUTING`, `DYNAMIC_TABLES`.
+
+Validation rules:
+
+- Use exactly one initial node: `START` or `TRIGGER_INTENT`.
+- `data.type` must match `type` when `data` is present.
+- Edges must reference existing source and target nodes.
+- No self-edges and no cycles.
+- `CONDITIONAL_ROUTING` and `TOOLS_AI` can use multiple outgoing handles; other nodes use one outgoing edge.
+
 ### Get analytics for a specific agent
 
 ```bash

package/dist/skills/frontline-workflows/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: frontline-workflows
-description: List, filter, and inspect Frontline workflows using the Frontline CLI. Use when the user asks about their workflows, wants to see workflow status, run counts, or analytics.
+description: Create, edit, connect, inspect, and delete Frontline automation workflows using the Frontline CLI. Use when the user asks to build workflows, add nodes or edges, manage workflow context, inspect status, or view analytics.
 ---
 
 ## Prerequisites
@@ -36,15 +36,182 @@ frontline workflows list --status active --json
 
 **Output columns:** `id`, `name`, `status`, `triggerType`, `runsCount`, `lastRunDate`
 
+### Create and select a workflow
+
+```bash
+frontline workflows create --name "Daily CRM Sync" [--description "..."]
+frontline workflows use <workflowId>
+frontline workflows describe [--include-nodes]
+frontline workflows graph [--table]
+```
+
+`create` saves the created workflow ID as the active workflow for the current
+profile. `use` changes the active workflow. All graph commands accept
+`--workflow-id <id>` to override the active workflow, which is preferred for
+scripts and CI.
+
+### Update or delete a workflow
+
+```bash
+frontline workflows update --status ACTIVE          # name is optional; fetched automatically if omitted
+frontline workflows update --name "Daily CRM Sync" --status ACTIVE
+frontline workflows delete
+```
+
+Use a USER API key for mutations. GENERAL keys can still read account-level
+workflow data where the API allows it.
+
+### Manage variables
+
+Workflow variable commands use the active workflow by default. Override with
+`--workflow-id <id>` in scripts and CI.
+
+```bash
+frontline workflows variables list --table
+frontline workflows variables all
+frontline workflows variables create --name order_id --description "Order ID"
+frontline workflows variables describe 123
+frontline workflows variables update 123 --name order_id --pattern "^[0-9]+$"
+frontline workflows variables delete 123
+frontline workflows variables check-name order_id
+```
+
+Use variables inside text fields as `{VARIABLE_NAME}`. Automation workflows also
+make each node output available by node ID, so a node with `nodeId` `api_1` can be
+referenced later as `{api_1}`.
+
+## Building Workflow Graphs
+
+Always inspect the graph before changing it:
+
+```bash
+frontline workflows graph --table
+frontline workflows nodes list --table
+```
+
+### nodeId Format
+
+All node IDs **must** follow the pattern `node_<uuid>`. Names like `trigger_1` or `api_1` will fail with a validation error.
+
+```
+node_a1b2c3d4-e5f6-7890-abcd-ef1234567890
+```
+
+### Create nodes
+
+Trigger node (CONTACT_CREATED):
+
+```bash
+frontline workflows nodes create --data '{"nodeId":"node_11111111-1111-1111-1111-111111111111","type":"TRIGGER","position":{"positionX":0,"positionY":0},"data":{"type":"TRIGGER","triggerType":"CONTACT_CREATED"}}'
+```
+
+Incoming webhook trigger — first create the webhook resource:
+
+```bash
+frontline incoming-webhooks create --name "My Webhook"
+# Save the returned id
+frontline workflows nodes create --data '{"nodeId":"node_11111111-1111-1111-1111-111111111111","type":"TRIGGER","position":{"positionX":0,"positionY":0},"data":{"type":"TRIGGER","triggerType":"INCOMING_WEBHOOK","triggerByWebhookIds":["<incoming-webhook-id>"]}}'
+```
+
+When this fires, the POST body is available as `{webhook_payload}` in all downstream nodes.
+
+API action node:
+
+```bash
+frontline workflows nodes create --data '{"nodeId":"node_22222222-2222-2222-2222-222222222222","type":"API","position":{"positionX":320,"positionY":0},"data":{"type":"API","url":"https://example.com","method":"GET","headers":[]}}'
+```
+
+Supported automation node types:
+
+`TRIGGER`, `SCHEDULED_TRIGGER`, `WEBHOOK`, `TOOLS_AI`, `API`,
+`CONDITIONAL_ROUTING`, `AI_CAPTURE`, `DATA_TRANSFORMER`, `DYNAMIC_TABLES`,
+`SEND_MESSAGE`, `TRANSCRIPTION`.
+
+### DYNAMIC_TABLES node
+
+Used to create, update, delete, or search records in an object. Always get the object schema first:
+
+```bash
+frontline object get <object-name>
+# id → tableId, record_types[0].id → recordTypeId, fields[].name → rowData keys
+```
+
+`rowData` maps **field names** (e.g. `"First Name"`, `"Email"`) — not UUIDs — to static values or `{VARIABLE_NAME}` references. `inputModeByField` sets `"INPUT"` (static) or `"VARIABLE"` (interpolated) per field name. All variables used must exist and be populated by a prior node.
+
+**Variables are plain text substitutions** — `{my_var}` is replaced with the exact string stored in that variable. There is no dot-access: `{webhook_payload.firstName}` is not valid.
+
+```bash
+frontline workflows nodes create --data '{"nodeId":"node_22222222-2222-2222-2222-222222222222","type":"DYNAMIC_TABLES","position":{"positionX":640,"positionY":0},"data":{"type":"DYNAMIC_TABLES","tableId":2,"recordTypeId":2,"actionType":"CREATE","rowData":{"First Name":"{first_name}","Email":"{email}"},"inputModeByField":{"First Name":"VARIABLE","Email":"VARIABLE"}}}'
+```
+
+`actionType` values: `CREATE`, `UPDATE`, `DELETE`, `SEARCH`, `SEARCH_BY_ID`.
+
+### Connect nodes
+
+```bash
+frontline workflows edges add \
+  --source node_11111111-1111-1111-1111-111111111111 \
+  --source-handle default \
+  --target node_22222222-2222-2222-2222-222222222222 \
+  --target-handle default
+```
+
+The API enforces one outgoing edge per node, no self-edges, source/target
+existence, and no cycles.
+
+### Edit and delete nodes
+
+```bash
+frontline workflows nodes update node_22222222-2222-2222-2222-222222222222 --data '{"alias":"Fetch external data"}'
+frontline workflows nodes delete node_22222222-2222-2222-2222-222222222222
+```
+
+Deleting a node also removes incoming and outgoing edges.
+
+### Remove an edge
+
+```bash
+frontline workflows edges remove \
+  --source node_11111111-1111-1111-1111-111111111111 \
+  --source-handle default \
+  --target node_22222222-2222-2222-2222-222222222222 \
+  --target-handle default
+```
+
+## Validation Checklist
+
+- Use exactly one initial trigger node (`TRIGGER` or `SCHEDULED_TRIGGER`).
+- All node IDs must follow `node_<uuid>` format.
+- Use only supported automation node types.
+- Ensure `data.type` matches the node `type`.
+- Connect only existing source and target nodes.
+- Keep a single outgoing edge per node.
+- Avoid self-edges and cycles.
+- Inspect `frontline workflows graph` after each structural change.
+
+## Variable Interpolation
+
+Interpolable workflow fields include API `url`, `headers[].value`,
+`parameters[].value`, `body`; Send Message / Say AI `message` and `prompt`;
+Response AI `instructions`; Tools AI `instructions` and `prompt`; AI Capture
+`prompt` and `instructions`; Data Transformer `prompt`; Conditional Routing AI
+`conditions[].expression`; Dynamic Tables `rowId`, `search`, `rowData` values;
+Transcription `audioUrl`; and WhatsApp template variables in
+`templateVariables.header`, `templateVariables.body`, and
+`templateVariables.buttons`.
+
+Each node's output is also available as `{nodeId}` in downstream nodes.
+
 ### Get analytics for a specific workflow
 
 ```bash
-frontline workflows analytics <workflowId> [--start-date <YYYY-MM-DD>] [--end-date <YYYY-MM-DD>] [--json] [--debug]
+frontline workflows analytics [workflowId] [--workflow-id <id>] [--start-date <YYYY-MM-DD>] [--end-date <YYYY-MM-DD>] [--json] [--debug]
 ```
 
 | Flag                  | Description                            |
 | --------------------- | -------------------------------------- |
-| `<workflowId>`        | **(required)** The workflow ID         |
+| `<workflowId>`        | Optional workflow ID                   |
+| `--workflow-id <id>`  | Override the active workflow           |
 | `--start-date <date>` | Start date in `YYYY-MM-DD` format      |
 | `--end-date <date>`   | End date in `YYYY-MM-DD` format        |
 | `--json`              | Output raw JSON                        |

package/dist/skills/incoming-webhooks/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: incoming-webhooks
+description: Create Frontline incoming webhooks from the CLI and use the returned URL/token in automation workflows.
+allowed-tools: Bash(frontline:*)
+---
+
+# Incoming Webhooks
+
+Create a webhook:
+
+```bash
+frontline incoming-webhooks create --name "CRM payload" --description "Receives contacts"
+```
+
+Create an unauthenticated webhook:
+
+```bash
+frontline incoming-webhooks create --name "Open endpoint" --no-authentication
+```
+
+The create response includes:
+
+- `id`: use this in workflow trigger payloads as `triggerByWebhookIds`.
+- `url`: endpoint that receives the webhook request.
+- `accessToken`: bearer token returned only on creation when authentication is enabled.
+
+To trigger an automation from this webhook, create a workflow `TRIGGER` node with
+`triggerType` and `triggeredBy` set to `INCOMING_WEBHOOK`, and include the
+webhook ID:
+
+```bash
+frontline workflows nodes create --data '{"nodeId":"incoming_webhook_1","type":"TRIGGER","position":{"positionX":0,"positionY":0},"data":{"type":"TRIGGER","triggerType":"INCOMING_WEBHOOK","triggeredBy":"INCOMING_WEBHOOK","triggerByWebhookIds":["<incomingWebhookId>"]}}'
+```
+
+Incoming webhook payload data is available to later automation nodes through the
+runtime webhook payload variables documented in the workflow builder skill.

package/dist/skills/tools/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: tools
+description: Create, list, inspect, update, delete, and assign Frontline API call tools from the CLI. Use when the user asks about tools, custom tools, API tools, headers, arguments, query params, or assigning tools to agents.
+---
+
+## Prerequisites
+
+- Authenticate with `frontline auth login <api-key>`.
+- Creating, updating, and deleting tools requires a USER API key.
+- This public surface supports `API_CALL` tools only. WhatsApp template tools are not exposed yet.
+
+## List And Inspect
+
+```bash
+frontline tools list
+frontline tools list --status ACTIVE --filter-text contact
+frontline tools list --table
+frontline tools describe <toolId>
+```
+
+Tool list output includes `id`, `name`, `status`, `method`, `url`, and timestamps.
+
+## Create An API Tool
+
+```bash
+frontline tools create \
+  --name "Fetch contact" \
+  --description "Fetches a CRM contact" \
+  --method GET \
+  --url "https://api.example.com/contacts/{{contactId}}" \
+  --arguments '[{"name":"contactId","description":"CRM contact ID","dataType":"STRING"}]' \
+  --headers '[{"key":"Authorization","value":"Bearer {{apiKey}}"}]' \
+  --query-params '[{"key":"include","value":"deals"}]'
+```
+
+Complex options are JSON arrays:
+
+- `--arguments`: `[{ "name": "...", "description": "...", "dataType": "STRING" }]`
+- `--headers`: `[{ "key": "...", "value": "..." }]`
+- `--query-params`: `[{ "key": "...", "value": "..." }]`
+
+Supported argument data types are `STRING`, `NUMBER`, `DECIMAL`, and `BOOLEAN`.
+Supported methods are `GET`, `POST`, `PUT`, `PATCH`, and `DELETE`.
+
+## Update And Delete
+
+```bash
+frontline tools update <toolId> --status PAUSED
+frontline tools update <toolId> --url "https://api.example.com/v2/contacts/{{contactId}}"
+frontline tools update <toolId> --headers '[{"key":"Authorization","value":"Bearer {{apiKey}}"}]'
+frontline tools delete <toolId>
+```
+
+Update replaces `arguments`, `headers`, or `queryParams` when those options are
+provided. Delete is a soft delete.
+
+## Assign To An Agent
+
+Use `customToolIds` in the agent setting payload:
+
+```bash
+frontline agents agent-setting update --data '{"customToolIds":[123],"instructions":"Use the contact tool when a user asks about CRM data.","temperature":0.2,"aiModelId":1}'
+```
+
+The API validates that assigned tool IDs belong to the same account.

package/dist/skills/variables/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: variables
+description: Manage Frontline agent variables, workflow variables, and flow intents from the CLI, and explain variable interpolation in nodes and actions.
+allowed-tools: Bash(frontline:*)
+---
+
+# Variables And Intents
+
+## Agent Variables
+
+```bash
+frontline agents use <agentId>
+frontline agents variables list --table
+frontline agents variables all
+frontline agents variables create --name customer_name --description "Customer name"
+frontline agents variables describe 123
+frontline agents variables update 123 --name customer_name --pattern "^[A-Za-z ]+$"
+frontline agents variables delete 123
+frontline agents variables check-name customer_name
+```
+
+Use `--agent-id <id>` to avoid relying on saved context.
+
+## Agent Intents
+
+```bash
+frontline agents intents list --table
+frontline agents intents all
+frontline agents intents create --name cancellation --phrases '["cancel order","stop subscription"]'
+frontline agents intents update 10 --name cancellation --phrases '[{"id":1,"phrase":"cancel order"},{"phrase":"stop order"}]'
+frontline agents intents delete 10
+frontline agents intents generate-phrases --name cancellation --samples '["cancel order"]' --amount 5
+```
+
+For create, `--phrases` is a JSON array of strings. For update, `--phrases` is a
+JSON array of objects; existing phrases include `id`, and new phrases omit it.
+
+## Workflow Variables
+
+```bash
+frontline workflows use <workflowId>
+frontline workflows variables list --table
+frontline workflows variables all
+frontline workflows variables create --name order_id --description "Order ID"
+frontline workflows variables describe 123
+frontline workflows variables update 123 --name order_id --pattern "^[0-9]+$"
+frontline workflows variables delete 123
+frontline workflows variables check-name order_id
+```
+
+Use `--workflow-id <id>` to avoid relying on saved context.
+
+## Interpolation Syntax
+
+Variables are referenced inside text fields as `{VARIABLE_NAME}`. The name must
+match `variable.name` exactly. Automation workflows also expose each node output
+as a runtime variable named after the node ID. Because node IDs follow the
+`node_<uuid>` format, a node with `nodeId`
+`node_a1b2c3d4-e5f6-7890-abcd-ef1234567890` is referenced downstream as
+`{node_a1b2c3d4-e5f6-7890-abcd-ef1234567890}`.
+
+Agent flow fields with variable replacement:
+
+- API: `url`, `headers[].value`, `parameters[].value`, `body`.
+- Say AI: `message`, `prompt`.
+- Response AI: `instructions`.
+- Tools AI: `instructions`.
+- Conditional Routing AI: `conditions[].expression`.
+- Dynamic Tables: `rowId`, `search`, `rowData` values.
+
+Automation workflow fields with variable replacement:
+
+- API: `url`, `headers[].value`, `parameters[].value`, `body`.
+- Send Message / Say AI: `message`, `prompt`.
+- Response AI: `instructions`.
+- Tools AI: `instructions`, `prompt`.
+- AI Capture: `prompt`, `instructions`.
+- Data Transformer: `prompt`.
+- Conditional Routing AI: `conditions[].expression`.
+- Dynamic Tables: `rowId`, `search`, `rowData` values.
+- Transcription: `audioUrl`.
+- WhatsApp Template: `templateVariables.header`, `templateVariables.body`, `templateVariables.buttons`.