Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
31 commits
Select commit Hold shift + click to select a range
847cba3
Initial version of Temporal Agent
moedash Dec 29, 2025
8804a90
Fix follow namespaces
moedash Dec 30, 2025
a0ee202
implemented error contains
moedash Dec 30, 2025
f28dc42
Improved the cli: multiple status
moedash Dec 30, 2025
fa58ffc
Added OpenAI/LangChain tool-spec
moedash Dec 30, 2025
b3106b5
Added Claude tool
moedash Dec 30, 2025
b0e822c
Added leaf-only
moedash Dec 30, 2025
f6a9f3a
Added compact error
moedash Dec 30, 2025
0a23a6b
Added state
moedash Dec 30, 2025
a409fa3
Support multi-namespace travesal using Nexus
moedash Dec 30, 2025
e18b402
Updated README
moedash Dec 31, 2025
582a110
Added group-by feature
moedash Dec 31, 2025
d404a66
Added more nextus info in State
moedash Dec 31, 2025
149fba3
Improved docs.
moedash Dec 31, 2025
4477632
Added mermaid output
moedash Dec 31, 2025
9f8d835
Updated .gitignore
moedash Dec 31, 2025
437cd37
nitz.
moedash Dec 31, 2025
11cddac
Add Run ID to output
moedash Dec 31, 2025
4d5eff6
Fixed JSON output
moedash Dec 31, 2025
d2510a2
fixed format flag
moedash Dec 31, 2025
9cb2ee1
failures always available
moedash Dec 31, 2025
ba9dd8a
Fixed failure output
moedash Dec 31, 2025
dbef96d
Consolidated temporal agent with temporal workflow
moedash Jan 1, 2026
1c982bd
Fixed handling terminal
moedash Jan 1, 2026
0fa031c
Merge branch 'moe/fix-cli-hang' into moe/temporal-agent-cli
moedash Jan 1, 2026
f209147
Renamed
moedash Jan 1, 2026
0047259
Nitz.
moedash Jan 1, 2026
db512ff
Merge branch 'main' into moe/fix-cli-hang
moedash Jan 9, 2026
77ad541
Merge branch 'moe/fix-cli-hang' into moe/temporal-agent-cli
moedash Jan 9, 2026
9928544
Fixed JSON printing.
moedash Jan 9, 2026
d8dd581
Merge branch 'main' into moe/temporal-agent-cli
moedash Jan 9, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
190 changes: 190 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,196 @@ The executable will be at `temporal` (`temporal.exe` for Windows).

Reference [the documentation](https://docs.temporal.io/cli) for detailed usage information.

## AI-Optimized Debugging Commands

The CLI includes workflow commands optimized for AI agents, LLM tooling, and automated debugging:

### New Commands

- **`temporal workflow failures`** - List recent workflow failures with auto-traversed root cause
- **`temporal workflow diagnose`** - Trace a workflow through its child chain to the deepest failure
- **`temporal tool-spec`** - Output tool specifications for AI agent frameworks

### Enhanced Commands

- **`temporal workflow show --compact`** - Show a compact event timeline
- **`temporal workflow show --format mermaid`** - Generate a sequence diagram
- **`temporal workflow describe --pending`** - Show pending activities, children, and Nexus operations
- **`temporal workflow describe --format mermaid`** - Generate a state diagram

### Examples

```bash
# List failures from the last hour with automatic chain traversal
temporal workflow failures --namespace prod --since 1h --follow-children

# Filter failures by error message (case-insensitive)
temporal workflow failures --namespace prod --since 1h --error-contains "timeout"

# Show only leaf failures (de-duplicate parent/child chains)
temporal workflow failures --namespace prod --since 1h --follow-children --leaf-only

# Compact error messages (strip wrapper context, show core error)
temporal workflow failures --namespace prod --since 1h --follow-children --compact-errors

# Combine leaf-only and compact-errors for cleanest output
temporal workflow failures --namespace prod --since 1h --follow-children --leaf-only --compact-errors

# Group failures by error type for quick summary
temporal workflow failures --namespace prod --since 24h --follow-children --compact-errors --group-by error

# Group failures by namespace to see which services are failing
temporal workflow failures --namespace prod --since 24h --follow-children --group-by namespace

# Trace a workflow to find the deepest failure in the chain
temporal workflow diagnose --workflow-id order-123 --namespace prod

# Get a compact timeline of workflow events
temporal workflow show --workflow-id order-123 --namespace prod --compact

# Get current workflow state (pending activities, child workflows)
temporal workflow describe --workflow-id order-123 --namespace prod --pending

# Cross-namespace traversal (Nexus/child workflows in other namespaces)
TEMPORAL_API_KEY_FINANCE_NS="$FINANCE_KEY" \
temporal workflow diagnose --workflow-id order-123 --namespace commerce-ns \
--follow-namespaces finance-ns
```

### Cross-Namespace Traversal

When tracing workflows that span multiple namespaces (via Nexus or child workflows), you can provide namespace-specific API keys using environment variables:

```bash
# Format: TEMPORAL_API_KEY_<NAMESPACE>
# Namespace names are normalized: dots/dashes → underscores, then UPPERCASED
#
# Examples of namespace → environment variable:
# finance-ns → TEMPORAL_API_KEY_FINANCE_NS
# moedash-finance-ns → TEMPORAL_API_KEY_MOEDASH_FINANCE_NS
# finance.temporal-dev → TEMPORAL_API_KEY_FINANCE_TEMPORAL_DEV

# Primary namespace uses TEMPORAL_API_KEY
export TEMPORAL_API_KEY="primary-ns-key"

# Additional namespaces use namespace-specific keys
export TEMPORAL_API_KEY_FINANCE_NS="finance-ns-key"
export TEMPORAL_API_KEY_LOGISTICS_NS="logistics-ns-key"

# Now diagnose can follow Nexus operations and child workflows across namespaces
temporal workflow diagnose --workflow-id order-123 --namespace commerce-ns \
--follow-namespaces finance-ns,logistics-ns

# For failures command, use --follow-children with --follow-namespaces
temporal workflow failures --namespace commerce-ns --since 1h \
--follow-children --follow-namespaces finance-ns,logistics-ns \
--leaf-only --compact-errors
```

### Mermaid Visualization

Commands support `--format mermaid` to generate visual diagrams:

```bash
# Visualize workflow chain as a flowchart
temporal workflow diagnose --workflow-id order-123 --namespace prod --format mermaid

# Visualize timeline as a sequence diagram
temporal workflow show --workflow-id order-123 --namespace prod --format mermaid

# Visualize current state with pending activities
temporal workflow describe --workflow-id order-123 --namespace prod --pending --format mermaid

# Visualize failures as a pie chart (when grouped)
temporal workflow failures --namespace prod --since 1h --group-by error --format mermaid

# Visualize failures as a flowchart (when not grouped)
temporal workflow failures --namespace prod --since 1h --follow-children --format mermaid
```

The mermaid output renders directly in:
- Cursor AI and VS Code with Mermaid extension
- GitHub markdown files and comments
- Notion pages
- Any markdown preview with Mermaid support

Example diagnose output with `--format mermaid`:
```
graph TD
W0[🔄 OrderWorkflow<br/>Failed]
W1[❌ PaymentWorkflow<br/>Failed<br/>🎯 LEAF]
W0 -->|failed| W1
RC(((connection timeout)))
W1 -.->|root cause| RC
style RC fill:#ff6b6b,stroke:#c92a2a,color:#fff
```

### AI Agent Integration

The `temporal tool-spec` command outputs tool definitions compatible with AI agent frameworks:

```bash
# OpenAI function calling format (default)
temporal tool-spec --format openai

# Anthropic Claude format
temporal tool-spec --format claude

# LangChain tool format
temporal tool-spec --format langchain

# Raw function definitions
temporal tool-spec --format functions
```

These tool specs can be used to integrate Temporal debugging capabilities into AI agents, allowing them to:
- Query recent failures and their root causes
- Trace workflow chains to find the deepest failure
- Get compact workflow timelines

Example OpenAI integration:
```python
import subprocess
import json

# Get tool specs
result = subprocess.run(
["temporal", "tool-spec", "--format", "openai"],
capture_output=True, text=True
)
tools = json.loads(result.stdout)

# Use with OpenAI API
response = openai.chat.completions.create(
model="gpt-4",
messages=[{"role": "user", "content": "Find recent failures in the prod namespace"}],
tools=tools
)
```

Example Claude integration:
```python
import subprocess
import json
import anthropic

# Get tool specs
result = subprocess.run(
["temporal", "tool-spec", "--format", "claude"],
capture_output=True, text=True
)
tools = json.loads(result.stdout)

# Use with Anthropic API
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=1024,
tools=tools,
messages=[{"role": "user", "content": "Find recent failures in the prod namespace"}]
)
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).
Loading