/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 $I