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.

Install

The CLI is published as @chatterfly/cli and exposes a single chatterfly binary.

bash

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

Configuration

Configure the CLI by setting environment variables. Optionally, save defaults to ~/.chatterfly/config.json; environment variables take precedence.

Set the following variables:

Variable	Purpose
CHATTERFLY_TOKEN	Management bearer token (required for most commands).
CHATTERFLY_API_URL	Backend origin. Defaults to `http://localhost:8080`.
CHATTERFLY_TENANT_ID	Optional tenant id, sent as the `X-Tenant-ID` header.

Example:

bash

export CHATTERFLY_API_URL="https://api.your-host.com"
export CHATTERFLY_TOKEN="cf_..."
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

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

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

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

Tip: deploy always validates before saving, so a broken definition never reaches a live deployment.

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 }}