Agent skill

temporal-cli

Master Temporal CLI workflow management with smart query building, payload decoding, and history filtering using temporal, base64, and jq

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/development/temporal-cli

SKILL.md

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:

bash
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

Operation Reference Guide Use Case
list workflows Command Patterns Find workflows by query
count workflows Command Patterns Get result scope before listing
describe workflow Command Patterns Get current workflow state
show history Command Patterns View execution events
start workflow Command Patterns Create new execution
signal workflow Command Patterns Send signal to running workflow
query workflow Command Patterns Query workflow state
cancel workflow Command Patterns Request cancellation
terminate workflow Command Patterns Force termination
reset workflow Command Patterns Reset execution to previous point
stack trace Command Patterns Get workflow stack trace

Knowledge Guides

Guide Purpose
Query Construction Complete query syntax with 50+ examples
Custom Search Attributes Using custom fields in queries
Payload Decoding Base64/jq recipes for history payloads
History Filtering jq patterns for managing large histories
Smart Patterns Count-first, auto-retry, validation logic
Error Handling Common errors and recovery
Safety Checks Validation for destructive operations

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

bash
# 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:

bash
# 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:

bash
# 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:

bash
# 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

bash
# 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:

bash
# 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:

bash
# 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

bash
# 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

bash
# 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

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

Start New Workflow

bash
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

bash
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.

Didn't find tool you were looking for?

Be as detailed as possible for better results