### Development Environment Setup Commands

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/tests/test_config_examples.md

Provides a sequence of commands for initial project setup, including cloning the repository, installing dependencies, validating the environment, running tests, and demonstrating the infrastructure.

```bash
# Initial setup
git clone <repo>
cd temporal-cli-mcp
task setup                      # Install everything
task validate:env              # Verify setup
task test                       # Run tests
task demo:mcp                   # Demo the infrastructure

# Daily development
task test:watch                 # Start TDD session
# ... develop ...
task ci                         # Pre-commit check
```

--------------------------------

### Run MCP Server in Development Mode

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/CLAUDE.md

Starts the MCP server in development mode using uv. Ensure you have uv installed and configured.

```bash
uv run python -m temporal_cli_mcp --env staging
```

--------------------------------

### Install Temporal CLI MCP Server (Recommended)

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/README.md

Use this command to install the temporal-cli-mcp using uvx from GitHub. It configures the server to use the 'prod' environment.

```bash
claude mcp add temporal-cli-mcp -- uvx git+https://github.com/eantyshev/temporal-cli-mcp temporal-cli-mcp --env prod
```

--------------------------------

### Query Workflows by StartTime (Last 24 Hours)

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/temporal-cli-skill/references/02-query-construction.md

Retrieve workflows that started within the last 24 hours, using an example date.

```bash
temporal --env prod -o json --time-format iso workflow list \
  --query "StartTime > '2025-11-21T00:00:00Z'"
```

--------------------------------

### Get example queries and common mistakes

Source: https://context7.com/eantyshev/temporal-cli-mcp/llms.txt

Use this tool to retrieve a catalog of example queries categorized by type, including basic filters, pattern matching, time comparisons, IN-list filters, and combined conditions. It also highlights common mistakes with correct alternatives.

```json
{
  "tool": "get_query_examples",
  "arguments": {}
}
```

```json
{
  "success": true,
  "examples": {
    "basic_filters": {
      "workflow_type":     "WorkflowType = 'MyWorkflow'",
      "execution_status":  "ExecutionStatus = 'Running'",
      "workflow_id":       "WorkflowId = 'workflow-123'"
    },
    "pattern_matching": {
      "workflow_name_prefix": "WorkflowType STARTS_WITH 'Patient'"
    },
    "advanced_filters": {
      "workflow_id_list": "WorkflowId IN ('wf-1', 'wf-2', 'wf-3')",
      "time_range":       "StartTime BETWEEN '2024-01-01T00:00:00Z' AND '2024-01-31T23:59:59Z'"
    },
    "combined_filters": {
      "failed_onboarding": "WorkflowType STARTS_WITH 'patient' AND ExecutionStatus = 'Failed'"
    }
  },
  "common_mistakes": {
    "avoid_like_operator": {
      "wrong":   "WorkflowType LIKE '%onboard%'",
      "correct": "WorkflowType STARTS_WITH 'onboard'",
      "explanation": "LIKE operator is not supported. Use STARTS_WITH for prefix matching."
    },
    "multiple_values": {
      "wrong":   "WorkflowType = 'Type1' OR WorkflowType = 'Type2' OR WorkflowType = 'Type3'",
      "correct": "WorkflowType IN ('Type1', 'Type2', 'Type3')"
    }
  }
}
```

--------------------------------

### Run MCP Server in Production Mode

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/CLAUDE.md

Starts the MCP server in production mode. This assumes the package has been installed.

```bash
temporal-cli-mcp --env prod
```

--------------------------------

### MCP Client Configuration Example

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/README.md

Example JSON configuration for an MCP client, specifying the 'temporal-cli' server details. This includes the command to run, arguments, and the working directory.

```json
{
	"mcpServers": {
		"temporal-cli": {
			"command": "uv",
			"args": ["run", "python", "-m", "temporal_cli_mcp", "--env", "prod"],
			"cwd": "/path/to/temporal-cli-mcp"
		}
	}
}
```

--------------------------------

### Install Temporal CLI MCP Server (Development)

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/README.md

Install the temporal-cli-mcp locally from the repository root for development purposes. This command sets the environment to 'staging'.

```bash
claude mcp add temporal-cli-mcp -- uv run python -m temporal_cli_mcp --env staging
```

--------------------------------

### Install Test Dependencies

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/CLAUDE.md

Installs necessary dependencies required for running the project's tests.

```bash
task test:install-deps
```

--------------------------------

### Start Workflow with Input Data

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/temporal-cli-skill/references/01-command-patterns.md

Starts a workflow and provides initial input data as a JSON string.

```bash
temporal --env prod -o json --time-format iso workflow start \
  --type "OrderProcessing" \
  --task-queue "order-queue" \
  --workflow-id "order-$(uuidgen)" \
  --input '{"customerId": "cust-123", "amount": 99.99, "items": ["item1", "item2"]}'
```

--------------------------------

### Example MCP Client Configuration

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/CLAUDE.md

Illustrates a JSON configuration for an MCP client, specifying how to connect to the temporal-cli-mcp server.

```json
{
  "mcpServers": {
    "temporal-cli": {
      "command": "uv",
      "args": ["run", "python", "-m", "temporal_cli_mcp", "--env", "prod"],
      "cwd": "/path/to/temporal-cli-mcp"
    }
  }
}
```

--------------------------------

### Start New Workflow with Temporal CLI

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/temporal-cli-skill/SKILL.md

Initiate a new workflow with a specified type, task queue, and unique ID. Includes an example of passing workflow input as a JSON string.

```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"}'
```

--------------------------------

### Install Temporal CLI MCP Server in Dev Mode

Source: https://context7.com/eantyshev/temporal-cli-mcp/llms.txt

Installs the Temporal CLI MCP Server in development mode from a local checkout, configuring it for the 'staging' Temporal CLI environment.

```bash
# Dev mode from local checkout
claude mcp add temporal-cli-mcp -- uv run python -m temporal_cli_mcp --env staging
```

--------------------------------

### Validate Temporal CLI Setup

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/CLAUDE.md

Verifies that the Temporal CLI is correctly installed and accessible for integration testing.

```bash
task validate:temporal
```

--------------------------------

### Get Detailed Validation Help for Temporal Queries

Source: https://context7.com/eantyshev/temporal-cli-mcp/llms.txt

Retrieves detailed help information, including suggestions and examples, for validating Temporal query strings.

```python
help_info = TemporalQueryBuilder.get_validation_help("WorkflowType LIKE '%foo%'")
```

--------------------------------

### Start Workflow Basic

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/temporal-cli-skill/references/01-command-patterns.md

Initiates a new workflow execution. Specify the workflow type and task queue.

```bash
temporal --env staging -o json --time-format iso workflow start \
  --type "OnboardingFlow" \
  --task-queue "patient-workflows"
```

--------------------------------

### Verify Temporal CLI Installation

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/temporal-cli-skill/SKILL.md

Check if the Temporal CLI is installed and view its version.

```bash
temporal --version
```

--------------------------------

### Query Workflows by StartTime (After Date)

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/temporal-cli-skill/references/02-query-construction.md

Retrieve workflows that started after a specific date and time.

```bash
temporal --env prod -o json --time-format iso workflow list \
  --query "StartTime > '2025-01-01T00:00:00Z'"
```

--------------------------------

### Prerequisites for Temporal CLI

Source: https://context7.com/eantyshev/temporal-cli-mcp/llms.txt

Verifies the installed Temporal CLI version and displays the configuration file path, ensuring prerequisites are met.

```bash
# Prerequisites: Temporal CLI v1.4.1+ in PATH and environments configured
# temporal --version
# cat ~/.config/temporalio/temporal.yaml
```

--------------------------------

### List Workflows by Tenant ID and Start Time

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/temporal-cli-skill/references/02-query-construction.md

Use this query to find workflows belonging to a specific tenant that started after a certain date and time.

```bash
temporal --env staging -o json --time-format iso workflow list \
  --query "`tenant-id` = 'tenant-abc' AND StartTime > '2025-11-20T00:00:00Z'"
```

--------------------------------

### Query Workflows by StartTime (Before Date)

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/temporal-cli-skill/references/02-query-construction.md

Retrieve workflows that started before a specific date and time.

```bash
temporal --env staging -o json --time-format iso workflow list \
  --query "StartTime < '2025-12-31T23:59:59Z'"
```

--------------------------------

### Setup Temporal Test Environment

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/tests/TEST_STRATEGY.md

Sets up the test environment by checking for Temporal CLI availability and validating the specified Temporal environment. Raises a RuntimeError if prerequisites are not met.

```python
def setup_temporal_test_environment(env="staging"):
    """Setup test environment with proper configuration"""
    if not check_temporal_cli_available():
        raise RuntimeError("Temporal CLI not found")
    
    if not validate_temporal_env(env):
        raise RuntimeError(f"Cannot access Temporal environment: {env}")
    
    return env
```

--------------------------------

### Development Environment Variables

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/tests/test_config_examples.md

Set up environment variables for a local development setup, including retries.

```bash
# .env file for development
TEMPORAL_MCP_TEST_MOCK_MODE=1
TEMPORAL_TEST_ENV=staging
TEMPORAL_TEST_TIMEOUT=30
TEMPORAL_TEST_LOG_LEVEL=DEBUG
TEMPORAL_TEST_RETRIES=3
```

--------------------------------

### Start Workflow with Complex Input

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/temporal-cli-skill/references/01-command-patterns.md

Starts a workflow with complex input data defined in a heredoc, allowing for multi-line JSON.

```bash
# Create input JSON
INPUT=$(cat <<'EOF'
{
  "customer": {
    "id": "cust-456",
    "email": "customer@example.com"
  },
  "plan": "premium",
  "metadata": {
    "source": "web",
    "campaign": "summer2025"
  }
}
EOF
)

temporal --env staging -o json --time-format iso workflow start \
  --type "OnboardingFlow" \
  --task-queue "patient-workflows" \
  --workflow-id "onboard-$(date +%s)" \
  --input "$INPUT"
```

--------------------------------

### Example Custom Search Attributes Configuration

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/temporal-cli-skill/references/03-custom-search-attributes.md

This YAML snippet shows an example configuration for custom search attributes in a Temporal cluster, defining attributes like `CustomerId`, `TenantId`, `Priority`, `Amount`, `IsUrgent`, `DueDate`, `Tags`, `Environment`, and `Region` with their respective types.

```yaml
# Example: Temporal cluster search attributes config
customSearchAttributes:
  CustomerId:
    type: Keyword
  TenantId:
    type: Keyword
  Priority:
    type: Int
  Amount:
    type: Double
  IsUrgent:
    type: Bool
  DueDate:
    type: Datetime
  Tags:
    type: KeywordList
  Environment:
    type: Keyword
  Region:
    type: Keyword
```

--------------------------------

### Query Workflows by StartTime (Specific Range)

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/temporal-cli-skill/references/02-query-construction.md

Retrieve workflows that started within a specified date and time range.

```bash
temporal --env staging -o json --time-format iso workflow list \
  --query "StartTime BETWEEN '2025-01-01T00:00:00Z' AND '2025-01-31T23:59:59Z'"
```

--------------------------------

### Synchronize Dependencies

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/CLAUDE.md

Installs or updates project dependencies based on the lock file using uv.

```bash
uv sync
```

--------------------------------

### MCP Server Configuration Entry

Source: https://context7.com/eantyshev/temporal-cli-mcp/llms.txt

Example JSON configuration for registering the Temporal CLI MCP Server within an MCP client's configuration file.

```json
# mcp_config.json entry
# {
#   "mcpServers": {
#     "temporal-cli": {
#       "command": "uv",
#       "args": ["run", "python", "-m", "temporal_cli_mcp", "--env", "prod"],
#       "cwd": "/path/to/temporal-cli-mcp"
#     }
#   }
# }
```

--------------------------------

### Run Integration Tests with Temporal CLI

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/CLAUDE.md

Commands for integration testing with a real Temporal CLI. Use with caution. Includes a setup check and options for testing against staging environments.

```bash
task validate:temporal  # Check Temporal CLI setup first
task test:staging       # Test against staging
```

--------------------------------

### Temporal CLI Query Examples (Backtick Escaping)

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/temporal-cli-skill/references/03-custom-search-attributes.md

Shows how to use the Temporal CLI to query workflows, demonstrating the correct usage of backticks for field names containing special characters like hyphens and dots.

```bash
# ✅ No backticks needed (alphanumeric + underscore)
temporal --env prod -o json --time-format iso workflow list \
  --query "CustomerId = 'value'"

# ✅ Backticks required (contains hyphen)
temporal --env prod -o json --time-format iso workflow list \
  --query "\`customer-id\` = 'value'"

# ✅ Backticks required (contains dot)
temporal --env staging -o json --time-format iso workflow list \
  --query "\`user.email\` = 'user@example.com'"

# ✅ Backticks required (contains hyphen)
temporal --env prod -o json --time-format iso workflow list \
  --query "\`tenant-id\` = 'tenant-123'"
```

--------------------------------

### Correctly Use STARTS_WITH Operator

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/temporal-cli-skill/references/02-query-construction.md

Demonstrates the correct way to filter workflow types that start with a specific string, avoiding the unsupported LIKE operator.

```bash
# ✅ CORRECT
temporal --env prod -o json --time-format iso workflow list \
  --query "WorkflowType STARTS_WITH 'patient'"
```

--------------------------------

### start_workflow

Source: https://context7.com/eantyshev/temporal-cli-mcp/llms.txt

Starts a new workflow execution. Returns the new workflow's execution details including workflowId and runId.

```APIDOC
## start_workflow

### Description
Starts a new workflow execution. Returns the new workflow's execution details including workflowId and runId.

### Arguments
- **workflow_type** (string) - Required - The type of the workflow to start.
- **task_queue** (string) - Required - The task queue to use for the workflow.
- **workflow_id** (string) - Required - The unique ID for the workflow execution.
- **input_data** (string) - Optional - JSON string representing the input data for the workflow.

### Request Example
```json
{
  "tool": "start_workflow",
  "arguments": {
    "workflow_type": "OnboardingFlow",
    "task_queue": "patient-workflows",
    "workflow_id": "patient-onboard-1705999999",
    "input_data": "{\"customerId\": \"cust-abc-123\", \"plan\": \"premium\"}"
  }
}
```

### Response Example
```json
{
  "success": true,
  "data": {
    "workflowId": "patient-onboard-1705999999",
    "runId": "new-run-uuid"
  }
}
```
```

--------------------------------

### E-Commerce Use Cases: High-value and Customer Orders

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/temporal-cli-skill/references/03-custom-search-attributes.md

Examples for filtering e-commerce workflows by order value, customer ID, and time.

```bash
# High-value orders
temporal --env prod -o json --time-format iso workflow list \
  --query "WorkflowType = 'OrderProcessing' AND Amount > 1000.0"
```

```bash
# Orders by customer
temporal --env staging -o json --time-format iso workflow list \
  --query "CustomerId = 'cust-456' AND StartTime > '2025-11-01T00:00:00Z'"
```

--------------------------------

### List Workflows with Smart Fallback

Source: https://context7.com/eantyshev/temporal-cli-mcp/llms.txt

Illustrates the smart fallback mechanism where a 'WorkflowType' query that returns no results is automatically retried as a 'WorkflowId STARTS_WITH' query. Includes example response with fallback metadata.

```json
# Smart fallback example — WorkflowType not found, retries with WorkflowId prefix:
{
  "tool": "list_workflows",
  "arguments": {"query": "WorkflowType = 'megaflow'", "limit": 10}
}
# If WorkflowType = 'megaflow' returns empty, the server automatically retries:
# WorkflowId STARTS_WITH 'megaflow'
# Response includes fallback metadata:
{
  "success": true,
  "fallback_used": true,
  "original_query": "WorkflowType = 'megaflow'",
  "fallback_query": "WorkflowId STARTS_WITH 'megaflow'",
  "fallback_reason": "WorkflowType 'megaflow' not found, tried WorkflowId prefix instead",
  "data": [...] 
}
```

--------------------------------

### Basic CI Workflow for GitHub Actions

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/tests/test_config_examples.md

A GitHub Actions workflow file to automate testing on push and pull requests. It sets up Python, installs dependencies, runs tests in mock mode, and uploads coverage reports.

```yaml
# .github/workflows/test.yml
name: Test Temporal CLI MCP

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: [3.11, 3.12]
        test-mode: [mock]

    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: ${{ matrix.python-version }}
      
      - name: Install dependencies
        run: |
          pip install uv
          uv sync
          uv add --dev pytest pytest-asyncio pytest-cov pytest-html
      
      - name: Run tests
        env:
          TEMPORAL_MCP_TEST_MOCK_MODE: 1
          TEMPORAL_TEST_LOG_LEVEL: INFO
        run: |
          uv run pytest tests/ --cov=src/temporal_cli_mcp --cov-report=xml
      
      - name: Upload coverage
        uses: codecov/codecov-action@v3
        with:
          file: ./coverage.xml
```

--------------------------------

### Pretty Print Workflow List with jq

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/temporal-cli-skill/references/01-command-patterns.md

Formats the workflow list output using jq to display specific fields like workflow ID, status, and start time in a human-readable format.

```bash
temporal --env prod -o json --time-format iso workflow list \
  --query "ExecutionStatus = 'Running'" \
  --limit 20 | \
  jq -r '.[] | "\(.execution.workflowId) - \(.status) - \(.startTime)"'
```

--------------------------------

### Demo MCP Client Simulator

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/CLAUDE.md

Runs a demonstration of the MCP client simulator to showcase its functionality.

```bash
task demo:mcp
```

--------------------------------

### Workflow Describe Response Structure

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/temporal-cli-skill/references/01-command-patterns.md

This is an example JSON structure for the output of the `temporal workflow describe` command. It contains details about the workflow's configuration, execution info, and pending activities.

```json
{
  "executionConfig": {
    "taskQueue": { "name": "string", "kind": "TASK_QUEUE_KIND_NORMAL" },
    "workflowExecutionTimeout": "0s",
    "workflowRunTimeout": "0s",
    "defaultWorkflowTaskTimeout": "60s"
  },
  "workflowExecutionInfo": {
    "execution": { "workflowId": "string", "runId": "string" },
    "type": { "name": "string" },
    "startTime": "2025-12-20T17:11:40.092Z",
    "status": "WORKFLOW_EXECUTION_STATUS_RUNNING",
    "historyLength": "39",
    "searchAttributes": { "indexedFields": { ... } },
    "autoResetPoints": {
      "points": [
        { "buildId": "string", "firstWorkflowTaskCompletedId": "4", "resettable": true }
      ]
    },
    "taskQueue": "string",
    "stateTransitionCount": "24",
    "historySizeBytes": "7124",
    "firstRunId": "string"
  },
  "workflowExtendedInfo": {
    "runExpirationTime": "0001-01-01T00:00:00Z",
    "originalStartTime": "2025-12-20T17:11:40.092Z"
  },
  "pendingActivities": [
    {
      "activityId": "5",
      "activityType": { "name": "SendEmail" },
      "state": "PENDING_ACTIVITY_STATE_STARTED",
      "attempt": 1,
      "lastStartedTime": "2025-12-20T17:11:41.000Z"
    }
  ],
  "pendingChildren": [
    {
      "workflowId": "string",
      "workflowTypeName": "ChildFlow",
      "parentClosePolicy": "PARENT_CLOSE_POLICY_TERMINATE"
    }
  ]
}
```

--------------------------------

### Demo Test Utilities

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/CLAUDE.md

Runs a demonstration of the test utilities provided by the project.

```bash
task demo:utils
```

--------------------------------

### GitHub Actions: Integration Tests Workflow

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/tests/test_config_examples.md

Sets up integration tests in GitHub Actions, including installing the Temporal CLI, configuring environment variables, and running pytest. This job only runs on the main branch.

```yaml
integration-tests:
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4
      - name: Install Temporal CLI
        run: |
          # Install Temporal CLI for integration tests
          curl -sSf https://temporal.download/cli.sh | sh
      - name: Setup and test
        env:
          TEMPORAL_TEST_ENV: staging
          # Add Temporal Cloud credentials as secrets
        run: |
          pip install uv
          uv sync
          uv add --dev pytest pytest-asyncio
          uv run pytest tests/ -v -m "not slow"
```

--------------------------------

### Start Workflow with ID

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/temporal-cli-skill/references/01-command-patterns.md

Starts a workflow and assigns a unique workflow ID, useful for idempotency.

```bash
temporal --env staging -o json --time-format iso workflow start \
  --type "OnboardingFlow" \
  --task-queue "patient-workflows" \
  --workflow-id "patient-onboard-$(date +%s)"
```

--------------------------------

### Extract Started Workflow ID

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/temporal-cli-skill/references/01-command-patterns.md

Starts a workflow and captures its output to extract the workflow ID using jq.

```bash
RESULT=$(temporal --env staging -o json --time-format iso workflow start \
  --type "MyWorkflow" \
  --task-queue "my-queue")

WORKFLOW_ID=$(echo "$RESULT" | jq -r '.workflowId')
echo "Started workflow: $WORKFLOW_ID"
```

--------------------------------

### Run Quick Test Suite

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/CLAUDE.md

Executes a quick subset of tests. 'task quick' runs a single quick test, while 'task quick:all' runs the quick core test suite.

```bash
task quick
```

```bash
task quick:all
```

--------------------------------

### Structured workflow failure triage decision flow

Source: https://context7.com/eantyshev/temporal-cli-mcp/llms.txt

Obtain a machine-readable, step-by-step decision guide for workflow failure analysis. This guide is designed for LLM agents and SRE runbooks to ensure consistent and safe triage sequences.

```json
{
  "tool": "workflow_failure_analysis_guide",
  "arguments": {}
}
```

```json
{
  "success": true,
  "title": "Workflow Failure Analysis Guide",
  "summary": "Start with get_failed_runs for fast retry assessment; escalate to analyze_workflow_run for comprehensive diagnostics. Use history/describe to confirm hypotheses; trace_workflow for stalls. Use count/list with the query builder to assess scope; apply reset/terminate/cancel carefully.",
  "decision_flow": [
    {"step": 1, "question": "Are we investigating retries or a possible retry storm?",         "tool": "get_failed_runs",         "why": "Fast, lightweight count of failed attempts"},
    {"step": 2, "question": "Do we need comprehensive diagnostics?",                           "tool": "analyze_workflow_run",    "why": "Aggregates retry stats, scans history for patterns"},
    {"step": 3, "question": "Do we need raw execution details to confirm the root cause?",     "tool": ["get_workflow_history", "describe_workflow"]},
    {"step": 4, "question": "Is the workflow stuck or blocked right now?",                     "tool": "trace_workflow",          "why": "Fetches stack trace to diagnose stalls"},
    {"step": 5, "question": "Need population-level impact or to find similar failures?",       "tool": ["count_workflows", "list_workflows", "build_workflow_query"]},
    {"step": 6, "question": "Is an operational action required?",                              "tool": ["reset_workflow", "terminate_workflow", "cancel_workflow"]}
  ],
  "recommended_queries": [
    {"goal": "All failed runs for a workflow", "query": "WorkflowId = '<ID>' AND ExecutionStatus = 'Failed'"},
    {"goal": "Stuck/running for a long time",  "query": "ExecutionStatus = 'Running' AND RunTime >= 'PT1H'"}
  ]
}
```

--------------------------------

### Configure Custom Temporal Instance

Source: https://context7.com/eantyshev/temporal-cli-mcp/llms.txt

Instantiate and configure a custom TemporalConfig object for specific environments and logging levels. Call setup_logging() to apply the configuration.

```python
custom_config = TemporalConfig(
    env="staging",
    timeout=120.0,
    log_level="DEBUG"
)
custom_config.setup_logging()
```

--------------------------------

### Basic Development Task Commands

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/tests/test_config_examples.md

Common task commands for setting up the environment, validating, and running tests during development. Includes commands for iterative development and pre-commit checks.

```bash
# Start development session
task setup                          # Set up environment
task validate:env                   # Validate setup
task test                           # Run all tests (mock mode)

# Iterative development
task quick                          # Quick single test
task test:core                      # Core functionality tests
task test:watch                     # Watch mode for TDD

# Before committing
task test:coverage                  # Run with coverage
task ci                            # Simulate CI pipeline
```

--------------------------------

### List Workflows by TaskQueue Prefix

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/temporal-cli-skill/references/02-query-construction.md

Filter workflows where the TaskQueue name starts with a specific prefix.

```bash
temporal --env staging -o json --time-format iso workflow list \
  --query "TaskQueue STARTS_WITH 'prod-'"
```

--------------------------------

### List Workflows by Workflow ID Prefix

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/temporal-cli-skill/references/02-query-construction.md

Filter workflows where the WorkflowId starts with a specific prefix.

```bash
temporal --env staging -o json --time-format iso workflow list \
  --query "WorkflowId STARTS_WITH 'user-'"
```

--------------------------------

### Basic Test Environment Variables

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/tests/test_config_examples.md

Configure mock mode, test environment, timeouts, and log level for basic testing. Mock mode is recommended for development.

```bash
# Mock mode (no Temporal CLI calls) - RECOMMENDED for development
export TEMPORAL_MCP_TEST_MOCK_MODE=1

# Test environment selection
export TEMPORAL_TEST_ENV=staging

# Test timeouts
export TEMPORAL_TEST_TIMEOUT=30

# Logging configuration
export TEMPORAL_TEST_LOG_LEVEL=INFO  # DEBUG, INFO, WARNING, ERROR
```

--------------------------------

### Run Quick Development Workflow Tests

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/CLAUDE.md

Provides commands for quick development workflows, including running a single test, the core test suite, or enabling watch mode for Test-Driven Development (TDD).

```bash
# Quick development workflow
task quick              # Single test
task quick:all          # Core test suite
task test:watch         # Watch mode for TDD
```

--------------------------------

### Query Custom Keyword Field with Prefix

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/temporal-cli-skill/references/02-query-construction.md

Filter workflows where a custom keyword field starts with a specific prefix.

```bash
temporal --env staging -o json --time-format iso workflow list \
  --query "CustomerId STARTS_WITH 'customer-'"
```

--------------------------------

### Using STARTS_WITH for Flexible Matching

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/temporal-cli-skill/references/03-custom-search-attributes.md

Employ the `STARTS_WITH` operator for flexible matching of custom attributes, such as finding all customers with a specific prefix or tenants in a region.

```bash
# ✅ GOOD: Find all customers with prefix
temporal --env prod -o json --time-format iso workflow list \
  --query "CustomerId STARTS_WITH 'enterprise-'"

# Find all tenants in region
temporal --env staging -o json --time-format iso workflow list \
  --query "TenantId STARTS_WITH 'us-west-'"
```

--------------------------------

### Get All Field Types for Temporal Queries

Source: https://context7.com/eantyshev/temporal-cli-mcp/llms.txt

Fetches a reference of all available field types supported in Temporal queries.

```python
field_types = TemporalQueryBuilder.get_all_field_types()
```

--------------------------------

### Simulate CI Pipeline

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/CLAUDE.md

Commands to simulate the Continuous Integration (CI) pipeline. Includes options for basic CI simulation and a full CI run with coverage and reports.

```bash
# Simulate CI pipeline
task ci                 # Basic CI simulation
task ci:full            # Full CI with coverage and reports
```

--------------------------------

### Filter for Critical Path Events

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/temporal-cli-skill/references/05-history-filtering.md

Filters workflow history to show only critical events like start, completion, or failure.

```bash
temporal --env prod -o json --time-format iso workflow show \
  --workflow-id "my-workflow" | \
  jq '.events[] |
    select(.eventType |
      test("WorkflowExecutionStarted|WorkflowExecutionCompleted|WorkflowExecutionFailed|ActivityTaskFailed|ChildWorkflowExecutionFailed")
    )'
```

--------------------------------

### List Workflows (Basic)

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/temporal-cli-skill/references/01-command-patterns.md

Lists workflow executions with a specified limit. Ensure the global flags are set correctly.

```bash
temporal --env staging -o json --time-format iso workflow list --limit 10
```

--------------------------------

### E-Commerce Use Cases: Urgent and Regional Orders

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/temporal-cli-skill/references/03-custom-search-attributes.md

Examples for filtering e-commerce workflows by urgency, fulfillment status, and region.

```bash
# Urgent unfulfilled orders
temporal --env prod -o json --time-format iso workflow list \
  --query "IsUrgent = true AND IsFulfilled = false AND ExecutionStatus = 'Running'"
```

```bash
# Orders in specific region
temporal --env staging -o json --time-format iso workflow list \
  --query "Region = 'us-west-2' AND ExecutionStatus IN ('Running', 'Failed')"
```

--------------------------------

### List Workflows by Execution Time

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/temporal-cli-skill/references/02-query-construction.md

Query workflows based on their execution start or end times. Supports both range and greater-than comparisons.

```bash
temporal --env prod -o json --time-format iso workflow list \
  --query "ExecutionTime BETWEEN '2025-01-15T00:00:00Z' AND '2025-01-20T00:00:00Z'"
```

```bash
temporal --env staging -o json --time-format iso workflow list \
  --query "ExecutionTime > '2025-11-01T00:00:00Z'"
```

--------------------------------

### Access Temporal Configuration

Source: https://context7.com/eantyshev/temporal-cli-mcp/llms.txt

Demonstrates how to access and modify global runtime configuration for the Temporal CLI MCP, including environment, output format, and timeouts.

```python
from temporal_cli_mcp.config import config, TemporalConfig

# Default config (set by --env flag at startup)
print(config.env)            # e.g. "prod"
print(config.output_format)  # "json"
print(config.time_format)    # "iso"
print(config.timeout)        # 60.0 seconds
print(config.log_level)      # "INFO"

# Override timeout for large history operations
config.timeout = 180.0
```

--------------------------------

### Get Basic Workflow History

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/temporal-cli-skill/references/01-command-patterns.md

Retrieve the complete event history for a workflow execution using its ID. The output is in JSON format.

```bash
temporal --env staging -o json --time-format iso workflow show \
  --workflow-id "patient-onboard-12345"
```

--------------------------------

### Get Last WorkflowTaskFailed Event

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/temporal-cli-skill/references/07-error-handling.md

Retrieves the last 'EVENT_TYPE_WORKFLOW_TASK_FAILED' event for a specific workflow ID, which can help in diagnosing non-deterministic errors.

```bash
temporal --env prod -o json --time-format iso workflow show \
  --workflow-id "workflow-id-here" | \
  jq '[.events[] | select(.eventType == "EVENT_TYPE_WORKFLOW_TASK_FAILED")] | .[-1]'
```

--------------------------------

### Dockerfile for Testing

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/tests/test_config_examples.md

A Dockerfile to set up a Python environment with necessary dependencies and configurations for running tests.

```dockerfile
# Dockerfile.test
FROM python:3.11

WORKDIR /app
COPY . .

# Install dependencies
RUN pip install uv
RUN uv sync

# Install test dependencies
RUN uv add --dev pytest pytest-asyncio pytest-cov

# Set test environment
ENV TEMPORAL_MCP_TEST_MOCK_MODE=1
ENV TEMPORAL_TEST_LOG_LEVEL=INFO

# Run tests
CMD ["uv", "run", "pytest", "tests/", "-v"]
```

--------------------------------

### Count Workflows with Temporal CLI

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/temporal-cli-skill/SKILL.md

Get a count of workflows in a specified environment. This is useful for verifying operations before performing destructive actions.

```bash
temporal --env staging -o json --time-format iso workflow count
```

--------------------------------

### Correctly Use STARTS_WITH for Workflow Types

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/temporal-cli-skill/references/02-query-construction.md

Shows the correct method for filtering workflow types when wildcards are not supported, using STARTS_WITH instead.

```bash
# ✅ CORRECT
temporal --env staging -o json --time-format iso workflow list \
  --query "WorkflowType STARTS_WITH 'patient'"
```

--------------------------------

### Get Workflow Stack Trace

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/temporal-cli-skill/SKILL.md

Fetches the stack trace for a specific workflow ID. This is crucial for debugging stuck or problematic workflows.

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

--------------------------------

### Start New Workflow Execution

Source: https://context7.com/eantyshev/temporal-cli-mcp/llms.txt

Initiates a new workflow execution. Returns the workflow ID and run ID of the newly created execution.

```json
{
  "tool": "start_workflow",
  "arguments": {
    "workflow_type": "OnboardingFlow",
    "task_queue": "patient-workflows",
    "workflow_id": "patient-onboard-1705999999",
    "input_data": "{\"customerId\": \"cust-abc-123\", \"plan\": \"premium\"}"
  }
}
```

```json
# Response:
{
  "success": true,
  "data": {
    "workflowId": "patient-onboard-1705999999",
    "runId": "new-run-uuid"
  }
}
```

--------------------------------

### Check Temporal Environment Configuration

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/temporal-cli-skill/SKILL.md

View the Temporal CLI's environment configuration file.

```bash
cat ~/.config/temporalio/temporal.yaml
```

--------------------------------

### Task: Watch Mode for TDD

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/tests/test_config_examples.md

Starts a TDD session by running tests in watch mode. This is part of a common workflow for test-driven development.

```bash
# 1. Start watch mode
task test:watch

# 2. Write failing test
# 3. Make it pass
# 4. Refactor
# 5. Repeat
```

--------------------------------

### Build Temporal CLI Workflow Stack Command

Source: https://context7.com/eantyshev/temporal-cli-mcp/llms.txt

Constructs a full Temporal CLI command to get the stack trace of a stuck workflow.

```python
from temporal_cli_mcp.command_builder import TemporalCommandBuilder

builder = TemporalCommandBuilder(env="prod", timeout_seconds=120)

reset_cmd    = builder.build_full_command(
    builder.build_workflow_stack("stuck-wf-id")
)
```

--------------------------------

### Configure Temporal Environment Address

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/temporal-cli-skill/references/07-error-handling.md

If you encounter a 'connection refused' error, ensure your Temporal CLI environment is configured with the correct server address. Use 'temporal env set' to update the configuration.

```bash
# Update environment configuration
temporal env set staging --address temporal.staging.example.com:7233

```

--------------------------------

### Count Workflows with WorkflowTask Failures

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/temporal-cli-skill/references/02-query-construction.md

Get a count of running workflows that have encountered WorkflowTask failures. This is useful for assessing the scope of non-deterministic issues.

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

--------------------------------

### Extract Workflow Status using jq

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/temporal-cli-skill/references/01-command-patterns.md

Retrieve the status of a workflow execution and parse it using jq for programmatic access. Ensure jq is installed.

```bash
temporal --env staging -o json --time-format iso workflow describe \
  --workflow-id "my-workflow-123" | \
  jq -r '.workflowExecutionInfo.status'
```

--------------------------------

### Count Problematic Workflows

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/temporal-cli-skill/SKILL.md

Counts running workflows that have reported WorkflowTask failures. This is useful for getting a quick overview of workflows experiencing task-related issues.

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

--------------------------------

### Simulate MCP Client for Temporal Testing

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/tests/TEST_STRATEGY.md

Provides a comprehensive MCP client simulator for testing Temporal workflow operations at the protocol level. It includes methods for calling workflow tools and simulating specific operations like workflow listing.

```python
class TemporalMCPClientSimulator:
    """Simulate an MCP client for testing Temporal workflow operations"""
    
    def __init__(self, env="staging", timeout=30):
        """Initialize with Temporal environment configuration"""
        self.env = env
        self.timeout = timeout
        
    def call_workflow_tool(self, tool_name: str, **kwargs):
        """Call temporal workflow tools through MCP protocol"""
        return self.call_tool(tool_name, kwargs)
    
    def test_workflow_listing(self, query=None, limit=10):
        """Test workflow listing with optional query"""
        args = {"limit": limit}
        if query:
            args["query"] = query
        return self.call_workflow_tool("list_workflows", **args)
```

--------------------------------

### Build Temporal Query with Time Range Filter

Source: https://context7.com/eantyshev/temporal-cli-mcp/llms.txt

Constructs a Temporal query to filter workflows by start time within a specific range and task queue.

```python
query3 = (
    create_query_builder()
    .time_range(
        SupportedField.START_TIME,
        start=datetime(2025, 1, 1),
        end=datetime(2025, 1, 31, 23, 59, 59)
    )
    .task_queue("patient-workflows")
    .build()
)
```

--------------------------------

### Query Workflows by CloseTime (Still Running)

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/temporal-cli-skill/references/02-query-construction.md

Retrieve workflows that are still running (CloseTime is not set).

```bash
temporal --env staging -o json --time-format iso workflow list \
  --query "CloseTime IS NULL"
```

--------------------------------

### Handle Piping Issues with Temporal CLI and jq

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/temporal-cli-skill/references/05-history-filtering.md

Demonstrates two reliable methods for piping Temporal CLI output to jq: storing in a variable for smaller outputs or writing to a file for any size.

```bash
# Option 1: Store in variable first (works for smaller outputs)
HISTORY=$(temporal --env prod -o json --time-format iso workflow show -w "my-workflow")
echo "$HISTORY" | jq '.events[] | select(.eventType | contains("Failed"))'
```

```bash
# Option 2: Write to file first (works for any size, recommended)
temporal --env prod -o json --time-format iso workflow show -w "my-workflow" > /tmp/wf.json
jq '.events[] | select(.eventType | contains("Failed"))' /tmp/wf.json
```

--------------------------------

### List Workflows by Indexed Custom Attribute

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/temporal-cli-skill/references/02-query-construction.md

If a custom attribute like CustomerId is indexed, querying it directly is efficient. This example demonstrates filtering by a specific CustomerId.

```bash
temporal --env prod -o json --time-format iso workflow list \
  --query "CustomerId = 'customer-123'"
```

--------------------------------

### Validate Workflow Queries

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/temporal-cli-skill/SKILL.md

Pre-validate workflow queries to prevent execution errors. This example checks for the unsupported 'LIKE' operator and suggests using 'STARTS_WITH' instead.

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

--------------------------------

### VS Code Launch Configuration: Run Single Test

Source: https://github.com/eantyshev/temporal-cli-mcp/blob/main/tests/test_config_examples.md

Sets up VS Code to launch and run a single Python test file using pytest in mock mode. It dynamically includes the current file being edited.

```json
{
            "name": "Run Single Test",
            "type": "python",
            "request": "launch",
            "module": "pytest",
            "args": ["${file}", "-v"],
            "console": "integratedTerminal",
            "env": {
                "TEMPORAL_MCP_TEST_MOCK_MODE": "1"
            }
        }
    ]
}
```