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

Knowledge Guides

Progressive Disclosure Strategy

1. Start here - Read this SKILL.md for overview
2. Need specific command? - Check [Command Patterns](references/01-command-patterns.md)
3. Building queries? - See [Query Construction](references/02-query-construction.md)
4. Large history? - Use [History Filtering](references/05-history-filtering.md)
5. Custom attributes? - Review [Custom Search Attributes](references/03-custom-search-attributes.md)
6. Hit errors? - Consult [Error Handling](references/07-error-handling.md)
7. Destructive ops? - Verify [Safety Checks](references/08-safety-checks.md)

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](references/05-history-filtering.md) 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](references/06-smart-patterns.md) 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](references/04-payload-decoding.md) 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 ACTIVITYTASKSCHEDULED — 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 ACTIVITYTASKSCHEDULED 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](references/08-safety-checks.md)

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](references/01-command-patterns.md) for detailed examples

When Things Go Wrong

1. Query syntax error? → Check [Query Construction](references/02-query-construction.md)
2. Unknown operator? → See [Error Handling](references/07-error-handling.md)
3. Empty results with WorkflowType query? → Discover actual workflow types first (see Principle 0 above)
4. Empty results? → Try WorkflowId fallback in [Smart Patterns](references/06-smart-patterns.md)
5. Large history overwhelming? → Use [History Filtering](references/05-history-filtering.md)
6. Non-deterministic errors? → Use TemporalReportedProblems query (see above) or [Error Handling](references/07-error-handling.md#non-deterministic-workflow-errors)
7. Activity stuck with only SCHEDULED event? → Use workflow describe → pendingActivities (see "Investigate Stuck/Retrying Activities" above)

Next Steps

Start with [Command Patterns](references/01-command-patterns.md) for complete bash examples of all operations.