Skip to content

pull-command.md

Latest commit

 

History

History
310 lines (235 loc) · 7.79 KB

pull-command.md

File metadata and controls

310 lines (235 loc) · 7.79 KB
Raw

workflow pull — Export Workflows from Platform

Pull (export) existing platform workflows to local .workflow.yaml definition files for version control, local editing, or transfer to another instance.

Usage

# Pull by workflow UUID
workflow pull abc123-def456-7890-abcd-ef1234567890

# Pull to a specific output file
workflow pull abc123-def456-... -o invoices.workflow.yaml

# Pull by workflow name (fuzzy match)
workflow pull "Invoice Processing"
workflow pull "Invoice"

Options

Option Short Description
IDENTIFIER Workflow UUID or name to pull
--output -o Output file path. Defaults to <slugified-name>.workflow.yaml

How It Works

The pull command follows a multi-stage workflow:

  1. Resolve Identifier — Determines if input is a UUID or name, resolves to workflow ID
  2. Fetch Workflow Data — Gets workflow, nodes, edges, and metadata via API
  3. Reverse-Resolve Dependencies — Converts server-side UUIDs to human-readable names:
    • agent_id → agent_name (via API lookup)
    • knowledge_base_id → knowledge_base_name (via API lookup)
  4. Convert to WDF — Transforms API response to .workflow.yaml format:
    • Generates readable node slugs from function_name (fallback: config_type)
    • Handles slug collisions with _2, _3 suffixes
    • Maps entry/exit UUIDs to slugs
    • Strips visual-only data (positions, edge paths)
  5. Write .workflow.yaml — Serializes WDF to YAML
  6. Write .workflow.lock — Saves lockfile with slug-to-UUID mappings

Slug Generation

Node slugs in the YAML file are generated from server-side data:

Priority Source Example
1st function_name (if set) invoice_agent
2nd config_type (fallback) llm-call

Slug rules:

  • Derived from function_name: lowercased, underscores preserved (for backend variable reference compatibility)
  • Derived from config_type (fallback): lowercased, underscores converted to hyphens
  • Collisions resolved with numeric suffixes: agent, agent_2, agent_3

Name-Based Lookup

When pulling by name instead of UUID:

Single Match

workflow pull "Invoice Processing Pipeline"
# Finds exact match, pulls immediately

Partial Match

workflow pull "Invoice"
# If only one workflow contains "Invoice" in its name, pulls it

Multiple Matches (Interactive Selection)

workflow pull "Invoice"

# Multiple workflows match "Invoice":
#   1. Invoice Processing Pipeline (abc123...)
#   2. Invoice Approval Flow (def456...)
# Select a workflow: 1

Reverse Dependency Resolution

Agent UUIDs → Names

On the platform (stored as UUID):

{
  "config": {
    "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "primaryInput": "{{<uuid>.output.text}}"
  }
}

After pull (in .workflow.yaml):

nodes:
  my-agent:
    type: agent
    execution_mode: MESSAGES
    config:
      agent_name: Customer Support Agent
      primaryInput: "{{user_input.output.text}}"

Knowledge Base UUIDs → Names

On the platform (stored as UUID):

{
  "config": {
    "knowledge_base_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "topK": 5
  }
}

After pull (in .workflow.yaml):

nodes:
  retrieval:
    type: retrieve
    execution_mode: FLOW
    config:
      knowledge_base_name: Company Policies
      topK: 5

If a UUID cannot be resolved (e.g., agent was deleted), it remains as-is in the config.

Lockfile Generation

The pull command writes a .workflow.lock file alongside the YAML, enabling subsequent push operations to update instead of create:

# Auto-generated by workflow CLI. Do not edit manually.
workflow_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
organization_id: 11111111-2222-3333-4444-555555555555
version: 1
instance: https://api.sb.allogy.com
nodes:
  user-input: 22222222-3333-4444-5555-666666666666
  invoice-agent: 33333333-4444-5555-6666-777777777777
  result: 44444444-5555-6666-7777-888888888888
edges:
  user-input->invoice-agent: 10001
  invoice-agent->result: 10002
pushed_at: '2026-02-18T14:30:00+00:00'

This means workflow pull + workflow push forms a round-trip: pull a workflow, modify it locally, push it back to update in place.

Configuration

The pull command requires CLI configuration (same as other commands):

Environment variables:

export WORKFLOW_API_HOST=https://api.sb.allogy.com
export WORKFLOW_API_KEY=your-api-key
export WORKFLOW_ORG_ID=your-org-uuid
# Optional: user JWT sent as a Bearer token for endpoints that reject API-key auth.
export WORKFLOW_JWT=your-jwt-access-token

Or CLI flags:

workflow pull abc123 \
  --host https://api.sb.allogy.com \
  --api-key your-api-key \
  --org your-org-uuid

See README.md for full configuration details.

Examples

Pull by UUID

workflow pull a1b2c3d4-e5f6-7890-abcd-ef1234567890

# Output:
# Pulling workflow: a1b2c3d4-e5f6-7890-abcd-ef1234567890
# Fetching workflow data... ✓ (5 nodes, 4 edges)
# Resolving dependencies... ✓ (1 resolved)
# Converting to WDF... ✓
# Writing invoice-processing-pipeline.workflow.yaml... ✓
# Writing lockfile... ✓ invoice-processing-pipeline.workflow.lock
# Pulled workflow: invoice-processing-pipeline.workflow.yaml

Pull to Custom Path

workflow pull a1b2c3d4-... -o workflows/invoices.workflow.yaml

# Output:
# ...
# Writing invoices.workflow.yaml... ✓
# Writing lockfile... ✓ invoices.workflow.lock
# Pulled workflow: workflows/invoices.workflow.yaml

Pull by Name

workflow pull "Invoice Processing"

# Output:
# Searching for workflow: "Invoice Processing"
# Found workflow: a1b2c3d4-...
# Fetching workflow data... ✓ (5 nodes, 4 edges)
# ...

Round-Trip: Pull, Modify, Push

# 1. Pull workflow from staging
workflow pull "Customer Support" -o support.workflow.yaml \
  --host https://stage.sb.allogy.com

# 2. Edit locally
vim support.workflow.yaml

# 3. Validate changes
workflow validate support.workflow.yaml

# 4. Push back to staging
workflow push support.workflow.yaml

# Or push to production
workflow push support.workflow.yaml --host https://api.sb.allogy.com

Error Handling

Workflow Not Found

workflow pull 00000000-0000-0000-0000-000000000000

# Output:
# Error: Failed to fetch workflow data: 404 Not Found

Name Not Found

workflow pull "Nonexistent Workflow"

# Output:
# Searching for workflow: "Nonexistent Workflow"
# Error: No workflow found matching "Nonexistent Workflow"

Missing Configuration

workflow pull abc123

# Output:
# Error: Missing required configuration: host

Integration with Other Commands

Licensing Workflow (Export & Deliver)

# Pull from internal instance
workflow pull "Invoice Processing" -o licensed-workflow.workflow.yaml

# Validate the export
workflow validate licensed-workflow.workflow.yaml

# Deliver to customer instance
workflow push licensed-workflow.workflow.yaml \
  --host https://customer.api.example.com \
  --api-key customer-api-key \
  --org customer-org-uuid

Backup All Workflows

#!/bin/bash
# backup-workflows.sh

mkdir -p backups

# List all workflows, pull each one
workflow list --format json | jq -r '.[].id' | while read id; do
  echo "Pulling $id..."
  workflow pull "$id" -o "backups/$id.workflow.yaml"
done

echo "Backup complete!"

Reference

  • Jira Ticket: RAG-952 (Pull Command)
  • Related Commands: workflow push, workflow validate, workflow list
  • Dependencies: RAG-946 (API Client), RAG-945 (WDF Schema), RAG-949 (Lockfile)
  • API Endpoints: GET /v1/workflows/{id}, GET /v1/workflow-nodes/, GET /v1/workflow-edges/, GET /v1/workflow-metadata/{id}
  • WDF Schema: See docs/validate-command.md for node types