examples: "failures" and "diagnose" become flags for extra data on list and describe

Author: moedash

examples/EXPERIMENT.md

@@ -100,7 +100,7 @@ The `debug-loop-fresh` example contains a TOCTOU race condition with all hints r
 ### LLM's Diagnosis Process
 
 1. **Ran the scenario** - Started worker and triggered race condition
-2. **Used `temporal workflow diagnose`** - Found `ReserveInventory` failed for KEYBOARD-03
+2. **Used `temporal workflow describe --trace-root-cause`** - Found `ReserveInventory` failed for KEYBOARD-03
 3. **Used `temporal workflow show --compact`** - Analyzed timestamps of both workflows
 4. **Built a race timeline** - Correlated events across both orders:
 
@@ -136,8 +136,8 @@ Based on experiment findings, the following improvements were made:
 
 | Feature | Status | Command |
 |---------|--------|---------|
-| Find recent failures | ✅ Done | `temporal workflow failures` |
-| Trace workflow chain | ✅ Done | `temporal workflow diagnose` |
+| Find recent failures | ✅ Done | `temporal workflow list --failed` |
+| Trace workflow chain | ✅ Done | `temporal workflow describe --trace-root-cause` |
 | Workflow timeline | ✅ Done | `temporal workflow show --compact` |
 
 ### Phase 2: Filtering & Compaction
@@ -179,11 +179,11 @@ Based on experiment findings, the following improvements were made:
 
 | Feature | Status | Flag/Command |
 |---------|--------|--------------|
-| Trace flowchart | ✅ Done | `temporal workflow diagnose --format mermaid` |
+| Trace flowchart | ✅ Done | `temporal workflow describe --trace-root-cause --format mermaid` |
 | Timeline sequence diagram | ✅ Done | `temporal workflow show --compact --format mermaid` |
 | State diagram | ✅ Done | `temporal workflow describe --pending --format mermaid` |
-| Failures pie chart | ✅ Done | `temporal workflow failures --group-by error --format mermaid` |
-| Failures flowchart | ✅ Done | `temporal workflow failures --format mermaid` |
+| Failures pie chart | ✅ Done | `temporal workflow list --failed --group-by error --format mermaid` |
+| Failures flowchart | ✅ Done | `temporal workflow list --failed --format mermaid` |
 
 ---
 

examples/agent-demo/README.md

@@ -87,7 +87,7 @@ After workflows have run, use the agent commands to analyze them.
 ### List Recent Failures
 
 ```bash
-temporal workflow failures \
+temporal workflow list --failed \
     --address $TEMPORAL_ADDRESS \
     --namespace $TEMPORAL_NAMESPACE \
     --api-key $TEMPORAL_API_KEY \
@@ -101,7 +101,7 @@ temporal workflow failures \
 
 ```bash
 # Find the deepest failure in an order workflow
-temporal workflow diagnose \
+temporal workflow describe --trace-root-cause \
     --address $TEMPORAL_ADDRESS \
     --namespace $TEMPORAL_NAMESPACE \
     --api-key $TEMPORAL_API_KEY \
@@ -110,7 +110,7 @@ temporal workflow diagnose \
     --format json | jq
 
 # Trace the nested failure workflow (3 levels deep)
-temporal workflow diagnose \
+temporal workflow describe --trace-root-cause \
     --address $TEMPORAL_ADDRESS \
     --namespace $TEMPORAL_NAMESPACE \
     --api-key $TEMPORAL_API_KEY \
@@ -161,6 +161,6 @@ NestedFailureWorkflow (depth=0)
                     └── FailingActivity → FAILS: "database connection refused"
 ```
 
-The `temporal workflow diagnose` command will automatically traverse this entire chain
+The `temporal workflow describe --trace-root-cause` command will automatically traverse this entire chain
 and identify the leaf failure with its root cause.
 

examples/agent-demo/starter/main.go

@@ -266,5 +266,5 @@ func runDeepChainScenario(ctx context.Context, c client.Client, taskQueue, times
 	}
 	log.Printf("Started DeepChainWorkflow (4 levels deep, fails with DB error): %s", run.GetID())
 	log.Println("TIP: Trace the full chain with:")
-	log.Printf("  temporal workflow diagnose --workflow-id %s --namespace <your-namespace> --format json", workflowID)
+	log.Printf("  temporal workflow describe --trace-root-cause --workflow-id %s --namespace <your-namespace> --format json", workflowID)
 }

examples/ai-research-agent-impl/CLAUDE.md

@@ -6,15 +6,15 @@ When debugging Temporal workflows, use the `temporal workflow` CLI commands inst
 
 ### Find Failures
 ```bash
-temporal workflow failures --since 1h --format json
-temporal workflow failures --since 1h --follow-children --leaf-only --compact-errors --format json
-temporal workflow failures --since 1h --group-by error --format json
+temporal workflow list --failed --since 1h --format json
+temporal workflow list --failed --since 1h --follow-children --leaf-only --compact-errors --format json
+temporal workflow list --failed --since 1h --group-by error --format json
 ```
 
 ### Trace Workflow Chain
 ```bash
-temporal workflow diagnose --workflow-id <id> --format json
-temporal workflow diagnose --workflow-id <id> --format mermaid
+temporal workflow describe --trace-root-cause --workflow-id <id> --format json
+temporal workflow describe --trace-root-cause --workflow-id <id> --format mermaid
 ```
 
 ### Get Timeline
@@ -60,7 +60,7 @@ Use `--format mermaid` to generate diagrams:
 User: "The order workflow failed"
 
 You should:
-1. Run `temporal workflow diagnose --workflow-id order-123 --format json`
+1. Run `temporal workflow describe --trace-root-cause --workflow-id order-123 --format json`
 2. If complex, add `--format mermaid` for visual
 3. Identify the leaf failure and root cause
 4. Explain what went wrong

examples/ai-research-agent/PLAN.md

@@ -33,8 +33,8 @@ Or create your own `.cursorrules` file with this content:
 ```
 When debugging Temporal workflows, use the `temporal workflow` CLI commands:
 
-- `temporal workflow failures --since 1h` - Find recent failures
-- `temporal workflow diagnose --workflow-id <id>` - Trace workflow chain to leaf failure
+- `temporal workflow list --failed --since 1h` - Find recent failures
+- `temporal workflow describe --trace-root-cause --workflow-id <id>` - Trace workflow chain to leaf failure
 - `temporal workflow show --compact --workflow-id <id>` - Get event timeline
 - `temporal workflow describe --pending --workflow-id <id>` - Check pending activities/children
 
@@ -70,8 +70,8 @@ Then load this into your agent framework's tool configuration.
 At the beginning of each session, tell your AI:
 
 > "I'm using Temporal for workflow orchestration. When I have issues, use the `temporal workflow` CLI to debug. The commands are:
-> - `temporal workflow failures` - find failures
-> - `temporal workflow diagnose` - trace workflow chains  
+> - `temporal workflow list --failed` - find failures
+> - `temporal workflow describe --trace-root-cause` - trace workflow chains  
 > - `temporal workflow show --compact` - see event history
 > - `temporal workflow describe --pending` - check pending work
 > 
@@ -85,8 +85,8 @@ Test that your AI knows the commands by asking:
 
 **Expected response should include:**
 ```bash
-temporal workflow diagnose --workflow-id <id> --format json
-temporal workflow failures --since 1h --follow-children --format json
+temporal workflow describe --trace-root-cause --workflow-id <id> --format json
+temporal workflow list --failed --since 1h --follow-children --format json
 ```
 
 If the AI suggests looking at logs, remind it about the workflow debugging commands (`failures`, `diagnose`, `show --compact`, `describe --pending`).
@@ -128,7 +128,7 @@ go run ./starter -question "What is Temporal?"
 temporal workflow list
 
 # Use workflow diagnose to see what happened
-temporal workflow diagnose --workflow-id <id> --format json
+temporal workflow describe --trace-root-cause --workflow-id <id> --format json
 ```
 
 **This teaches:** Using `workflow diagnose` to understand workflow state.
@@ -150,7 +150,7 @@ activity not registered: ProcessQuestion
 
 **AI uses workflow CLI to diagnose:**
 ```bash
-temporal workflow diagnose --workflow-id <id> --format json | jq '.root_cause'
+temporal workflow describe --trace-root-cause --workflow-id <id> --format json | jq '.root_cause'
 # Shows: "activity not registered"
 ```
 
@@ -241,8 +241,8 @@ go run ./starter -question "Very complex philosophical question"
 
 **Diagnose timeout:**
 ```bash
-temporal workflow failures --since 5m --format json
-temporal workflow diagnose --workflow-id <id> --format json | jq '.root_cause'
+temporal workflow list --failed --since 5m --format json
+temporal workflow describe --trace-root-cause --workflow-id <id> --format json | jq '.root_cause'
 # Shows: "activity StartToClose timeout"
 ```
 
@@ -260,11 +260,11 @@ temporal workflow diagnose --workflow-id <id> --format json | jq '.root_cause'
 
 **Verify chain:**
 ```bash
-temporal workflow diagnose --workflow-id <id> --format json | jq '.chain'
+temporal workflow describe --trace-root-cause --workflow-id <id> --format json | jq '.chain'
 # Shows parent-child hierarchy
 
 # Visualize the chain as a flowchart:
-temporal workflow diagnose --workflow-id <id> --format mermaid
+temporal workflow describe --trace-root-cause --workflow-id <id> --format mermaid
 ```
 
 The flowchart will show:
@@ -283,13 +283,13 @@ Coordinator → ResearchAgent1
 **AI suggests using agent CLI:**
 ```bash
 # Find recent failures
-temporal workflow failures --since 10m --format json
+temporal workflow list --failed --since 10m --format json
 
 # Get detailed trace showing which child failed
-temporal workflow diagnose --workflow-id <id> --format json | jq '{depth: .depth, root_cause: .root_cause}'
+temporal workflow describe --trace-root-cause --workflow-id <id> --format json | jq '{depth: .depth, root_cause: .root_cause}'
 
 # Use leaf-only to see actual failure, not parent wrapper
-temporal workflow failures --since 10m --follow-children --leaf-only --format json
+temporal workflow list --failed --since 10m --follow-children --leaf-only --format json
 ```
 
 **This teaches:** Using `--follow-children` and `--leaf-only` for nested workflows.
@@ -302,7 +302,7 @@ temporal workflow failures --since 10m --follow-children --leaf-only --format js
 
 **Expected AI response:**
 ```bash
-temporal workflow diagnose --workflow-id coordinator-12345 --format mermaid
+temporal workflow describe --trace-root-cause --workflow-id coordinator-12345 --format mermaid
 ```
 
 **AI outputs this diagram:**
@@ -339,7 +339,7 @@ graph TD
 go run ./starter -question "Mixed success question"
 
 # See partial results
-temporal workflow diagnose --workflow-id <id> --format json
+temporal workflow describe --trace-root-cause --workflow-id <id> --format json
 # Shows some children completed, some failed, parent still succeeded
 ```
 
@@ -390,7 +390,7 @@ Synthesizer → Coordinator: ✅ Done
 ```bash
 go run ./starter -question "Gibberish input that produces bad results"
 
-temporal workflow failures --since 5m --compact-errors --format json | jq '.failures[].root_cause'
+temporal workflow list --failed --since 5m --compact-errors --format json | jq '.failures[].root_cause'
 # Shows: "quality check failed: score 0.45 below threshold 0.7"
 ```
 
@@ -426,14 +426,14 @@ temporal workflow describe --pending --workflow-id <id> --format json | jq '.pen
 **Diagnose failures:**
 ```bash
 # After batch completes
-temporal workflow failures --since 10m --format json | jq '.total_count'
+temporal workflow list --failed --since 10m --format json | jq '.total_count'
 
 # Group by error type to find patterns
-temporal workflow failures --since 10m --group-by error --format json | jq '.groups'
+temporal workflow list --failed --since 10m --group-by error --format json | jq '.groups'
 # Might show: "rate limit: 6, timeout: 2, success: 2"
 
 # Visualize as a pie chart - instantly see the breakdown:
-temporal workflow failures --since 10m --group-by error --format mermaid
+temporal workflow list --failed --since 10m --group-by error --format mermaid
 ```
 
 The pie chart makes patterns obvious at a glance:
@@ -454,7 +454,7 @@ pie title Failures by error
 
 **Expected AI response:**
 ```bash
-temporal workflow failures --since 10m --follow-children --leaf-only --compact-errors --group-by error --format mermaid
+temporal workflow list --failed --since 10m --follow-children --leaf-only --compact-errors --group-by error --format mermaid
 ```
 
 **AI outputs this diagram:**
@@ -475,7 +475,7 @@ pie title Failures by error
 
 **AI response:**
 ```bash
-temporal workflow failures --since 10m --follow-children --group-by namespace --format mermaid
+temporal workflow list --failed --since 10m --follow-children --group-by namespace --format mermaid
 ```
 
 ```mermaid
@@ -504,8 +504,8 @@ pie title Failures by namespace
 go run ./starter -load-test -count 20
 
 # Watch for timeouts vs retries
-temporal workflow failures --since 10m --status TimedOut --format json
-temporal workflow failures --since 10m --status Failed --format json
+temporal workflow list --failed --since 10m --status TimedOut --format json
+temporal workflow list --failed --since 10m --status Failed --format json
 ```
 
 ---
@@ -607,7 +607,7 @@ go run ./starter -question "Very long research"
 temporal workflow cancel --workflow-id <id>
 
 # Check that children were also cancelled
-temporal workflow failures --since 5m --format json | jq '.failures[] | select(.status == "Canceled")'
+temporal workflow list --failed --since 5m --format json | jq '.failures[] | select(.status == "Canceled")'
 ```
 
 ---
@@ -621,27 +621,27 @@ temporal workflow failures --since 5m --format json | jq '.failures[] | select(.
 **AI walks through debugging:**
 ```bash
 # Step 1: Visualize the chain - immediately see where failure occurred
-temporal workflow diagnose --workflow-id <id> --format mermaid
+temporal workflow describe --trace-root-cause --workflow-id <id> --format mermaid
 # The flowchart highlights the failing path in red
 
 # Step 2: Get the JSON details
-temporal workflow diagnose --workflow-id <id> --format json | jq '.root_cause'
+temporal workflow describe --trace-root-cause --workflow-id <id> --format json | jq '.root_cause'
 # Shows: error in SynthesizerWorkflow
 
 # Step 3: Trace the child
-temporal workflow diagnose --workflow-id <synth-id> --format json | jq '.root_cause'
+temporal workflow describe --trace-root-cause --workflow-id <synth-id> --format json | jq '.root_cause'
 # Shows: "no findings to synthesize"
 
 # Step 4: Visualize the timeline to see what happened
 temporal workflow show --compact --workflow-id <id> --format mermaid
 # Sequence diagram shows: 3 research agents all returned errors!
 
 # Step 5: Find the actual root cause
-temporal workflow failures --since 10m --follow-children --leaf-only --compact-errors --format json
+temporal workflow list --failed --since 10m --follow-children --leaf-only --compact-errors --format json
 # Shows: "API key expired"
 
 # Step 6: Visualize failure breakdown
-temporal workflow failures --since 10m --group-by error --format mermaid
+temporal workflow list --failed --since 10m --group-by error --format mermaid
 # Pie chart confirms: 100% of failures are "API key expired"
 ```
 
@@ -658,7 +658,7 @@ temporal workflow failures --since 10m --group-by error --format mermaid
 "Let me trace the workflow and show you what happened."
 
 ```bash
-temporal workflow diagnose --workflow-id coordinator-99999 --format mermaid
+temporal workflow describe --trace-root-cause --workflow-id coordinator-99999 --format mermaid
 ```
 
 ```mermaid
@@ -680,7 +680,7 @@ graph TD
 **AI explains:** "The diagram shows the Coordinator spawned 4 child workflows. All 3 ResearchAgents failed, and the Synthesizer also failed because it had no data to synthesize. But wait - this doesn't show WHY the research agents failed. Let me dig deeper..."
 
 ```bash
-temporal workflow failures --since 10m --follow-children --leaf-only --group-by error --format mermaid
+temporal workflow list --failed --since 10m --follow-children --leaf-only --group-by error --format mermaid
 ```
 
 ```mermaid
@@ -768,7 +768,7 @@ The AI should respond with:
 After completing all phases, you should:
 
 1. ✅ Have a working multi-agent research system
-2. ✅ Understand how to use `temporal workflow diagnose` for debugging
+2. ✅ Understand how to use `temporal workflow describe --trace-root-cause` for debugging
 3. ✅ Know when to use `--follow-children` and `--leaf-only`
 4. ✅ Be able to analyze failures with `--group-by`
 5. ✅ Use `workflow describe --pending` to check pending work

examples/debug-loop/README.md

@@ -70,7 +70,7 @@ This is a classic TOCTOU race condition!
 
 ```bash
 # Get the trace - shows root cause
-temporal workflow diagnose --workflow-id order-123456 --namespace default --format json
+temporal workflow describe --trace-root-cause --workflow-id order-123456 --namespace default --format json
 
 # THIS IS KEY: Get the timeline to see the race condition
 temporal workflow show --compact --workflow-id order-123456 --namespace default --format json
@@ -103,7 +103,7 @@ A workflow failed with "insufficient inventory for KEYBOARD-03: requested 1, ava
 The logs show the inventory check passed, but the reservation failed.
 
 Use temporal workflow CLI to diagnose:
-  temporal workflow diagnose --workflow-id [id] --namespace default --format json
+  temporal workflow describe --trace-root-cause --workflow-id [id] --namespace default --format json
   temporal workflow show --compact --workflow-id [id] --namespace default --format json
 
 Questions to answer:

examples/debug-loop/create-fresh.sh

@@ -517,7 +517,7 @@ func runRaceScenario(c client.Client, namespace, orderID string, ts int64, wait
 		log.Println("=== DEBUG CHALLENGE ===")
 		log.Println("One order failed. Use temporal workflow CLI to diagnose why.")
 		log.Println("")
-		log.Printf("  temporal workflow diagnose --workflow-id %s --namespace %s --format json", failedID, namespace)
+		log.Printf("  temporal workflow describe --trace-root-cause --workflow-id %s --namespace %s --format json", failedID, namespace)
 		log.Printf("  temporal workflow show --compact --workflow-id %s --namespace %s --format json", failedID, namespace)
 		log.Println("")
 		log.Println("Question: Why did the inventory check pass but the reservation fail?")
@@ -602,8 +602,8 @@ But the workflow checks inventory before reserving. Why does the check pass but
 Diagnose using `temporal workflow`:
 
 ```bash
-temporal workflow failures --namespace default --since 5m --format json
-temporal workflow diagnose --workflow-id <id> --namespace default --format json
+temporal workflow list --failed --namespace default --since 5m --format json
+temporal workflow describe --trace-root-cause --workflow-id <id> --namespace default --format json
 temporal workflow show --compact --workflow-id <id> --namespace default --format json
 ```
 

examples/debug-loop/starter/main.go

@@ -187,7 +187,7 @@ func runRaceScenario(c client.Client, namespace, orderID string, ts int64, wait
 		log.Println("")
 		log.Println("Use temporal workflow CLI to analyze the failed order:")
 		log.Println("")
-		log.Printf("  temporal workflow diagnose --workflow-id %s --namespace %s --format json", failedID, namespace)
+		log.Printf("  temporal workflow describe --trace-root-cause --workflow-id %s --namespace %s --format json", failedID, namespace)
 		log.Printf("  temporal workflow show --compact --workflow-id %s --namespace %s --format json", failedID, namespace)
 		log.Println("")
 		log.Println("Key insight: Look at the timeline to see that:")