Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.output.ai/llms.txt

Use this file to discover all available pages before exploring further.

You’ve defined a workflow. Now you need to run it. Output gives you two execution modes:
  • Synchronous — output workflow run executes the workflow and waits for the result. Use this during development and for short-lived workflows.
  • Asynchronous — output workflow start kicks off the workflow and returns immediately. Use status and result to check on it later. Use this for long-running workflows or batch jobs.
Both modes accept input the same way: either a scenario file or inline JSON. Scenario files are covered at the end of this page.

​
Running a Workflow

output workflow run executes a workflow and waits for the result: 
# Using a scenario file (recommended)
output workflow run lead_enrichment acme

# Using inline JSON
output workflow run lead_enrichment --input '{"companyDomain": "acme.com"}'

# Using a JSON file path
output workflow run lead_enrichment --input ./test_input.json
The command blocks until the workflow completes, then prints the output: 
Using scenario: src/workflows/lead_enrichment/scenarios/acme.json

Executing workflow: lead_enrichment...

Workflow ID: lead_enrichment-22b798f9-4812-4f48-80b2-89fac07285ed

Output:
{
  "company": "Acme Corp",
  "summary": "Enterprise software company focused on..."
}
Use --format json if you need machine-readable output, for example when piping to another command or in scripts: 
output workflow run lead_enrichment acme --format json
If the workflow fails, the command prints the error and exits with code 1.
FlagDefaultDescription
--input, -i—JSON string or file path (overrides scenario)
--catalog, -cOUTPUT_CATALOG_IDCatalog name (the deprecated --task-queue, -q aliases still work)
--format, -ftextOutput format: json, text

​
Starting a Workflow Asynchronously

output workflow start fires off a workflow without waiting. It returns a workflow ID immediately: 
output workflow start lead_enrichment acme

Workflow started successfully

Workflow ID: lead_enrichment-a1b2c3d4-5678-90ab-cdef-1234567890ab

Use "workflow status <workflow-id>" to check the workflow status
Use "workflow result <workflow-id>" to get the workflow result when complete
This is the right choice when:
  • The workflow takes minutes or longer to complete
  • You’re launching multiple workflows in a batch
  • You want to check results later rather than keeping a terminal open
The flags are the same as run, minus --format (there’s no result to format yet).

​
Checking Status

Poll a running workflow with output workflow status: 
output workflow status lead_enrichment-a1b2c3d4-5678-90ab-cdef-1234567890ab

Workflow ID: lead_enrichment-a1b2c3d4-5678-90ab-cdef-1234567890ab
Status: running

Started At: 2026-03-06T10:30:45.123Z
The status will be one of:
StatusMeaning
runningStill executing
completedFinished successfully
failedCompleted with an error
canceledStopped gracefully via workflow stop
terminatedForce-stopped via workflow terminate
timed_outExceeded the execution timeout

​
Getting Results

Once a workflow completes, retrieve its output with output workflow result: 
output workflow result lead_enrichment-a1b2c3d4-5678-90ab-cdef-1234567890ab

Workflow ID: lead_enrichment-a1b2c3d4-5678-90ab-cdef-1234567890ab

Output:
{
  "company": "Acme Corp",
  "summary": "Enterprise software company focused on..."
}
If the workflow failed, you’ll see the error instead: 
Workflow ID: lead_enrichment-a1b2c3d4-5678-90ab-cdef-1234567890ab

Status: failed
Error: Step 'lookup_company' failed: 404 Not Found
Use --format json for the full structured response including status, output, and error fields.

​
Debugging Execution

When something goes wrong — or you just want to understand what happened — use output workflow debug to see the execution trace: 
output workflow debug lead_enrichment-a1b2c3d4-5678-90ab-cdef-1234567890ab
This prints a tree showing every step that ran, what it received, what it returned, and how long it took: 
Trace Log:
──────────────────────────────────────────────────────────────────────────────
┌─ [lead_enrichment] completed
│  ├─ [lookup_company] [END] 150ms
│  │  ├─ input: {"companyDomain":"acme.com"}
│  │  └─ output: {"name":"Acme Corp","domain":"acme.com",...}
│  └─ [generate_summary] [END] 1200ms
│     ├─ input: {"name":"Acme Corp","domain":"acme.com",...}
│     └─ output: "Enterprise software company focused on..."
──────────────────────────────────────────────────────────────────────────────
The text format truncates long values for readability. Use --format json to get the full untruncated trace — this is especially useful when you need to see complete LLM inputs and outputs: 
output workflow debug lead_enrichment-a1b2c3d4-5678-90ab-cdef-1234567890ab --format json
Traces are also saved as JSON files in your project’s logs/runs/ directory. You can open these directly, share them with teammates, or feed them to Claude Code for analysis.

​
Stopping Workflows

If you need to cancel a running workflow:
  • output workflow stop <workflowId> — Graceful cancellation. The workflow has a chance to clean up.
  • output workflow terminate <workflowId> — Immediate kill. Use for stuck workflows or cleanup after branch switches.
# Graceful stop
output workflow stop lead_enrichment-a1b2c3d4

# Force terminate with a reason
output workflow terminate lead_enrichment-a1b2c3d4 --reason "Cleaning up old runs"

​
Rerunning From a Step

When a workflow fails late — or you’ve edited a prompt that only affects a downstream step — you usually don’t want to re-run the whole thing. Early steps may have made expensive LLM calls, or slow API requests whose results haven’t changed. output workflow reset creates a new run that replays up to a given completed step (reusing its recorded output), then re-executes every step after it: 
# After editing a prompt used by `generate_blog_post`, rerun just the steps
# after `consolidate_competitors` — the upstream competitor analysis is reused.
output workflow reset lead_enrichment-a1b2c3d4 \
  --step consolidate_competitors \
  --reason "Retry with updated blog-post prompt"
Find valid step names with output workflow debug <workflowId> --format json. The step itself is not re-executed; only the steps after it.

​
Quick Reference

What you want to doCommand
Run and wait for resultoutput workflow run <name> [scenario]
Start without waitingoutput workflow start <name> [scenario]
Check if still runningoutput workflow status <workflowId>
Get the final outputoutput workflow result <workflowId>
See the execution traceoutput workflow debug <workflowId>
Stop gracefullyoutput workflow stop <workflowId>
Force stopoutput workflow terminate <workflowId>
Rerun from after a stepoutput workflow reset <workflowId> --step <stepName>
For the full CLI reference including all flags and additional commands like workflow cost and workflow test, see the CLI package docs.

​
Scenario Files

A scenario file is a plain JSON file that contains the input for a workflow run. It lives in the workflow’s scenarios/ directory and matches the workflow’s inputSchema: 
src/workflows/lead_enrichment/
├── workflow.ts
├── steps.ts
└── scenarios/
    ├── acme.json
    └── small_company.json
scenarios/acme.json
{
  "companyDomain": "acme.com"
}
Scenarios are useful because they’re repeatable — you can re-run the same input without retyping it, share them with teammates, and check them into version control. Think of them as saved test inputs for your workflow. The scenario name is the filename without .json. To run with the acme scenario: 
output workflow run lead_enrichment acme