CLI

The chatterfly CLI lets you validate, deploy, and operate workflows from your terminal or CI pipeline. Workflow definitions are just JSON, so you can keep them in git and ship them like any other code.

Tip: Prefer building visually instead? See the Quickstart for the dashboard-editor path. Using an AI coding assistant? See the Agent Quickstart for setup + copy-paste prompts.

Install

The CLI is published as @chatterfly/cli and exposes a single chatterfly binary. Node.js 18 or newer is required.

bash

npm install -g @chatterfly/cli
# or run ad-hoc
npx @chatterfly/cli --help

Configuration

First, mint a personal access token in the dashboard under Settings → API tokens (the token starts with cfpat_). Save it locally:

bash

chatterfly login --token cfpat_your_token_here

This writes ~/.chatterfly/config.json. Alternatively, set environment variables, which always take precedence over the saved file:

Variable	Purpose
CHATTERFLY_TOKEN	Personal access token (`cfpat_…`) from Settings → API tokens.
CHATTERFLY_API_URL	Backend origin. Defaults to `http://localhost:8080`.
CHATTERFLY_TENANT_ID	Optional tenant id, sent as the `X-Tenant-ID` header. A token is already bound to one workspace, so this is rarely needed.

Example:

bash

export CHATTERFLY_API_URL="https://api.your-host.com"
export CHATTERFLY_TOKEN="cfpat_..."
chatterfly login

Commands

Add --json to any command for machine-readable output.

bash

# Verify your token and print identity
chatterfly login

# Validate a definition (full server-side validation)
chatterfly validate flow.json
chatterfly validate flow.json --offline   # JSON shape check only

# Create/update a workflow from a file and deploy it
chatterfly deploy flow.json --name "My Flow" \
  --workflow-id <id> --environment production
chatterfly deploy flow.json --name "Public Form" --public
chatterfly deploy flow.json --name "Survey" --survey-slug customer-feedback

# Download a workflow definition to a file
chatterfly pull --workflow-id <id> --out flow.json
chatterfly pull --workflow-id <id> --deployment-id <id> --out deployed.json

# List immutable deployment history (metadata only)
chatterfly deployments list --workflow-id <id>

# Inspect and operate durable Parallel branch items
chatterfly runs fanouts <run-id>
chatterfly runs fanouts <run-id> --status failed
chatterfly runs fanouts <run-id> --json  # script-friendly item envelopes
chatterfly runs retry-item <run-id> <fanout-id> <item-id> --confirm
chatterfly runs cancel-item <run-id> <fanout-id> <item-id> --confirm
chatterfly runs retry-items <run-id> <fanout-id> <item-id>... --confirm
chatterfly runs cancel-items <run-id> <fanout-id> <item-id>... --confirm

# Manage stable workflow keys for server integrations
chatterfly keys create --workflow-id <id> --name "production"
chatterfly keys list --workflow-id <id>
chatterfly keys revoke --workflow-id <id> --key-id <key-id>

# Print a copy-paste widget embed snippet
chatterfly embed --workflow-id <id>
chatterfly embed --workflow-id <id> --framework script-tag
chatterfly embed --workflow-id <id> --theme primary=#0ea5e9,radius=4px

# Inspect runs
chatterfly runs list
chatterfly runs get <run-id>

# Discover reusable registered agents and their harness configuration
chatterfly agents list
chatterfly agents get <agent-id>

# Explore the surface registry (traits, voice styles, node permissions)
chatterfly surfaces
chatterfly surfaces phone

# Create and authorize a least-privilege Zoho connection
chatterfly connections catalog zoho
chatterfly oauth-apps list
chatterfly oauth-apps set zoho --input @zoho-app.json
chatterfly connections create --name "Sales CRM" --slug sales-crm   --capability crm_identity --capability crm_leads_read
chatterfly connections auth-url <connection-id>
chatterfly connections test <connection-id>
chatterfly connections refresh-metadata <connection-id>
chatterfly connections upgrade <connection-id>
chatterfly connections history-status <connection-id>
chatterfly connections history-rebuild <connection-id> --module Deals --days 30 --confirm
chatterfly connections aliases-list <connection-id>
chatterfly connections alias-revoke <connection-id> --alias-id <alias-id> --confirm

# Trigger a test run
chatterfly trigger --deployment-id <id> --input '{"foo":"bar"}'
chatterfly trigger --deployment-id <id> --input @payload.json

Note: Zoho authorization is browser-based. The CLI prints a trusted dashboard URL and intentionally has no access-token, refresh-token, accounts-host, or API-host flags. OAuth app input is owner/admin-only and its client secret is write-only; list output reports lifecycle and referenced-grant counts without returning credentials.

Tip: deploy always validates before saving, so a broken definition never reaches a live deployment. It also prints next-step guidance — a serverless embed one-liner for public deployments, or a keys create pointer for private ones. See Script Tag & Web Component for the full embed reference.

Warning: When validate finds an ephemeralWorkflowCall.for_each, it reports the batch count. Those items run inline, can repeat accepted provider requests, and do not retain live per-item traces. Use provider idempotency and the required at-least-once acknowledgement.

Use in CI

Fail a build when a workflow definition is invalid by running validate — it exits non-zero on validation errors.

yaml

# .github/workflows/validate.yml
- run: npx @chatterfly/cli validate workflows/*.json
  env:
    CHATTERFLY_API_URL: ${{ secrets.CHATTERFLY_API_URL }}
    CHATTERFLY_TOKEN: ${{ secrets.CHATTERFLY_TOKEN }}