Butterfly CLI

CLI tool for downloading and synchronizing resources from the Butterfly platform.

Installation

# Global installation
npm install -g @rglabs/butterfly

# Or use with npx (no installation required)
npx @rglabs/butterfly <command>

Quick Start

# 1. Configure authentication
butterfly setup

# 2. Download all resources
butterfly download

# 3. Start watching for changes
butterfly start

Commands

butterfly setup

Configure authentication for the Butterfly platform.

butterfly setup

You'll be prompted to enter:

• Endpoint: Your Butterfly platform URL (e.g., https://app.example.com)
• Email: Your login email
• Password: Your password

Configuration is saved to .butterfly/config.json.

butterfly download

Download resources from the Butterfly platform.

# Download all resource types
butterfly download

# Download specific resource type
butterfly download -t objects
butterfly download -t reports
butterfly download -t bfy_workflows
butterfly download -t bfy_ai_tasks
butterfly download -t bfy_state_machines
butterfly download -t pages
butterfly download -t bfy_cronjobs
butterfly download -t cms_email_templates
butterfly download -t cms_email_layouts

# Download specific resource by name
butterfly download -t objects -n users

# Custom output directory
butterfly download -o ./my-resources

# Clean existing files before downloading
butterfly download --cleanup

Options: | Option | Description | |--------|-------------| | -t, --type <type> | Resource type to download | | -n, --name <name> | Specific resource name | | -o, --output <path> | Output directory (default: ./butterfly-resources) | | --cleanup | Clean existing contents before downloading |

butterfly start

Watch for local file changes and sync them to the Butterfly platform in real-time.

butterfly start

# Custom directory
butterfly start -o ./my-resources

Supported file types for sync:

• Object specs (spec.json, code.js, style.css, *.bfy, *.yaml)
• Reports (report.json, query.json, *.bfy, *.js)
• Workflows (workflow.json, version.json, node.json, code.bfy, params.yaml, connections.json)
• AI Tasks (task.json, prompt.twig, *.twig)
• And more...

butterfly upload

Upload specific files or folders to the platform.

# Upload a single file
butterfly upload butterfly-resources/objects/app/users/name/spec.json

# Upload a folder
butterfly upload butterfly-resources/objects/app/users

# Upload multiple targets
butterfly upload file1.json folder1 file2.json

butterfly add

Create new resources via API and download them locally.

# Create a new workflow
butterfly add -t workflow --title "My Workflow" --system-name my_workflow

# Add a node to a workflow
butterfly add -t workflow-node -w my_workflow --title "Process Data" --node-type CustomScript --node-group Code

# Add a node and connect it to an existing node
butterfly add -t workflow-node -w my_workflow --title "Send Email" --node-type Email --node-group Output --connect-from 123

# Create a connection between nodes
butterfly add -t workflow-connection -w my_workflow --from 123 --to 456

Options: | Option | Description | |--------|-------------| | -t, --type <type> | Resource type (workflow, workflow-node, workflow-connection) | | -w, --workflow <name> | Workflow name or ID | | -v, --version <number> | Version number (defaults to latest) | | --title <title> | Title/name of the resource | | --node-type <type> | Node identifier (e.g., CustomScript, WebHook, RESTAPI) | | --node-group <group> | Node group (e.g., Code, Trigger, Connector, Output) | | --connect-from <spec> | Connect from existing node to new node | | --connect-to <spec> | Connect from new node to existing node |

butterfly workflow-info

Get information about available workflow node types.

# List all node groups
butterfly workflow-info --groups

# List nodes in a specific group
butterfly workflow-info --nodes Database

# Get details for a specific node
butterfly workflow-info --details RESTAPI --group Connector

Directory Structure

After downloading, resources are organized as follows:

butterfly-resources/
├── objects/
│   ├── butterfly/              # Core CMS objects
│   └── app/                    # Application objects
│       └── [table_name]/
│           ├── object.json
│           ├── listing_query.bfy
│           └── [field_name]/
│               ├── spec.json
│               └── [code_files]
├── reports/
│   └── [report-alias]/
│       ├── report.json
│       ├── main_query.bfy
│       ├── queries/
│       └── specs/
├── bfy_workflows/
│   └── [workflow_name]/
│       ├── workflow.json
│       └── v1/
│           ├── version.json
│           ├── connections.json
│           └── nodes/
├── bfy_ai_tasks/
├── bfy_state_machines/
├── pages/
├── bfy_cronjobs/
├── cms_email_templates/
└── cms_email_layouts/

Field Type Code Files

The CLI automatically extracts code from field specs:

| Field Type | Parameter | Output File | |------------|-----------|-------------| | calculated | val_1 | code.bfy | | custom | val_1 | template_code.bfy | | custom | val_2 | processing_code.bfy | | filter | val_3 | filter_code.bfy | | nested | val_1 | configuration.yaml | | js_code | - | code.js | | css_code | - | style.css |

Requirements

• Node.js >= 16.0.0

License

ISC