@output.ai/cli 0.4.2 → 0.5.0

package/dist/templates/agent_instructions/skills/output-workflow-runs-list/SKILL.md.template

@@ -0,0 +1,141 @@
+---
+name: output-workflow-runs-list
+description: List Output SDK workflow execution history. Use when finding failed runs, reviewing past executions, identifying workflow IDs for debugging, filtering runs by workflow type, or investigating recent workflow activity.
+allowed-tools: [Bash]
+---
+
+# List Workflow Execution History
+
+## Overview
+
+This skill helps you view the execution history of workflows. Use it to find failed runs, identify workflow IDs for debugging, and review past executions.
+
+## When to Use This Skill
+
+- Finding recent failed workflow runs
+- Getting a workflow ID for debugging
+- Reviewing execution history for a specific workflow
+- Investigating when a problem started occurring
+- Checking the status of recent executions
+
+## Instructions
+
+### List All Recent Runs
+
+```bash
+output workflow runs list
+```
+
+By default, this shows the 100 most recent workflow executions across all workflow types.
+
+### Available Flags
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--limit <n>` | Number of runs to display | 100 |
+| `--format <type>` | Output format: table, json, text | table |
+
+### Filter by Workflow Name
+
+```bash
+output workflow runs list <workflowName>
+```
+
+This shows only runs for the specified workflow type.
+
+### Get Detailed JSON Output
+
+```bash
+output workflow runs list --format json
+```
+
+Use JSON format for programmatic analysis or when you need full details.
+
+## Understanding the Output
+
+### Status Values
+
+| Status | Meaning | Action |
+|--------|---------|--------|
+| RUNNING | Workflow is currently executing | Wait or monitor |
+| COMPLETED | Workflow finished successfully | No action needed |
+| FAILED | Workflow encountered an error | Debug with trace |
+| TERMINATED | Workflow was manually stopped | Review if expected |
+| TIMED_OUT | Workflow exceeded time limit | Check for long operations |
+
+### Key Fields
+
+When viewing runs, pay attention to:
+
+- **Workflow ID**: Unique identifier needed for debugging commands
+- **Status**: Current execution state
+- **Start Time**: When the execution began
+- **End Time**: When the execution completed (if finished)
+- **Workflow Name**: The type of workflow that ran
+
+## Examples
+
+**Scenario**: Find failed workflow runs
+
+```bash
+# List recent runs and look for FAILED status
+output workflow runs list --limit 20
+
+# Or use JSON format with jq to filter
+output workflow runs list --format json | jq '.[] | select(.status == "FAILED")'
+```
+
+**Scenario**: Get workflow ID for debugging
+
+```bash
+# List runs for a specific workflow
+output workflow runs list my-workflow --limit 5
+
+# Note the workflow ID from the output (e.g., "abc123xyz")
+# Then debug it
+output workflow debug abc123xyz --format json
+```
+
+**Scenario**: Review recent activity for a specific workflow
+
+```bash
+# See the last 10 runs of the data-pipeline workflow
+output workflow runs list data-pipeline --limit 10
+```
+
+**Scenario**: Export run history for analysis
+
+```bash
+# Get all recent runs as JSON for external analysis
+output workflow runs list --format json > workflow-runs.json
+```
+
+**Scenario**: Find when failures started
+
+```bash
+# Look at more history to find patterns
+output workflow runs list --limit 50 --format json | jq 'group_by(.status) | map({status: .[0].status, count: length})'
+```
+
+## Identifying Problems
+
+### Signs of Issues
+
+1. **Multiple FAILED runs**: Indicates a persistent bug
+2. **Mix of COMPLETED and FAILED**: Could be input-dependent issues
+3. **All recent runs TERMINATED**: Someone may be stopping workflows
+4. **Long RUNNING times**: Possible hang or performance issue
+
+### Next Steps After Finding a Failed Run
+
+1. Copy the workflow ID from the run
+2. Get the execution trace: `output workflow debug <workflowId> --format json`
+3. Analyze the trace to identify the failure
+4. Apply the appropriate fix based on the error pattern
+
+## Related Commands
+
+- `output workflow debug <id>` - Analyze execution trace
+- `output workflow status <id>` - Check current status
+- `output workflow result <id>` - Get execution result
+- `output workflow list` - List available workflows

package/dist/templates/agent_instructions/skills/output-workflow-start/SKILL.md.template

@@ -0,0 +1,201 @@
+---
+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 `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
+
+```bash
+output workflow start <workflowName> --input '<json-input>'
+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:
+
+```bash
+output workflow start data-migration --input '{"batchSize": 1000}'
+```
+
+#### 2. File Path (Recommended)
+
+Reference a JSON file containing the input:
+
+```bash
+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: `output workflow status <id>`
+- Getting results: `output workflow result <id>`
+- Debugging: `output workflow debug <id>`
+
+## Examples
+
+**Scenario**: Start a long-running workflow with scenario file
+
+```bash
+output workflow start data-migration --input src/data_migration/scenarios/full_migration.json
+
+# Output:
+# Started workflow: data-migration
+# Workflow ID: abc123xyz
+# Use 'output workflow status abc123xyz' to check progress
+```
+
+**Scenario**: Start multiple workflows in parallel using scenario files
+
+```bash
+# Start several workflows with different scenario files
+output workflow start process-batch --input src/process_batch/scenarios/batch_1.json
+output workflow start process-batch --input src/process_batch/scenarios/batch_2.json
+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
+
+```bash
+# 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
+output workflow start generate-report --input src/generate_report/scenarios/annual_2024.json
+# Output: Workflow ID: report-2024-abc
+
+# Check status periodically
+output workflow status report-2024-abc
+# Output: Status: RUNNING
+
+# Later, check again
+output workflow status report-2024-abc
+# Output: Status: COMPLETED
+
+# Get the result
+output workflow result report-2024-abc
+```
+
+**Scenario**: Quick inline test for development
+
+```bash
+output workflow start quick-job --input '{"test": true}'
+```
+
+**Scenario**: Script for parallel execution
+
+```bash
+# Start workflows and capture IDs
+ID1=$(output workflow start job --input src/job/scenarios/type_a.json | grep "Workflow ID" | cut -d: -f2 | tr -d ' ')
+ID2=$(output workflow start job --input src/job/scenarios/type_b.json | grep "Workflow ID" | cut -d: -f2 | tr -d ' ')
+
+# Wait and check results
+output workflow result $ID1
+output workflow result $ID2
+```
+
+## Following Up After Starting
+
+### Check Status
+
+```bash
+output workflow status <workflowId>
+```
+
+Status values:
+- **RUNNING**: Still executing
+- **COMPLETED**: Finished successfully
+- **FAILED**: Encountered an error
+- **TERMINATED**: Was manually stopped
+
+### Get Result
+
+```bash
+output workflow result <workflowId>
+```
+
+Only works for COMPLETED workflows. For FAILED workflows, use debug.
+
+### Debug If Failed
+
+```bash
+output workflow debug <workflowId> --format json
+```
+
+### Stop If Needed
+
+```bash
+output workflow stop <workflowId>
+```
+
+## Workflow ID Management
+
+When starting multiple workflows, keep track of IDs:
+
+```bash
+# Log IDs to a file
+output workflow start batch-job --input src/batch_job/scenarios/id_1.json >> workflow-ids.txt
+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 `output workflow status` to check progress
+4. **Handle failures**: Check status before getting results
+5. **Clean up**: Stop any stuck workflows with `output workflow stop`
+
+## Related Commands
+
+- `output workflow run <name> --input` - Execute synchronously
+- `output workflow status <id>` - Check execution status
+- `output workflow result <id>` - Get execution result
+- `output workflow stop <id>` - Stop a running workflow
+- `output workflow debug <id>` - Debug a workflow execution

package/dist/templates/agent_instructions/skills/output-workflow-status/SKILL.md.template

@@ -0,0 +1,151 @@
+---
+name: output-workflow-status
+description: Check the status of an Output SDK workflow execution. Use when monitoring a running workflow, checking if a workflow completed, or determining workflow state (RUNNING, COMPLETED, FAILED, TERMINATED).
+allowed-tools: [Bash]
+---
+
+# Check Workflow Execution Status
+
+## Overview
+
+This skill checks the current execution status of a workflow. Use it to monitor running workflows, verify completion, or determine if a workflow failed before attempting to get its result.
+
+## When to Use This Skill
+
+- Monitoring a workflow started asynchronously
+- Checking if a workflow has completed
+- Determining why you can't get a workflow result
+- Verifying workflow state before taking action
+- Polling for completion in scripts
+
+## When to Use Other Commands
+
+- **Getting results**: Use `output workflow result` after confirming COMPLETED status
+- **Debugging failures**: Use `output workflow debug` for FAILED workflows
+- **Execution history**: Use `output workflow runs list` for multiple runs
+
+## Instructions
+
+### Check Status
+
+```bash
+output workflow status <workflowId>
+```
+
+Replace `<workflowId>` with the ID from `output workflow start` or `output workflow runs list`.
+
+## Understanding Status Values
+
+| Status | Meaning | Next Action |
+|--------|---------|-------------|
+| RUNNING | Workflow is currently executing | Wait and check again |
+| COMPLETED | Workflow finished successfully | Get result with `output workflow result` |
+| FAILED | Workflow encountered an error | Debug with `output workflow debug` |
+| TERMINATED | Workflow was manually stopped | Review if expected, restart if needed |
+| TIMED_OUT | Workflow exceeded time limit | Check for long operations, adjust timeout |
+
+## Examples
+
+**Scenario**: Monitor a running workflow
+
+```bash
+# Start a workflow
+output workflow start data-sync '{"source": "external"}'
+# Output: Workflow ID: sync-abc123
+
+# Check status
+output workflow status sync-abc123
+# Output: Status: RUNNING
+
+# Wait and check again
+sleep 30
+output workflow status sync-abc123
+# Output: Status: COMPLETED
+```
+
+**Scenario**: Poll for completion in a script
+
+```bash
+WORKFLOW_ID="abc123xyz"
+
+while true; do
+  STATUS=$(output workflow status $WORKFLOW_ID)
+  echo "Current status: $STATUS"
+
+  if [[ "$STATUS" == *"COMPLETED"* ]]; then
+    echo "Workflow completed!"
+    output workflow result $WORKFLOW_ID
+    break
+  elif [[ "$STATUS" == *"FAILED"* ]]; then
+    echo "Workflow failed!"
+    output workflow debug $WORKFLOW_ID --format json
+    break
+  fi
+
+  sleep 10
+done
+```
+
+**Scenario**: Check before getting result
+
+```bash
+# Verify status first
+output workflow status my-workflow-123
+
+# If COMPLETED, get result
+output workflow result my-workflow-123
+
+# If FAILED, debug instead
+output workflow debug my-workflow-123 --format json
+```
+
+**Scenario**: Batch status check
+
+```bash
+# Check multiple workflows
+for id in abc123 def456 ghi789; do
+  echo "Workflow $id: $(output workflow status $id)"
+done
+```
+
+## Status Transitions
+
+Workflows typically follow these paths:
+
+```
+RUNNING -> COMPLETED (success)
+RUNNING -> FAILED (error occurred)
+RUNNING -> TERMINATED (manually stopped)
+RUNNING -> TIMED_OUT (exceeded limit)
+```
+
+## Interpreting Status Output
+
+The status command returns information including:
+- **Status**: Current state (RUNNING, COMPLETED, FAILED, etc.)
+- **Duration**: How long the workflow has been running or ran
+- **Start Time**: When the workflow began
+
+## Troubleshooting
+
+### "Workflow not found"
+- The workflow ID may be incorrect
+- The workflow may have been deleted from history
+- Check `output workflow runs list` to find the correct ID
+
+### Status stays RUNNING too long
+1. Check if the workflow is stuck: `output workflow debug <id>`
+2. Look for infinite loops or waiting operations
+3. Consider stopping: `output workflow stop <id>`
+
+### Unexpected TERMINATED status
+- Someone may have manually stopped the workflow
+- Check with `output workflow debug` for context
+- Restart if needed: `output workflow start`
+
+## Related Commands
+
+- `output workflow result <id>` - Get execution result (after COMPLETED)
+- `output workflow debug <id>` - Debug execution (after FAILED)
+- `output workflow stop <id>` - Stop a running workflow
+- `output workflow runs list` - View execution history

package/dist/templates/agent_instructions/skills/output-workflow-stop/SKILL.md.template

@@ -0,0 +1,164 @@
+---
+name: output-workflow-stop
+description: Stop a running Output SDK workflow execution. Use when cancelling a workflow, stopping a long-running process, terminating a stuck workflow, or when you need to abort a workflow in progress.
+allowed-tools: [Bash]
+---
+
+# Stop Running Workflow
+
+## Overview
+
+This skill stops a running workflow execution. The workflow will be marked as TERMINATED and will not complete its remaining steps. Use this carefully as it cannot be undone.
+
+## When to Use This Skill
+
+- Cancelling a workflow that's no longer needed
+- Stopping a workflow that appears stuck
+- Terminating a long-running workflow to free resources
+- Aborting a workflow with incorrect input
+- Emergency stop during unexpected behavior
+
+## When NOT to Use This
+
+- If the workflow is about to complete (let it finish)
+- If you're unsure whether stopping is safe
+- For debugging (use `output workflow debug` instead)
+- If the workflow has side effects that may leave data in an inconsistent state
+
+## Instructions
+
+### Stop a Workflow
+
+```bash
+output workflow stop <workflowId>
+```
+
+### Safety Considerations
+
+Before stopping, consider:
+
+1. **Side effects**: Has the workflow made changes that need to be rolled back?
+2. **Partial completion**: Are there steps that completed with side effects?
+3. **Dependencies**: Are other workflows or systems waiting on this result?
+4. **Recovery**: Do you need to restart or clean up after stopping?
+
+## Examples
+
+**Scenario**: Stop a stuck workflow
+
+```bash
+# Check status - workflow has been running too long
+output workflow status abc123xyz
+# Status: RUNNING (for 2 hours)
+
+# Decide to stop it
+output workflow stop abc123xyz
+# Workflow abc123xyz has been stopped
+
+# Verify it's terminated
+output workflow status abc123xyz
+# Status: TERMINATED
+```
+
+**Scenario**: Cancel a workflow started with wrong input
+
+```bash
+# Realized input was wrong immediately after starting
+output workflow start expensive-job '{"wrong": "input"}'
+# Workflow ID: job-abc123
+
+# Stop before it processes too much
+output workflow stop job-abc123
+
+# Start again with correct input
+output workflow start expensive-job '{"correct": "input"}'
+```
+
+**Scenario**: Stop multiple workflows
+
+```bash
+# Get list of running workflows
+output workflow runs list --format json | jq '.[] | select(.status == "RUNNING") | .workflowId'
+
+# Stop each one (carefully review first!)
+for id in abc123 def456; do
+  echo "Stopping $id"
+  output workflow stop $id
+done
+```
+
+## After Stopping a Workflow
+
+### Check the State
+
+```bash
+output workflow status <workflowId>
+# Status: TERMINATED
+```
+
+### Review What Happened
+
+```bash
+output workflow debug <workflowId> --format json
+```
+
+This shows:
+- Which steps completed before termination
+- Any partial results or side effects
+- The point at which the workflow was stopped
+
+### Clean Up If Needed
+
+If the workflow made partial changes:
+1. Review the debug output to see what completed
+2. Manually revert any side effects if necessary
+3. Consider creating a cleanup workflow for this scenario
+
+### Restart If Appropriate
+
+```bash
+# Start a fresh execution
+output workflow start <workflowName> '<input>'
+```
+
+## What Happens When You Stop
+
+1. The Temporal server receives the termination request
+2. The currently executing step may complete or abort
+3. No further steps are executed
+4. The workflow status changes to TERMINATED
+5. The result will not be available (workflow didn't complete)
+
+## Troubleshooting
+
+### "Workflow not found"
+- Check the workflow ID is correct
+- Use `output workflow runs list` to find valid IDs
+
+### "Workflow already completed"
+- The workflow finished before the stop command
+- Check status and get result if needed
+
+### "Workflow already terminated"
+- The workflow was already stopped
+- No action needed
+
+### Stop command hangs
+- The Temporal server may be unresponsive
+- Check if services are running: `docker ps | grep output`
+- May need to restart services
+
+## Best Practices
+
+1. **Always check status first**: Confirm the workflow is actually RUNNING
+2. **Review before stopping**: Use `output workflow debug` to understand state
+3. **Document why**: Note why you stopped the workflow for future reference
+4. **Plan for cleanup**: Know what side effects may need manual handling
+5. **Consider alternatives**: Sometimes waiting is better than stopping
+
+## Related Commands
+
+- `output workflow status <id>` - Check current status
+- `output workflow debug <id>` - Review execution details
+- `output workflow start <name>` - Start a new execution
+- `output workflow runs list` - View execution history