Temporal CLI

Temporal CLI Skill

Execute Temporal CLI commands with smart patterns for workflow management. This skill provides comprehensive knowledge for using Temporal CLI v1.5.1 effectively with base64 and jq.

Prerequisites

• Temporal CLI v1.5.1+ installed and available in PATH
• Configured environments in ~/.config/temporalio/temporal.yaml
• base64 command-line tool (standard on most systems)
• jq JSON processor for parsing and filtering

Core Command Pattern

ALL Temporal CLI commands follow this base pattern:

temporal --env <environment> -o json --time-format iso workflow <operation> [args...]

Global flags (ALWAYS used):

• --env <env> - Temporal environment from config
• -o json - JSON output format
• --time-format iso - ISO 8601 timestamps

Quick Reference

Essential Operations

Knowledge Guides

Progressive Disclosure Strategy

1. Start here - Read this SKILL.md for overview
2. Need specific command? - Check Command Patterns
3. Building queries? - See Query Construction
4. Large history? - Use History Filtering
5. Custom attributes? - Review Custom Search Attributes
6. Hit errors? - Consult Error Handling
7. Destructive ops? - Verify Safety Checks

Key Principles

1. Always Count Before Listing

# Get count first to understand scope
COUNT=$(temporal --env prod -o json --time-format iso workflow count \
  --query "ExecutionStatus = 'Failed'" | jq '.count')

# Then list with appropriate limit
temporal --env prod -o json --time-format iso workflow list \
  --query "ExecutionStatus = 'Failed'" \
  --limit ${COUNT}

2. Filter Large Histories

Histories with 100+ events should be filtered:

# Use jq to show only failures
temporal --env prod -o json --time-format iso workflow show \
  --workflow-id "my-workflow" | \
  jq '.events[] | select(.eventType | contains("Failed"))'

See History Filtering for more patterns.

3. Validate Queries First

Pre-validate queries before execution to avoid errors:

# Check for unsupported LIKE operator
if echo "$QUERY" | grep -qi 'LIKE'; then
  echo "ERROR: Use STARTS_WITH instead of LIKE"
  exit 1
fi

See Smart Patterns for validation logic.

4. Decode Payloads Carefully

Workflow event payloads are base64-encoded:

# Decode workflow input
temporal --env prod -o json --time-format iso workflow show \
  --workflow-id "my-workflow" | \
  jq -r '.events[0].workflowExecutionStartedEventAttributes.input.payloads[0].data' | \
  base64 -d | \
  jq '.'

See Payload Decoding for complete recipes.

Common Workflows

Find Failed Workflows

# Count failures
temporal --env prod -o json --time-format iso workflow count \
  --query "ExecutionStatus = 'Failed'"

# List failed workflows
temporal --env prod -o json --time-format iso workflow list \
  --query "ExecutionStatus = 'Failed'" \
  --limit 10

Find Non-Deterministic / Problematic Workflows

IMPORTANT: Workflows with non-deterministic errors often remain in Running status, not Failed. Use TemporalReportedProblems to find them:

# Find running workflows with WorkflowTask failures (includes non-deterministic errors)
temporal --env prod -o json --time-format iso workflow list \
  --query "ExecutionStatus = 'Running' AND TemporalReportedProblems IN ('category=WorkflowTaskFailed', 'category=WorkflowTaskTimedOut')" \
  --limit 20

# Count problematic workflows
temporal --env prod -o json --time-format iso workflow count \
  --query "ExecutionStatus = 'Running' AND TemporalReportedProblems IN ('category=WorkflowTaskFailed')"

TemporalReportedProblems values:

• category=WorkflowTaskFailed - WorkflowTask failed (includes non-deterministic errors)
• category=WorkflowTaskTimedOut - WorkflowTask timed out
• cause=WorkflowTaskFailedCauseNonDeterministicError - Specifically non-deterministic errors

Get failure details from history:

# Get the last WorkflowTaskFailed event with full error message
temporal --env prod -o json --time-format iso workflow show \
  --workflow-id "my-workflow" | \
  jq '[.events[] | select(.eventType == "EVENT_TYPE_WORKFLOW_TASK_FAILED")] | .[-1]'

Debug Stuck Workflow

# Get stack trace
temporal --env prod -o json --time-format iso workflow stack \
  --workflow-id "stuck-workflow-123"

# Check history for patterns
temporal --env prod -o json --time-format iso workflow show \
  --workflow-id "stuck-workflow-123" | \
  jq '[.events[] | .eventType] | group_by(.) | map({type: .[0], count: length})'

Customer-Specific Workflows

# Using custom search attribute
temporal --env prod -o json --time-format iso workflow list \
  --query "CustomerId = 'customer-abc-123'" \
  --limit 20

Safety First

Before destructive operations (terminate, reset):

1. Double-check workflow ID
2. ALWAYS provide --reason
3. For batch operations, count affected workflows first
4. Review Safety Checks

Quick Examples

List Workflows by Type

temporal --env staging -o json --time-format iso workflow list \
  --query "WorkflowType = 'OnboardingFlow'" \
  --limit 10

Start New Workflow

temporal --env staging -o json --time-format iso workflow start \
  --type "OnboardingFlow" \
  --task-queue "patient-workflows" \
  --workflow-id "patient-onboard-$(date +%s)" \
  --input '{"customerId": "cust-123"}'

Signal Workflow

temporal --env prod -o json --time-format iso workflow signal \
  --workflow-id "order-processing-456" \
  --name "approvalReceived" \
  --input '{"approved": true}'

Asset Templates

Pre-built templates available in assets/:

• query-templates.json - Common query patterns
• jq-filters.json - Reusable jq filters
• event-types.json - Event type reference

Getting Started

1. Verify Temporal CLI is installed: temporal --version
2. Check environment configuration: cat ~/.config/temporalio/temporal.yaml
3. Try counting workflows: temporal --env staging -o json --time-format iso workflow count
4. Explore Command Patterns for detailed examples

When Things Go Wrong

1. Query syntax error? → Check Query Construction
2. Unknown operator? → See Error Handling
3. Empty results? → Try WorkflowId fallback in Smart Patterns
4. Large history overwhelming? → Use History Filtering
5. Non-deterministic errors? → Use TemporalReportedProblems query (see above) or Error Handling

Next Steps

Start with Command Patterns for complete bash examples of all operations.