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>

Start and Watch in One Command

Add --monitor (-m) to attach immediately after starting and stream step updates until the workflow ends, instead of polling workflow status:

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

This attaches to the exact run that was just started. Ctrl+C detaches without stopping the workflow (exit 130), and the command exits 1 if the workflow fails. If monitoring itself drops (an API restart, a reset connection), the workflow keeps running and the command exits 3 instead — so a retry keyed on a failed workflow can't re-submit one that is already in flight.

Monitoring reports progress, not the return value; the command closes by naming the follow-up — npx output workflow result <id> after a run that completed, npx output workflow debug <id> after one that failed.

These flags tune the stream and require --monitor:

Flag	Default	Description
--interval	2500	Poll interval in milliseconds
--include-payloads	false	Include decoded step input/output payloads
--color	true	Colorize status output (--no-color to disable)

--monitor cannot be combined with --json. Under --json the CLI suppresses progress output and prints one JSON object at the end, so the stream would be silently swallowed and the command would look hung until the workflow finished. To get JSON, either use npx output workflow run --json (wait for the result), or start without --monitor and attach with npx output workflow monitor <id> --format json (streaming NDJSON).

Prefer --monitor over a workflow status polling loop when you're watching a single workflow through to completion. Keep the plain async form when starting several workflows in parallel, since --monitor blocks until the run ends.

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 monitor <id> - Attach to a run already in progress
• 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