Skip to content

Conversation

@moedash
Copy link
Contributor

@moedash moedash commented Jan 9, 2026

What was changed

Enhanced existing CLI commands with AI-friendly debugging features:

Enhanced temporal workflow list:

  • --failed - Lists failed workflows with automatic root cause analysis
  • --since - Time window filter (e.g., 1h, 24h)
  • --follow-children - Traverses child workflows to find leaf failures
  • --follow-namespaces - Cross-namespace traversal support
  • --group-by - Aggregate failures by type, namespace, status, or error
  • --leaf-only - De-duplicates parent/child failure chains
  • --compact-errors - Strips verbose wrapper context from errors
  • --error-contains - Filter by error message substring

Enhanced temporal workflow describe:

  • --trace-root-cause - Traces through child chain to find deepest failure
  • --pending - Shows pending activities, children, and Nexus operations
  • --follow-namespaces - Cross-namespace traversal for root cause tracing

Enhanced temporal workflow show:

  • --compact - Shows condensed event timeline

New global output format:

  • --output mermaid - Generates visual diagrams (sequence, flowchart, pie chart)

New command:

  • temporal tool-spec - Outputs tool definitions for AI frameworks (OpenAI, Claude, LangChain)

Why?

When debugging distributed Temporal applications, finding the root cause of failures often requires manually traversing chains of child workflows and Nexus operations across namespaces. This is tedious for humans and nearly impossible for AI agents without structured output.

These enhancements provide:

  1. Machine-readable JSON output that AI agents can parse and reason about
  2. Automatic chain traversal so you don't have to manually follow failed children
  3. Visual Mermaid diagrams for quick human understanding
  4. Tool specifications so AI agents can invoke these commands directly

Checklist

  1. Closes #N/A (new feature)

  2. How was this tested:

    • Unit tests for all new packages (internal/workflowdebug/...)
    • Integration tests covering:
      • Compact timeline generation
      • Workflow chain tracing with child workflows
      • Failure finding with various filters
      • Leaf-only and error-contains filtering
      • Multi-status queries
  3. Any docs updates needed?

    • README.md updated with usage examples
    • Command help text includes examples for all new flags

Here's a follow-up PR that contains examples: moedash#1

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant