@refly/cli

Refly CLI - Workflow orchestration for Claude Code

A command-line interface for building, managing, and executing Refly workflows with deterministic state management.

Features

• Builder Mode: Incrementally build workflows with local state persistence
• DAG Validation: Automatic cycle detection and dependency validation
• JSON-First: All commands output structured JSON for reliable automation
• Claude Code Integration: SKILL.md installation for seamless Claude Code usage
• Secure: Token storage with file permissions, never exposed in logs

Installation

npm install -g @refly/cli

Quick Start

# Initialize and install skill files
refly init

# Authenticate
refly login

# Start building a workflow
refly builder start --name "my-workflow"

# Add nodes
refly builder add-node --node '{"id":"parse","type":"document.parse","input":{}}'
refly builder add-node --node '{"id":"summarize","type":"llm.summarize","input":{},"dependsOn":["parse"]}'

# Validate and commit
refly builder validate
refly builder commit

# Run the workflow
refly workflow run <workflowId>

Core Commands

Authentication

refly init                    # Initialize CLI and install skill files
refly login                   # Authenticate with API key
refly logout                  # Remove credentials
refly status                  # Check configuration and auth status
refly whoami                  # Show current user

Builder Mode

Build workflows incrementally with local state:

refly builder start --name "workflow-name"
refly builder add-node --node '<json>'
refly builder update-node --id "<nodeId>" --patch '<json>'
refly builder remove-node --id "<nodeId>"
refly builder connect --from "<nodeId>" --to "<nodeId>"
refly builder disconnect --from "<nodeId>" --to "<nodeId>"
refly builder status
refly builder graph [--ascii]
refly builder validate
refly builder commit
refly builder abort

Workflow Management

refly workflow create --name "<name>" --spec '<json>'
refly workflow list [--limit N]
refly workflow get <workflowId>
refly workflow edit <workflowId> --ops '<json>'
refly workflow delete <workflowId>

Workflow Execution

refly workflow run <workflowId> [--input '<json>']
refly workflow run-status <runId>
refly workflow abort <runId>

Node Debugging

refly node types [--category <category>]
refly node run --type "<nodeType>" --input '<json>'

Builder State Machine

The builder uses a deterministic state machine:

IDLE → DRAFT → VALIDATED → COMMITTED
  ↑      ↓          ↓
  └──────┴──────────┘
       (abort)

States:

• IDLE: No active session
• DRAFT: Editing in progress
• VALIDATED: DAG validation passed
• COMMITTED: Workflow created (terminal)

Rules:

• Any edit operation invalidates validation
• Only VALIDATED sessions can be committed
• COMMITTED sessions are read-only

JSON Output Format

All commands output JSON with this structure:

Success:

{
  "ok": true,
  "type": "workflow.create",
  "version": "1.0",
  "payload": { ... }
}

Error:

{
  "ok": false,
  "type": "error",
  "version": "1.0",
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "Not authenticated",
    "hint": "refly login"
  }
}

Configuration

Configuration is stored in ~/.refly/config.json:

{
  "version": 1,
  "auth": {
    "apiKey": "...",
    "expiresAt": "..."
  },
  "api": {
    "endpoint": "https://api.refly.ai"
  }
}

Environment Variables:

• REFLY_API_KEY: API key for authentication
• REFLY_API_ENDPOINT: Override API endpoint

Claude Code Integration

After running refly init, skill files are installed to:

• ~/.claude/skills/refly/SKILL.md
• ~/.claude/skills/refly/references/
• ~/.claude/commands/refly-*.md (if commands directory exists)

This enables Claude Code to:

• Understand Refly workflow concepts
• Use builder mode correctly
• Handle state transitions
• Output deterministic results

Error Codes

| Code | Description | Hint | |------|-------------|------| | AUTH_REQUIRED | Not authenticated | refly login | | BUILDER_NOT_STARTED | No active builder session | refly builder start | | VALIDATION_REQUIRED | Must validate before commit | refly builder validate | | VALIDATION_ERROR | DAG validation failed | Check error details | | DUPLICATE_NODE_ID | Node ID already exists | Use unique ID | | CYCLE_DETECTED | Circular dependency | Remove cycle | | WORKFLOW_NOT_FOUND | Workflow does not exist | Check workflow ID |

Examples

Build a Document Processing Workflow

# Start builder
refly builder start --name "doc-processor"

# Add nodes
refly builder add-node --node '{
  "id": "input",
  "type": "document.input",
  "input": {"format": "pdf"}
}'

refly builder add-node --node '{
  "id": "parse",
  "type": "document.parse",
  "input": {},
  "dependsOn": ["input"]
}'

refly builder add-node --node '{
  "id": "summarize",
  "type": "llm.summarize",
  "input": {"maxLength": 500},
  "dependsOn": ["parse"]
}'

refly builder add-node --node '{
  "id": "export",
  "type": "document.export",
  "input": {"format": "markdown"},
  "dependsOn": ["summarize"]
}'

# Validate and commit
refly builder validate
refly builder commit

Run a Workflow

# Run with input
refly workflow run wf-abc123 --input '{"documentUrl": "https://..."}'

# Check status
refly workflow run-status run-xyz789

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Watch mode
pnpm dev

# Run locally
node dist/bin/refly.js

License

MIT