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
version	1.0.0

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

⚠️ PIPING CAVEAT: Direct piping from temporal to jq can fail with mysterious errors. Use one of these patterns instead:

# Option 1: Store in variable (for smaller outputs)
RESULT=$(temporal --env prod -o json workflow show -w "my-wf")
echo "$RESULT" | jq '...'

# Option 2: Write to file first (recommended for histories)
temporal --env prod -o json workflow show -w "my-wf" > /tmp/wf.json
jq '...' /tmp/wf.json

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

0. Discover Workflow Types First

When searching for workflows by type and you're unsure of the exact type name, always discover available workflow types first. Workflow type names in code (e.g., OnboardingWorkflow) may differ from the registered name in Temporal (e.g., PatientOnboarding).

# List recent workflows and extract unique workflow types
temporal --env prod -o json --time-format iso workflow list --limit 100 | \
  jq -r '[.[].type.name] | unique | sort | .[]'

# Or find workflows with type names containing a keyword
temporal --env prod -o json --time-format iso workflow list --limit 200 | \
  jq -r '[.[].type.name] | unique | .[] | select(test("onboard"; "i"))'

Why this matters:

• Go method names like handler.PatientOnboarding register as PatientOnboarding, not the struct/file name
• TypeScript workflow function names may be different from file names
• Saves time by avoiding trial-and-error with incorrect type names

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})'

Investigate Stuck/Retrying Activities

⚠️ CRITICAL: Activity retries are invisible in event history (workflow show). While an activity is retrying, the history only shows ACTIVITY_TASK_SCHEDULED — no STARTED/FAILED events until the final outcome. Use workflow describe → pendingActivities instead:

# See last failure, attempt count, and next retry time for all pending activities
temporal --env prod -o json workflow describe -w "stuck-workflow-123" | \
  jq '.pendingActivities[] | {activityType: .activityType.name, attempt, state, lastFailure: .lastFailure.message, nextRetry: .nextAttemptScheduleTime}'

When to use this: Whenever workflow show reveals an ACTIVITY_TASK_SCHEDULED as the last event with no subsequent STARTED/COMPLETED/FAILED — the activity is retrying, and pendingActivities has the error.

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 with WorkflowType query? → Discover actual workflow types first (see Principle 0 above)
4. Empty results? → Try WorkflowId fallback in Smart Patterns
5. Large history overwhelming? → Use History Filtering
6. Non-deterministic errors? → Use TemporalReportedProblems query (see above) or Error Handling
7. Activity stuck with only SCHEDULED event? → Use workflow describe → pendingActivities (see "Investigate Stuck/Retrying Activities" above)

Next Steps

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