@powerformer/refly-cli 0.1.23 → 0.1.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powerformer/refly-cli",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "description": "Refly CLI - Command-line interface for Refly workflow orchestration",
   "bin": {
     "refly": "./dist/bin/refly.js"

package/skill/SKILL.md

@@ -1,11 +1,6 @@
 ---
 name: refly
-description: |
-  Base skill for Refly ecosystem: creates, discovers, and runs domain-specific skills bound to workflows.
-  Routes user intent to matching domain skills via symlinks in ~/.claude/skills/, delegates execution to Refly backend.
-  Use when user asks to: create skills, run workflows, automate multi-step tasks, or manage pipelines.
-  Triggers: refly, skill, workflow, run skill, create skill, automation, pipeline.
-  Requires: @refly/cli installed and authenticated.
+description: "Base skill for Refly ecosystem: creates, discovers, and runs domain-specific skills bound to workflows. Routes user intent to matching domain skills via symlinks, delegates execution to Refly backend. Use when user asks to: create skills, run workflows, automate multi-step tasks, or manage pipelines. Triggers: refly, skill, workflow, run skill, create skill, automation, pipeline. Requires: @refly/cli installed and authenticated."
 ---
 
 # Refly
@@ -18,17 +13,123 @@ description: |
 4. **No tokens** - Never print or request auth tokens.
 5. **Stop on error** - If `ok=false`, stop and show `hint`.
 
-## Quick Commands
+## Available Commands
+
+| Command | ID Format | Description |
+|---------|-----------|-------------|
+| `refly status` | - | Check authentication and connection status |
+| `refly login` | - | Authenticate with Refly |
+| `refly skill list` | - | List all available skills in the marketplace |
+| `refly skill installations` | - | List your installed skills (get installationId here) |
+| `refly skill run --id <installationId> --input '<json>'` | skpi-xxx | Run an installed skill, returns runId (we-xxx) |
+| `refly workflow status <runId> --watch` | we-xxx | Watch workflow execution status |
+| `refly workflow detail <runId>` | we-xxx | Get workflow run details |
+| `refly workflow toolcalls <runId> --files --latest` | we-xxx | Get files from latest toolcall |
+| `refly file download <fileId> -o <path>` | df-xxx | Download a file |
+
+**Tip**: Get `installationId` (skpi-xxx) from `refly skill installations`.
+
+### Command Options
+
+| Command | Option | Description |
+|---------|--------|-------------|
+| `workflow status` | `--watch` | Poll until workflow completes |
+| `workflow status` | `--interval <ms>` | Polling interval in milliseconds (default: 5000) |
+| `workflow toolcalls` | `--files` | Return simplified output with only files and content |
+| `workflow toolcalls` | `--latest` | With `--files`, return only files from the most recent toolcall |
+| `workflow toolcalls` | `--raw` | Disable output sanitization (show full tool outputs) |
+
+**Recommended**: Use `--files --latest` to get files from the final output without processing all toolcalls.
+
+## Skill Categories & Execution Patterns
+
+Choose the execution pattern based on the skill's output type:
+
+| Category | Skills | Output | Pattern |
+|----------|--------|--------|---------|
+| **File Generation** | image, video, audio skills | Files (png/mp4/mp3) | Run → Wait → Download → Open |
+| **Text/Data** | search, research, report skills | Text content | Run → Wait → Extract content |
+| **Action** | email, messaging, integration skills | Status confirmation | Run → Wait → Confirm |
+
+---
+
+### Pattern A: File Generation Skills
+**Use for**: nano-banana-pro, fal-image, fal-video, fal-audio, seedream-image, kling-video, wan-video
+
+```bash
+# Step 1: Run and capture RUN_ID
+RESULT=$(refly skill run --id <installationId> --input '<json>')
+RUN_ID=$(echo "$RESULT" | jq -r '.payload.workflowExecutions[0].id')
+
+# Step 2: Wait for completion
+refly workflow status "$RUN_ID" --watch --interval 30000
+
+# Step 3: Get files and download to Desktop
+FILES=$(refly workflow toolcalls "$RUN_ID" --files --latest | jq -r '.payload.files[]')
+echo "$FILES" | jq -c '.' | while read -r file; do
+  FILE_ID=$(echo "$file" | jq -r '.fileId')
+  FILE_NAME=$(echo "$file" | jq -r '.name')
+  if [ -n "$FILE_ID" ] && [ "$FILE_ID" != "null" ]; then
+    refly file download "$FILE_ID" -o "$HOME/Desktop/${FILE_NAME}"
+    open "$HOME/Desktop/${FILE_NAME}"
+  fi
+done
+```
+
+---
+
+### Pattern B: Text/Data Skills
+**Use for**: jina, perplexity, weather-report, exa, research skills
+
+```bash
+# Step 1: Run and capture RUN_ID
+RESULT=$(refly skill run --id <installationId> --input '<json>')
+RUN_ID=$(echo "$RESULT" | jq -r '.payload.workflowExecutions[0].id')
+
+# Step 2: Wait for completion
+refly workflow status "$RUN_ID" --watch --interval 30000
+
+# Step 3: Extract text content from toolcalls
+CONTENT=$(refly workflow toolcalls "$RUN_ID" --files --latest | jq -r '.payload.nodes[].content')
+echo "$CONTENT"
+```
+
+---
+
+### Pattern C: Action Skills
+**Use for**: send-email, slack, microsoft-teams, zoom, calendar, CRM integrations
 
 ```bash
-refly status
-refly login
-refly skill list
-refly skill installations
-refly skill run <installationId> --input '<json>'
+# Step 1: Run and capture RUN_ID
+RESULT=$(refly skill run --id <installationId> --input '<json>')
+RUN_ID=$(echo "$RESULT" | jq -r '.payload.workflowExecutions[0].id')
+
+# Step 2: Wait for completion
+refly workflow status "$RUN_ID" --watch --interval 30000
+
+# Step 3: Confirm action status
+STATUS=$(refly workflow detail "$RUN_ID" | jq -r '.payload.status')
+echo "Action completed with status: $STATUS"
 ```
 
-Tip: Get `installationId` from `refly skill installations` after installing a skill.
+---
+
+**ID Types:**
+| ID Format | Example | Used For |
+|-----------|---------|----------|
+| `skpi-xxx` | skpi-h9kpmts9ho1kl9l1sohaloeu | `skill run --id` only |
+| `we-xxx` | we-abc123def456 | `workflow status`, `workflow detail`, `workflow toolcalls` |
+| `c-xxx` | c-g6emwcpi1wpalsz6j4gyi3d9 | Browser URL only |
+| `df-xxx` | df-b3yxyelshtwsbxbrkmcqxmx9 | `file download` |
+| `skpe-xxx` | skpe-qga5lpyv59yjzz2ghz2iv9bu | ⚠️ Do NOT use for workflow commands |
+
+**Required behavior:**
+- `skill run` returns `RUN_ID` (we-xxx) in `.payload.workflowExecutions[0].id`
+- Use `we-xxx` for all workflow commands (`status`, `detail`, `toolcalls`)
+- Choose execution pattern (A/B/C) based on skill category
+- File skills: Download to `~/Desktop/` and `open` to show user
+- Text skills: Extract `.payload.nodes[].content` for text output
+- Action skills: Confirm `.payload.status` for completion
 
 ## Directory Structure
 
@@ -37,6 +138,7 @@ Tip: Get `installationId` from `refly skill installations` after installing a sk
 ├── base/                       # Base skill files (this symlink target)
 │   ├── SKILL.md
 │   └── rules/
+│       ├── execution.md
 │       ├── workflow.md
 │       ├── node.md
 │       ├── file.md
@@ -56,6 +158,7 @@ User intent -> match domain skill (name/trigger) in `~/.claude/skills/`
 
 ## References
 
+- `rules/execution.md` - **Skill execution patterns and error handling**
 - `rules/workflow.md` - Workflow command reference
 - `rules/node.md` - Node command reference
 - `rules/file.md` - File command reference

package/skill/references/execution.md

@@ -0,0 +1,218 @@
+# Skill Execution Reference
+
+## Quick Reference
+
+| Command | Purpose |
+|---------|---------|
+| `refly skill run --id <skpi-xxx> --input '<json>'` | Run skill, returns RUN_ID |
+| `refly workflow status <we-xxx> --watch --interval 30000` | Wait for completion |
+| `refly workflow detail <we-xxx>` | Get execution details and status |
+| `refly workflow toolcalls <we-xxx> --files --latest` | Get files and text content |
+| `refly file download <df-xxx> -o <path>` | Download file to local path |
+
+## ID Formats
+
+| Format | Example | Used For |
+|--------|---------|----------|
+| `skpi-xxx` | skpi-h9kpmts9ho1kl9l1sohaloeu | `skill run --id` only |
+| `we-xxx` | we-abc123def456 | `workflow status`, `workflow detail`, `workflow toolcalls` |
+| `c-xxx` | c-g6emwcpi1wpalsz6j4gyi3d9 | Browser URL only (https://refly.ai/workflow/c-xxx) |
+| `df-xxx` | df-b3yxyelshtwsbxbrkmcqxmx9 | `file download` |
+| `skpe-xxx` | skpe-qga5lpyv59yjzz2ghz2iv9bu | **Do NOT use** for workflow commands |
+
+---
+
+## Standard Execution Flow
+
+### Step 1: Run Skill and Get Run ID
+
+```bash
+RESULT=$(refly skill run --id <installationId> --input '{
+  "key": "value"
+}')
+
+# Check if command succeeded
+if [ "$(echo "$RESULT" | jq -r '.ok')" != "true" ]; then
+  echo "Error: $(echo "$RESULT" | jq -r '.error.message')"
+  echo "Hint: $(echo "$RESULT" | jq -r '.hint // empty')"
+  exit 1
+fi
+
+RUN_ID=$(echo "$RESULT" | jq -r '.payload.workflowExecutions[0].id')
+echo "Run ID: $RUN_ID"
+```
+
+**Important**: Run ID is in `.payload.workflowExecutions[0].id` (we-xxx format)
+
+### Step 2: Open Workflow in Browser and Wait for Completion
+
+```bash
+# Open workflow in browser (optional, for monitoring)
+open "https://refly.ai/workflow/<workflowId>"
+
+# Poll every 30 seconds until workflow finishes
+refly workflow status "$RUN_ID" --watch --interval 30000
+```
+
+### Step 3: Get Results (Choose Based on Skill Category)
+
+Choose the pattern based on the skill's `category` field in SKILL.md:
+- `category: file-generation` → Pattern A
+- `category: text-data` → Pattern B
+- `category: action` → Pattern C
+
+---
+
+## Pattern A: File Generation Skills
+
+**Use for**: Skills with `category: file-generation` (image, video, audio skills)
+
+```bash
+# Get files from the latest toolcall
+TOOLCALL_RESULT=$(refly workflow toolcalls "$RUN_ID" --files --latest)
+
+# Check if files exist
+FILES=$(echo "$TOOLCALL_RESULT" | jq -r '.payload.files // empty')
+if [ -z "$FILES" ] || [ "$FILES" = "null" ]; then
+  echo "No files generated. Check workflow status:"
+  refly workflow detail "$RUN_ID"
+  exit 1
+fi
+
+# Download and open each file
+echo "$FILES" | jq -c '.[]' | while read -r file; do
+  FILE_ID=$(echo "$file" | jq -r '.fileId')
+  FILE_NAME=$(echo "$file" | jq -r '.name')
+  if [ -n "$FILE_ID" ] && [ "$FILE_ID" != "null" ]; then
+    refly file download "$FILE_ID" -o "$HOME/Desktop/${FILE_NAME}"
+    echo "Downloaded: $HOME/Desktop/${FILE_NAME}"
+    open "$HOME/Desktop/${FILE_NAME}"
+  fi
+done
+```
+
+**Expected Output**: Files downloaded to `~/Desktop/` and opened automatically
+
+---
+
+## Pattern B: Text/Data Skills
+
+**Use for**: Skills with `category: text-data` (search, research, report, analytics skills)
+
+```bash
+# Get text content from toolcalls
+TOOLCALL_RESULT=$(refly workflow toolcalls "$RUN_ID" --files --latest)
+
+# Extract content from nodes
+CONTENT=$(echo "$TOOLCALL_RESULT" | jq -r '.payload.nodes[].content // empty')
+if [ -z "$CONTENT" ]; then
+  echo "No content returned. Check workflow status:"
+  refly workflow detail "$RUN_ID"
+  exit 1
+fi
+
+echo "$CONTENT"
+```
+
+**Expected Output**: Text content displayed to user
+
+---
+
+## Pattern C: Action Skills
+
+**Use for**: Skills with `category: action` (email, messaging, CRM integration skills)
+
+```bash
+# Confirm action completed
+DETAIL=$(refly workflow detail "$RUN_ID")
+STATUS=$(echo "$DETAIL" | jq -r '.payload.status')
+
+if [ "$STATUS" = "finish" ]; then
+  echo "Action completed successfully"
+else
+  echo "Action status: $STATUS"
+  echo "$DETAIL" | jq '.payload'
+fi
+```
+
+**Expected Output**: Status confirmation (finish = success)
+
+---
+
+## Workflow Status Values
+
+| Status | Description | Action |
+|--------|-------------|--------|
+| `init` | Workflow is initializing | Wait |
+| `executing` | Workflow is running | Wait |
+| `finish` | Workflow completed successfully | Get results |
+| `failed` | Workflow encountered an error | Check error details |
+
+---
+
+## Error Handling
+
+### Check CLI Response
+```bash
+RESULT=$(refly skill run --id <installationId> --input '<json>')
+if [ "$(echo "$RESULT" | jq -r '.ok')" != "true" ]; then
+  echo "Error: $(echo "$RESULT" | jq -r '.error.message')"
+  echo "Hint: $(echo "$RESULT" | jq -r '.hint // empty')"
+fi
+```
+
+### Check Workflow Failed
+```bash
+DETAIL=$(refly workflow detail "$RUN_ID")
+STATUS=$(echo "$DETAIL" | jq -r '.payload.status')
+if [ "$STATUS" = "failed" ]; then
+  echo "Workflow failed. Details:"
+  echo "$DETAIL" | jq '.payload.nodes[] | select(.status == "failed")'
+fi
+```
+
+### No Files or Content Returned
+```bash
+# Get verbose output to debug
+refly workflow toolcalls "$RUN_ID" --raw
+```
+
+---
+
+## Troubleshooting
+
+### Get Full Workflow Details
+```bash
+refly workflow detail "$RUN_ID"
+```
+
+### Get All Toolcalls (Verbose)
+```bash
+refly workflow toolcalls "$RUN_ID" --raw
+```
+
+### Filter Toolcalls by Status
+```bash
+refly workflow toolcalls "$RUN_ID" --status completed
+refly workflow toolcalls "$RUN_ID" --status failed
+```
+
+### Check Authentication
+```bash
+refly status
+```
+
+### List Installed Skills
+```bash
+refly skill installations
+```
+
+---
+
+## Required Behavior
+
+1. **CLI only** - Use `refly <command>`, never call API directly
+2. **Trust JSON** - Only trust CLI JSON (`ok`, `payload`, `error`, `hint`)
+3. **No fabricated IDs** - Never invent workflow/run/node IDs
+4. **Stop on error** - If `ok=false`, stop and show `hint`
+5. **Use correct IDs** - `skpi-xxx` for run, `we-xxx` for workflow commands