Refly

Rules

• CLI only - Use refly <command> , never call API directly.

• Trust JSON - Only trust CLI JSON (ok , payload , error , hint ).

• No fabricated IDs - Never invent workflow/run/node IDs.

• No tokens - Never print or request auth tokens.

• Stop on error - If ok=false , stop and show hint .

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

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

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

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"

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

~/.refly/skills/ ├── base/ # Base skill files (this symlink target) │ ├── SKILL.md │ └── rules/ │ ├── execution.md │ ├── workflow.md │ ├── node.md │ ├── file.md │ └── skill.md └── <skill-name>/ # Domain skill directories └── SKILL.md

~/.claude/skills/ ├── refly → ~/.refly/skills/base/ # Base skill symlink └── <skill-name> → ~/.refly/skills/<name>/ # Domain skill symlinks

Routing

User intent -> match domain skill (name/trigger) in ~/.claude/skills/

-> read domain skill SKILL.md -> execute via refly skill run -> return CLI-verified result.

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

• rules/skill.md

• Customized Skill command reference