/output-workflow-start

name: output-workflow-start
description: Start an Output SDK workflow asynchronously without waiting for completion. Use when starting long-running workflows, getting a workflow ID for later monitoring, running workflows in the background, or executing multiple workflows in parallel.
allowed-tools: [Bash, Read, Write]

Start Workflow Asynchronously

Overview

This skill starts a workflow asynchronously, meaning the command returns immediately with a workflow ID while the workflow executes in the background. Use this for long-running workflows or when you need to run multiple workflows in parallel.

When to Use This Skill

• Starting workflows that take minutes or hours
• Running multiple workflows in parallel
• When you need to disconnect and check results later
• Monitoring workflow progress separately
• When you need the workflow ID immediately for tracking

When to Use Sync Instead

Consider using `npx output workflow run` (sync) when:

• Workflow completes quickly (seconds)
• You need the result immediately in your terminal
• Simple testing during development
• You want a single command with the result

Instructions

Basic Syntax

npx output workflow start <workflowName> --input '<json-input>'
npx output workflow start <workflowName> --input <path-to-json-file>

The `--input` flag is required when the workflow expects input data.

Input Methods

1. Inline JSON

Pass JSON directly on the command line:

npx output workflow start data-migration --input '{"batchSize": 1000}'

2. File Path (Recommended)

Reference a JSON file containing the input:

npx output workflow start data-migration --input src/data_migration/scenarios/large_batch.json

This is the recommended approach because:

• Input is version controlled and reproducible
• Complex inputs are easier to read and edit
• Scenarios can be shared and reused

Getting the Workflow ID

The command outputs the workflow ID which you'll need for:

• Checking status: `npx output workflow status <id>`
• Getting results: `npx output workflow result <id>`
• Debugging: `npx output workflow debug <id>`

Examples

**Scenario**: Start a long-running workflow with scenario file

npx output workflow start data-migration --input src/data_migration/scenarios/full_migration.json

# Output:
# Started workflow: data-migration
# Workflow ID: abc123xyz
# Use 'npx output workflow status abc123xyz' to check progress

**Scenario**: Start multiple workflows in parallel using scenario files

# Start several workflows with different scenario files
npx output workflow start process-batch --input src/process_batch/scenarios/batch_1.json
npx output workflow start process-batch --input src/process_batch/scenarios/batch_2.json
npx output workflow start process-batch --input src/process_batch/scenarios/batch_3.json

# Note: Save the workflow IDs to check them later

**Scenario**: Create scenario then start workflow

# Create a scenario file
mkdir -p src/generate_report/scenarios
cat > src/generate_report/scenarios/annual_2024.json << 'EOF'
{
  "year": 2024,
  "includeCharts": true,
  "format": "pdf"
}
EOF

# Start the workflow
npx output workflow start generate-report --input src/generate_report/scenarios/annual_2024.json
# Output: Workflow ID: report-2024-abc

# Check status periodically
npx output workflow status report-2024-abc
# Output: Status: RUNNING

# Later, check again
npx output workflow status report-2024-abc
# Output: Status: COMPLETED

# Get the result
npx output workflow result report-2024-abc

**Scenario**: Quick inline test for development

npx output workflow start quick-job --input '{"test": true}'

**Scenario**: Script for parallel execution

# Start workflows and capture IDs
ID1=$(npx output workflow start job --input src/job/scenarios/type_a.json | grep "Workflow ID" | cut -d: -f2 | tr -d ' ')
ID2=$(npx output workflow start job --input src/job/scenarios/type_b.json | grep "Workflow ID" | cut -d: -f2 | tr -d ' ')

# Wait and check results
npx output workflow result $ID1
npx output workflow result $ID2

Following Up After Starting

Check Status

npx output workflow status <workflowId>

Status values:

• **RUNNING**: Still executing
• **COMPLETED**: Finished successfully
• **FAILED**: Encountered an error
• **TERMINATED**: Was manually stopped

Get Result

npx output workflow result <workflowId>

Only works for COMPLETED workflows. For FAILED workflows, use debug.

Debug If Failed

npx output workflow debug <workflowId> --json

Stop If Needed

npx output workflow stop <workflowId>

Workflow ID Management

When starting multiple workflows, keep track of IDs:

# Log IDs to a file
npx output workflow start batch-job --input src/batch_job/scenarios/id_1.json >> workflow-ids.txt
npx output workflow start batch-job --input src/batch_job/scenarios/id_2.json >> workflow-ids.txt

# Or use a naming convention in your workflow that makes IDs predictable

Best Practices

1. **Use scenario files**: Store inputs in `src/<workflow>/scenarios/` for reproducibility 2. **Save the workflow ID**: Always note the ID for later reference 3. **Monitor long workflows**: Use `npx output workflow status` to check progress 4. **Handle failures**: Check status before getting results 5. **Clean up**: Stop any stuck workflows with `npx output workflow stop`

Related Commands

• `npx output workflow run <name> --input` - Execute synchronously
• `npx output workflow status <id>` - Check execution status
• `npx output workflow result <id>` - Get execution result
• `npx output workflow stop <id>` - Stop a running workflow
• `npx output workflow debug <id>` - Debug a workflow execution