temporal-cli

name	temporal-cli
description	Master Temporal CLI workflow management with smart query building, payload decoding, and history filtering using temporal, base64, and jq Use when this capability is needed.
metadata	{"author":"eantyshev"}

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

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

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

---

Converted and distributed by TomeVault — claim your Tome and manage your conversions.